# Sanity Edition

## Sanity Edition

**Files:** `.env`, `sanity.config.ts`, `sanity/` · **Skill level:** Beginner

In the Sanity edition, your content lives in your own Sanity project and you edit it in **Sanity Studio**, an editing app that runs in your browser. The live site is still static files. The project, the content, and the Studio are all yours, and nothing in the theme connects to anyone else's account.

### A Few Words To Know
| Word             | What it means                                                                  |
| ---------------- | ------------------------------------------------------------------------------ |
| **Studio**       | The editing app. It runs at `http://localhost:3333`, and you can put it online |
| **Project**      | Your space at Sanity, in your own account                                      |
| **Dataset**      | The content database in your project. The theme uses one called `production`   |
| **Draft**        | A saved change that visitors can't see until you click **Publish**             |
| **Live preview** | The Studio view that shows your site beside the editor, with click-to-edit     |
| **Webhook**      | A message Sanity sends when you publish, such as "rebuild my site now"         |
| **Attribute**    | One distinct field path in your content. Sanity's plans limit how many you use |

### Look Around Without An Account
Run `npm ci`, then `npm run dev`, with no `.env` file. The site runs straight away with the bundled demo content, and `npm run build` works the same way, so you can try the theme before you set anything up.

### Set Up Your Project
<Steps>

1. Unzip the theme, open a terminal in its folder, and run `npm ci`.

2. Run the guided setup:

   ```bash
   npm run setup
   ```

   It logs you in to Sanity, creates or picks a project, writes your `.env` file, adds the allowed addresses, creates a read token, and offers to upload the demo content. To upload it again later, run `npm run import-seed`, which uses your own Sanity login.

3. Start the site and the Studio together:

   ```bash
   npm run dev:all
   ```

4. Open the Studio at `http://localhost:3333`, and log in with the same Sanity account.

</Steps>

### Editing And Publishing
**Content** has one entry per language, then **Site settings**. Open a document and edit it. Until you click **Publish**, your change is a draft that only you can see in the preview.

A draft shows in Live preview after a few seconds, or longer on a dev server that has just started. A plain browser tab on `http://localhost:4321` shows published content through Sanity's CDN, so a published change reaches it much later: up to about 2 minutes in our tests. Give it 3 minutes before you decide a change didn't work. A static build doesn't use that CDN, so it has the change at its next build. The first time a page opens on the dev server it takes a while to compile. Draft preview used to run the dev server out of memory after many pages. That is fixed in this edition: we measured it before and after the fix on Finzo, Consultiz, and Taskly, by reading pages in draft mode. Long editing sessions are not tested, so if the server ever stops with an out-of-memory error, start it again. If Live preview says it could not connect, wait a few seconds and press **Retry**.

Pages, posts, menus (including mega menus), the footer, site settings, and interface labels are edited in the Studio, in every language. Arabic documents edit right to left.

[What Is Editable In Sanity](../what-is-editable-sanity/) lists each thing for this theme, what stays in code, and what has been tested for it.

### Click To Edit
**Live preview** shows your site beside the editor. Click text on the page to open its field. Type, and the page shows your change shortly after. It's built to run on your computer with `npm run dev:all`. `npm run setup` asks whether to turn it on, and `SANITY_VISUAL_EDITING=true` in `.env` is the setting it writes.

### Online Preview Needs A Node Host
Static files can't show drafts. To use click-to-edit and draft preview online, such as with a Studio on `*.sanity.studio`, you need a second copy of the site running as a small **Node.js server** on a host that can run one, with HTTPS.

<Aside type="caution">
  Your static host can't do this, and Netlify and Vercel functions aren't
  supported. We have not tested any online host or a deployed Studio, so try it
  on your own host before you rely on it. What we did test varies by theme, and
  [What Is Editable In Sanity](../what-is-editable-sanity/) says what ran for
  this one.
</Aside>

To build and start the preview server on your Node host, with your `.env` beside it and `HOST` and `PORT` set:

```bash
npm run build:preview
npm run start:preview
```

Then set `SANITY_STUDIO_PREVIEW_URL` to the server's HTTPS address before you run `npm run studio:deploy`, and add the address under CORS origins in your Sanity project.

Without a preview server, editors online can still edit in the Studio's forms and publish. They just don't see the page beside the form.

### Environment Variables
`.env.example` lists every variable, and `npm run setup` fills in the main ones.

