---
title: "Project identity"
description: "The values that name and describe your project, and every resource name, origin, and sending domain derived from them."
canonical_url: "https://nuxtstart.com/docs/reference/project-identity"
---

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

Your project's name appears in Worker names, bucket names, database names, origins, and the domain
your transactional mail is sent from. You set it in one place, and everything deterministic follows.

```mermaid
flowchart LR
    S["PROJECT_SLUG"] --> W["Worker names"]
    S --> R["Bucket, database, and pool names"]
    S --> M["Non-production sending domains"]
    Z["PROJECT_ZONE"] --> M
    Z -. "defaults to" .-> D["PROJECT_DOMAIN"]
    N["PROJECT_DISPLAY_NAME"] --> A["The product name people read"]
    X["PROJECT_DESCRIPTION"] --> L["Meta description and llms.txt summary"]
    D --> P["Production routes"]
    D --> E["Production sending domains"]
```

This page is the human view of the rule. The rules themselves live in
`skills/internal/project-context/domains/project-identity.md`, which is what your agent reads and
what the implementation follows. When this page and that file disagree, that file is right.

## The values you set

They're declared in `.env.project.schema` at the root of the repository. That's a different file
from the `.env.schema` beside it, which holds repository tooling and nothing about your project.

<table>
<thead>
  <tr>
    <th>
      Item
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      What it is
    </th>
    
    <th>
      Example
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        PROJECT_SLUG
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      The lowercase name inside every resource name
    </td>
    
    <td>
      <code>
        my-app
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROJECT_DISPLAY_NAME
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      The product name people read
    </td>
    
    <td>
      <code>
        My App
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROJECT_DESCRIPTION
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      One sentence saying what your product is
    </td>
    
    <td>
      <code>
        A CRM
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROJECT_ZONE
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Your Project Zone: the DNS zone you own
    </td>
    
    <td>
      <code>
        example.com
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PROJECT_DOMAIN
      </code>
    </td>
    
    <td>
      No, defaults to the zone
    </td>
    
    <td>
      Your Project Domain: the hostname production is served from
    </td>
    
    <td>
      <code>
        example.com
      </code>
    </td>
  </tr>
</tbody>
</table>

