> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipthing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> How to handle environment variables in ShipThing.

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](https://env.t3.gg/), 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.

<Note>
  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.
</Note>

Here are the values you must fill in for each environment variable file:

* `app/.env.local` - The app's environment variables.

```env .env.local theme={"system"}
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 .env.local theme={"system"}
NEXT_PUBLIC_APP_URL=
NEXT_PUBLIC_WEB_URL=
```

* `api/.env.local` - The API app's environment variables.

```env .env.local theme={"system"}
NEXT_PUBLIC_APP_URL=
NEXT_PUBLIC_WEB_URL=
NEXT_PUBLIC_API_URL=
```

* `packages/database/.env` - The database package's environment variables.

```env .env theme={"system"}
DATABASE_URL=
```

* `packages/internationalization/.env.local` - The internationalization package's environment variables.

<Info>
  - 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.
</Info>

## 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.

<Tip>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.</Tip>

## 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`](https://vercel.com/docs/environment-variables/system-environment-variables) is a very handy environment variable that refers to the "production" URL to which this project is deployed on Vercel.

<Tip>
  For `VERCEL_PROJECT_PRODUCTION_URL`, when you deploy to vercel, it defaults to the domain you deployed for the application
</Tip>

## 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.