Local Secrets
During local development, tsdevstack stores secrets in JSON files and provides them to services through a consistent interface. This page covers how to work with secrets in your local environment.
The Secrets Files
After running npx tsdevstack generate-secrets, you will have these files in your project root:
All of these files are gitignored. The per-app .env files are generated by generate-secrets so that tools like Prisma CLI and Next.js can read environment variables directly. Backend services should still use SecretsService at runtime — the .env files exist for CLI tools (e.g., npx prisma studio) and frontend builds.
Adding Your Own Secrets
To add a custom secret, edit .secrets.user.json. Where you put the value decides which backend services can read it:
- The top-level
secretsobject is shared. Every backend service can readSENTRY_DSN. - A value in a service's section belongs to that service. Only
offers-servicereadsSTRIPE_API_KEY, locally and in the cloud.
Then regenerate:
In the cloud, cloud-secrets:push asks for each environment's value and puts it in the same scope. Top-level secrets go to shared. A service section's values go to that service's scope. To set one directly:
See How Secrets Work.
In the cloud's secret store, the scope is part of the name: {projectName}-{scope}-{KEY}. With a project named myapp, SENTRY_DSN is stored as myapp-shared-SENTRY_DSN and STRIPE_API_KEY as myapp-offers-service-STRIPE_API_KEY (hyphens instead of underscores on Azure). You only need these names when you create a secret in the cloud console yourself, for example before the first CI deployment. See Secret Naming in Cloud.
Values in a frontend's or a worker's section stay local. In the cloud, a frontend gets the shared keys listed in its secrets array, and a worker reads its base service's scope. cloud-secrets:push lists these values so you can move them.
Frontends (Next.js, SPA) work differently. Their section's secrets array lists the shared keys they get as environment variables at deploy, for example "frontend": { "secrets": ["SENTRY_DSN"] }. Backends ignore this array. They read the shared scope and their own at runtime.
Overriding Framework Defaults
You can override any framework-generated value by adding it to your user file:
Your values always take precedence over framework defaults.
Accessing Secrets in Backend Services
Backend services (NestJS) use the SecretsService to access secrets. Never use process.env directly.
This pattern ensures your code works the same way locally and in production.
Accessing Secrets in Frontend (Next.js)
Frontend applications receive secrets through generated .env files. Access them via process.env:
To add a secret to your frontend, update .secrets.user.json:
Accessing Secrets in SPAs (Rsbuild)
SPAs receive secrets through generated .env files (created by generate-secrets based on your secrets configuration) and expose them via build configuration:
Configure which env vars are bundled in your rsbuild.config.js:
Security note: Any secret exposed to an SPA is visible in the browser. Only expose values that are safe to be public, like API URLs.
Common Workflows
Initial Setup
The sync command generates secrets, Kong configuration, and other required files.
Adding a New Third-Party Service
- Add the API key to the section of the service that calls the third party, in
.secrets.user.json:
- Regenerate:
The service picks the value up within a minute, without a restart. SecretsService caches values for a minute locally.
- Access in your service:
Troubleshooting
"SECRETS_PROVIDER not set"
Run npx tsdevstack generate-secrets to create the necessary files.
Secret Not Available in Service
- Check that the secret is in
.secrets.user.json, in the top-levelsecretsobject (shared) or in this service's section. A service can't read a value in another service's section - For a frontend, check that the key is in its
secretsarray - Regenerate with
npx tsdevstack generate-secrets - Backends see the change within a minute; restart a frontend
Changes Not Taking Effect
After modifying .secrets.user.json:
- Run
npx tsdevstack generate-secrets - Wait up to 1 minute for the cache to refresh (SecretsService has a 1-minute TTL)
Note: Backend services using SecretsService automatically reload secrets from the file when the cache expires. Restarting is only needed if you're using process.env directly (which you shouldn't in backend services).