ShipThing has a composable environment variable system that allows you to define and validate environment variables in a type-safe way for each package, then compose them together into a single environment variable file for the app.

​
Overview

Type safety is provided by @t3-oss/env-nextjs, which provides runtime validation and autocompletion for all environment variables. Each package can define its own environment variables in a keys.ts file, which exports an keys object that contains all validated environment variables, separated into server and client variables. These keys are then composed together into a single environment variable file for the app, located in an env.ts file in the root of the app.

​
Environment variable files

As part of the initial setup script, each .env.example file is copied to a real environment variable file in each Next.js application and some packages. From here, you can fill in the variables yourself.
To enable the application to run normally with a minimum configuration, each module has a placeholder set in the environment variable in advance. You just need to change these placeholders to the actual value you want to use according to your actual needs.
Here are the values you must fill in for each environment variable file:
  • app/.env.local - The app’s environment variables.
.env.local
DATABASE_URL=
NEXT_PUBLIC_APP_URL=
NEXT_PUBLIC_WEB_URL=

CLERK_WEBHOOK_SECRET=
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
NEXT_PUBLIC_CLERK_SIGN_IN_URL=
NEXT_PUBLIC_CLERK_SIGN_UP_URL=
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=
  • web/.env.local - The web app’s environment variables.
.env.local
NEXT_PUBLIC_APP_URL=
NEXT_PUBLIC_WEB_URL=
  • api/.env.local - The API app’s environment variables.
.env.local
NEXT_PUBLIC_APP_URL=
NEXT_PUBLIC_WEB_URL=
NEXT_PUBLIC_API_URL=
  • packages/database/.env - The database package’s environment variables.
.env
DATABASE_URL=
  • packages/internationalization/.env.local - The internationalization package’s environment variables.
  • For NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_WEB_URL, and NEXT_PUBLIC_API_URL, you do not need to modify them locally, but should replace them with the URLs of your individual applications when you deploy them.
  • For *CLERK*, you should use the test key locally and the production key when deploying.

​
Validation rules

Each package’s keys.ts file contains the validation rules for each environment variable. These are used to validate the environment variables in the .env.local files. You can inspect these files to see the validation rules for each variable.
You should be as specific as possible with your validation. For example, if you know that a vendor secret starts with sec_, you should validate it as z.string().min(1).startsWith('sec_'). This will not only make your intent clearer to anyone reading your code, but will also help prevent errors at runtime.

​
Integration environment variables

Some environment variables will be added by integrations and other tooling. For example, environment variables prefixed with SENTRY_ are automatically added to a Vercel project when you add the Sentry integration from the Vercel Marketplace. Additionally, VERCEL_PROJECT_PRODUCTION_URL is a very handy environment variable that refers to the “production” URL to which this project is deployed on Vercel.
For VERCEL_PROJECT_PRODUCTION_URL, when you deploy to vercel, it defaults to the domain you deployed for the application

​
Adding an environment variable

To add a new environment variable, you need to do two things:
  1. Add the variable to each of the .env.local files across the project
  2. Add the variable to the server or client object in the relevant package’s keys.ts file.