| Variable                    | Secret? | What it does                                                                     |
| --------------------------- | ------- | -------------------------------------------------------------------------------- |
| `PUBLIC_SANITY_PROJECT_ID`  | No      | Your project. Empty means the site uses the demo content                         |
| `PUBLIC_SANITY_DATASET`     | No      | The dataset to read                                                              |
| `PUBLIC_SANITY_STUDIO_URL`  | No      | Where your Studio runs                                                           |
| `SITE_URL`                  | No      | Your site's address. It wins over the Base URL in Site settings                  |
| `SITE_PORT`, `STUDIO_PORT`  | No      | Local ports. The defaults are 4321 and 3333. `npm run setup` keeps ports you set, and a plain local address follows them |
| `SANITY_API_READ_TOKEN`     | **Yes** | A read token used only to preview drafts. Never set it on your static host       |
| `SANITY_VISUAL_EDITING`     | No      | `true` lets the local and preview servers show drafts and click-to-edit. Don't set it on your static host |
| `SANITY_STUDIO_PROJECT_ID`  | No      | The same project, for the Studio                                                 |
| `SANITY_STUDIO_DATASET`     | No      | The same dataset, for the Studio                                                 |
| `SANITY_STUDIO_PREVIEW_URL` | No      | The site or preview server the Studio shows beside the editor                    |
| `SANITY_STUDIO_HOSTNAME`    | No      | The address of a Studio online: `https://<this>.sanity.studio`                   |

`.env` is ignored by Git. `npm run build` always makes the normal static site.

### Publish The Site
<Steps>

1. Deploy the site to a static host, and set `PUBLIC_SANITY_PROJECT_ID` and `PUBLIC_SANITY_DATASET` in its settings, plus `PUBLIC_SANITY_STUDIO_URL` once your Studio is online. See [Deployment](../../deployment/).

2. A static site doesn't change until it is rebuilt. After you publish in the Studio, run `npm run build` and upload, or use your host's rebuild button.

3. To rebuild on every publish, create a **build hook** on your host, then add a webhook in your Sanity project's settings, under **API**, that sends to it. We have not tested a webhook on any host, so publish a small change and check that a rebuild starts.

</Steps>

To put the Studio online, so editors don't need to run anything, run:

```bash
npm run studio:deploy
```

We have not tested a deployed Studio. Add its address under CORS origins in your Sanity project, and invite other editors under **Members** at [sanity.io/manage](https://www.sanity.io/manage). After the trial, the free plan needs each of them to be an Administrator: see [The Free Trial](#the-free-trial).

**Site settings** apply when the site builds. While `npm run dev:all` runs, they apply when you publish them, and they don't change as you type.

### Images
Images you upload load from Sanity's image CDN, and they count towards your plan's bandwidth. Your visitors don't contact Sanity for anything else.

### Plans And Limits
You use your own free Sanity account. At the time of writing, the free plan allows 2,000 attributes, one for each distinct field path in your content. [What Is Editable In Sanity](../what-is-editable-sanity/) says how many this theme's demo content uses. New fields use more attributes. See [Sanity's pricing](https://www.sanity.io/pricing) for current limits.

### The Free Trial
Sanity starts every new project on a free trial of paid features, with no card needed. The Studio shows a "You got a free upgrade!" popover at the top right. It can take clicks meant for the form beneath it until you press **Got it**. If you do nothing, the project moves to the free plan when the trial ends, and you aren't charged. Sanity's page says the trial has the same 2,000 attribute limit as the free plan.

When the trial ends, you lose Comments, Tasks, Scheduled drafts, AI Assist, and the extra roles. Document history on the free plan goes back 3 days. Nothing this theme needs relies on those features, and Sanity lists Live preview on the free plan.

<Aside type="caution">
  On the free plan, everyone who edits must be an Administrator, which also
  gives access to the project's settings. Anyone invited with another role
  becomes a Viewer and can no longer edit.
</Aside>

We ran our tests during the trial, and we have not seen a project after its trial ended. So try one edit when yours ends. See [Sanity's trial page](https://www.sanity.io/docs/platform-management/growth-plan-trial) for what is current.

### What Stays In Code
Design and structure stay in the project, not the Studio, such as the language list in `src/config/language.json`, colors, fonts, and the components themselves. Change these in your code editor, then rebuild. [What Is Editable In Sanity](../what-is-editable-sanity/) has the exact list.

<Aside type="note">
  Other pages in these docs list content files in their **Files:** line. In this
  edition, most of that content is edited in the Studio instead.
</Aside>

### Troubleshooting
| What you see                                    | What to do                                                                                             |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| The site shows demo content                     | `PUBLIC_SANITY_PROJECT_ID` is empty. Run `npm run setup`, or set it on your host                       |
| A published change isn't on the live site       | The site must rebuild to show changes. Rebuild it, or check your webhook and the deploy log on your host |
| The Studio can't connect, or shows a CORS error | Add the Studio's or site's address to CORS origins at [sanity.io/manage](https://www.sanity.io/manage) |
| Live preview says it could not connect          | Wait a few seconds and press **Retry**. Check `SANITY_STUDIO_PREVIEW_URL`, and that the site is running |

### Do It With AI
```text
Add a field called [FIELD] to [SECTION] in the Sanity edition. Follow the "Add a field" skill in
SKILLS.md. Use stegaClean if the value drives logic instead of being shown as text. Don't print or
change anything in .env. Then run npm run sanity:validate and npm run astro-check and tell me the
results.
```