Sanity CMS Integration

Some Lexington themes are available with Sanity CMS integration. These variants ship as a monorepo with both your Astro website and a fully configured Sanity Studio, giving content editors a visual editing experience while developers keep the speed and flexibility of Astro.

Two Ways to Use Your Theme

Sanity-enabled themes support two data sources — choose what works best for you:

Option A: Content Collections (No CMS Required)

Use markdown files in apps/web/src/content/. Perfect for:

Quick setup with no external services
Git-based content workflow
Developers comfortable editing markdown

Option B: Sanity CMS (Recommended for Clients)

Use Sanity Studio for a visual editing experience. Perfect for:

Non-technical content editors
Teams collaborating on content
Dynamic content updates without code changes

By default, the theme uses Content Collections. Follow the instructions below to switch to Sanity.

Quick Start (Content Collections)

If you just want to get started without Sanity:

# Install dependencies
pnpm install

# Start the website
pnpm dev:web

Open http://localhost:4321 — your site is ready with sample content!

Edit content in apps/web/src/content/ — the exact folders depend on your theme.

Getting Started with Sanity

Prerequisites

Node.js 18+ — Download here
pnpm — Install with npm install -g pnpm
Sanity account — Free at sanity.io

Step 1: Install Dependencies

pnpm install

Step 2: Create Your Sanity Project

Go to sanity.io/manage
Sign up or log in
Click “Create project”
Give it a name (e.g., “My Website”)
Choose the Free plan
Create a dataset named production
Copy your Project ID (you’ll need this next)

Step 3: Set Up Environment Variables

For the website — Create apps/web/.env:

cp apps/web/.env.example apps/web/.env

Open apps/web/.env and add your Project ID:

SANITY_PROJECT_ID=your-project-id-here
SANITY_DATASET=production
SANITY_API_VERSION=2024-01-01

For the CMS — Create apps/studio/.env:

cp apps/studio/.env.example apps/studio/.env

Open apps/studio/.env and add the same Project ID:

SANITY_STUDIO_PROJECT_ID=your-project-id-here
SANITY_STUDIO_DATASET=production

Step 4: Enable Sanity Mode

Open apps/web/src/lib/data.ts and change:

export const USE_SANITY = true;

Step 5: Migrate Your Content (Optional)

Want to use the existing sample content? Run the migration script:

Get a Sanity API token:
- Go to sanity.io/manage → Your Project → API
- Click “Add API token”
- Name it “Migration” with Editor permissions
- Copy the token
Run the migration:

cd scripts
SANITY_TOKEN=your-token-here npx tsx migrate-to-sanity.ts

The script automatically reads SANITY_PROJECT_ID from apps/web/.env.

This uploads all content from apps/web/src/content/ to your Sanity project, including images.

Step 6: Start Development

pnpm dev

This starts:

Website → http://localhost:4321
Sanity Studio (CMS) → http://localhost:3333

Step 7: Add Content in Studio

Go to http://localhost:3333
Create or edit content
Click Publish so updates show up on http://localhost:4321

Switching Between Data Sources

The USE_SANITY flag in apps/web/src/lib/data.ts controls the data source:

// Use Sanity CMS
export const USE_SANITY = true;

// Use Content Collections (markdown files)
export const USE_SANITY = false;

Both options use the same components and layouts — just different data sources.

Project Structure

/
├── apps/
│   ├── web/              # Your Astro website
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── layouts/
│   │   │   ├── lib/sanity/  # Sanity integration
│   │   │   ├── pages/
│   │   │   └── styles/
│   │   └── .env.example
│   │
│   └── studio/           # Sanity CMS
│       ├── schemas/      # Content models
│       └── .env.example
│
├── scripts/              # Utility scripts (migrations, cleanup)
├── pnpm-workspace.yaml
└── package.json

Deployment

Deploy the Website

Vercel (recommended):

cd apps/web
npx vercel

Netlify:

cd apps/web
npx netlify deploy --prod

Add these environment variables in your hosting dashboard:

SANITY_PROJECT_ID
SANITY_DATASET
SANITY_API_VERSION

Deploy the CMS

Deploy to Sanity’s free hosting:

cd apps/studio
pnpm deploy

You’ll get a URL like https://your-project.sanity.studio

Customization

Styling

Edit apps/web/src/styles/global.css for global styles. Lexington themes use Tailwind CSS v4.

Adding New Content Types

Create schema in apps/studio/schemas/
Register in apps/studio/schemas/index.ts
Add to apps/studio/structure.ts
Create query in apps/web/src/lib/sanity/queries.ts
Add types in apps/web/src/lib/sanity/types.ts

Troubleshooting

”Cannot find module” errors?

Run pnpm install in the project root to reinstall dependencies.

Content not showing?

Make sure you clicked “Publish” in Sanity Studio
Check that your Project ID is correct in both .env files
Verify your dataset name matches (default: production)

“Failed to fetch” error?

Your Project ID might be wrong
Go to sanity.io/manage and verify the ID

Images not loading?

Images must be uploaded directly to Sanity
Check that your image fields have the required asset data

CORS errors?

Go to sanity.io/manage → Your Project → API → CORS Origins
Add http://localhost:4321 for development
Add your production URL for deployment

Useful Commands

Command	Description
`pnpm install`	Install all dependencies
`pnpm dev`	Start website + CMS
`pnpm dev:web`	Start website only
`pnpm dev:studio`	Start CMS only
`pnpm build`	Build both for production
`pnpm clean`	Remove node_modules/.env/dist before packaging