Saavo

Run locally

Start the development server and confirm that the project, environment file, and local databases are ready.

The project root contains the main structure of the current Saavo default template. Only node_modules, build output, and local runtime caches are omitted below:

errors.ts
index.tsx
types.ts
.env
.gitattributes
.gitignore
.prettierrc
AGENTS.md
components.json
eslint.config.js
example.vars
LICENSE
package-lock.json
package.json
README.md
tsconfig.json
vite.analytics.config.ts
vite.config.ts
vitest.config.ts
worker-configuration.d.ts
wrangler.jsonc

Start with these locations: config/ holds product and feature configuration, src/pages/ holds pages, src/api/ holds API endpoints, and src/core/ holds business logic. content/ and locales/ manage content and internationalization. .env is only for the local environment. Cloudflare bindings and Worker configuration are in wrangler.jsonc.

Start the local development server:

cd my-project
npm run dev

The documentation search index is generated before startup. Vite and the Cloudflare plugin then start the local Workers runtime. The terminal shows the actual address, usually:

http://127.0.0.1:5173

If the port is occupied, Vite switches to another port. Use the terminal output for both the browser address and local VITE_SITE_URL. Do not assume that 5173 is the only possible port.

Local development server started successfully

Run a basic check

Open the address shown in the terminal and check, in order, that:

  • The homepage displays correctly.
  • /docs opens.
  • The sign-in and sign-up pages are accessible.
  • Refreshing does not produce missing database table or binding errors.

The local databases were initialized during project creation. You do not need another terminal to run wrangler d1 execute. To check the environment again, run:

npm run doctor

Local environment check

doctor may report that Resend, Stripe, or OAuth is not configured. As long as the output contains no ERROR, these unused services do not prevent further development.

Keep local and production environments separate

Local development reads only .env. By default:

  • saavo:init has generated SAAS_SECRET.
  • Turnstile uses Cloudflare test keys.
  • Credentials for Resend, Stripe, GitHub, Google, and similar services can remain empty.
  • The local Workers runtime simulates D1, KV, R2, Queues, and Durable Objects.

Restart npm run dev after changing .env. Do not put production keys in .env ahead of time. The initial deployment writes them to .env.production.

If initialization is incomplete

If the terminal reports a missing .env, SAAS_SECRET, database table, or generated types, stop the development server and run:

npm run saavo:init
npm run dev

Use npm run db:migrate:local for routine new database migrations. Use npm run db:reset:local only when you are sure all local data can be deleted. It is not a routine repair command.

Decide what to configure before deployment

If you only want to verify the deployment process, you can keep most template content. Turnstile can temporarily use Cloudflare's official test keys. For email, prepare the keys required by your selected provider and your own sender and support addresses. You can continue to skip Stripe, GitHub sign-in, and Google sign-in if they are not ready.

Before opening the site to users, follow the tutorial to update branding, products, prices, the administrator email address, and legal pages. The quickstart only ensures that the project runs and deploys. It does not mean the default template content is ready to publish as your product.

Next: Initial deployment.