Configuration

Set up your secret store

Create your Infisical projects, connect your machine to them, and add the credentials your project needs.

Your project needs credentials to run: a session signing key, OAuth client secrets, a payments token. None of them can live in Git, so NuxtStart keeps them in Infisical and reads them when the applications start.

Follow this page once. Afterwards, configuring a new deployment is a folder you fill in.

New to Infisical? You don't need to learn the product first. Three of its concepts map onto NuxtStart, and the steps below use only those three:

  • A project is one application. You create two: one for apps/web, one for apps/site.
  • An environment is a secret tier. You get development, staging, and production.
  • A folder is one runtime context. Local development reads /local.

Environment values explains why it's arranged that way. You don't need it to finish this page.

Prerequisites

  • An Infisical account. The free plan covers everything here.
  • Your project cloned, so you can edit apps/web/.env.infisical and apps/site/.env.infisical.

Create your projects

Create two projects

Create one project for apps/web and one for apps/site. Name them so you can tell them apart. See Infisical projects.

Rename the environment slugs

A new Infisical project ships with the slugs dev, staging, and prod. NuxtStart asks for development, staging, and production. In each project, go to Project > Settings > Environments and rename the slugs:

Ships asRename the slug to
devdevelopment
stagingstaging
prodproduction

The slug is the part everything addresses. The display name beside it is yours. Renaming edits the environment in place, so any secrets already in it survive.

Do this before anything else. A project still on dev is asked for an environment it doesn't have, and every command that reads a secret then fails there instead of failing on what you were changing.

Copy each project ID into your repository

Go to Project > Settings > General and copy the Project ID. Then paste it after projectId= in that application's .env.infisical, where it ships empty:

apps/web/.env.infisical
# @initInfisical(
#   projectId=<your apps/web project ID>,

Do the same for apps/site/.env.infisical with the other project's ID.

A project ID names a project without granting access to it, which is why it's committed.

Create the folders

Go to Project > Secrets in the apps/web project and select the development environment. Select the chevron next to Add Secret, then Add Folder, and create three folders: local, preview, and development. See Infisical folders.

Nothing else needs folders. The staging and production environments keep their secrets at the root, and apps/site stores no secrets at all.

Create a machine identity for your machine

Your machine signs in to Infisical as a machine identity, using a client ID and client secret pair. Machine identities creates it and adds it to both projects — one identity per person, reused by every project you own.

Come back here with its Client ID and Client Secret.

Connect your machine

Create a gitignored .env.local in each application and paste the pair into both files:

.env.local
INFISICAL_CLIENT_ID=<your client ID>
INFISICAL_CLIENT_SECRET=<your client secret>

Both applications sign in separately, so both files need the values.

Add the credentials

Go to Project > Secrets in the apps/web project, select the development environment, open the local folder, and add every key from the table below.

What to put in the /local folder

All of these belong to apps/web. Needed for names the feature each key serves and the layer that feature comes from, so you can tell which keys you need today.

KeyComes fromNeeded for
NUXT_APP_SECRETopenssl rand -base64 32Every sign-in (@app/layer-auth). Rotating it ends every session
GOOGLE_CLIENT_SECRETYour Google OAuth clientGoogle sign-in (@app/layer-auth)
GITHUB_CLIENT_SECRETYour GitHub OAuth appGitHub sign-in (@app/layer-auth)
POLAR_ACCESS_TOKENYour Polar organizationPayments (@app/layer-payments)
POLAR_WEBHOOK_SECRETYour Polar webhookPayments (@app/layer-payments)
NUXT_EMAIL_PLATFORM_ADMIN_EMAILSAddresses you choosePlatform alerts (@app/layer-email). Optional — leave it empty to turn them off

Set up sign-in and payments creates the Google, GitHub, and Polar side of these.

Skipping a feature for now? Every key here except NUXT_EMAIL_PLATFORM_ADMIN_EMAILS has to hold a value before apps/web installs or starts, so put a stand-in such as unused in the ones you're skipping. The product starts, and only the feature that reads the key fails when you first use it. A deployed context's folder behaves the same way: the deploy succeeds, and the feature fails at its first use there.

Two values that look like they belong here don't:

  • DATABASE_URL is per checkout locally: pnpm dev:web hands the server its checkout's Postgres, so no file holds it.
  • GOOGLE_CLIENT_ID and GITHUB_CLIENT_ID go in the committed apps/web/.env.development. Environment values explains why an OAuth client ID isn't a secret.

Setting up a deployed context

Everything above is the same for preview, development, staging, and production. Only two things change: which folder you fill in, and how the build signs in. /preview also holds NEON_API_KEY, SEED_PLATFORM_ADMIN_EMAIL, and SEED_PLATFORM_ADMIN_PASSWORD, which Adding pull request previews has you set.

A GitHub Actions runner never uses your client ID and secret. It signs in with OIDC, as one of two identities bound to your repository.

Troubleshooting

What you seeWhat to fix
Infisical authentication is requiredThe client ID and secret in that application's .env.local
projectId is requiredThe project ID in that application's .env.infisical
An error naming an environmentThe environment slugs aren't renamed yet
An error naming a single keyThat key is missing from the folder for the context you're running
Secrets resolve, but they're the wrong onesYou're running in a different context than you expected

Next steps

Copyright © 2026