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

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

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

2. Run the guided setup:

   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:

   npm run dev:all

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

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

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

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.

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

Publish The Site

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.

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.

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

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. After the trial, the free plan needs each of them to be an Administrator: see 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 says how many this theme’s demo content uses. New fields use more attributes. See Sanity’s 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.

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 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 has the exact list.

Troubleshooting

Do It With AI

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.