Your copy ships with every required item empty, so `pnpm install`, the dev server, and
a deploy's build stop on an empty one and name it, in both applications at once because both read
this file. The `test` context carries fake values of its own, so CI checks pass before you've set
them.
[Local setup](https://nuxtstart.com/docs/getting-started/local-setup#name-your-project) is the step that fills them in.

`PROJECT_SLUG` is typed, because it becomes part of every resource name: lowercase letters, digits,
and dashes, starting and ending with a letter or digit, and at most 38 characters. The length limit
comes from a pull request preview's hostname label, `pr-<n>-<slug>-site-preview`, which DNS caps at
63 characters: the slug gets what a pull request number of up to eight digits leaves.

`PROJECT_DESCRIPTION` becomes the website's default meta description and the summary at the top of
its `llms.txt`, the index AI agents read. Nothing can derive it, so you write it, in at most 160
characters, because search results cut a meta description off there.

Your Project Zone and Project Domain are the same value when your project owns a whole zone. They
differ when your project lives at a subdomain of a zone you use for other things: the Project Zone
stays `example.com` and the Project Domain becomes `my-app.example.com`.

The Project Zone is required and the Project Domain isn't. Mail reads the Project Zone in the five
runtime contexts that have no production hostname, and only production reads the Project Domain. You can own a zone and send
mail from `development` long before you've chosen a production hostname, and you don't have to
invent one to get there.

## What derives from them

You don't write any of these in a value file. They're expressions in each application's
`.env.schema`, and they change when you change the values above.

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Shape
    </th>
    
    <th>
      Which context it reads
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        NUXT_PUBLIC_APP_NAME
      </code>
    </td>
    
    <td>
      The display name
    </td>
    
    <td>
      None — the same everywhere
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NUXT_PUBLIC_APP_DESCRIPTION
      </code>
    </td>
    
    <td>
      The description, in <code>
        apps/site
      </code>
    </td>
    
    <td>
      None — the same everywhere
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_WORKER_NAME
      </code>
    </td>
    
    <td>
      <code>
        <slug>-<app>-<context>
      </code>
    </td>
    
    <td>
      The runtime context, as-is
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_R2_BUCKET_NAME
      </code>
    </td>
    
    <td>
      <code>
        <slug>-web-<context>
      </code>
    </td>
    
    <td>
      The runtime context, as-is
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_HYPERDRIVE_NAME
      </code>
    </td>
    
    <td>
      <code>
        <slug>-web-<context>
      </code>
    </td>
    
    <td>
      The runtime context, as-is
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CLOUDFLARE_D1_DATABASE_NAME
      </code>
    </td>
    
    <td>
      <code>
        <slug>-site-<context>
      </code>
    </td>
    
    <td>
      The runtime context, as-is
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NUXT_EMAIL_SENDER_DOMAIN
      </code>
    </td>
    
    <td>
      <code>
        <app>.<domain>
      </code>
      
       in production, <code>
        <slug>-<app>-<context>.<zone>
      </code>
      
       in all others
    </td>
    
    <td>
      The runtime context, as-is
    </td>
  </tr>
</tbody>
</table>

Every name reads the context as-is, so every context — `local` and `preview` included — names its
own Worker, bucket, pool, database, and sender, and `production` is the one context whose sender
reaches your domain. A pull request preview is a Cloudflare Worker Preview on preview's own Worker.
Nothing creates a `local` resource; [Resources](https://nuxtstart.com/docs/deployment/resources#local) says why that's
fine.

The `test` context is the exception to the heading. Its two `.env.test` files override the derived
names with fakes, because `test` reaches no deployed service and a derived name names one.

## Serving origins

`local` and `test` run on localhost. Every deployed context except production is served from your
Cloudflare account's `workers.dev` subdomain:

```text
https://<slug>-<app>-<context>.<subdomain>.workers.dev
```

A pull request preview is preview's origin with `pr-<n>-` in front of it, so it is served from
`https://pr-<n>-<slug>-<app>-preview.<subdomain>.workers.dev`. None of these touches your domain.

That `workers.dev` subdomain belongs to your Cloudflare account rather than to the project, so it
isn't part of project identity. One account can serve several projects, and a project can move
between accounts.

Production is the only context where your domain appears, and it has five shapes:

<table>
<thead>
  <tr>
    <th>
      What you're deploying
    </th>
    
    <th>
      <code>
        apps/site
      </code>
    </th>
    
    <th>
      <code>
        apps/web
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Both apps, on a zone you own
    </td>
    
    <td>
      <code>
        example.com
      </code>
    </td>
    
    <td>
      <code>
        app.example.com
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Both apps, at a subdomain
    </td>
    
    <td>
      <code>
        my-app.example.com
      </code>
    </td>
    
    <td>
      <code>
        app.my-app.example.com
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The website only
    </td>
    
    <td>
      <code>
        example.com
      </code>
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      The product application only
    </td>
    
    <td>
      —
    </td>
    
    <td>
      <code>
        example.com
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The product mounted under the site
    </td>
    
    <td>
      <code>
        example.com
      </code>
    </td>
    
    <td>
      <code>
        example.com/app/
      </code>
    </td>
  </tr>
</tbody>
</table>

The first three follow one rule: the website takes your domain, and the product application takes
`app.` in front of it. That rule is what `CLOUDFLARE_WORKER_ROUTE` in each `.env.production` is built
from, so those three topologies need no edit. The last two break the rule — replace that key, and for
a path-scoped route set `CLOUDFLARE_WORKER_ROUTE_ZONE` alongside it.

None of the five serves `www.`. When production takes your zone's apex, a Cloudflare Redirect Rule
sends `www.` there instead, and
[Going to production](https://nuxtstart.com/docs/getting-started/going-to-production#configure-and-deploy) sets it up.

<caution>

The route and the origin are two values that have to agree, and nothing checks them against each
other. `CLOUDFLARE_WORKER_ROUTE` decides where the Worker answers; `NUXT_PUBLIC_APP_BASE_URL` is
baked into the bundle and reaches your canonical tags, social images, sitemap and email. Edit them
together, or production answers on one name and advertises another.

</caution>

Origins aren't derived at all. They carry your account's `workers.dev` subdomain in the deployed
non-production contexts, the production value has the five shapes above, and the deploy workflow
reads `NUXT_PUBLIC_APP_BASE_URL` as text to build each preview origin — an expression there would be
prefixed unresolved. So you write one into each deployed context's value file yourself, at the
Getting Started stage that adds the context.

## Sending domains

Transactional mail is sent from a hostname on the zone you own. Production takes the short form and
every other runtime context carries its own name, so a bug in `development` can never send from
production's `From:` domain:

<table>
<thead>
  <tr>
    <th>
      Runtime context
    </th>
    
    <th>
      <code>
        apps/web
      </code>
    </th>
    
    <th>
      <code>
        apps/site
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        app.<domain>
      </code>
    </td>
    
    <td>
      <code>
        site.<domain>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
      
      , <code>
        development
      </code>
      
      , <code>
        preview
      </code>
      
      , <code>
        local
      </code>
    </td>
    
    <td>
      <code>
        <slug>-web-<context>.<zone>
      </code>
    </td>
    
    <td>
      <code>
        <slug>-site-<context>.<zone>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        test
      </code>
    </td>
    
    <td>
      <code>
        mail.example.test
      </code>
    </td>
    
    <td>
      <code>
        mail.example.test
      </code>
    </td>
  </tr>
</tbody>
</table>

Production's two prefixes are the ones its routes already use. `apps/web` sends from the same
hostname it serves — a Custom Domain is a proxied address record, and the SPF and DKIM records live
at that name alongside it. `apps/site` takes `site.` rather than your domain itself, because its
route is the apex.

`local` resolves a hostname nothing ever onboards, which is correct: local mail is caught by Mailpit
and never reaches Cloudflare. The test suite uses a fake on a reserved domain.

<caution>

Cloudflare Email Sending is onboarded one exact hostname at a time. SPF is looked up on the `From:`
domain, and the DKIM key sits at `<selector>._domainkey.<hostname>`, so each context needs its own
records. A hostname you haven't onboarded still resolves, still builds, and still deploys — the
message fails at the recipient instead. Adding a runtime context means adding an onboarding.

</caution>

A sender is not an origin, and you can't point one at the other. Your non-production **origins** are
on your Cloudflare account's `workers.dev` subdomain, and a sender can never go there: onboarding
writes SPF and DKIM records into the sending hostname's zone, and `workers.dev` belongs to
Cloudflare rather than to you.

## Worked scenarios

Each of these sets the identity values and changes nothing else. The route, the resource names, and
the sending domains all follow. Only the origins are yours to write, because no expression can know
your account's `workers.dev` subdomain — the section above says why.

### You own the whole zone

The common case, and the one the defaults are built for. Leave `PROJECT_DOMAIN` alone and it takes
the zone.

```sh [.env.project.schema]
PROJECT_SLUG=my-app
PROJECT_DISPLAY_NAME=My App
PROJECT_DESCRIPTION="A project-planning tool for small teams."
PROJECT_ZONE=example.com
PROJECT_DOMAIN=$PROJECT_ZONE
```

<table>
<thead>
  <tr>
    <th>
      Runtime context
    </th>
    
    <th>
      Application
    </th>
    
    <th>
      Serves
    </th>
    
    <th>
      Sends mail from
    </th>
    
    <th>
      Worker name
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        apps/site
      </code>
    </td>
    
    <td>
      <code>
        example.com
      </code>
    </td>
    
    <td>
      <code>
        site.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-site-production
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      <code>
        app.example.com
      </code>
    </td>
    
    <td>
      <code>
        app.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-web-production
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        apps/site
      </code>
    </td>
    
    <td>
      <code>
        workers.dev
      </code>
    </td>
    
    <td>
      <code>
        my-app-site-staging.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-site-staging
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      <code>
        workers.dev
      </code>
    </td>
    
    <td>
      <code>
        my-app-web-staging.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-web-staging
      </code>
    </td>
  </tr>
</tbody>
</table>

### Your slug doesn't match your domain

Nothing forces them to agree. The slug names resources inside your Cloudflare account; the domain
names what the public sees. A company called Acme can ship a product at `getacme.com` and still keep
`acme-crm` on every bucket and Worker.

```sh [.env.project.schema]
PROJECT_SLUG=acme-crm
PROJECT_DISPLAY_NAME=Acme CRM
PROJECT_DESCRIPTION="A CRM for small agencies, with pipelines, invoicing and client portals."
PROJECT_ZONE=getacme.com
PROJECT_DOMAIN=$PROJECT_ZONE
```

<table>
<thead>
  <tr>
    <th>
      Runtime context
    </th>
    
    <th>
      Application
    </th>
    
    <th>
      Serves
    </th>
    
    <th>
      Sends mail from
    </th>
    
    <th>
      Worker name
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        apps/site
      </code>
    </td>
    
    <td>
      <code>
        getacme.com
      </code>
    </td>
    
    <td>
      <code>
        site.getacme.com
      </code>
    </td>
    
    <td>
      <code>
        acme-crm-site-production
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      <code>
        app.getacme.com
      </code>
    </td>
    
    <td>
      <code>
        app.getacme.com
      </code>
    </td>
    
    <td>
      <code>
        acme-crm-web-production
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        apps/site
      </code>
    </td>
    
    <td>
      <code>
        workers.dev
      </code>
    </td>
    
    <td>
      <code>
        acme-crm-site-staging.getacme.com
      </code>
    </td>
    
    <td>
      <code>
        acme-crm-site-staging
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      <code>
        workers.dev
      </code>
    </td>
    
    <td>
      <code>
        acme-crm-web-staging.getacme.com
      </code>
    </td>
    
    <td>
      <code>
        acme-crm-web-staging
      </code>
    </td>
  </tr>
</tbody>
</table>

The slug never appears in a production hostname, so pick it for your resource list rather than for
your marketing.

### Your project lives at a subdomain

You own `example.com` and use it for other things, so this project gets `my-app.example.com`. This
is the one case where you set `PROJECT_DOMAIN` yourself.

```sh [.env.project.schema]
PROJECT_SLUG=my-app
PROJECT_DISPLAY_NAME=My App
PROJECT_DESCRIPTION="A project-planning tool for small teams."
PROJECT_ZONE=example.com
PROJECT_DOMAIN=my-app.example.com
```

<table>
<thead>
  <tr>
    <th>
      Runtime context
    </th>
    
    <th>
      Application
    </th>
    
    <th>
      Serves
    </th>
    
    <th>
      Sends mail from
    </th>
    
    <th>
      Worker name
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        apps/site
      </code>
    </td>
    
    <td>
      <code>
        my-app.example.com
      </code>
    </td>
    
    <td>
      <code>
        site.my-app.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-site-production
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        production
      </code>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      <code>
        app.my-app.example.com
      </code>
    </td>
    
    <td>
      <code>
        app.my-app.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-web-production
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        apps/site
      </code>
    </td>
    
    <td>
      <code>
        workers.dev
      </code>
    </td>
    
    <td>
      <code>
        my-app-site-staging.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-site-staging
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        staging
      </code>
    </td>
    
    <td>
      <code>
        apps/web
      </code>
    </td>
    
    <td>
      <code>
        workers.dev
      </code>
    </td>
    
    <td>
      <code>
        my-app-web-staging.example.com
      </code>
    </td>
    
    <td>
      <code>
        my-app-web-staging
      </code>
    </td>
  </tr>
</tbody>
</table>

Read the two staging rows against the two production rows. Production hangs off the **domain** and
everything else hangs off the **zone**, so your non-production senders stay flat at
`my-app-web-staging.example.com` rather than nesting another label deep.

### The two topologies that need an edit

The last two rows of the production table above — the product application deployed alone, and the
product mounted under the website — break the `app.` rule, so they're the only ones where you
replace `CLOUDFLARE_WORKER_ROUTE` in `apps/web/.env.production` by hand. For a path-scoped route, set
`CLOUDFLARE_WORKER_ROUTE_ZONE` alongside it. The sending domains still derive, and still need
onboarding.

## What you still write by hand

Project identity covers your project's names and its description. Some values stay explicit, because nothing
here can derive them correctly:

<table>
<thead>
  <tr>
    <th>
      Kind
    </th>
    
    <th>
      Examples
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Values your Cloudflare account owns
    </td>
    
    <td>
      The <code>
        workers.dev
      </code>
      
       subdomain, the origins built from it, and <code>
        CLOUDFLARE_ACCOUNT_ID
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Values registered elsewhere
    </td>
    
    <td>
      <code>
        GOOGLE_CLIENT_ID
      </code>
      
      , <code>
        GITHUB_CLIENT_ID
      </code>
    </td>
  </tr>
</tbody>
</table>

No resource id is ever one of them. Every run that deploys finds each bucket, database, and
connection pool by the name its schema derives, creates the one that's missing, and hands the build
the ids its bindings need, so the value you set once names all of them.
[Resources](https://nuxtstart.com/docs/deployment/resources) covers how.

## Next steps

- [Local setup](https://nuxtstart.com/docs/getting-started/local-setup#name-your-project) is where you set these
values, if you haven't yet.
- [Environment values](https://nuxtstart.com/docs/reference/environment-values) explains which file each value lives in
and which one wins.
- [Deploying development](https://nuxtstart.com/docs/getting-started/deploying-development) walks through the accounts
and credentials a deploy needs before any of these names reaches Cloudflare.
- [Going to production](https://nuxtstart.com/docs/getting-started/going-to-production) is where your domain and the two
production sending hostnames come into use.

## Sitemap

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