| Understand entity architecture |
Entity Architecture Fundamentals |
When starting any Drupal entity or field development work, you need to understand the two-layer architecture that separates configuration from content and how entity types relate to bundles. |
| Create a content type via config |
Content Type Configuration |
When creating content types via configuration management (YAML files) for deployment across environments, or when exporting existing content types for version control. |
| Build a custom bundle entity |
Bundle Entity Implementation |
When building custom content entity types that need bundle support (multiple subtypes with different field configurations), requiring programmatic bundle creation or custom bundle behavior. |
| Add base fields to entities |
Base Field Definitions |
When adding fields that exist on ALL bundles of an entity type (e.g., title on all nodes, uid on all content), or creating non-configurable fields that store critical entity data. |
| Choose the right field type |
Field Type Selection |
When adding fields to content types or entities, you must choose the appropriate field type that matches your data structure and validation requirements. |
| Create field storage config |
Field Storage Configuration |
When creating fields that can be reused across multiple bundles, defining the technical specifications (data type, cardinality, storage schema) independent of bundle-specific settings. |
| Configure field instances |
Field Instance Configuration |
When attaching a field storage to a specific bundle with bundle-specific settings (label, description, required status, default values, widget/formatter settings). |
| Build custom field types |
Custom Field Type Development |
When core field types don't meet your data structure needs, requiring custom storage schema, validation, or business logic for a specific data pattern. |
| Develop field widgets |
Field Widget Development |
When creating custom input interfaces for field types in entity forms, requiring specialized UI controls beyond core textfields/selects/checkboxes. |
| Create field formatters |
Field Formatter Development |
When creating custom display output for field values in view modes, requiring specialized rendering beyond core label/plain text formatters. |
| Configure form displays |
Form Display Configuration |
When controlling how fields appear in entity edit forms, including widget selection, field order, and visibility across different form modes. |
| Configure view displays |
View Display Configuration |
When controlling how fields appear in entity view modes (full, teaser, RSS, etc.), including formatter selection, label display, and field visibility. |
| Create custom view modes |
View Mode Development |
When creating custom display contexts beyond default/teaser (e.g., 'card', 'embed', 'json_api'), requiring entity-specific formatter configurations. |
| Work with entity references |
Entity Reference Patterns |
When creating relationships between entities (nodes ↔ taxonomy, nodes ↔ users, nodes ↔ nodes), requiring referential integrity and access-controlled relationships. |
| Handle file/image fields |
File and Image Field Patterns |
When handling file uploads (documents, images, media) requiring file validation, storage organization, and derivative generation. |
| Implement computed fields |
Computed Field Patterns |
When creating virtual/derived fields that calculate values from other fields without storing data, requiring dynamic values that update when dependencies change. |
| Use entity query API |
Entity Query Patterns |
When querying entities by field values, properties, or relationships, requiring performant database queries with access control and cache invalidation. |
| Secure field access |
Field Access Control |
When restricting field visibility or editability based on user permissions, entity state, or custom business logic, requiring fine-grained access control beyond entity-level permissions. |
| Optimize entity queries |
Entity Query Performance |
When optimizing entity queries for large datasets, high-traffic scenarios, or complex filtering requirements, requiring careful query construction and caching. |
| Validate field data |
Field Validation Patterns |
When enforcing data integrity constraints on field values, requiring validation beyond basic required/max_length checks, ensuring data quality and business rule compliance. |