Improvements
SnapsVault is open source under the Apache-2.0 license, and improvements to its code, tools and docs are welcome. This page covers the repositories, issues, pull requests, the local setup and the checks.
Contributors who list snapshots follow Contribute snapshots instead. Questions and bug reports are on the Feedback page.
Repositories
The Marketplace, the SnapsOS CLI, the REST API, the website and these docs live in one public repository, and the contributor listings live in a second one.
| Repository | Contents | Changes by |
|---|---|---|
| SnapsVault repository | Marketplace app and REST API, SnapsOS CLI, website, docs | Issues and pull requests |
| Registry repository | One JSON file per contributor and chain ID, pointing at its feeds | Pull requests from contributors, see Contribute snapshots |
Layout of the SnapsVault repository
| Path | What it holds |
|---|---|
/ (root) | The Marketplace app and the REST API, built with Next.js |
cli/snapsos.sh | SnapsOS CLI, a single bash script |
landing/ | The website, a separate Next.js app |
docs-site/ | These docs, built with VitePress |
docs/ | Feed and registry contract as the code reads it, design rules |
Full rules
This page is the short version of CONTRIBUTING.md on GitHub.
Issues
Bugs and feature requests go to GitHub issues. The issue form offers a template for each kind. Searching existing issues first avoids duplicates.
| A good bug report has | |
|---|---|
| What happened | The page, API route or CLI command, and the result |
| What was expected | The result that should have appeared instead |
| How to reproduce | Steps, the chain ID and contributor if relevant, the CLI flags or the request URL |
| Environment | Browser, or operating system and bash version for the CLI |
| A good feature request has | |
|---|---|
| Problem | What cannot be done today, or what is slow or unclear |
| Who it helps | Node operators, contributors or developers, and in which situation |
| Example | A concrete case, such as a network, chain ID, contributor or command, with the expected result |
Describe the need rather than the implementation. Planned work is listed on the SnapsVault website. A request is not a commitment to build.
Pull requests
- Fork the SnapsVault repository and clone the fork.
- Create a branch from
mainnamed<type>/<short-topic>, for examplefix/cli-latest-testnet. Common types arefeat,fix,docs,design,copy,chore. - Set up the project as described in Local setup and make the change.
- Run the checks for every part the change touches.
- Push the branch and open a pull request against
main. The description states the current behavior, the change and how it can be checked. A linked issue goes in the description. - A maintainer reviews the pull request. Review comments are answered with new commits on the same branch. An accepted pull request is merged into
main.
A pull request stays small and covers one change. A larger change, such as a new route or a new page, starts as an issue so the approach can be agreed first. Registry pull requests (contributor files) are reviewed and merged in the registry repository.
Local setup
Requirements: Node.js 22.18 or later, npm, git, and a MongoDB instance for the app. A local MongoDB, or one in Docker, is enough. Clone the fork and install:
bash
git clone https://github.com/<GitHub user>/snapsvault.git
cd snapsvault
npm ciThen set up the part to change.
bash
cp .env.example .env.local
npm run devbash
cd landing
npm ci
npm run devbash
cd docs-site
npm ci
npm run docs:devbash
bash cli/snapsos.sh --api-base http://localhost:3000| Part | Runs at | Notes |
|---|---|---|
| App and API | http://localhost:3000 | Needs .env.local, see below |
| Website | http://localhost:3001 | Reads the live REST API and needs no environment variables. Set SNAPSHOTS_API_URL=http://localhost:3000 to point it at a local app. |
| Docs | The address VitePress prints, by default http://localhost:5173 | |
| SnapsOS CLI | N/A | Needs no build. It runs against the production API by default, or against a local app with --api-base. |
App environment
In .env.local, set:
MONGODB_URIto the local MongoDB, for examplemongodb://localhost:27017/snapsvault.GITHUB_TOKENto a GitHub token with read access to public repositories. The registry is public, and the token raises the GitHub API rate limit for the sync.
The other variables are described in the README.
The database starts empty. A sync reads the registry and every feed into it. With CRON_SECRET set in .env.local, run one sync with:
bash
curl -H "Authorization: Bearer <cron secret>" http://localhost:3000/api/sync-snapshotsChecks
| Part | Commands |
|---|---|
| App and REST API (root) | npx tsc --noEmit, npm run lint, npm run build |
Website (landing/) | npx tsc --noEmit, npm run lint, npm run build |
Docs (docs-site/) | npm run docs:build |
| Node tests | node --test "src/**/*.test.mjs" runs every *.test.mjs file (Node.js 22.18 or later, which runs the imported .ts files directly) |
| CLI | bash -n cli/snapsos.sh, bash cli/tests/run.sh, and shellcheck cli/snapsos.sh when available |
A pull request with failing checks is not accepted.
Style
- Code follows the style of the file it changes. New dependencies are added only when the change needs them.
- Interface and docs text follows
docs/DESIGN.md. Docs are written in the third person or the imperative. - Commit messages are short, in English and in the imperative, for example
Fix testnet default in --latest.
License
SnapsVault is licensed under the Apache License 2.0. A contribution submitted to the repository is licensed under the same terms.
Need help?
Ask on Telegram or open an issue in the SnapsVault repository. More options are on the Feedback page.
Next steps
- Feedback: ask a question, report a bug or report a security issue
- Contribute snapshots: list your snapshots on SnapsVault
- SnapsOS CLI: the script in
cli/snapsos.sh