---
title: "Environment values"
description: "Where each kind of value lives, which file wins, and how the secret store is organised."
canonical_url: "https://nuxtstart.com/docs/reference/environment-values"
---

> Index of every page on this site: [llms.txt](https://nuxtstart.com/llms.txt)

Every value the applications read comes from one of three places: a default in the schema, a
committed file for one runtime context, or the secret store. This page explains the model. The
pages under Configuration are the procedures that apply it.

## Runtime contexts

A runtime context is the situation the code is running in. There are six, and they differ in what
they own rather than only in name.

<table>
<thead>
  <tr>
    <th>
      Context
    </th>
    
    <th>
      What it is
    </th>
    
    <th>
      What selects it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        local
      </code>
    </td>
    
    <td>
      A developer machine
    </td>
    
    <td>
      The default when nothing sets one
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        test
      </code>
    </td>
    
    <td>
      The test suite
    </td>
    
    <td>
      Every CI job, and <code>
        pnpm test
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        preview
      </code>
    </td>
    
    <td>
      A pull request deployment
    </td>
    
    <td>
      Any pull request
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        development
      </code>
    </td>
    
    <td>
      The shared development deployment
    </td>
    
    <td>
      A push to the <code>
        development
      </code>
      
       branch
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      An optional pre-production deployment
    </td>
    
    <td>
      A push to the <code>
        staging
      </code>
      
       branch
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      The live deployment
    </td>
    
    <td>
      A push to <code>
        main
      </code>
    </td>
  </tr>
</tbody>
</table>

Nothing reads a branch name to work this out at load time. The deploy workflow maps each event to a
context, and that mapping lives in one place.

A project doesn't start with every context. It starts with `local`. `development` and `preview`
come next, each on its own: a pull request's preview runs on preview's own Worker, so a project adds
previews before `development`, after it, or without it. `staging` is optional and comes later, and
`production` comes last, once the application and its name are final. Getting Started walks them in
that order, from [Local setup](https://nuxtstart.com/docs/getting-started/local-setup) to
[Going to production](https://nuxtstart.com/docs/getting-started/going-to-production).

Two contexts deploy nothing. `local` runs against Docker and your filesystem, and `test` reaches
nothing at all — it reads committed fake values, so a clean checkout runs the test suite with no
credentials.

`local` is the one context with no value file of its own. It loads the `development` file, which is
why local overrides have to go somewhere that loads later.

## Three homes for a value

Ask one question per bucket. The answer decides the home.

<table>
<thead>
  <tr>
    <th>
      Home
    </th>
    
    <th>
      For
    </th>
    
    <th>
      Ask
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        .env.schema
      </code>
      
       default
    </td>
    
    <td>
      A value that's the same in every context
    </td>
    
    <td>
      Does it change between contexts?
    </td>
  </tr>
  
  <tr>
    <td>
      Committed <code>
        .env.<context>
      </code>
    </td>
    
    <td>
      A non-secret value that differs by context
    </td>
    
    <td>
      Would you show it in a pull request?
    </td>
  </tr>
  
  <tr>
    <td>
      The secret store
    </td>
    
    <td>
      A credential
    </td>
    
    <td>
      Would a leak hurt?
    </td>
  </tr>
</tbody>
</table>

Your project's identity is a schema default that lives outside either application:
`.env.project.schema` at the repository root, which both application schemas import. Every
deterministic resource name and sending domain is built from it rather than written down.
[Project identity](https://nuxtstart.com/docs/reference/project-identity) is that file and everything derived from it.

Non-secret configuration belongs in Git. Git gives you review, history, attribution, and rollback
next to the code that reads the value. Infisical's free plan keeps no secret history, so a value
moved there loses all four and gains nothing.

Two homes sit outside the three: a gitignored file for anything specific to one machine, and CI for
anything generated per build — the D1 and Hyperdrive ids the deploy hands its build, for example.

[Technical details](https://nuxtstart.com/docs/getting-started/technical-details) lists the environment files each
application owns.

## Which file wins

Files load in this order, and a later file overrides an earlier one:

1. Defaults written in `.env.schema`, including everything it imports — layer schemas and
`.env.project.schema`
2. `.env.local`
3. `.env.<context>`, the value file for the current context
4. `.env.<context>.local`

Both gitignored files exist because they sit on opposite sides of the value file:

- `.env.local` loads **before** it, so it can supply a key no committed file sets, and can't
override one that's already set.
- `.env.<context>.local` loads **after** it, so it overrides a committed value.

The second file is named after the value file, not after the context. Under `local` the value file
is `.env.development`, so the override file is `.env.development.local`.

## How the secret store is organised

NuxtStart stores credentials in [Infisical](https://infisical.com). Three Infisical concepts carry a
NuxtStart meaning:

<table>
<thead>
  <tr>
    <th>
      Infisical concept
    </th>
    
    <th>
      Holds
    </th>
    
    <th>
      Here it is
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Project
    </td>
    
    <td>
      A set of secrets
    </td>
    
    <td>
      One application: <code>
        apps/web
      </code>
      
       or <code>
        apps/site
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Environment
    </td>
    
    <td>
      A slice of a project
    </td>
    
    <td>
      A secret tier: <code>
        development
      </code>
      
      , <code>
        staging
      </code>
      
      , <code>
        production
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Folder
    </td>
    
    <td>
      A path in a tier
    </td>
    
    <td>
      One runtime context
    </td>
  </tr>
</tbody>
</table>

Two projects, because the two applications deploy separately and must never read each other's
secrets. `apps/web` holds every credential. `apps/site` declares none today, and still has a project
so a credential has somewhere to go later.

Three contexts share the `development` tier, so that tier carries three folders:

<table>
<thead>
  <tr>
    <th>
      Runtime context
    </th>
    
    <th>
      Environment
    </th>
    
    <th>
      Folder
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        local
      </code>
    </td>
    
    <td>
      <code>
        development
      </code>
    </td>
    
    <td>
      <code>
        /local
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        preview
      </code>
    </td>
    
    <td>
      <code>
        development
      </code>
    </td>
    
    <td>
      <code>
        /preview
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        development
      </code>
    </td>
    
    <td>
      <code>
        development
      </code>
    </td>
    
    <td>
      <code>
        /development
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        /
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        /
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        test
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      none
    </td>
  </tr>
</tbody>
</table>

Folders carry runtime context, not repository structure. There's no folder per layer or per package:
environment variables are one flat namespace at runtime, and the schemas already say which layer owns
which key.

<caution>

`/local` is shared team configuration for the local runtime context. It isn't storage for one
developer's personal values — those belong in a gitignored file.

</caution>

## How each context authenticates

Two mechanisms, and exactly one runs per build.

<table>
<thead>
  <tr>
    <th>
      Where
    </th>
    
    <th>
      What's set
    </th>
    
    <th>
      Mechanism
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A developer machine
    </td>
    
    <td>
      A client ID and client secret
    </td>
    
    <td>
      Universal Auth
    </td>
  </tr>
  
  <tr>
    <td>
      A GitHub Actions runner
    </td>
    
    <td>
      A machine identity ID
    </td>
    
    <td>
      OIDC
    </td>
  </tr>
</tbody>
</table>

A runner sets no client credentials and falls through to OIDC, where GitHub mints a token for one
workflow run of one repository and Infisical exchanges it. No long-lived Infisical credential is
stored in GitHub at all.

Two OIDC identities exist, and the workflow picks between them:

<table>
<thead>
  <tr>
    <th>
      Trusted for
    </th>
    
    <th>
      Granted
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Pull requests
    </td>
    
    <td>
      The <code>
        /preview
      </code>
      
       folder
    </td>
  </tr>
  
  <tr>
    <td>
      Branch pushes
    </td>
    
    <td>
      The <code>
        /development
      </code>
      
       folder, plus the staging and production tiers
    </td>
  </tr>
</tbody>
</table>

A machine identity ID is an identifier rather than a credential, which is why it travels as a
repository variable instead of a repository secret.

## Why some credentials are committed

`GOOGLE_CLIENT_ID` and `GITHUB_CLIENT_ID` sit in Git while their client secrets sit in the secret
store. That isn't an oversight. A browser sends an OAuth client ID in every authorization request,
so keeping one private can't be a security boundary. Committing it buys review and history; hiding
it buys nothing.

The same reasoning applies to an Infisical project ID and to a Cloudflare account ID. Each names
something without granting access to it.

## Next steps

- [Set up your secret store](https://nuxtstart.com/docs/configuration/secret-store) — the procedure this page explains
- [Technical details](https://nuxtstart.com/docs/getting-started/technical-details) — the environment files each
application owns, and how code reads a value
- [Deploy pipeline](https://nuxtstart.com/docs/deployment/pipeline) — which event deploys which context

## Sitemap

See the full [sitemap](https://nuxtstart.com/sitemap.md) for all pages.
