Let's give you a quick guide on how and why we use Cursor .mdc rules. If you don't know what .mdc stands for, well...neither do we. But if I had to hazard a guess, I'd say it's probably Misguided Decisions & Chaos.
Moving quickly on from the Dad joke, I'm going to talk about why the rules are important, the specific things that this rule does, and why we would advise heavily tweaking it to your own preferences.
Schema layout
We have a very rigid way of building schema because, in most situations, you don't want to be debugging a large website project with one giant index file with 300+ schema types imported. That's why we have pre-determined patterns for adding indexes and spread operators on a folder-by-folder level.
This way, it becomes far easier to debug at scale and quickly include new schemas from within the same folder. The only trip hazard with this is that if you do not update the import in the index, you will not see your page builder block, so please be aware of this.
Typesafety
You'll notice a recurring theme in the way we build our Sanity websites... We hate having to manually type interfaces. We want to make as much typescript automated as physically possible, and for that reason, you'll notice it's heavily embedded within our .mdc file as well. Ultimately, you're making it easier for yourself in the long run, and the more you can automate, the easier you can scale.
Predefined schema
You may also notice there are a couple of predefined schema titles, names and types. There's a good reason for this. Usually, we're not the biggest fan of the DRY (Don't Repeat Yourself) way of coding. Purely because we find it's very easy to create spaghetti code when one requirement's goalposts inevitably shift and mutate content.
However, you will notice we regularly recycle the same naming conventions on different blocks. This helps to reuse Tailwindcss and ultimately increases your development momentum.
Image recognition
Finally, there's a real advantage to screenshot wireframes within Figma and get a rough draft for your schema. That's why we included some standardisation that correlates the point above of matching certain UI layouts with certain schema types to ensure you create consistent, user-friendly fields with descriptions and icons.
The rules themselves
markdown1# Sanity Development Guidelines23## Sanity Schema Rules45When creating sanity schema make sure to include an appropriate icon for the schema using lucide-react or sanity icons as a fallback. Make sure it's always a named export, make sure you're always using the Sanity typescript definitions if it's a ts file.67### Basic Schema Structure89For TypeScript files, always import the necessary Sanity types:1011```typescript12import {defineField, defineType, defineArrayMember} from 'sanity'13```1415Always use `defineField` on every field and `defineType` throughout the whole type. Only import `defineArrayMember` if needed:1617```typescript18defineType({19 type: 'object',20 name: 'custom-object',21 fields: [22 defineField({23 type: 'array',24 name: 'arrayField',25 title: 'Things',26 of: [27 defineArrayMember({28 type: 'object',29 name: 'type-name-in-array',30 fields: [defineField({type: 'string', name: 'title', title: 'Title'})],31 }),32 ],33 }),34 ],35})36```3738### Adding icons3940When adding icons to a schema, make sure you use the default sanity/icons first, and then if no icon is relevant, refer to any other iconset the user has installed - e.g lucide-react.4142### Structuring files and folders4344This is a rough idea of how to structure folders and files, ensuring you always have an index within the folder to create an array of documents/blocks. Do not use these as exact names, it's used purely for layout purposes.4546 │ ├── studio/47 │ │ ├── README.md48 │ │ ├── eslint.config.mjs49 │ │ ├── location.ts50 │ │ ├── package.json51 │ │ ├── prettier.config.mjs52 │ │ ├── sanity-typegen.json53 │ │ ├── sanity.cli.ts54 │ │ ├── sanity.config.ts55 │ │ ├── schema.json56 │ │ ├── structure.ts57 │ │ ├── tsconfig.json58 │ │ ├── .env.example59 │ │ ├── .gitignore60 │ │ ├── components/61 │ │ │ ├── logo.tsx62 │ │ │ └── slug-field-component.tsx63 │ │ ├── plugins/64 │ │ │ └── presentation-url.ts65 │ │ ├── schemaTypes/66 │ │ │ ├── common.ts67 │ │ │ ├── index.ts68 │ │ │ ├── blocks/69 │ │ │ │ ├── cta.ts70 │ │ │ │ ├── faq-accordion.ts71 │ │ │ │ ├── feature-cards-icon.ts72 │ │ │ │ ├── hero.ts73 │ │ │ │ ├── image-link-cards.ts74 │ │ │ │ ├── index.ts75 │ │ │ │ └── subscribe-newsletter.ts76 │ │ │ ├── definitions/77 │ │ │ │ ├── button.ts78 │ │ │ │ ├── custom-url.ts79 │ │ │ │ ├── index.ts80 │ │ │ │ ├── pagebuilder.ts81 │ │ │ │ └── rich-text.ts82 │ │ │ └── documents/83 │ │ │ ├── author.ts84 │ │ │ ├── blog.ts85 │ │ │ ├── faq.ts86 │ │ │ └── page.ts87 │ │ └── utils/88 │ │ ├── const-mock-data.ts89 │ │ ├── constant.ts90 │ │ ├── helper.ts91 │ │ ├── mock-data.ts92 │ │ ├── og-fields.ts93 │ │ ├── parse-body.ts94 │ │ ├── seo-fields.ts95 │ │ ├── slug.ts96 │ │ └── types.ts9798### Layout of page builder index example99100This is an example of how the blocks index file would be structured, you would create multiple of these on multiple nested routes to make it easier to create an array of files at each level, rather than bundling a large number of imports in a singular index.ts on the root101102```typescript103import { callToAction } from './call-to-action';104import { exploreHero } from './explore-hero';105import { faqList } from './faq-list';106import { htmlEmbed } from './html-embed';107import { iconGrid } from './icon-grid';108import { latestDocs } from './latest-docs';109import { calculator } from './calculator';110import { navigationCards } from './navigation-cards';111import { quinstreetEmbed } from './quinstreet-embed';112import { quote } from './quote';113import { richTextBlock } from './rich-text-block';114import { socialProof } from './social-proof';115import { splitForm } from './split-form';116import { statsCard } from './stats-card';117import { trustCard } from './trust-card';118import { rvEmbed } from './rv-embed';119120export const pagebuilderBlocks = [121 navigationCards,122 socialProof,123 quote,124 latestDocs,125 faqList,126 callToAction,127 trustCard,128 quinstreetEmbed,129 statsCard,130 iconGrid,131 exploreHero,132 splitForm,133 richTextBlock,134 calculator,135 htmlEmbed,136 rvEmbed,137];138139export const blocks = [...pagebuilderBlocks];140```141142### Common Field Templates143144When writing any Sanity schema, always include a description, name, title, and type. The description should explain functionality in simple terms for non-technical users. Place description above type.145146Use these templates when implementing common fields:147148#### Eyebrow149```typescript150defineField({151 name: 'eyebrow',152 title: 'Eyebrow',153 description: 'The smaller text that sits above the title to provide context',154 type: 'string',155})156```157158#### Title159```typescript160defineField({161 name: 'title',162 title: 'Title',163 description: 'The large text that is the primary focus of the block',164 type: 'string',165})166```167168#### Heading Level Toggle169```typescript170defineField({171 name: 'isHeadingOne',172 title: 'Is it a <h1>?',173 type: 'boolean',174 description:175 'By default the title is a <h2> tag. If you use this as the top block on the page, you can toggle this on to make it a <h1> instead',176 initialValue: false,177})178```179180#### Rich Text181```typescript182defineField({183 name: 'richText',184 title: 'Rich Text',185 description: 'Large body of text that has links, ordered/unordered lists and headings.',186 type: 'richText',187})188```189190#### Buttons191```typescript192defineField({193 name: 'buttons',194 title: 'Buttons',195 description: 'Add buttons here, the website will handle the styling',196 type: 'array',197 of: [{type: 'button'}],198})199```200201#### Image202```typescript203defineField({204 name: 'image',205 title: 'Image',206 type: 'image',207 fields: [208 defineField({209 name: 'alt',210 type: 'string',211 description:212 "Remember to use alt text for people to be able to read what is happening in the image if they are using a screen reader, it's also important for SEO",213 title: 'Alt Text',214 }),215 ],216})217```218219### Type Generation220221After adding new Sanity schema, run the type command to generate TypeScript definitions:222223```bash224sanity schema extract && sanity typegen generate --enforce-required-fields225```226227## GROQ Rules228229Whenever there is an image within a GROQ query, do not expand it unless explicitly instructed to do so.230231232## GROQ Query Structure and Organization233234- Import `defineQuery` and `groq` from `next-sanity` at the top of query files235- Export queries as constants using the `defineQuery` function236- Organize queries by content type (blogs, pages, products, etc.)237- Group related queries together238239### Naming Conventions240241- Use camelCase for all query names242- Prefix query names with action verb (get, getAll, etc.) followed by content type243- Suffix all queries with "Query" (e.g., `getAllBlogIndexTranslationsQuery`)244- Prefix reusable fragments with underscore (e.g., `_richText`, `_buttons`)245246### Fragment Reuse247248- Define common projection fragments at the top of the file249- Create reusable fragments for repeated patterns (e.g., `_richText`, `_buttons`, `_icon`)250- Use string interpolation to include fragments in queries251- Ensure fragments are composable and focused on specific use cases252253### Query Parameters254255- Use `$` for parameters (e.g., `$slug`, `$locale`, `$id`)256- Handle localization with consistent patterns (e.g., `${localeMatch}`)257- Use `select()` for conditional logic within queries258- Define default parameters using `coalesce()`259260### Response Types261262- Export TypeScript interfaces for query responses when needed263- Use descriptive types that match the query structure264- Follow the pattern: `export type GetAllMainPageTranslationsQueryResponse = string[];`265266### Best Practices267268- Use explicit filtering (`_type == "x"`) rather than implicit type checking269- Prefer projection over returning entire documents270- Use `order()` for explicit sorting rather than relying on document order271- Check for defined fields (`defined(field)`) before accessing them272- Use conditional projections for optional fields273- Add pagination parameters (`[$start...$end]`) for list queries274275### Code Style276277- Use template literals for query strings278- Indent nested query structures for readability279- Keep related query parts together280- Maintain consistent whitespace and indentation281- Use comments to explain complex query logic282283284## File Naming Conventions285286- Use kebab-case for ALL file names287 - ✅ CORRECT: `user-profile.tsx`, `auth-layout.tsx`, `api-utils.ts`288 - ❌ INCORRECT: `userProfile.tsx`, `AuthLayout.tsx`, `apiUtils.ts`289- MUST use `.tsx` extension for React components290- MUST use `.ts` extension for utility files291- MUST use lowercase for all file names292- MUST separate words with hyphens293- MUST NOT use spaces or underscores294295## Screenshot Rules296297When asked to produce schema from screenshots, follow these guidelines:298299- Help describe types and interfaces using the provided image300- Use the Sanity schema format shown above301- Always include descriptions based on the visual elements in the image302303### Visual Cues304305- Tiny text above a title is likely an **eyebrow**306- Large text without formatting that looks like a header should be a **title** or **subtitle**307- Text with formatting (bold, italic, lists) likely needs **richText**308- Images should include **alt text** fields309- Background images should be handled appropriately310- Use reusable button arrays for button patterns311- If `richTextField` or `buttonsField` exists in the project, use them312
Do your homework
Naturally, this .mdc file is very specific to our way of building Next.js and Sanity websites. We want you to take this ruleset and chop and change it to exactly the way you develop websites.
I would highly recommend seeing how we do it with our own open-source Turbo Start Sanity. The crux of our opinionation happens in the Sanity queries file. It's primarily around reusability in queries, especially when it comes to page builders. Inside of these, we want to nest things like rich text but don't necessarily want to figure out how to resolve internal links three blocks deep. That's where our query structure comes into play.
If you're new to Sanity and want something a little more chilled-out, we would highly recommend starting with Sanity Learn. When you're finished with that, we recommend reading Simeon's - Opinionated Guide to Sanity Studio.
