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

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.

> [!NOTE]
>
> * 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.

> [!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.

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.