Developer Documentation

Welcome to the React / Next.js DatoCMS Starter

This starter template demonstrates how to seamlessly connect a DatoCMS backend to a Next.js frontend using the Headless.li middleware. This stack provides a typed, schema-aware bridge between your content and your components.

1. Getting Started: The .env File

To connect this app to your own DatoCMS instance, you only need to configure your DATO_BEARER_TOKEN environment variable with your DatoCMS API token.

• →DATO_BEARER_TOKEN: (Required) Your API Read-only token. Find this in DatoCMS under Settings > API Tokens.

2. The Infrastructure Stack

This starter uses a streamlined cloud-first architecture:

• →DatoCMS: Acts as your "Single Source of Truth" for content, assets, and SEO metadata.
• →Headless.li Middleware: Acts as a typed orchestrator. It performs an introspection of your DatoCMS schema and provides a cleaned "Tree" of data to your frontend.
• →Next.js Frontend: Renders the data using the QueenofheartsRenderComponent, which maps backend records to your local React components.

3. DatoCMS Development Quirks

Professional Headless CMSs have specific behaviors that impact how you write your code. Keep these three rules in mind:

• →The "Record" Suffix: DatoCMS appends Record to every model API ID. When registering components in src/registerComponents.ts, you must use this name (e.g., HeroRecord, PageRecord).
• →Lowercase Mapping: The GraphQL schema often normalizes field names to lowercase. If you defined buttonLabel in the admin dashboard, it will arrive at your component as buttonlabel. Update your TypeScript interfaces accordingly.
• →Asset Objects: Images are not simple strings; they are rich objects. To display an image, access image.url. You also have access to alt text and responsive metadata within the same object.

4. How to Register Components

To render a DatoCMS block, you must map the backend __typename to a local React component in src/registerComponents.ts:

registerLazyComponent(
  () => import('./blocks/Hero'), 
  'HeroRecord'
);

5. Troubleshooting

1. →Page Not Found: Ensure the slug in DatoCMS matches the URL you are visiting. The homepage should have the slug homepage.
2. →Empty Data: By default, the API only fetches Published content. If you are seeing 404s or null data, ensure you have clicked the "Publish" button in the DatoCMS editor.
3. →Case Sensitivity: If a specific field is missing, check the network response or Postman. The middleware follows the DatoCMS GraphQL schema strictly, which often favors lowercase identifiers.

6. How the "Magic" Happens

This starter uses a declarative rendering pattern. You don't manually map data to components in your routes; instead, the system uses a three-pillar approach to build your page dynamically:

• →Pillar 1: The CMS Tree: When you request a page, DatoCMS returns a "Tree" of data. Every block in your Paragraphs field arrives with a __typename (e.g., HeroRecord).
• →Pillar 2: The Registry: Inside src/registerComponents.ts, you tell the app which React component handles which Typename. This creates a "Map" that the middleware uses to understand your frontend architecture.
• →Pillar 3: The Render Component: The <QueenofheartsRenderComponent /> is the engine. It takes the CMS Tree and the Registry Map, matches them up, and injects the correct data into the correct React components automatically.

Example Workflow:

1. →You add a Call To Action block in DatoCMS.
2. →The API returns a CalltoactionRecord object.
3. →The Registry finds the local CallToAction.tsx component.
4. →The Render Component places that component on the screen and passes it the title and buttonlabel props.

This architecture allows you to change the order of your website directly from the CMS dashboard without touching a single line of code or redeploying your frontend.