Environment Variables
Create a .env file in the root of the project. The variables marked Required must be set before the app will start. All others are optional depending on which features you enable.
| Variable | Required | Description |
|---|---|---|
| DATABASE_URL | Required | PostgreSQL connection string. For production on DigitalOcean Managed DB, append &connection_limit=5 to cap the Prisma pool per instance. e.g. postgresql://user:password@localhost:5432/mydb?connection_limit=5 |
| NEXTAUTH_URL | Required | Canonical URL of your deployment. Must match the domain exactly. e.g. https://yourstore.com |
| NEXTAUTH_SECRET | Required | A random secret string used to sign session tokens. Generate one with: openssl rand -base64 32 e.g. your-random-secret |
| APP_ENCRYPTION_KEY | Required | 64-character hex key used to encrypt payment and shipping provider credentials stored in the database. Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" |
| ADMIN_EMAILS | Required | Comma-separated list of email addresses that are automatically assigned the ADMIN role when they sign up or sign in for the first time. |
| NEXT_PUBLIC_SITE_URL | Required | Public-facing site URL, baked into the client bundle at build time. Used for canonical links, sitemap generation, and OG images. e.g. https://yourstore.com |
| SITE_URL | Optional | Server-side site URL. Used to derive NEXTAUTH_URL when that variable is not set explicitly. Typically the same value as NEXT_PUBLIC_SITE_URL. e.g. https://yourstore.com |
| SITE_NAME | Optional | Display name for the site, used in email templates and the admin panel. e.g. My Store |
| SENDGRID_API_KEY | Optional | SendGrid API key for transactional emails (order confirmations, password resets, welcome emails). |
| SENDGRID_FROM_EMAIL | Optional | The verified sender email address in your SendGrid account. e.g. [email protected] |
| DO_SPACES_ENDPOINT | Optional | DigitalOcean Spaces endpoint URL. e.g. https://sfo3.digitaloceanspaces.com |
| NEXT_PUBLIC_DO_SPACES_CDN | Optional | CDN endpoint for serving media files publicly. Used in Next.js image remotePatterns. e.g. https://your-bucket.sfo3.digitaloceanspaces.com |
| DO_SPACES_REGION | Optional | DigitalOcean Spaces region. e.g. sfo3 |
| DO_SPACES_BUCKET | Optional | Name of your Spaces bucket. |
| DO_SPACES_FOLDER | Optional | Root folder within the bucket for this deployment's uploaded files. Use different values for dev vs production. e.g. production |
| DO_SPACES_KEY | Optional | Spaces access key ID. Generate under API → Spaces Keys in your DO account. |
| DO_SPACES_SECRET | Optional | Spaces secret access key. Shown only once at creation time. |
| GOOGLE_CLIENT_ID | Optional | Google OAuth client ID for Google sign-in. Create credentials at console.cloud.google.com. |
| GOOGLE_CLIENT_SECRET | Optional | Google OAuth client secret. Never expose this on the client. |
Payment & Shipping Credentials
Payment processor keys (Stripe, Authorize.net, Clover, Square) and shipping provider keys (EasyPost, Shippo, ShipStation) are not configured through environment variables. They are entered directly in the admin panel under Settings → Payment Settings and Settings → Shipping Settings, then stored encrypted in the database using APP_ENCRYPTION_KEY. This means you can change providers without redeploying.
Security Notes
- Never commit your
.envfile to version control. Ensure.envis in.gitignore. - Admin API keys (Stripe secret, SendGrid) must only be used server-side. They are never accessed from client components.
- Rotate
NEXTAUTH_SECRETimmediately if it is ever exposed. Rotating it will invalidate all active sessions.