Browse Rules

# Sanity Development Guidelines ## Sanity Schema Rules When 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. ### Basic Schema Structure For TypeScript files, always import the necessary Sanity types: ```typescript import {defineField, defineType, defineArrayMember} from 'sanity' ``` Always use `defineField` on every field and `defineType` throughout the whole type. Only import `defineArrayMember` if needed: ```typescript defineType({ type: 'object', name: 'custom-object', fields: [ defineField({ type: 'array', name: 'arrayField', title: 'Things', of: [ defineArrayMember({ type: 'object', name: 'type-name-in-array', fields: [defineField({type: 'string', name: 'title', title: 'Title'})], }), ], }), ], }) ``` ### Adding icons When 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. ### Structuring files and folders This 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. │ ├── studio/ │ │ ├── README.md │ │ ├── eslint.config.mjs │ │ ├── location.ts │ │ ├── package.json │ │ ├── prettier.config.mjs │ │ ├── sanity-typegen.json │ │ ├── sanity.cli.ts │ │ ├── sanity.config.ts │ │ ├── schema.json │ │ ├── structure.ts │ │ ├── tsconfig.json │ │ ├── .env.example │ │ ├── .gitignore │ │ ├── components/ │ │ │ ├── logo.tsx │ │ │ └── slug-field-component.tsx │ │ ├── plugins/ │ │ │ └── presentation-url.ts │ │ ├── schemaTypes/ │ │ │ ├── common.ts │ │ │ ├── index.ts │ │ │ ├── blocks/ │ │ │ │ ├── cta.ts │ │ │ │ ├── faq-accordion.ts │ │ │ │ ├── feature-cards-icon.ts │ │ │ │ ├── hero.ts │ │ │ │ ├── image-link-cards.ts │ │ │ │ ├── index.ts │ │ │ │ └── subscribe-newsletter.ts │ │ │ ├── definitions/ │ │ │ │ ├── button.ts │ │ │ │ ├── custom-url.ts │ │ │ │ ├── index.ts │ │ │ │ ├── pagebuilder.ts │ │ │ │ └── rich-text.ts │ │ │ └── documents/ │ │ │ ├── author.ts │ │ │ ├── blog.ts │ │ │ ├── faq.ts │ │ │ └── page.ts │ │ └── utils/ │ │ ├── const-mock-data.ts │ │ ├── constant.ts │ │ ├── helper.ts │ │ ├── mock-data.ts │ │ ├── og-fields.ts │ │ ├── parse-body.ts │ │ ├── seo-fields.ts │ │ ├── slug.ts │ │ └── types.ts ### Layout of page builder index example This 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 root ```typescript import { callToAction } from './call-to-action'; import { exploreHero } from './explore-hero'; import { faqList } from './faq-list'; import { htmlEmbed } from './html-embed'; import { iconGrid } from './icon-grid'; import { latestDocs } from './latest-docs'; import { calculator } from './calculator'; import { navigationCards } from './navigation-cards'; import { quinstreetEmbed } from './quinstreet-embed'; import { quote } from './quote'; import { richTextBlock } from './rich-text-block'; import { socialProof } from './social-proof'; import { splitForm } from './split-form'; import { statsCard } from './stats-card'; import { trustCard } from './trust-card'; import { rvEmbed } from './rv-embed'; export const pagebuilderBlocks = [ navigationCards, socialProof, quote, latestDocs, faqList, callToAction, trustCard, quinstreetEmbed, statsCard, iconGrid, exploreHero, splitForm, richTextBlock, calculator, htmlEmbed, rvEmbed, ]; export const blocks = [...pagebuilderBlocks]; ``` ### Common Field Templates When 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. Use these templates when implementing common fields: #### Eyebrow ```typescript defineField({ name: 'eyebrow', title: 'Eyebrow', description: 'The smaller text that sits above the title to provide context', type: 'string', }) ``` #### Title ```typescript defineField({ name: 'title', title: 'Title', description: 'The large text that is the primary focus of the block', type: 'string', }) ``` #### Heading Level Toggle ```typescript defineField({ name: 'isHeadingOne', title: 'Is it a <h1>?', type: 'boolean', description: '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', initialValue: false, }) ``` #### Rich Text ```typescript defineField({ name: 'richText', title: 'Rich Text', description: 'Large body of text that has links, ordered/unordered lists and headings.', type: 'richText', }) ``` #### Buttons ```typescript defineField({ name: 'buttons', title: 'Buttons', description: 'Add buttons here, the website will handle the styling', type: 'array', of: [{type: 'button'}], }) ``` #### Image ```typescript defineField({ name: 'image', title: 'Image', type: 'image', fields: [ defineField({ name: 'alt', type: 'string', description: "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", title: 'Alt Text', }), ], }) ``` ### Type Generation After adding new Sanity schema, run the type command to generate TypeScript definitions: ```bash sanity schema extract && sanity typegen generate --enforce-required-fields ``` ## GROQ Rules Whenever there is an image within a GROQ query, do not expand it unless explicitly instructed to do so. ## GROQ Query Structure and Organization - Import `defineQuery` and `groq` from `next-sanity` at the top of query files - Export queries as constants using the `defineQuery` function - Organize queries by content type (blogs, pages, products, etc.) - Group related queries together ### Naming Conventions - Use camelCase for all query names - Prefix query names with action verb (get, getAll, etc.) followed by content type - Suffix all queries with "Query" (e.g., `getAllBlogIndexTranslationsQuery`) - Prefix reusable fragments with underscore (e.g., `_richText`, `_buttons`) ### Fragment Reuse - Define common projection fragments at the top of the file - Create reusable fragments for repeated patterns (e.g., `_richText`, `_buttons`, `_icon`) - Use string interpolation to include fragments in queries - Ensure fragments are composable and focused on specific use cases ### Query Parameters - Use `$` for parameters (e.g., `$slug`, `$locale`, `$id`) - Handle localization with consistent patterns (e.g., `${localeMatch}`) - Use `select()` for conditional logic within queries - Define default parameters using `coalesce()` ### Response Types - Export TypeScript interfaces for query responses when needed - Use descriptive types that match the query structure - Follow the pattern: `export type GetAllMainPageTranslationsQueryResponse = string[];` ### Best Practices - Use explicit filtering (`_type == "x"`) rather than implicit type checking - Prefer projection over returning entire documents - Use `order()` for explicit sorting rather than relying on document order - Check for defined fields (`defined(field)`) before accessing them - Use conditional projections for optional fields - Add pagination parameters (`[$start...$end]`) for list queries ### Code Style - Use template literals for query strings - Indent nested query structures for readability - Keep related query parts together - Maintain consistent whitespace and indentation - Use comments to explain complex query logic ## File Naming Conventions - Use kebab-case for ALL file names - ✅ CORRECT: `user-profile.tsx`, `auth-layout.tsx`, `api-utils.ts` - ❌ INCORRECT: `userProfile.tsx`, `AuthLayout.tsx`, `apiUtils.ts` - MUST use `.tsx` extension for React components - MUST use `.ts` extension for utility files - MUST use lowercase for all file names - MUST separate words with hyphens - MUST NOT use spaces or underscores ## Screenshot Rules When asked to produce schema from screenshots, follow these guidelines: - Help describe types and interfaces using the provided image - Use the Sanity schema format shown above - Always include descriptions based on the visual elements in the image ### Visual Cues - Tiny text above a title is likely an **eyebrow** - Large text without formatting that looks like a header should be a **title** or **subtitle** - Text with formatting (bold, italic, lists) likely needs **richText** - Images should include **alt text** fields - Background images should be handled appropriately - Use reusable button arrays for button patterns - If `richTextField` or `buttonsField` exists in the project, use them

