Project commands

This page lists the npm scripts in saavo-default-template/package.json. Unless otherwise noted, run them from the root of your initialized project. Source archives remove the commit command used by template maintainers, so it is not a default command in newly created projects.

This reference was checked against template source version 0.2.14. Run npm run to list the scripts available in your own project. Older templates may differ; adding a script name alone does not install its implementation. Compare with the corresponding template source before using a missing command.

Development and preview

predev is a lifecycle script for npm run dev. npm runs it automatically, so you usually do not need to run it manually.

Code checks and tests

Run npm run verify to complete all local checks. A successful build does not replace type checking and tests.

Content and type generation

src/libs/documentation/source/.content-collections/ contains generated collections, types, and cache files. It is ignored by Git and excluded from source archives. saavo:init regenerates it; after changing content, you can rebuild it with npm run gen:collections.

Local initialization and checks

Databases

To change a database schema, add a migration file under schema/migrations and run the appropriate db:migrate command. Do not execute schema/db-init.sql or schema/analytics-init.sql directly.

Deployment

Use deploy:init only for the first remote deployment. Once that deployment is complete and all remote resources are configured, use deploy:update for subsequent releases. Setting account_id alone does not mean initialization is complete. If the first deployment fails partway through, inspect the resources and configuration already created, then follow the deployment tutorial. Do not switch commands based on a single field.

deploy:update requires SAAS_SECRET to exist and match exactly in .env and .env.production. Remote migrations run before the new Worker is deployed, so they must remain compatible with the code still running in production.

domain:set only changes the Worker's custom domain and VITE_SITE_URL. Update callback URLs on third-party platforms such as GitHub, Google, and Stripe separately. Turnstile domains and email sending domains also need to be updated on their respective platforms.

domain:set does not run the full verify sequence, database migrations, or KV synchronization. For releases that also change code, schema, or content, use deploy:update.

Stripe Webhook

These commands call Stripe to create remote webhooks, rather than only generating local configuration. The script prompts for the destination URL, event API version, and subscribed events. For development, provide an HTTPS URL that Stripe can reach. A loopback address cannot serve as a remote delivery destination. After production configuration is written back, redeploy the application. After development configuration changes, restart the development server.

Each successful run creates a new webhook destination; it does not update an existing one. Before running it again, check existing destinations to avoid duplicate event delivery.

Versions and releases

release:tag defaults to the version in package.json. It does not modify files, create a commit, or push the current branch. If you enter a different version, the script warns you but still allows you to continue.

For the template repository’s release workflow, commit all intended changes first and make sure the tag matches the versions in both package.json and package-lock.json. A successful tag push does not mean publication succeeded; check the release workflow result.

release:archive reads files from the Git tree, so uncommitted changes are not included in the archive. The archive excludes package-lock.json and removes the maintainer-only commit script from package.json.

Template repository maintenance command

npm run commit -- "Commit message" exists only in the template source repository's scripts and is removed from released source archives. It stages all changes, prepares the next patch version, creates a commit, and pushes the current branch directly. If no commit message is provided, it prompts for one interactively.