# Drupal 10 Module Development Rules You are an expert Drupal 10 developer with deep knowledge of PHP 8+, object-oriented programming, and SOLID principles. Your role is to provide technically precise guidance for module development that follows Drupal coding standards and best practices. Draw from your extensive experience with Drupal's API, entity system, service container, and plugin architecture to create clean, maintainable code. Prioritize security, performance, and scalability while suggesting modern PHP features when appropriate. Your recommendations should always align with Drupal's architectural patterns and community-endorsed approaches, leveraging proper dependency injection, type hinting, and comprehensive documentation through PHPDoc blocks. ## Core Principles - Write concise, technically accurate PHP code with proper Drupal API examples - Follow SOLID principles for object-oriented programming - Write maintainable code that follows the DRY (Don't Repeat Yourself) principle by extracting repeated logic into reusable functions, methods, or classes with clear responsibilities. - Adhere to Drupal coding standards and best practices - Design for maintainability and integration with other Drupal modules - Use consistent naming conventions that follow Drupal patterns - Leverage Drupal's service container and plugin system ## Dependencies - PHP 8.1+ - Drupal 10.x - Composer for dependency management ## PHP Standards - Use PHP 8.1+ features when appropriate (typed properties, match expressions, etc.) - Follow Drupal's PHP coding standards (based on PSR-12 with modifications) - Always use strict typing: `declare(strict_types=1);` - Implement proper error handling with try-catch blocks and Drupal's logging system - Use type hints for method parameters and return types ## Drupal Best Practices - Use Drupal's database API instead of raw SQL queries - Implement the Repository pattern for data access logic - Utilize Drupal's service container for dependency injection - Leverage Drupal's caching API for performance optimization - Use Drupal's Queue API for background processing - Implement comprehensive testing using PHPUnit and Drupal's testing framework - Follow Drupal's configuration management system for module settings - Use Drupal's entity system and Field API when appropriate - Implement proper hook implementations following Drupal naming conventions - Use Drupal's Form API for handling user input with proper validation - Always align array item assignment operator (`=>`) in multi-line array item declarations - Always align variable assignment operators (`=`) in variables defined in a sequence line after line ## Code Architecture - **Naming Conventions**: - Follow Drupal's naming patterns for files, classes, and methods - Use PSR-4 autoloading and namespace structure - Prefix custom services and plugins with module name - **Controller Design**: - Controllers should be final classes to prevent inheritance - Use dependency injection via the service container - Keep controllers thin, moving business logic to services - **Entity Design**: - Extend Drupal's entity classes following its class hierarchy - Use proper annotations for entity and field definitions - **Services**: - Create module services using proper dependency injection - Register services in the module's services.yml file - Keep services focused on single responsibility - **Routing**: - Define routes in module.routing.yml following Drupal conventions - Use proper access checks and permissions - **Type Declarations**: - Always use explicit return type declarations - Use appropriate PHP type hints for method parameters - Document complex types in PHPDoc blocks - **PHPDoc Blocks**: - Provide complete documentation for classes, methods, and properties - Document parameters with correct types and descriptions - Include `@return`, `@throws`, and `@deprecated` tags as needed - Document hook implementations with `@see` references ## Drupal-Specific Standards - Use hook_schema() for database table definitions - Implement update hooks for schema changes - Use proper Drupal Events instead of procedural hooks when possible - Implement proper form validation and submission handlers - Use Drupal's translation system (t(), TranslatableMarkup) for user-facing strings - Follow Drupal's security practices (sanitization, CSRF protection) - Use Drupal's configuration system for module settings