# Brease Documentation

> The complete developer documentation for the Brease headless CMS and the brease-next Next.js integration package. Brease is a headless CMS for agencies and teams: content editors work in the CMS, and developers use brease-next to fetch and render that content.



---

# Brease Documentation

Source: https://docs.brease.io/

The complete developer documentation for the Brease headless CMS and the `brease-next` integration package. {% .lead %}

{% quick-links %}

{% quick-link title="Core Concepts" icon="presets" href="/docs/core-concepts" description="Understand the key entities — Sites, Environments, Sections, Collections, Templates, and how they relate to each other." /%}

{% quick-link title="Content Modeling" icon="lightbulb" href="/docs/entity-hierarchy" description="Learn how to structure content in Brease: the entity hierarchy, element types, and recommended patterns." /%}

{% quick-link title="Getting Started" icon="installation" href="/docs/getting-started" description="Install brease-next, configure your environment, and render your first CMS-driven page in minutes." /%}

{% quick-link title="API Reference" icon="plugins" href="/docs/api-reference" description="Complete reference for all fetch functions, components, hooks, and types exported by brease-next." /%}

{% /quick-links %}

{% callout title="Using these docs with AI coding agents" %}
These docs are available as plain Markdown for LLMs and AI coding tools (Claude Code, Cursor, Copilot, and others). Point your tool at [`/llms.txt`](/llms.txt) for an index linking to the raw Markdown of every page, or [`/llms-full.txt`](/llms-full.txt) for the entire documentation in a single file. Any page is also available as raw Markdown by appending `.md` to its URL — for example [`/docs/getting-started.md`](/docs/getting-started.md).
{% /callout %}

---

## What is Brease?

Brease is a headless content management system built for agencies and development teams who need a structured, collaborative way to manage website content. It consists of two parts:

- **Brease CMS** — the admin panel where content editors and developers define content structures, manage pages, and collaborate in real-time.
- **brease-next** — an npm package that provides a type-safe API client, React components, and utilities for rendering Brease content in Next.js applications.

Content editors work in the CMS to create and manage pages, sections, collections, navigations, and media. Developers use `brease-next` to fetch that content and render it in their Next.js frontend.

## How content flows

```
Brease CMS (admin panel)
    ↓ defines structures, fills content
Brease API (REST)
    ↓ delivers content as JSON
brease-next (npm package)
    ↓ fetches, provides context, renders
Your Next.js website
```

## Where to start

**If you are new to Brease**, start with [Core Concepts](/docs/core-concepts) to understand the data model, then follow the [Getting Started](/docs/getting-started) guide to set up your first project.

**If you need to model content**, read the [Content Modeling](/docs/entity-hierarchy) section to learn how to structure Sites, Sections, Collections, Templates, and Page Types.

**If you are building a frontend**, jump to the [brease-next Package](/docs/getting-started) section for API reference, components, and implementation patterns.

**If you need code examples**, see the [Implementation Patterns](/docs/project-setup) section for task-oriented guides covering routing, collections, navigation, locales, media, and deployment.


---

# Core Concepts

Source: https://docs.brease.io/docs/core-concepts

Brease CMS is organized around a set of core entities. Understanding how they relate is essential before building with `brease-next`.

---

## Team

An organizational unit that owns sites. Each team has members with roles (owner, admin, editor). When you sign up, a team is created automatically.

## Site

A web project belonging to a team. Each site has a name, a production domain, and a preview domain. A site contains one or more environments.

## Environment

A deployment context within a site (e.g., `main`, `staging`). Environments scope **all** content: pages, sections, collections, navigations, redirects, media, and locales. Each environment has a UUID used for API access.

{% callout title="Environments are fully independent" type="note" %}
Content in the `main` environment is completely separate from `staging`. You can build and preview changes in staging without affecting production.
{% /callout %}

## Locale

A language/region code (e.g., `en`, `sk`, `de-AT`). Each environment can have multiple locales, with one marked as the default. All content — page sections, collection entries, navigation items — is stored per locale.

## Page

A URL route within an environment. Each page has:

- **slug**: the URL path (e.g., `/about`, `/services/consulting`)
- **SEO metadata**: metaTitle, metaDescription, openGraph, twitterCard, canonicalUrl, structuredData
- **sections**: ordered content blocks (see below)
- **indexing**: toggle to control search engine indexing
- **customCode**: HTML/JS injection into the page head or body

## Section

A reusable content structure (schema) defined in the Editor. A section has a matrix of rows and slots — each slot holds an Element with a type and key.

The section's **`key`** is what maps to a React component in `brease-next`'s `sectionMap`. For example, a section with key `hero` maps to `sectionMap.hero`.

Sections can be **Global** — shared across multiple pages with the same content.

## Element

A typed content field within a section or collection. Each element has a unique key within its parent and one of 14+ types: String, Long Text, Rich Text, Integer, Decimal, Boolean, DateTime, Media, Link, Collection, Reference, Option, List, JSON, Location.

See [Element Types Reference](/docs/element-types) for the full list.

## Collection

Like a Section, but designed for repeatable data. You define the structure once (with elements), then create many Entries. Think: partner logos, FAQs, team members.

## Entry

A single record in a Collection. Each entry has:

- **name**: identification
- **status**: published or unpublished
- **visibility**: hidden or shown
- **ordering**: drag-and-drop reordering
- **per-locale element content**: the actual data, scoped by locale

## Template

An ordered bundle of Sections. A template defines "this page has Hero, then Content, then CTA." Used to standardize page layouts across your site.

## Page Type

Combines a Template with Reference fields (page-level data). When you assign a Page Type to a new page, its template sections are pre-populated and reference fields become available as page-level data.

## Navigation

A named container of navigation items, scoped per environment and localized per locale. Items can be:

- **page**: internal link to a page
- **url**: external URL
- **media**: link to a media file
- **group**: a dropdown container with nested children

Items support arbitrary nesting for multi-level menus.

## Redirect

A source/destination URL pair with a type:

- **301**: permanent redirect
- **302**: temporary redirect
- **307**: temporary, preserves HTTP method
- **308**: permanent, preserves HTTP method

## Media

Uploaded files with automatic responsive variants: `sm`, `md`, `lg`, `xl`, `2xl`, `hd`, and `original`. Supports images, video, audio, and documents.

---

## Editor vs Builder vs Manager

This is the most important distinction in Brease.

| Tool        | Purpose                                                   | What you do                                                                                                                                 |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Editor**  | Define section and collection **schemas** (the structure) | Create sections with rows, slots, and elements. Define collections with element fields. This is where you design _what_ content looks like. |
| **Builder** | Fill in page section **content** (the data per page)      | Select a page, then populate its section elements with actual content — text, images, links, etc.                                           |
| **Manager** | Fill in collection entry **content** (the data per entry) | Browse a collection, create entries, and fill in their element fields with data.                                                            |

{% callout title="Think of it this way" type="note" %}
The **Editor** is the architect (designs the blueprint). The **Builder** is the interior designer (decorates each room/page). The **Manager** is the librarian (manages the catalog/collection of entries).
{% /callout %}


---

# Entity Hierarchy

Source: https://docs.brease.io/docs/entity-hierarchy

Every piece of content in Brease follows a strict ownership and scoping chain. Understanding this hierarchy is key to working with the CMS and the `brease-next` package.

---

## The Hierarchy

```
Team
└── Site
    └── Environment (e.g., main, staging)
        ├── Pages
        │   └── Page Sections (ordered content blocks)
        ├── Sections (schema definitions)
        ├── Collections
        │   └── Entries (individual records)
        ├── Templates (ordered bundles of sections)
        ├── Page Types (template + reference fields)
        ├── Navigations
        │   └── Navigation Items (nested tree)
        ├── Redirects
        ├── Media (files + variants)
        └── Locales (language/region codes)
```

## Ownership Chain

**Teams own Sites.** A team is the top-level organizational unit. All billing, membership, and permissions are managed at the team level. A team can own multiple sites.

**Sites have Environments.** Each site has at least one environment. Environments let you maintain separate content contexts — for example, a `main` environment for production and a `staging` environment for preview.

**Environments scope content.** Everything below the environment level — pages, sections, collections, navigations, redirects, media, and locales — is environment-scoped. The same section can exist in both `main` and `staging` with completely different content.

## Environment Scoping

This is the most important architectural concept: **all content is scoped to an environment**.

- A page in `main` and a page in `staging` with the same slug are independent entities
- Sections defined in `main` do not exist in `staging` unless explicitly created there
- Collection entries, navigations, and redirects are all per-environment
- Media files are shared at the site level but their usage in content is per-environment

## Default Environment and Default Page

Each site has a **default environment** — typically `main`. This is the environment used for production deployments.

Each environment has a **default page** — the page served at the root URL (`/`). This is usually your homepage.

## API Access

The `brease-next` package identifies which environment to fetch from using two values:

| Variable | Purpose |
|----------|---------|
| `BREASE_ENV` | The environment UUID — scopes all API requests to this environment |
| `BREASE_TOKEN` | The API token — authenticates requests to the public API |

These are set as environment variables in your Next.js project:

```env
BREASE_ENV=your_environment_uuid
BREASE_TOKEN=your_api_token
```

Every fetch function in `brease-next` — `fetchPage()`, `fetchCollectionById()`, `fetchNavigation()`, etc. — automatically uses these values. You never need to pass the environment or token manually.

{% callout title="On the frontend" type="note" %}
In `brease-next`, you configure `BREASE_ENV` with your environment UUID and `BREASE_TOKEN` with your API token. All fetch functions are automatically scoped to that environment. To switch between environments (e.g., staging vs production), change the environment variables in your `.env.local` or deployment configuration.
{% /callout %}


---

# Sections & Elements

Source: https://docs.brease.io/docs/sections-and-elements

Sections and elements are the building blocks of all page content in Brease. A section defines the structure; elements define the fields within that structure.

---

## What is a Section?

A section is a **reusable content structure** — like a database table definition. It specifies what fields (elements) exist and their types, but contains no data itself. Data is filled in per page via the Builder.

For example, a "Hero" section might define: a `title` (string), a `subtitle` (long text), and an `image` (media). Every page that uses this section gets its own copy of those fields to fill in.

## Section Layout

Sections use a **matrix layout** of rows and slots:

- **Rows** are horizontal containers stacked vertically
- Each row can have **multiple slots** side by side
- Each slot holds **one Element**

This matrix is a visual organizing tool in the CMS Editor — it does not affect frontend rendering. On the frontend, you receive a flat `elements` object keyed by element keys.

## Section Properties

| Property        | Description                                    |
| --------------- | ---------------------------------------------- |
| **name**        | Display name in the CMS (e.g., "Hero Section") |
| **description** | Optional description for content editors       |
| **key**         | Unique identifier used for frontend mapping    |
| **published**   | Whether the section is available for use       |

### The `key` Property

The section `key` is critical — it maps a section to a React component in `brease-next`'s `sectionMap`.

```typescript
// CMS: Section with key "hero"
// Frontend: maps to HeroSection component

export const sectionMap = {
  hero: HeroSection, // key "hero" → HeroSection
  features: FeaturesSection, // key "features" → FeaturesSection
  cta: CtaSection, // key "cta" → CtaSection
}
```

If a section's key doesn't exist in the `sectionMap`, it is skipped during rendering.

{% callout title="Section components must be client components" type="warning" %}
Every component in the `sectionMap` must include `'use client'` at the top of the file. `BreasePage` is a client component and renders sections within a client component tree.
{% /callout %}

## Elements

Elements are **typed content fields** within a section. Each element has:

| Property          | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| **key**           | Unique identifier within the section (used as prop name on the frontend) |
| **type**          | One of 14+ types (string, media, link, etc.)                             |
| **required**      | Whether the field must be filled in                                      |
| **configuration** | Type-specific options (e.g., media mimeGroup, option values)             |

Element keys become property names when accessing content on the frontend. A section with elements `title`, `subtitle`, and `heroImage` produces:

```typescript
{
  title: "Welcome to our site",
  subtitle: "We build great things",
  heroImage: { path: "https://...", alt: "Hero", width: 1920, height: 1080, ... }
}
```

See [Element Types Reference](/docs/element-types) for the full list of types and their frontend values.

## Global Sections

Sections can be created as **global** in the Editor. A global section's content is shared across every page that uses it — editing it on one page updates it everywhere. Use cases: site-wide banners, shared CTAs, footer content blocks.

## How It Maps to the Frontend

```
CMS Editor: Section "hero" with elements: title (string), subtitle (long-text), image (media)
    ↓
Frontend sectionMap: { hero: HeroSection }
    ↓
HeroSection component receives: { title: "Welcome", subtitle: "...", image: { path: "...", variants: [...] } }
```

A complete example:

```typescript
// 1. Define the component (must be a client component)
'use client'

import { BreaseImage, type BreaseMedia } from 'brease-next'

interface HeroSectionProps {
  title: string;
  subtitle: string;
  image: BreaseMedia;
}

export default function HeroSection({ title, subtitle, image }: HeroSectionProps) {
  return (
    <section>
      <h1>{title}</h1>
      <p>{subtitle}</p>
      <BreaseImage breaseImage={image} />
    </section>
  );
}

// 2. Register in sectionMap
export const sectionMap = {
  hero: HeroSection,
};

// 3. BreasePage renders it automatically
<BreasePage page={pageData} sectionMap={sectionMap} />
```

{% callout title="On the frontend" type="note" %}
Section content arrives in `brease-next` as `section.elements` — a `Record<string, unknown>` keyed by element keys. Use `sectionMap` to map section keys to React components. Each component receives the elements object spread as props.
{% /callout %}


---

# Collections & Entries

Source: https://docs.brease.io/docs/collections-and-entries

Collections let you manage repeatable, structured data — FAQs, team members, products, and more.

---

## What is a Collection?

A collection is like a Section, but designed for **repeatable data**. You define the structure once (with elements using the same drag-and-drop Editor interface), then create many Entries that follow that structure.

| Concept                  | Section                | Collection          |
| ------------------------ | ---------------------- | ------------------- |
| **Structure defined in** | Editor                 | Editor              |
| **Content filled in**    | Builder (per page)     | Manager (per entry) |
| **Content instances**    | One per page placement | Many entries        |
| **Use case**             | Page layouts           | Lists of data       |

**Common use cases:** FAQs, team members, products, testimonials, portfolio items, job listings, event listings, partner logos.

## Defining a Collection

Collections are created in the **Editor** using the same interface as sections — rows, slots, and elements.

{% callout title="No circular references" type="warning" %}
Collections cannot use the `collection` element type. This prevents circular references where a collection would contain another collection.
{% /callout %}

## Entries

An entry is a single record in a collection. Each entry has:

| Property       | Description                              |
| -------------- | ---------------------------------------- |
| **uuid**       | Unique identifier                        |
| **name**       | Display name in the CMS                  |
| **status**     | Published or unpublished                 |
| **visibility** | Hidden or shown                          |
| **ordering**   | Position in the list (drag-and-drop)     |
| **elements**   | Per-locale content keyed by element keys |

Only published entries with "shown" visibility are returned by the public API.

---

## Fetching via BreaseContext

For collections needed globally (e.g., in navigation or footer), configure them in `BreaseContext`:

```typescript
// src/lib/brease-config.ts
export const contextData = {
  navigations: [],
  collections: [
    { key: 'faqs', id: 'col-a01c8223-4e4a-40aa-90d9-70149e87322c' },
    { key: 'testimonials', id: 'col-b02d9334-5f5b-51bb-a1ea-81250f98433d' },
  ],
}
```

Then access in client components:

```typescript
'use client';

import { useBrease } from 'brease-next';

export default function Testimonials() {
  const { collections } = useBrease();
  const { testimonials } = collections;

  if (!testimonials || testimonials.length === 0) return null;

  return (
    <div>
      {testimonials.map(entry => (
        <blockquote key={entry.uuid}>
          <p>{entry.elements.quote as string}</p>
          <cite>{entry.elements.author as string}</cite>
        </blockquote>
      ))}
    </div>
  );
}
```

{% callout title="Type casting" type="note" %}
Collection entry elements are untyped (`Record<string, unknown>`). Always cast them to the appropriate type based on your collection schema: `entry.elements.title as string`, `entry.elements.image as BreaseMedia`, etc.
{% /callout %}


---

# Templates & Page Types

Source: https://docs.brease.io/docs/templates-and-page-types

Templates and Page Types help you standardize page layouts and attach page-level metadata across your site.

---

## Templates

A template is an **ordered bundle of sections**. It defines "this page layout has these sections in this order."

Instead of manually adding sections to every new page, you create a template once and reuse it.

### Creating a Template

1. Go to **Editor → Templates**
2. Select from existing **published sections**
3. Reorder sections as needed
4. Publish the template

A template named "Blog Layout" might contain:

```
1. Hero Section (key: smallHero)
2. Content Section (key: text)
3. Related Posts Section (key: latestNews)
```

### Purpose

Templates solve a common problem: ensuring consistency. When multiple pages share the same structure (e.g., all blog posts have a hero, content area, and related posts), a template guarantees they all use the same sections in the same order.

---

## Page Types

A Page Type combines a **Template** with **Reference fields**. Reference fields use the same element types (string, media, link, datetime, etc.) and act as **page-level metadata** — data that belongs to the page itself rather than to any specific section.

### Use Case

A "Blog Post" Page Type could have:

- **Template**: "Blog Layout" (smallHero + text + latestNews sections)
- **Reference fields**:
  - `author` (string) — who wrote it
  - `publishDate` (datetime) — when it was published
  - `featuredImage` (media) — for social sharing and listings
  - `category` (option) — blog category

This is useful for example when you want to create components that uses content from a page without fetching the full content of that page (e.g: Latest News cards from blog post pages)

When you create a page with this Page Type, the template sections are automatically added and the reference fields appear as page-level metadata fields.

### Reference Fields vs Section Elements

|                | Reference Fields                       | Section Elements                      |
| -------------- | -------------------------------------- | ------------------------------------- |
| **Scope**      | Page-level                             | Section-level                         |
| **Defined in** | Page Type                              | Section schema                        |
| **Filled in**  | Page settings                          | Builder                               |
| **Use case**   | Page metadata (author, date, category) | Section content (title, body, images) |

---

## Recommended Workflow

{% callout title="Build bottom-up" type="note" %}
Follow this order to build your content architecture efficiently. Each step builds on the previous one.
{% /callout %}

### 1. Define Sections in the Editor

Create the individual content blocks your site needs: hero, text, CTA, image grid, testimonials, etc. Each section defines its own elements (fields).

### 2. Compose Sections into Templates

Group sections into reusable page layouts. A "Landing Page" template might combine hero + features + testimonials + CTA. A "Blog Post" template might combine smallHero + text + relatedPosts.

### 3. Wrap Templates in Page Types with Reference Fields

Add page-level metadata fields to your templates. A "Blog Post" Page Type adds author, publish date, and category on top of the blog layout template.

### 4. Create Pages Using Page Types

When creating a new page, select a Page Type. The template sections are pre-populated and reference fields are ready to fill in. Content editors can focus on writing instead of assembling page structure.

---

## On the Frontend

Reference field data arrives in `page.references` as an array of objects. Access it via the `useBrease()` hook in client components:

```typescript
'use client';

import { useBrease } from 'brease-next';

export default function BlogMeta() {
  const { references } = useBrease();

  if (!references || references.length === 0) return null;

  return (
    <div>
      {references.map((ref, index) => (
        <span key={index}>{ref.key}: {String(ref.value)}</span>
      ))}
    </div>
  );
}
```

{% callout title="References are page-scoped" type="note" %}
Reference data is specific to each page. It is available via `useBrease().references` in client components and directly on the page object in server components.
{% /callout %}


---

# Navigations & Redirects

Source: https://docs.brease.io/docs/navigations-and-redirects

Navigations and redirects are managed per environment in the CMS and consumed on the frontend via `brease-next`.

---

## Navigations

A navigation is a **named container of navigation items**, scoped per environment and localized per locale.

### Item Types

In the CMS, each navigation item is one of: **page** (internal link), **url** (external link), **media** (file link), **entry** (collection entry link), or **group** (dropdown container with children).

On the frontend, all items arrive as `BreaseNavigationItem`:

```typescript
interface BreaseNavigationItem {
  uuid: string
  label: string           // Display text
  isExternal: boolean     // false for pages, true for external URLs
  value: string           // The URL or slug
  target: '_blank' | '_self' | null
  children: BreaseNavigationItem[]  // Nested items
}
```

Use the `isExternal` flag and `value` to determine link behavior — or simply pass the item to `BreaseLink` which handles this automatically.

### Ordering and Nesting

Items are reordered via drag-and-drop in the CMS. Nesting is supported — drag items under a group or another item to create multi-level dropdown menus. Nested items appear in the `children` array.

### On the Frontend

Configure navigations in `BreaseContext`:

```typescript
// src/lib/brease-config.ts
export const contextData = {
  navigations: [
    { key: 'header', id: 'nav-a01c4cbb-21f7-46d5-a89c-564307998128' },
    { key: 'footer', id: 'nav-b02d5ecc-32f8-57e6-b9ad-675418009239' },
  ],
  collections: [],
}
```

Access in client components via `useBrease()` and render items with `BreaseLink`:

```typescript
'use client'

import { useBrease, BreaseLink } from 'brease-next'

export default function Header() {
  const { navigations } = useBrease()
  const headerNav = navigations.header

  if (!headerNav) return null

  return (
    <nav className="flex items-center gap-6">
      {headerNav.items.map((item) => (
        <BreaseLink key={item.uuid} linkData={item} className="text-sm font-medium">
          {item.label}
        </BreaseLink>
      ))}
    </nav>
  )
}
```

`BreaseLink` handles internal vs external links automatically — it renders a Next.js `Link` for internal URLs and a native `<a>` with `rel="noopener noreferrer"` for external ones. Since `BreaseNavigationItem` extends `BreaseLinkData`, you can pass navigation items directly as `linkData`.

For nested items (dropdowns), iterate `item.children`:

```typescript
{item.children.map((child) => (
  <BreaseLink key={child.uuid} linkData={child}>
    {child.label}
  </BreaseLink>
))}
```

{% callout title="Finding navigation UUIDs" type="note" %}
Open the Brease dashboard, go to **Navigations**, select your navigation, and copy the UUID from the settings panel or URL.
{% /callout %}

---

## Redirects

Redirects are **source/destination URL pairs** with an HTTP status type, managed per environment in the CMS.

### Redirect Types

| Type    | Name               | Behavior                                                  |
| ------- | ------------------ | --------------------------------------------------------- |
| **301** | Moved Permanently  | Browsers and search engines cache this permanently        |
| **302** | Found (Temporary)  | Temporary redirect, not cached                            |
| **307** | Temporary Redirect | Like 302, but preserves the HTTP method (POST stays POST) |
| **308** | Permanent Redirect | Like 301, but preserves the HTTP method                   |

### On the Frontend

Fetch redirects and apply them in `next.config.ts`:

```typescript
// next.config.ts
import type { NextConfig } from 'next'
import { fetchRedirects } from 'brease-next/server'

const nextConfig: NextConfig = {
  async redirects() {
    const result = await fetchRedirects()

    if (!result.success) {
      console.error('Failed to fetch redirects:', result.error)
      return []
    }

    return result.data.map((redirect) => ({
      source: redirect.source,
      destination: redirect.destination,
      permanent: redirect.type === '301' || redirect.type === '308',
    }))
  },
}

export default nextConfig
```

{% callout title="Build-time only" type="warning" %}
Next.js redirects are evaluated at **build time**. After adding or changing redirects in the CMS, you need to rebuild and redeploy your site for the changes to take effect.
{% /callout %}

### Redirect Format

When creating redirects in the CMS:

- **Source**: the path to redirect from (e.g., `/old-page`)
- **Destination**: the path to redirect to (e.g., `/new-page`)
- Both must include leading slashes
- Supports Next.js path matching patterns (e.g., `/blog/:slug`)


---

# Multi-Locale Content

Source: https://docs.brease.io/docs/multi-locale

Brease supports multi-locale content out of the box. Each environment can have multiple locales, and all content is stored independently per locale.

---

## Locales in the CMS

Each environment can have multiple locales (e.g., `en`, `sk`, `de-AT`). One locale is marked as the **default**.

All content entities have per-locale content:

- **Pages**: section content is localized per locale
- **Collection entries**: element content is localized per locale
- **Navigation items**: labels and values are localized per locale

In the CMS, the **Builder** and **Manager** have a locale switcher to edit content for each locale independently. You fill in content for one locale at a time.

## Configuring Locales in `brease-next`

Set the default locale in your environment variables:

```env
BREASE_DEFAULT_LOCALE=en
```

This tells `brease-next` which locale to use when no locale is detected from the URL.

## Locale Derivation from URLs

`brease-next` determines the active locale from the **first segment** of the URL slug:

| URL | Detected Locale | Slug Passed to API |
|-----|----------------|-------------------|
| `/about` | default (`en`) | `/about` |
| `/sk/about` | `sk` | `/sk/about` |
| `/de-AT/kontakt` | `de-AT` | `/de-AT/kontakt` |

The first segment is checked against known locale codes for the environment. If it matches a configured locale, that locale is used. Otherwise, the default locale is used.

## Fetching Available Locales

Use `fetchLocales()` to get all active locales for the current environment:

```typescript
import { fetchLocales } from 'brease-next';

const result = await fetchLocales();

if (result.success) {
  console.log('Available locales:', result.data);
  // [{ code: 'en', name: 'English', default: true }, { code: 'sk', name: 'Slovak', default: false }]
}
```

## Alternate Links (hreflang)

Each page includes `alternateLinks` — a `Record<string, string>` mapping locale codes to URLs. Use these for SEO `hreflang` tags:

```typescript
import { fetchPage } from 'brease-next';

const result = await fetchPage('/about');

if (result.success) {
  const alternateLinks = result.data.alternateLinks;
  // { en: "/about", sk: "/sk/o-nas", de: "/de/ueber-uns" }
}
```

In client components, access via the `useBrease()` hook:

```typescript
'use client';

import { useBrease } from 'brease-next';

export default function HreflangTags() {
  const { alternateLinks } = useBrease();

  if (!alternateLinks) return null;

  return (
    <>
      {Object.entries(alternateLinks).map(([locale, url]) => (
        <link
          key={locale}
          rel="alternate"
          hrefLang={locale}
          href={url}
        />
      ))}
    </>
  );
}
```

## Language Switcher

Build a language selector using `useBrease()`:

```typescript
'use client';

import { useBrease } from 'brease-next';
import Link from 'next/link';

export default function LanguageSwitcher() {
  const { alternateLinks, availableLocales } = useBrease();

  if (!alternateLinks || !availableLocales) return null;

  return (
    <div>
      {availableLocales.map(locale => (
        <Link
          key={locale.code}
          href={alternateLinks[locale.code] || '/'}
        >
          {locale.name}
        </Link>
      ))}
    </div>
  );
}
```

## Static Generation with Multiple Locales

`generateBreasePageParams()` iterates all locales and all pages to generate params for `[[...slug]]` catch-all routes:

```typescript
// src/app/[[...slug]]/page.tsx
import { generateBreasePageParams, fetchPage, BreasePage } from 'brease-next';
import { sectionMap } from '@/lib/brease-config';
import { notFound } from 'next/navigation';

export async function generateStaticParams() {
  return generateBreasePageParams();
  // Returns params for all locale/page combinations:
  // [
  //   { slug: [] },              // homepage (default locale)
  //   { slug: ['about'] },       // /about (default locale)
  //   { slug: ['sk'] },          // /sk (Slovak homepage)
  //   { slug: ['sk', 'o-nas'] }, // /sk/o-nas (Slovak about page)
  // ]
}

export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
  const { slug } = await params;
  const pageSlug = slug ? `/${slug.join('/')}` : '/';

  const result = await fetchPage(pageSlug);

  if (!result.success) {
    if (result.status === 404) return notFound();
    throw new Error(`Failed to load page: ${result.error}`);
  }

  return <BreasePage page={result.data} sectionMap={sectionMap} />;
}
```

{% callout title="Locale-aware content" type="note" %}
All `brease-next` fetch functions automatically resolve the correct locale based on the slug you pass. You don't need to pass a locale parameter separately — the locale is derived from the URL structure.
{% /callout %}


---

# Element Types Reference

Source: https://docs.brease.io/docs/element-types

Brease supports 14+ element types for defining content fields in sections and collections. This reference covers each type, its frontend value, configuration options, and rendering guidance.

---

## Type Reference

### String

| | |
|-|-|
| **Key** | `string` |
| **Frontend value** | `string` |
| **Config** | `required` |

Plain text, single line. Render directly.

```typescript
<h1>{elements.title as string}</h1>
```

### Long Text

| | |
|-|-|
| **Key** | `long-text` |
| **Frontend value** | `string` |
| **Config** | `required` |

Multi-line plain text. May contain newlines. Use `white-space: pre-line` in CSS or split on `\n`:

```typescript
<p style={{ whiteSpace: 'pre-line' }}>{elements.description as string}</p>
```

### Rich Text

| | |
|-|-|
| **Key** | `richtext` |
| **Frontend value** | `string` (HTML) |
| **Config** | `required` |

HTML string from CKEditor. Render with `dangerouslySetInnerHTML`:

```typescript
<div
  className="prose"
  dangerouslySetInnerHTML={{ __html: elements.body as string }}
/>
```

{% callout title="Sanitization" type="warning" %}
Rich text content is HTML generated by CKEditor in the CMS. If you need additional sanitization, use a library like `DOMPurify` before rendering.
{% /callout %}

### Integer

| | |
|-|-|
| **Key** | `integer` |
| **Frontend value** | `number` |
| **Config** | `required` |

Whole number. Render directly.

```typescript
<span>{elements.count as number} items</span>
```

### Decimal

| | |
|-|-|
| **Key** | `float` |
| **Frontend value** | `number` |
| **Config** | `required` |

Floating-point number.

```typescript
<span>${(elements.price as number).toFixed(2)}</span>
```

### Boolean

| | |
|-|-|
| **Key** | `boolean` |
| **Frontend value** | `boolean` |
| **Config** | `required` |

Toggle/switch value. Use for conditional rendering:

```typescript
{(elements.showBanner as boolean) && <Banner />}
```

### DateTime

| | |
|-|-|
| **Key** | `datetime` |
| **Frontend value** | `string` (ISO 8601) |
| **Config** | `required` |

ISO 8601 date string. Parse with `new Date()` or a date library:

```typescript
const date = new Date(elements.publishDate as string);
<time dateTime={elements.publishDate as string}>
  {date.toLocaleDateString()}
</time>
```

### Media

| | |
|-|-|
| **Key** | `media` |
| **Frontend value** | `BreaseMedia` or `BreaseMedia[]` |
| **Config** | `required`, `multiple` (boolean), `mimeGroup` (image/video/audio/document/archive) |

Uploaded file with metadata and responsive variants. Check the `multiple` config to know if the value is an array.

```typescript
import { BreaseImage, type BreaseMedia } from 'brease-next';

// Single media
<BreaseImage breaseImage={elements.heroImage as BreaseMedia} />

// Multiple media
{(elements.gallery as BreaseMedia[]).map((img, i) => (
  <BreaseImage key={i} breaseImage={img} />
))}
```

The `BreaseMedia` object includes:

```typescript
{
  path: string;       // Full URL to original file
  alt: string;        // Alt text
  name: string;       // File name
  width: number;      // Original width
  height: number;     // Original height
  mimeType: string;   // e.g., "image/jpeg"
  mimeGroup: string;  // "image", "video", "audio", "document"
  variants: BreaseMediaVariant[]; // Responsive variants (sm, md, lg, xl, 2xl, hd)
}
```

### Link

| | |
|-|-|
| **Key** | `link` |
| **Frontend value** | `BreaseLinkData` — `{ label: string, isExternal: boolean, value: string, target: '_blank' \| '_self' \| null }` |
| **Config** | `required`, `allowedTypes` (page/url/media/entry) |

Use the `BreaseLink` component — it handles internal vs external links automatically:

```tsx
import { BreaseLink, type BreaseLinkData } from 'brease-next'

const link = elements.cta as BreaseLinkData

<BreaseLink linkData={link} className="text-blue-600 hover:underline">
  {link.label}
</BreaseLink>
```

`BreaseLink` renders a Next.js `Link` for internal URLs and a native `<a>` with `rel="noopener noreferrer"` for external ones. It respects the `target` property from the CMS.

### Collection

| | |
|-|-|
| **Key** | `collection` |
| **Frontend value** | `{ name: string, entries: BreaseCollectionEntry[] }` |
| **Config** | `collectionId` (linked collection UUID) |

{% callout title="Sections only" type="warning" %}
The collection element type is only available in Sections, not in Collections (to prevent circular references).
{% /callout %}

Contains the linked collection's entries inline within the section:

```typescript
import type { BreaseCollection } from 'brease-next'

const testimonials = elements.testimonials as BreaseCollection

{testimonials.entries.map(entry => (
  <blockquote key={entry.uuid}>
    <p>{entry.elements.quote as string}</p>
    <cite>{entry.elements.author as string}</cite>
  </blockquote>
))}
```

### Reference

| | |
|-|-|
| **Key** | `reference` |
| **Frontend value** | `object` |
| **Config** | - |

Used in Page Types for page-level metadata. The value shape depends on the element configuration within the Page Type definition.

### Option

| | |
|-|-|
| **Key** | `option` |
| **Frontend value** | `string` or `string[]` |
| **Config** | `values` (array of options), `type` (`select`/`radio`/`checkbox`) |

Single value for `select`/`radio`, array for `checkbox`:

```typescript
// Select or radio — single value
const color = elements.theme as string; // "dark"

// Checkbox — array of values
const tags = elements.categories as string[]; // ["news", "featured"]

{tags.map(tag => (
  <span key={tag} className="badge">{tag}</span>
))}
```

### List

| | |
|-|-|
| **Key** | `list` |
| **Frontend value** | `unknown[]` |
| **Config** | `required` |

Repeater field. An array of items:

```typescript
const items = elements.features as string[];

<ul>
  {items.map((item, i) => (
    <li key={i}>{item}</li>
  ))}
</ul>
```

### JSON

| | |
|-|-|
| **Key** | `json` |
| **Frontend value** | `any` |
| **Config** | `required` |

Raw JSON data. Parse and use as needed:

```typescript
const config = elements.settings as { color: string; size: number };

<div style={{ color: config.color, fontSize: config.size }}>
  Custom styled content
</div>
```

### Location

| | |
|-|-|
| **Key** | `location` |
| **Frontend value** | `{ lat: number, lng: number }` |
| **Config** | `required` |

Geographic coordinates. Use with map libraries:

```typescript
const location = elements.officeLocation as { lat: number; lng: number };

// Use with Google Maps, Mapbox, Leaflet, etc.
<Map center={[location.lat, location.lng]} zoom={15} />
```

---

## Quick Reference Table

| Type | Key | Frontend Value | Config Options |
|------|-----|----------------|----------------|
| String | `string` | `string` | `required` |
| Long Text | `long-text` | `string` | `required` |
| Rich Text | `richtext` | `string` (HTML) | `required` |
| Integer | `integer` | `number` | `required` |
| Decimal | `float` | `number` | `required` |
| Boolean | `boolean` | `boolean` | `required` |
| DateTime | `datetime` | `string` (ISO 8601) | `required` |
| Media | `media` | `BreaseMedia` / `BreaseMedia[]` | `required`, `multiple`, `mimeGroup` |
| Link | `link` | `BreaseLinkData` | `required`, `allowedTypes` |
| Collection | `collection` | `BreaseCollection` | `collectionId` |
| Reference | `reference` | `object` | - |
| Option | `option` | `string` / `string[]` | `values`, `type` |
| List | `list` | `unknown[]` | `required` |
| JSON | `json` | `any` | `required` |
| Location | `location` | `{ lat, lng }` | `required` |

{% callout title="Type safety" type="note" %}
All element values arrive as `unknown` from the API. Always cast them to the expected type based on your section/collection schema. Define TypeScript interfaces for your section props to get compile-time safety.
{% /callout %}


---

# Editor (Definitions)

Source: https://docs.brease.io/docs/editor

The Editor is where developers define content structures — the schemas that determine what content editors can fill in. Nothing is "content" here; everything is structure.

---

## Four Tabs

The Editor is organized into four tabs, each managing a different entity type:

### Sections

Define section schemas with drag-and-drop element layout. A section is a reusable content block structure (e.g., "Hero", "Feature Grid", "CTA Banner"). Sections are used by the Builder when editors populate page content.

### Collections

Same editing experience as sections, but designed for repeatable data — FAQs, team members, testimonials, products. The key difference: the `collection` element type is filtered out of the element palette to prevent circular references (a collection cannot reference itself or another collection within its own definition).

### Templates

Compose sections into ordered bundles that standardize page layouts. A template defines "this page should have Hero, then Features, then CTA" — giving content editors a pre-built structure when they create a new page.

### Page Types

Combine a template with reference fields for page-level metadata. When a page is assigned a page type, it inherits the template's sections and gains the reference fields as page-level configuration options.

---

## Section and Collection Editing

Both sections and collections share the same editing interface.

### Sidebar

The left sidebar lists all sections or collections for the current environment.

The sidebar provides:

- **Search**: filter items by name
- **Create New**: add a new section or collection

### Item Header

Each item displays:

- **Name**: the display name shown in the CMS
- **Description**: optional description for content editors
- **Status badge**: `Published` or `Unpublished`
- **Page usage count**: how many pages currently use this section

### Canvas

The main editing area is a drag-and-drop canvas with a matrix layout:

- **Rows**: horizontal containers stacked vertically. Add rows to organize elements into logical groups.
- **Slots**: each row contains one or more slots arranged side by side. Each slot holds exactly one element.

The canvas layout is a visual organizing tool for the CMS — it does not affect how elements are delivered to the frontend. On the frontend, you always receive a flat `elements` object keyed by element key.

### Kiosk (Element Palette)

The bottom bar is the **Kiosk** — the source palette for all available element types. To add an element to the canvas, drag it from the kiosk and drop it into an empty slot.

Available element types include: String, Long Text, Rich Text, Integer, Decimal, Boolean, DateTime, Media, Link, Collection, Reference, Option, List, JSON, Location, and more. See [Element Types Reference](/docs/element-types) for the full list.

### Element Slot Configuration

Click an element slot to configure it:

- **Key**: the unique identifier for this element within the section. Must be unique across all elements in the section.
- **Localized**: toggle whether this element has separate content per locale. When **on**, content editors see different values for each locale in the Builder/Manager. When **off**, the element shares a single value across all locales — useful for fields like images, coordinates, or IDs where the content is language-independent.
- **Media settings**: for media elements — allow multiple files, restrict by MIME group (images, video, audio, documents)
- **Collection link**: for collection elements — select which collection this element references
- **Option values**: for option elements — define the selectable values and option type (select/radio/checkbox)
- **Link restrictions**: for link elements — restrict which link types are available (page, URL, media, entry)

{% callout title="Keys become frontend property names" type="warning" %}
Section and collection `key` values are critical — they become the property names used in frontend code via `sectionMap` and `elements` object. Changing a key after content has been entered will break the link between existing content and your frontend components.
{% /callout %}

### Validation

Every element slot has a **Validation** panel (expandable in the slot configuration dropdown) with two settings:

**Required** — a toggle available on all element types. When enabled, content editors must fill in this field before publishing. Boolean elements default to `required: false`; reference elements default to `required: true`.

**Limit** — a numeric constraint available on most element types (not available on Boolean or Link elements). Controls how many values or how much content is acceptable. Three modes:

| Mode         | Fields          | Use case                                          |
| ------------ | --------------- | ------------------------------------------------- |
| **Between**  | `min` and `max` | Enforce a range — e.g., "between 1 and 5 tags"    |
| **Min only** | `min`           | Enforce a minimum — e.g., "at least 2 images"     |
| **Max only** | `max`           | Enforce a maximum — e.g., "no more than 10 items" |

How the limit applies depends on the element type:

- **String / Long Text**: character count
- **Rich Text**: character count
- **Integer / Decimal**: value range
- **Media** (multiple): number of files
- **Option** (checkbox): number of selected values
- **List**: number of items
- **Collection**: number of entries

{% callout title="Validation is enforced in the CMS" type="note" %}
These validations are enforced when content editors save or publish in the Builder and Manager. They do not affect the frontend — `brease-next` delivers whatever data the API returns. If you need client-side validation, implement it separately in your components.
{% /callout %}

---

## Global Sections

A **Global Section** is a section whose content is shared across every page that uses it. Unlike regular sections — where each page gets its own independent copy of the content — a global section has a single set of content values that appear identically everywhere.

### Creating Global Sections

Global sections are created in the **Editor**, just like regular sections. When creating or editing a section, mark it as global. Once marked, the section appears in the Builder's section picker alongside regular sections and can be added to any page.

### How Content Works

- When a content editor adds a global section to a page in the Builder, they can edit its content there
- Any changes to a global section's content apply to **every page** that includes it
- Regular sections have independent content per page; global sections share a single set of content values

### When to Use Global Sections

Global sections are ideal for content blocks that must stay consistent site-wide:

- **CTA banners** — a single call-to-action shown on multiple pages
- **Announcement bars** — a site-wide notice or promotion
- **Partner logos** — a logo strip that appears across pages
- **Shared testimonials** — a testimonial carousel reused on different pages

{% callout title="Schema vs content" type="note" %}
The global section's schema (structure and elements) is managed in the Editor. Its content values are managed in the Builder — but unlike regular sections, edits propagate to all pages that use it.
{% /callout %}

---

## Template Editing

Templates are ordered lists of sections:

- **Add sections**: select from available published sections to add to the template
- **Remove sections**: remove a section from the template lineup
- **Reorder sections**: drag-and-drop to change the section order
- **Publish/Unpublish**: control whether the template is available for use in page types and page creation

Only published sections appear in the section picker when editing a template.

---

## Page Type Editing

Page types combine structure and metadata:

- **Assign a template**: select a published template that defines the section lineup
- **Add reference fields**: add element fields (same types available as in sections) that serve as page-level metadata — e.g., a "Category" option, a "Featured Image" media field, or a "Related Page" reference
- **Publish/Unpublish**: control whether the page type is available when creating new pages

When a content editor creates a page and assigns a page type, the page is pre-populated with the template's sections and the reference fields become available as page-level configuration.


---

# Page Builder

Source: https://docs.brease.io/docs/page-builder

The Builder is where content editors fill in page content. While the Editor defines what a page _can_ contain, the Builder is where actual text, images, links, and other data are entered for each page.

---

## Overview

The workflow is straightforward:

1. Select a page from the page list
2. Manage which sections the page contains
3. Click a section to open its content editor and fill in element values

---

## Section Management

Once a page is selected, you can manage its sections:

### Adding Sections

Use the dropdown selector to pick from available published sections and add them to the page. Sections are added to the page's section list and become available for content editing.

### Removing Sections

Remove a section from the page. This deletes the section and any content entered for it on this page.

### Reordering Sections

Drag-and-drop sections to change their display order on the page. The order here determines the order in which sections are rendered on the frontend via `BreasePage`.

### Publish/Unpublish Sections

Individual sections on a page can be published or unpublished. Unpublished sections are not included in the API response when the page is fetched, so they won't render on the frontend.

### Show/Hide Sections

Toggle section visibility without removing the section. Hidden sections retain their content but are excluded from the API response — useful for temporarily hiding a section without losing its data.

### Global Sections

Global sections are created in the **Editor** (not the Builder). When adding sections to a page, global sections appear alongside regular sections in the section picker. Once added, you can edit a global section's content directly in the Builder — but unlike regular sections, changes to a global section's content apply to **every page** that includes it.

This is useful for content blocks that should be identical everywhere, such as a CTA banner, an announcement bar, or a newsletter signup form. See [Editor — Global Sections](/docs/editor#global-sections) for how to create them.

---

## Content Editing

Click a section (from the kiosk or the section list) to open the **content editor drawer**. The drawer displays all elements defined in that section's schema, each rendering a type-specific input:

- **String**: single-line text field
- **Long Text**: multi-line textarea
- **Rich Text**: CKEditor rich text editor with formatting toolbar
- **Integer / Decimal**: numeric input fields
- **Boolean**: toggle switch
- **DateTime**: date and time picker
- **Media**: media picker for selecting uploaded files (images, video, etc.)
- **Link**: link picker with support for internal pages, external URLs, media files, and collection entries
- **Collection**: selector for linking to collection entries
- **Option**: dropdown or checkbox group based on the defined option values
- **Reference**: reference to other entities
- **JSON**: raw JSON editor
- **Location**: location/coordinates input

Fill in each field and save. Values are stored per section, per page, per locale.

---

## Live Preview

When a site has a `previewDomain` configured in its settings, the Builder displays a live **iframe preview** alongside the content editor.

### How It Works

- The preview loads your frontend application in an iframe pointed at the preview domain
- As you edit content in the Builder, changes are streamed to the iframe in real time via the **PostMessage protocol**
- The frontend receives content updates and re-renders sections without a page reload

### Preview Toolbar

Inside the preview iframe, each section displays a toolbar with an **Edit** button. Clicking "Edit" jumps you back to the Builder's content editor drawer for that specific section, creating a seamless back-and-forth editing experience.

{% callout title="Preview requires frontend integration" type="note" %}
For live preview to work, your Next.js application must include the `BreasePreviewListener` component and `SectionToolbar` components from `brease-next`. See [Preview Integration](/docs/preview-integration) for setup instructions.
{% /callout %}

---

## Locale Switching

The Builder includes a **locale dropdown** that controls which locale's content you are editing.

- Switching locales reloads the content editor with that locale's data
- Saving content applies only to the currently selected locale
- Only **localized** elements show different values per locale. Elements marked as non-localized in the Editor share a single value across all locales (e.g., an image field that should display the same image regardless of language).

This allows content editors to manage translations directly within the Builder without switching to a separate tool.


---

# Collection Manager

Source: https://docs.brease.io/docs/collection-manager

The Manager is where content editors create and manage collection entries. While the Editor defines the collection schema, and the Builder handles page content, the Manager is where repeatable data — FAQs, team members, testimonials, products — is actually authored.

---

## Overview

The workflow:

1. Select a collection from the dropdown (all published collections are listed)
2. Browse the entry list, which shows all entries with drag-and-drop ordering
3. Click an entry to open the content editor and fill in its element values

---

## Entry Management

### Creating Entries

Click "Create" and provide a name for the new entry. The entry is created with empty content, ready to be filled in.

### Editing Content

Click an entry to open the content editor. The editor displays the same type-specific inputs as the Builder — text fields, rich text editors, media pickers, and so on — based on the collection's element schema.

### Duplicating Entries

Duplicate an entry to create a copy with the same content. Useful for creating variations of similar entries without starting from scratch.

### Publishing and Unpublishing

Each entry can be individually published or unpublished. Unpublished entries are excluded from API responses, so they won't appear on the frontend when fetching collection data.

### Show/Hide

Toggle entry visibility without deleting or unpublishing. Hidden entries retain their content and published status but are excluded from API responses — useful for temporarily removing an entry from display.

### Deleting Entries

Permanently remove an entry and all its content across all locales.

### Reordering Entries

Drag-and-drop entries in the list to change their order. The ordering is persisted to the backend and reflected in API responses, so the order you set here is the order your frontend receives.

---

## Content Editing

The content editing experience mirrors the Builder:

- Each element in the collection schema renders its type-specific input
- Content is saved **per locale** — switching locales shows different content for the same entry
- **Save** syncs all changes to the backend for the currently selected locale

{% callout title="Saving is per locale" type="note" %}
When you save an entry, only the content for the currently selected locale is persisted. Switch to each locale individually to enter and save translated content.
{% /callout %}

---

## Locale Switching

The Manager includes a **locale dropdown** for switching between locales:

- Switching locales reloads the entry list and entry content for the selected locale
- Each locale has independent content values for every element in every entry
- Entry names and ordering are shared across locales, but element content is locale-specific

This allows content editors to manage all translations for a collection's entries within a single interface.


---

# Getting Started

Source: https://docs.brease.io/docs/getting-started

This guide walks you through setting up `brease-next` in a Next.js project.

{% callout title="Reading these docs with an AI agent?" %}
Point your coding tool at [`/llms.txt`](/llms.txt) for a Markdown index of the whole documentation, or grab any page as raw Markdown by appending `.md` to its URL (e.g. [`/docs/getting-started.md`](/docs/getting-started.md)).
{% /callout %}

## Prerequisites

Before you begin, make sure you have:

- **Next.js 13+** (App Router)
- **React 18+**
- **Node.js 16+**
- A Brease CMS account with a site created

## Quick Start with CLI

The fastest way to get started is the CLI scaffolding tool:

```bash
npx brease-next
```

This interactive command creates a fully configured project with your CMS credentials, section mapping, and routing already wired up. See the [CLI Scaffolding](/docs/cli) page for details.

If you prefer manual setup, continue below.

---

## Step 1: Install the Package

```bash
npm install brease-next
```

## Step 2: Get Your API Credentials

You need two values from the Brease CMS dashboard:

1. Sign in at [app.brease.io](https://app.brease.io)
2. Open your site and navigate to **Site Settings**
3. In the **API Tokens** section, generate a new token (or copy an existing one)
4. Copy the **Environment ID** from the same settings page

![Site Settings - API Credentials](/images/img-2.png)

## Step 3: Configure Environment Variables

Create a `.env.local` file in your project root:

```env
BREASE_TOKEN=your_api_token_here
BREASE_ENV=your_environment_id_here
BREASE_DEFAULT_LOCALE=en
```

### Environment Variables Reference

| Variable                   | Required | Default | Description                                 |
| -------------------------- | -------- | ------- | ------------------------------------------- |
| `BREASE_TOKEN`             | Yes      | --      | API authentication token from Site Settings |
| `BREASE_ENV`               | Yes      | --      | Environment ID from Site Settings           |
| `BREASE_DEFAULT_LOCALE`    | Yes      | --      | Default locale code (e.g. `en`, `sk`)       |
| `BREASE_REVALIDATION_TIME` | No       | `30`    | ISR revalidation interval in seconds        |

## Step 4: Configure Next.js

Update your `next.config.ts` to support Brease media and redirects:

```typescript
import type { NextConfig } from 'next'
import { fetchRedirects } from 'brease-next/server'

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.brease.io',
        pathname: '/**',
      },
    ],
  },

  async redirects() {
    const result = await fetchRedirects()

    if (!result.success) {
      console.error('Failed to fetch redirects:', result.error)
      return []
    }

    return result.data.map((redirect) => ({
      source: redirect.source,
      destination: redirect.destination,
      permanent: redirect.type === '301' || redirect.type === '308',
    }))
  },
}

export default nextConfig
```

## Step 5: Create a Cached Page Fetcher

Create a shared, deduplicated page fetcher using React's `cache()`:

```typescript
// src/lib/brease/get-page.ts
import { cache } from 'react'
import { fetchPage } from 'brease-next'

export const getPage = cache(async (slug: string) => fetchPage(slug))
```

This ensures that your layout, `generateMetadata`, and page component all share a single request per render instead of making redundant API calls.

## Step 6: Create a Section Map

Create a configuration file that maps CMS section keys to React components:

```typescript
// src/lib/brease/brease-config.ts
import { ComponentType } from 'react'
import HeroSection from '@/sections/hero-section'
import TextSection from '@/sections/text-section'

export const sectionMap: Record<
  string,
  ComponentType<Record<string, unknown>>
> = {
  hero: HeroSection,
  text: TextSection,
}

export const contextConfig = {
  navigations: [
    // { key: 'header', id: 'your-navigation-uuid' },
    // { key: 'footer', id: 'your-navigation-uuid' },
  ],
  collections: [
    // { key: 'faqs', id: 'your-collection-uuid' },
  ],
  userParams: {},
}
```

## Step 7: Set Up Root Layout

Wrap your application with `BreaseContext` in the root layout. The `slug` prop tells the context which page is currently active:

```typescript
// src/app/[[...slug]]/layout.tsx
import { BreaseContext } from 'brease-next'
import { contextConfig } from '@/lib/brease/brease-config'
import { getPage } from '@/lib/brease/get-page'
import 'brease-next/styles'

export default async function SlugLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''

  return (
    <BreaseContext config={contextConfig} slug={pageSlug} getPage={getPage}>
      {children}
    </BreaseContext>
  )
}
```

Key points:

- The `slug` prop accepts the current route slug, optionally with a locale prefix (e.g. `sk/about-us`).
- The `getPage` prop passes your cached fetcher so the context can share page data with the page component.
- `import 'brease-next/styles'` loads the styles required for CMS preview toolbar functionality.

## Step 8: Create the Catch-All Page

```typescript
// src/app/[[...slug]]/page.tsx
import { BreasePage, generateBreasePageMetadata, ensureSuccess } from 'brease-next'
import { sectionMap } from '@/lib/brease/brease-config'
import { getPage } from '@/lib/brease/get-page'
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'

type Props = { params: Promise<{ slug?: string[] }> }

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''
  const result = await getPage(pageSlug)

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data)
}

export default async function Page({ params }: Props) {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''
  const result = await getPage(pageSlug)

  if (!result.success) {
    if (result.status === 404) return notFound()
    throw new Error(result.error)
  }

  return <BreasePage page={result.data} sectionMap={sectionMap} />
}
```

## Verification

Start the development server and check for errors:

```bash
npm run dev
```

Open your browser to `http://localhost:3000`. If everything is configured correctly:

- The page should render without console errors
- You should see your CMS content (or an empty page if no sections are configured yet)

If you see errors about missing environment variables, double-check your `.env.local` file and restart the dev server.

## Next Steps

- [API Reference](/docs/api-reference) -- all available functions and types
- [Components](/docs/components) -- BreasePage, BreaseImage, BreaseLink, and more
- [Context & Hooks](/docs/context-and-hooks) -- BreaseContext configuration and useBrease()
- [SEO & Metadata](/docs/seo-and-metadata) -- metadata, robots.txt, sitemap, structured data
- [CLI Scaffolding](/docs/cli) -- automated project setup


---

# API Reference

Source: https://docs.brease.io/docs/api-reference

Complete reference for all `brease-next` exports: functions, types, components, and utilities.

## Import

All public exports are available from the main package entry:

```typescript
import {
  // Functions
  fetchSite,
  fetchPage,
  fetchAllPages,
  fetchCollectionById,
  fetchEntryById,
  fetchNavigation,
  fetchAlternateLinks,
  fetchLocales,
  fetchRedirects,
  generateBreasePageParams,
  generateBreasePageMetadata,
  generateBreaseRobots,
  generateSitemap,
  validateBreaseConfig,
  ensureSuccess,

  // Components
  BreasePage,
  BreaseImage,
  BreaseLink,
  BreaseStructuredData,
  BreaseCustomCode,

  // Context & Hooks
  BreaseContext,
  useBrease,

  // Error class
  BreaseFetchError,
} from 'brease-next'
```

Types can be imported separately:

```typescript
import type {
  BreaseSection,
  SectionElementProps,
  BreaseMedia,
  BreaseMediaVariant,
  BreaseNavigation,
  BreaseNavigationItem,
  BreaseLinkData,
  BreasePageType,
  BreaseSite,
  BreaseConfig,
  BreaseCollection,
  BreaseCollectionEntry,
  BreaseResponse,
  BreaseContextConfig,
  BreaseGetPage,
  GenerateBreaseRobotsOptions,
} from 'brease-next'
```

---

## Configuration

### validateBreaseConfig

Reads and validates environment variables. Returns a `BreaseConfig` object. Throws if any required variable is missing.

```typescript
function validateBreaseConfig(): BreaseConfig
```

**Environment variables read:**

| Variable | Required | Default |
|---|---|---|
| `BREASE_TOKEN` | Yes | -- |
| `BREASE_ENV` | Yes | -- |
| `BREASE_DEFAULT_LOCALE` | Yes | -- |
| `BREASE_BASE_URL` | No | `"https://api.brease.io"` |
| `BREASE_REVALIDATION_TIME` | No | `30` |

**Returns:** `BreaseConfig`

```typescript
interface BreaseConfig {
  baseUrl: string
  token: string
  env: string
  defaultLocale: string
  revalidationTime: number
}
```

**Example:**

```typescript
import { validateBreaseConfig } from 'brease-next'

const config = validateBreaseConfig()
console.log(config.defaultLocale) // "en"
console.log(config.revalidationTime) // 30
```

---

## Page Functions

### fetchPage

Fetches a single page by slug. The slug can include a locale prefix (e.g. `sk/about-us`), and the locale is derived from the slug automatically.

```typescript
function fetchPage(pageSlug: string): Promise<BreaseResponse<BreasePage>>
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `pageSlug` | `string` | Page slug, optionally prefixed with locale (e.g. `"about-us"`, `"sk/about-us"`) |

**Returns:** `Promise<BreaseResponse<BreasePage>>`

**Example:**

```typescript
import { fetchPage, ensureSuccess } from 'brease-next'

// Default locale
const result = await fetchPage('about-us')

if (result.success) {
  console.log(result.data.name)
  console.log(result.data.sections.length)
}

// With locale prefix
const skResult = await fetchPage('sk/o-nas')

// Using ensureSuccess to throw on error
const page = ensureSuccess(await fetchPage('about-us'))
```

---

### fetchAllPages

Fetches all page slugs for a given locale. Used primarily for static generation.

```typescript
function fetchAllPages(locale: string): Promise<BreaseResponse<{ slug: string }[]>>
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `locale` | `string` | Locale code (e.g. `"en"`, `"sk"`) |

**Returns:** `Promise<BreaseResponse<{ slug: string }[]>>`

**Example:**

```typescript
import { fetchAllPages } from 'brease-next'

const result = await fetchAllPages('en')

if (result.success) {
  console.log('Total pages:', result.data.length)
  result.data.forEach(page => console.log(page.slug))
}
```

---

### fetchAlternateLinks

Fetches alternate language links for a page, used for hreflang tags.

```typescript
function fetchAlternateLinks(
  pageSlug: string
): Promise<BreaseResponse<Languages<string | URL | AlternateLinkDescriptor[] | null>>>
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `pageSlug` | `string` | Page slug |

**Returns:** `Promise<BreaseResponse<Languages<...>>>` -- compatible with Next.js `metadata.alternates.languages`

**Example:**

```typescript
import { fetchAlternateLinks } from 'brease-next'

const result = await fetchAlternateLinks('about-us')

if (result.success) {
  // result.data can be passed directly to metadata.alternates.languages
  console.log(result.data)
}
```

---

## Collection Functions

### fetchCollectionById

Fetches a collection and all its entries by collection ID and locale.

```typescript
function fetchCollectionById(
  collectionId: string,
  locale: string
): Promise<BreaseResponse<BreaseCollection>>
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `collectionId` | `string` | Collection UUID |
| `locale` | `string` | Locale code |

**Returns:** `Promise<BreaseResponse<BreaseCollection>>`

**Example:**

```typescript
import { fetchCollectionById, ensureSuccess } from 'brease-next'

const result = await fetchCollectionById('col-a01c8223-4e4a-40aa-90d9-70149e87322c', 'en')

if (result.success) {
  console.log('Collection:', result.data.name)
  result.data.entries.forEach(entry => {
    console.log(entry.uuid, entry.name)
  })
}
```

---

### fetchEntryById

Fetches a single collection entry by its UUID.

```typescript
function fetchEntryById(
  collectionId: string,
  entryId: string,
  locale: string
): Promise<BreaseResponse<BreaseCollectionEntry>>
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `collectionId` | `string` | Collection UUID |
| `entryId` | `string` | Entry UUID |
| `locale` | `string` | Locale code |

**Returns:** `Promise<BreaseResponse<BreaseCollectionEntry>>`

**Example:**

```typescript
import { fetchEntryById, ensureSuccess } from 'brease-next'

const result = await fetchEntryById(
  'col-a01c8223-4e4a-40aa-90d9-70149e87322c',
  'entry-uuid-here',
  'en'
)

if (result.success) {
  const entry = result.data
  console.log(entry.uuid, entry.name)
  console.log(entry.elements)
}
```

---

## Navigation & Site Functions

### fetchNavigation

Fetches a navigation structure by ID and locale.

```typescript
function fetchNavigation(
  navigationId: string,
  locale: string
): Promise<BreaseResponse<BreaseNavigation>>
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `navigationId` | `string` | Navigation UUID |
| `locale` | `string` | Locale code |

**Returns:** `Promise<BreaseResponse<BreaseNavigation>>`

**Example:**

```typescript
import { fetchNavigation } from 'brease-next'

const result = await fetchNavigation('nav-a01c4cbb-21f7-46d5-a89c-564307998128', 'en')

if (result.success) {
  result.data.items.forEach(item => {
    console.log(item.label, item.value)
    if (item.isExternal) {
      console.log('External link:', item.value)
    }
    // Nested children
    item.children.forEach(child => {
      console.log('  ', child.label)
    })
  })
}
```

---

### fetchSite

Fetches site-level information.

```typescript
function fetchSite(): Promise<BreaseResponse<BreaseSite>>
```

**Returns:** `Promise<BreaseResponse<BreaseSite>>`

**Example:**

```typescript
import { fetchSite } from 'brease-next'

const result = await fetchSite()

if (result.success) {
  console.log(result.data.name)
  console.log(result.data.domain)
  console.log(result.data.hasMultiLocale)
  console.log(result.data.sitemapIndexing)
}
```

---

### fetchRedirects

Fetches all redirect rules configured in the CMS.

```typescript
function fetchRedirects(): Promise<BreaseResponse<BreaseRedirect[]>>
```

**Returns:** `Promise<BreaseResponse<BreaseRedirect[]>>`

**Example:**

```typescript
import { fetchRedirects } from 'brease-next'

const result = await fetchRedirects()

if (result.success) {
  result.data.forEach(redirect => {
    console.log(redirect.source, '->', redirect.destination, `(${redirect.type})`)
  })
}
```

Typically used in `next.config.ts`:

```typescript
import { fetchRedirects } from 'brease-next/server'

const nextConfig = {
  async redirects() {
    const result = await fetchRedirects()
    if (!result.success) return []

    return result.data.map((r) => ({
      source: r.source,
      destination: r.destination,
      permanent: r.type === '301' || r.type === '308',
    }))
  },
}
```

---

### fetchLocales

Fetches all configured locales for the site.

```typescript
function fetchLocales(): Promise<BreaseResponse<BreaseLocale[]>>
```

**Returns:** `Promise<BreaseResponse<BreaseLocale[]>>`

```typescript
interface BreaseLocale {
  uuid: string
  code: string
  name: string
  isDefault: boolean
}
```

**Example:**

```typescript
import { fetchLocales } from 'brease-next'

const result = await fetchLocales()

if (result.success) {
  result.data.forEach(locale => {
    console.log(locale.code, locale.name, locale.isDefault ? '(default)' : '')
  })
}
```

---

## Static Generation

### generateBreasePageParams

Generates static params for all pages across all locales. Iterates every locale and fetches all pages for each.

```typescript
function generateBreasePageParams(): Promise<{ locale: string; slug: string[] }[]>
```

**Returns:** `Promise<{ locale: string; slug: string[] }[]>`

**Example:**

```typescript
// src/app/[[...slug]]/page.tsx
import { generateBreasePageParams } from 'brease-next'

export async function generateStaticParams() {
  return generateBreasePageParams()
  // Returns:
  // [
  //   { locale: "en", slug: ["about-us"] },
  //   { locale: "en", slug: ["contact"] },
  //   { locale: "sk", slug: ["o-nas"] },
  //   { locale: "sk", slug: ["kontakt"] },
  // ]
}
```

---

## SEO Functions

### generateBreasePageMetadata

Generates a Next.js `Metadata` object from a `BreasePage` object. Note: this takes a **page object**, not a slug string.

```typescript
function generateBreasePageMetadata(
  page: BreasePage,
  options?: { metadataBase?: string | URL }
): Metadata
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `page` | `BreasePage` | The page object (fetched via `fetchPage`) |
| `options` | `{ metadataBase?: string \| URL }` | Optional. Base URL for resolving relative URLs |

**Returns:** Next.js `Metadata` object

**Generated fields:**
- `title` -- from `page.metaTitle`, falls back to `page.name`
- `description` -- from `page.metaDescription`
- `robots` -- respects `page.indexing` toggle
- `alternates` -- canonical URL from `page.canonicalUrl`, hreflang from `page.alternateLinks`
- `openGraph` -- from `page.openGraph` fields
- `twitter` -- from `page.twitterCard` fields

**Example:**

```typescript
import { fetchPage, generateBreasePageMetadata, type Metadata } from 'brease-next'

export async function generateMetadata(): Promise<Metadata> {
  const result = await fetchPage('about-us')

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data, {
    metadataBase: 'https://example.com',
  })
}
```

---

### generateBreaseRobots

Generates a `robots.txt` configuration object.

```typescript
function generateBreaseRobots(
  siteUrl: string,
  options?: GenerateBreaseRobotsOptions
): MetadataRoute.Robots
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `siteUrl` | `string` | Your site's public URL |
| `options` | `GenerateBreaseRobotsOptions` | Optional overrides |

```typescript
interface GenerateBreaseRobotsOptions {
  rules?: MetadataRoute.Robots['rules']
  sitemap?: string | string[]
  host?: string
}
```

**Default behavior:** Allows all crawlers, sets sitemap to `{siteUrl}/sitemap.xml`.

**Example:**

```typescript
// src/app/robots.ts
import { generateBreaseRobots } from 'brease-next'
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return generateBreaseRobots('https://example.com')
}
```

---

### generateSitemap

Fetches sitemap data from the CMS API.

```typescript
function generateSitemap(): Promise<BreaseResponse<MetadataRoute.Sitemap>>
```

**Returns:** `Promise<BreaseResponse<MetadataRoute.Sitemap>>`

**Example:**

```typescript
// src/app/sitemap.ts
import { generateSitemap, ensureSuccess } from 'brease-next'
import type { MetadataRoute } from 'next'

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const result = await generateSitemap()
  return result.success ? result.data : []
}
```

---

## Error Handling

### ensureSuccess

Unwraps a `BreaseResponse`, returning the data on success or throwing a `BreaseFetchError` on failure.

```typescript
function ensureSuccess<T>(result: BreaseResponse<T>): T
```

**Parameters:**

| Name | Type | Description |
|---|---|---|
| `result` | `BreaseResponse<T>` | Any Brease API response |

**Returns:** `T` -- the unwrapped data

**Throws:** `BreaseFetchError` if `result.success` is `false`

**Example:**

```typescript
import { fetchPage, ensureSuccess } from 'brease-next'

// Throws BreaseFetchError if the request failed
const page = ensureSuccess(await fetchPage('about-us'))
console.log(page.name)
```

---

### BreaseFetchError

Error class thrown by `ensureSuccess` and other internal operations when an API request fails.

```typescript
class BreaseFetchError extends Error {
  status: number
  endpoint?: string
}
```

**Properties:**

| Name | Type | Description |
|---|---|---|
| `message` | `string` | Error description |
| `status` | `number` | HTTP status code |
| `endpoint` | `string \| undefined` | The API endpoint that failed |

**Example:**

```typescript
import { fetchPage, ensureSuccess, BreaseFetchError } from 'brease-next'

try {
  const page = ensureSuccess(await fetchPage('nonexistent'))
} catch (error) {
  if (error instanceof BreaseFetchError) {
    console.error(`API error ${error.status}: ${error.message}`)
    console.error('Endpoint:', error.endpoint)
  }
}
```

---

## Response Type

### BreaseResponse\<T\>

Discriminated union returned by all fetch functions. Check `success` before accessing data.

```typescript
type BreaseResponse<T> =
  | { success: true; data: T; status: number }
  | { success: false; error: string; status: number; endpoint?: string }
```

**Pattern:**

```typescript
const result = await fetchPage('about-us')

if (result.success) {
  // result.data is T (BreasePage in this case)
  console.log(result.data.name)
} else {
  // result.error is string
  console.error(result.error, result.status)
}
```

---

## Type Definitions

### BreasePage

```typescript
interface BreasePage {
  name: string | null
  slug: string | null
  uuid: string | null
  indexing: boolean
  variables: any | null
  customCode: string | null
  structuredData: object[] | null
  openGraph: {
    url: string | null
    type: string | null
    image: string | null
    title: string | null
    description: string | null
  }
  twitterCard: {
    site: string | null
    type: string | null
    image: string | null
    title: string | null
    creator: string | null
    description: string | null
  }
  canonicalUrl: string | null
  metaTitle: string | null
  metaDescription: string | null
  references: object[] | null
  alternateLinks: Record<string, string> | null
  parentPageSlug: string
  sections: BreaseSection[]
}
```

### BreaseSection

```typescript
interface BreaseSection {
  name: string
  page_section_uuid: string
  key: string
  uuid: string
  elements: SectionElementProps
}
```

### SectionElementProps

```typescript
type SectionElementProps = Record<string, unknown>
```

### BreaseMedia

```typescript
interface BreaseMedia {
  alt: string | null
  duration: number | null
  extension: string
  height: number
  mimeGroup: string
  mimeType: string
  name: string
  path: string
  size: string
  thumbnail: string
  uuid: string
  width: number
  variants: Record<string, BreaseMediaVariant>
}
```

### BreaseMediaVariant

```typescript
interface BreaseMediaVariant {
  alt: string | null
  extension: string
  height: number
  mimeType: string
  path: string
  size: string
  type: string
  width: number
}
```

### BreaseNavigation

```typescript
interface BreaseNavigation {
  name: string
  uuid: string
  description: string | null
  items: BreaseNavigationItem[]
}
```

### BreaseNavigationItem

```typescript
interface BreaseNavigationItem extends BreaseLinkData {
  uuid: string
  children: BreaseNavigationItem[]
}
```

### BreaseLinkData

```typescript
interface BreaseLinkData {
  label: string
  isExternal: boolean
  value: string
  target: '_blank' | '_self' | null
}
```

### BreaseSite

```typescript
interface BreaseSite {
  uuid: string
  name: string
  title: string | null
  domain: string
  published: boolean
  status: string
  hasMultiLocale: boolean | null
  sitemapIndexing: boolean
  customCode: string | null
}
```

### BreaseCollection

```typescript
interface BreaseCollection {
  uuid: string
  name: string
  description: string | null
  status: string
  entries: BreaseCollectionEntry[]
}
```

### BreaseCollectionEntry

```typescript
interface BreaseCollectionEntry {
  uuid: string
  name: string
  elements: Record<string, unknown>
}
```

### BreaseRedirect

```typescript
interface BreaseRedirect {
  uuid: string
  source: string
  destination: string
  type: '301' | '302' | '307' | '308'
}
```

### BreaseLocale

```typescript
interface BreaseLocale {
  uuid: string
  code: string
  name: string
  isDefault: boolean
}
```

### BreaseContextConfig

```typescript
interface BreaseContextConfig {
  navigations: Array<{ key: string; id: string }>
  collections?: Array<{ key: string; id: string }>
  userParams: any
}
```

### BreaseGetPage

```typescript
type BreaseGetPage = (slug: string) => Promise<BreaseResponse<BreasePage>>
```

### GenerateBreaseRobotsOptions

```typescript
interface GenerateBreaseRobotsOptions {
  rules?: MetadataRoute.Robots['rules']
  sitemap?: string | string[]
  host?: string
}
```

---

## Next Steps

- [Components](/docs/components) -- BreasePage, BreaseImage, BreaseLink, and more
- [Context & Hooks](/docs/context-and-hooks) -- BreaseContext and useBrease()
- [SEO & Metadata](/docs/seo-and-metadata) -- metadata generation, robots, sitemap


---

# Components

Source: https://docs.brease.io/docs/components

The `brease-next` package exports five React components for rendering CMS content.

| Component | Type | Purpose |
|---|---|---|
| `BreasePage` | Client | Renders page sections using a component map |
| `BreaseImage` | Client | Responsive image rendering with variant support |
| `BreaseLink` | Client | Smart internal/external link handling |
| `BreaseStructuredData` | Server | JSON-LD structured data injection |
| `BreaseCustomCode` | Server | Custom HTML/script injection |

---

## BreasePage

Client component that maps CMS page sections to React components and renders them in order.

### Import

```typescript
import { BreasePage } from 'brease-next'
```

### Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `page` | `BreasePage` | Yes | The page object from `fetchPage` |
| `sectionMap` | `Record<string, ComponentType<Record<string, unknown>>>` | Yes | Maps section keys to React components |

### How It Works

1. Iterates through `page.sections`
2. For each section, looks up the component from `sectionMap` using `section.key`
3. Spreads `section.elements` as props to the matched component
4. Renders with `section.uuid` as the React key
5. If no matching component is found for a section key, it is skipped

When rendered inside a `BreaseContext`, the component automatically uses the page from context if available. This enables live preview mode where the CMS pushes page updates via PostMessage, and BreasePage re-renders with the new content without a page reload.

### Usage

```typescript
// src/lib/brease/brease-config.ts
import { ComponentType } from 'react'
import HeroSection from '@/sections/hero-section'
import FeaturesSection from '@/sections/features-section'
import ContactSection from '@/sections/contact-section'

export const sectionMap: Record<string, ComponentType<Record<string, unknown>>> = {
  hero: HeroSection,
  features: FeaturesSection,
  contact: ContactSection,
}
```

```typescript
// src/app/[[...slug]]/page.tsx
import { BreasePage, ensureSuccess } from 'brease-next'
import { sectionMap } from '@/lib/brease/brease-config'
import { getPage } from '@/lib/brease/get-page'
import { notFound } from 'next/navigation'

export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''
  const result = await getPage(pageSlug)

  if (!result.success) {
    if (result.status === 404) return notFound()
    throw new Error(result.error)
  }

  return <BreasePage page={result.data} sectionMap={sectionMap} />
}
```

### Section Components

All section components **must** include `'use client'` at the top of the file. `BreasePage` is a client component and renders sections within a client component tree — server components cannot be used in the section map.

Each section component receives `section.elements` spread as props. Type your props based on the elements you configured in the CMS:

```typescript
'use client'

import { BreaseMedia, BreaseLinkData } from 'brease-next'

interface HeroSectionProps {
  title: string
  subtitle: string
  heroImage: BreaseMedia
  ctaButton: BreaseLinkData
}

export default function HeroSection({ title, subtitle, heroImage, ctaButton }: HeroSectionProps) {
  return (
    <section>
      <h1>{title}</h1>
      {subtitle && <p>{subtitle}</p>}
    </section>
  )
}
```

---

## BreaseImage

Wraps the Next.js `Image` component with Brease media data. Supports responsive variant-based srcSet and named variant selection.

### Import

```typescript
import { BreaseImage } from 'brease-next'
```

### Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `breaseImage` | `BreaseMedia` | Yes | The media object from CMS elements |
| `variant` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'hd' \| 'original'` | No | Render a specific variant instead of responsive srcSet |
| `alt` | `string` | No | Override the alt text from the media object |
| `sizes` | `string` | No | The `sizes` attribute for responsive images |
| `...rest` | any Next.js Image props | No | All other props are passed to the underlying `Image` component |

### Variant Behavior

When **no variant** is specified, the component generates a responsive srcSet from all available variants. The variants are ordered by size: `sm`, `md`, `lg`, `xl`, `2xl`, `hd`, `original`.

When a **specific variant** is provided, only that variant is rendered.

### Usage

**Responsive (automatic srcSet):**

```typescript
import { BreaseImage, type BreaseMedia } from 'brease-next'

interface HeroProps {
  heroImage: BreaseMedia
}

export default function HeroSection({ heroImage }: HeroProps) {
  return (
    <BreaseImage
      breaseImage={heroImage}
      sizes="100vw"
      className="w-full h-auto"
      priority
    />
  )
}
```

**Specific variant:**

```typescript
<BreaseImage
  breaseImage={thumbnail}
  variant="sm"
  className="rounded-full w-12 h-12"
/>
```

**With alt text override:**

```typescript
<BreaseImage
  breaseImage={productImage}
  alt="Product hero shot"
  sizes="(max-width: 768px) 100vw, 50vw"
/>
```

### Null Handling

Returns `null` if `breaseImage` is falsy, so you can safely pass optional media elements without conditional rendering.

---

## BreaseLink

Smart link component that renders internal links with Next.js `Link` and external links with a native `<a>` tag.

### Import

```typescript
import { BreaseLink } from 'brease-next'
```

### Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `linkData` | `BreaseLinkData` | Yes | Link data object from CMS elements |
| `children` | `ReactNode` | Yes | Link content |
| `...rest` | anchor/Link props | No | Additional props passed to the underlying element |

### BreaseLinkData Type

```typescript
interface BreaseLinkData {
  label: string       // Display label (you can use children instead)
  isExternal: boolean // Whether the link points to an external URL
  value: string       // The URL or path
  target: '_blank' | '_self' | null
}
```

### Behavior

- **Internal links** (`isExternal: false`): rendered with Next.js `<Link>` for client-side navigation
- **External links** (`isExternal: true`): rendered with a native `<a>` tag
- When `target` is `'_blank'`, `rel="noopener noreferrer"` is automatically added for security

### Usage

```typescript
import { BreaseLink, type BreaseLinkData } from 'brease-next'

interface CtaSectionProps {
  heading: string
  ctaLink: BreaseLinkData
}

export default function CtaSection({ heading, ctaLink }: CtaSectionProps) {
  return (
    <section>
      <h2>{heading}</h2>
      <BreaseLink linkData={ctaLink} className="btn btn-primary">
        {ctaLink.label}
      </BreaseLink>
    </section>
  )
}
```

**With custom children:**

```typescript
<BreaseLink linkData={link}>
  <span className="icon">-></span>
  <span>Read more</span>
</BreaseLink>
```

---

## BreaseStructuredData

Server component that renders JSON-LD structured data from `page.structuredData` as a `<script type="application/ld+json">` tag.

### Import

```typescript
import { BreaseStructuredData } from 'brease-next'
```

### Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `page` | `BreasePage` | Yes | The page object containing `structuredData` |

### Behavior

- Reads `page.structuredData` (an array of JSON-LD objects)
- Renders each as a `<script type="application/ld+json">` tag
- Renders nothing if `page.structuredData` is `null` or empty

### Usage

```typescript
import { BreaseStructuredData, ensureSuccess, fetchPage } from 'brease-next'

export default async function Page() {
  const page = ensureSuccess(await fetchPage('about-us'))

  return (
    <>
      <BreaseStructuredData page={page} />
      {/* rest of page */}
    </>
  )
}
```

Structured data is managed in the CMS page settings. Common schemas include Organization, Article, Product, FAQ, and BreadcrumbList.

---

## BreaseCustomCode

Server component that renders custom HTML and scripts from `page.customCode`. Useful for analytics snippets, third-party widgets, or page-specific scripts managed in the CMS.

### Import

```typescript
import { BreaseCustomCode } from 'brease-next'
```

### Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `page` | `BreasePage` | Yes | The page object containing `customCode` |

### Behavior

- Reads `page.customCode` (a string of HTML/script content)
- Renders the content using `dangerouslySetInnerHTML`
- Renders nothing if `page.customCode` is `null` or empty

### Usage

```typescript
import { BreaseCustomCode, ensureSuccess, fetchPage } from 'brease-next'

export default async function Page() {
  const page = ensureSuccess(await fetchPage('about-us'))

  return (
    <>
      {/* page content */}
      <BreaseCustomCode page={page} />
    </>
  )
}
```

Custom code is managed per page in the CMS page settings. Site-wide custom code is available via `BreaseSite.customCode`.

---

## Next Steps

- [Context & Hooks](/docs/context-and-hooks) -- BreaseContext setup and useBrease()
- [SEO & Metadata](/docs/seo-and-metadata) -- metadata, structured data, and robots
- [API Reference](/docs/api-reference) -- all functions and types


---

# Context & Hooks

Source: https://docs.brease.io/docs/context-and-hooks

The `BreaseContext` server component and `useBrease()` hook provide a data layer that fetches navigations, page data, collections, and locales on the server and makes them available to all client components in your app.

---

## BreaseContext

A server component that wraps your page tree, fetches shared data, and provides it via React Context.

### Import

```typescript
import { BreaseContext } from 'brease-next'
```

### Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `config` | `BreaseContextConfig` | Yes | Defines which navigations and collections to fetch |
| `slug` | `string` | Yes | Current route slug. May include locale prefix (e.g. `"sk/about-us"`) |
| `getPage` | `BreaseGetPage` | No | Cached page fetcher. Recommended for deduplication |
| `children` | `ReactNode` | Yes | Child components |

### BreaseContextConfig

```typescript
interface BreaseContextConfig {
  navigations: Array<{ key: string; id: string }>
  collections?: Array<{ key: string; id: string }>
  userParams: any
}
```

- **navigations**: Array of navigation resources to fetch. Each entry has a `key` (used to access the navigation in `useBrease()`) and an `id` (the navigation UUID from the CMS).
- **collections**: Optional array of collection resources. Same key/id pattern as navigations.
- **userParams**: Arbitrary data passed through to client components. Useful for feature flags, configuration, or any custom data your components need.

### What It Fetches

On each render, BreaseContext fetches the following data server-side:

1. **Locales** -- all configured locales via `fetchLocales()`
2. **Page** -- the current page via `getPage(slug)` or `fetchPage(slug)`
3. **Navigations** -- each configured navigation via `fetchNavigation(id, locale)`, using the locale derived from the slug
4. **Collections** -- each configured collection (if any) via `fetchCollectionById(id, locale)`
5. **Alternate links** -- language alternates for the current page

All fetch errors are logged to the console but do not throw. If a navigation or collection fails to load, it will be absent from the context data.

### The slug Prop

The `slug` prop tells the context which page is currently active. Pass the raw route slug from your catch-all route params:

```typescript
// src/app/[[...slug]]/layout.tsx
export default async function SlugLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''

  return (
    <BreaseContext config={contextConfig} slug={pageSlug} getPage={getPage}>
      {children}
    </BreaseContext>
  )
}
```

The locale is automatically derived from the slug. For example, `"sk/about-us"` yields locale `"sk"` and page slug `"about-us"`. A slug without a locale prefix (e.g. `"about-us"`) uses the default locale from `BREASE_DEFAULT_LOCALE`.

### The getPage Prop

The optional `getPage` prop accepts a cached page fetcher function. This is the recommended pattern because your layout, `generateMetadata`, and page component all need the same page data. Without caching, each would make a separate API request. With React's `cache()`, they share one request per render.

```typescript
type BreaseGetPage = (slug: string) => Promise<BreaseResponse<BreasePage>>
```

If `getPage` is not provided, the context calls `fetchPage(slug)` directly.

### Setup Example

```typescript
// src/lib/brease/brease-config.ts
export const contextConfig = {
  navigations: [
    { key: 'header', id: 'nav-a01c4cbb-21f7-46d5-a89c-564307998128' },
    { key: 'footer', id: 'nav-b12d5ebb-33f8-57e6-b90d-675418099239' },
  ],
  collections: [
    { key: 'faqs', id: 'col-c23e6fcc-44g9-68f7-c01e-786529100340' },
  ],
  userParams: {
    showBanner: true,
  },
}
```

```typescript
// src/app/[[...slug]]/layout.tsx
import { BreaseContext } from 'brease-next'
import { contextConfig } from '@/lib/brease/brease-config'
import { getPage } from '@/lib/brease/get-page'
import 'brease-next/styles'

export default async function SlugLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''

  return (
    <BreaseContext config={contextConfig} slug={pageSlug} getPage={getPage}>
      <Header />
      <main>{children}</main>
      <Footer />
    </BreaseContext>
  )
}
```

---

## Cached Page Fetcher Pattern

Create a cached wrapper around `fetchPage` using React's `cache()` function:

```typescript
// src/lib/brease/get-page.ts
import { cache } from 'react'
import { fetchPage } from 'brease-next'

export const getPage = cache(async (slug: string) => fetchPage(slug))
```

### Why This Matters

In a typical Next.js App Router setup, the same page data is needed in multiple places during a single render:

1. **`generateMetadata`** -- to build the page title, description, and Open Graph tags
2. **Layout component** -- to pass to `BreaseContext` for navigation context
3. **Page component** -- to render with `BreasePage`

Without `cache()`, each of these would trigger a separate HTTP request to the Brease API. With `cache()`, React deduplicates calls with the same arguments within a single server render, so only one request is made regardless of how many times `getPage(slug)` is called.

### Usage Across Files

```typescript
// In generateMetadata
import { getPage } from '@/lib/brease/get-page'

export async function generateMetadata({ params }) {
  const { slug } = await params
  const result = await getPage(slug ? slug.join('/') : '')
  // ...
}
```

```typescript
// In the page component
export default async function Page({ params }) {
  const { slug } = await params
  const result = await getPage(slug ? slug.join('/') : '')
  // Same call, same cache -- no extra request
}
```

---

## useBrease() Hook

Client-side hook that provides access to all data fetched by `BreaseContext`.

### Import

```typescript
import { useBrease } from 'brease-next'
```

### Requirements

- Must be called inside a component wrapped by `BreaseContext`
- Must be used in a client component (`'use client'`)
- Throws an error if used outside of `BreaseContext`

### Return Value

The hook returns a `BreaseContextData` object:

```typescript
const {
  navigations,
  collections,
  availableLocales,
  locale,
  userParams,
  pageSlug,
  page,
  alternateLinks,
  references,
  setAlternateLinks,
} = useBrease()
```

### Properties

| Property | Type | Description |
|---|---|---|
| `navigations` | `Record<string, BreaseNavigation>` | Navigations keyed by the `key` you defined in config |
| `collections` | `Record<string, BreaseCollection> \| undefined` | Collections keyed by config key. Undefined if none configured |
| `availableLocales` | `string[]` | All locale codes available on the site |
| `locale` | `string` | The current locale, derived from the slug |
| `userParams` | `any` | The `userParams` value from your config |
| `pageSlug` | `string` | The current page slug (without locale prefix) |
| `page` | `BreasePage` | The current page object |
| `alternateLinks` | `Record<string, string>` | Alternate language URLs for the current page |
| `references` | `object[]` | Page references |
| `setAlternateLinks` | `(links: Record<string, string>) => void` | Function to update alternate links client-side |

### Preview Mode

The `page` property updates automatically when the CMS sends live content updates in preview mode (via PostMessage). This means components using `useBrease().page` will re-render with the latest CMS edits without a page reload.

### Usage Examples

**Navigation component:**

```typescript
'use client'

import { useBrease, BreaseLink } from 'brease-next'

export default function Header() {
  const { navigations } = useBrease()
  const headerNav = navigations.header

  if (!headerNav) return null

  return (
    <header>
      <nav>
        <ul>
          {headerNav.items.map(item => (
            <li key={item.uuid}>
              <BreaseLink linkData={item}>{item.label}</BreaseLink>
            </li>
          ))}
        </ul>
      </nav>
    </header>
  )
}
```

**Locale switcher:**

```typescript
'use client'

import { useBrease } from 'brease-next'
import Link from 'next/link'

export default function LocaleSwitcher() {
  const { availableLocales, locale, alternateLinks } = useBrease()

  return (
    <div>
      {availableLocales.map(loc => (
        <Link
          key={loc}
          href={alternateLinks[loc] || `/${loc}`}
          className={loc === locale ? 'font-bold' : ''}
        >
          {loc.toUpperCase()}
        </Link>
      ))}
    </div>
  )
}
```

**Accessing collections:**

```typescript
'use client'

import { useBrease } from 'brease-next'

export default function FAQList() {
  const { collections } = useBrease()
  const faqs = collections?.faqs

  if (!faqs) return null

  return (
    <dl>
      <h2>Frequently Asked Questions</h2>
      {faqs.entries.map(entry => (
        <div key={entry.uuid}>
          <dt className="font-semibold">{entry.elements.question as string}</dt>
          <dd>{entry.elements.answer as string}</dd>
        </div>
      ))}
    </dl>
  )
}
```

**Using userParams:**

```typescript
'use client'

import { useBrease } from 'brease-next'

export default function Banner() {
  const { userParams } = useBrease()

  if (!userParams.showBanner) return null

  return <div className="banner">Special offer!</div>
}
```

---

## Next Steps

- [Components](/docs/components) -- BreasePage, BreaseImage, BreaseLink
- [SEO & Metadata](/docs/seo-and-metadata) -- metadata generation with page data
- [Preview Integration](/docs/preview-integration) -- how live preview works with context


---

# SEO & Metadata

Source: https://docs.brease.io/docs/seo-and-metadata

The `brease-next` package provides functions and components for generating SEO metadata, robots.txt, sitemaps, structured data, and custom code injection -- all driven by data managed in the Brease CMS.

---

## generateBreasePageMetadata

Generates a Next.js `Metadata` object from a `BreasePage` object. This is the primary way to set page-level SEO tags.

**Important:** This function takes a **page object** (the result of `fetchPage`), not a slug string.

### Signature

```typescript
function generateBreasePageMetadata(
  page: BreasePage,
  options?: { metadataBase?: string | URL }
): Metadata
```

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | `BreasePage` | Yes | The page object from `fetchPage` |
| `options` | `{ metadataBase?: string \| URL }` | No | Base URL for resolving relative URLs in Open Graph images, canonical URLs, etc. |

### Generated Metadata Fields

| Metadata Field | Source | Fallback |
|---|---|---|
| `title` | `page.metaTitle` | `page.name` |
| `description` | `page.metaDescription` | -- |
| `robots.index` | `page.indexing` | -- |
| `robots.follow` | `page.indexing` | -- |
| `alternates.canonical` | `page.canonicalUrl` | -- |
| `alternates.languages` | `page.alternateLinks` | -- |
| `openGraph.url` | `page.openGraph.url` | -- |
| `openGraph.type` | `page.openGraph.type` | -- |
| `openGraph.title` | `page.openGraph.title` | -- |
| `openGraph.description` | `page.openGraph.description` | -- |
| `openGraph.images` | `page.openGraph.image` | -- |
| `twitter.site` | `page.twitterCard.site` | -- |
| `twitter.card` | `page.twitterCard.type` | -- |
| `twitter.title` | `page.twitterCard.title` | -- |
| `twitter.description` | `page.twitterCard.description` | -- |
| `twitter.creator` | `page.twitterCard.creator` | -- |
| `twitter.images` | `page.twitterCard.image` | -- |

### Usage

```typescript
// src/app/[[...slug]]/page.tsx
import { generateBreasePageMetadata } from 'brease-next'
import { getPage } from '@/lib/brease/get-page'
import type { Metadata } from 'next'

type Props = { params: Promise<{ slug?: string[] }> }

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''
  const result = await getPage(pageSlug)

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data, {
    metadataBase: 'https://example.com',
  })
}
```

---

## generateBreaseRobots

Generates a `robots.txt` configuration object for the Next.js Metadata API.

### Signature

```typescript
function generateBreaseRobots(
  siteUrl: string,
  options?: GenerateBreaseRobotsOptions
): MetadataRoute.Robots
```

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `siteUrl` | `string` | Yes | Your site's public URL (e.g. `"https://example.com"`) |
| `options` | `GenerateBreaseRobotsOptions` | No | Override default rules, sitemap, or host |

```typescript
interface GenerateBreaseRobotsOptions {
  rules?: MetadataRoute.Robots['rules']
  sitemap?: string | string[]
  host?: string
}
```

### Default Behavior

Without options, the function generates:
- **rules**: Allow all user agents on all paths
- **sitemap**: `{siteUrl}/sitemap.xml`

### Usage

```typescript
// src/app/robots.ts
import { generateBreaseRobots } from 'brease-next'
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return generateBreaseRobots('https://example.com')
}
```

**With custom options:**

```typescript
// src/app/robots.ts
import { generateBreaseRobots } from 'brease-next'
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return generateBreaseRobots('https://example.com', {
    rules: [
      { userAgent: '*', allow: '/' },
      { userAgent: 'Googlebot', allow: '/', disallow: '/private/' },
    ],
    sitemap: [
      'https://example.com/sitemap.xml',
      'https://example.com/blog-sitemap.xml',
    ],
    host: 'https://example.com',
  })
}
```

---

## generateSitemap

Fetches sitemap data from the Brease CMS API. Returns data in the format expected by Next.js `MetadataRoute.Sitemap`.

### Signature

```typescript
function generateSitemap(): Promise<BreaseResponse<MetadataRoute.Sitemap>>
```

### Usage

```typescript
// src/app/sitemap.ts
import { generateSitemap } from 'brease-next'
import type { MetadataRoute } from 'next'

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const result = await generateSitemap()
  return result.success ? result.data : []
}
```

The CMS controls which pages appear in the sitemap based on the **indexing** toggle on each page. Pages with indexing disabled are excluded.

---

## BreaseStructuredData

Server component that renders JSON-LD structured data from `page.structuredData`.

### How It Works

- Reads the `structuredData` field from the page object (an array of JSON-LD objects)
- Renders each object as a `<script type="application/ld+json">` tag
- Renders nothing if `structuredData` is `null` or an empty array

### Usage

```typescript
import { BreaseStructuredData, ensureSuccess, fetchPage } from 'brease-next'

export default async function Page() {
  const page = ensureSuccess(await fetchPage('about-us'))

  return (
    <>
      <BreaseStructuredData page={page} />
      {/* page content */}
    </>
  )
}
```

Structured data is managed per page in the CMS under the page's SEO settings. Common JSON-LD schemas include:

- **Organization** -- company info, logo, contact
- **Article** -- blog posts, news articles
- **Product** -- e-commerce product data
- **FAQ** -- frequently asked questions
- **BreadcrumbList** -- breadcrumb navigation

---

## BreaseCustomCode

Server component that renders custom HTML and scripts from `page.customCode`.

### How It Works

- Reads the `customCode` field from the page object (a string of HTML/script content)
- Renders the content using `dangerouslySetInnerHTML`
- Renders nothing if `customCode` is `null` or empty

### Usage

```typescript
import { BreaseCustomCode, ensureSuccess, fetchPage } from 'brease-next'

export default async function Page() {
  const page = ensureSuccess(await fetchPage('about-us'))

  return (
    <>
      {/* page content */}
      <BreaseCustomCode page={page} />
    </>
  )
}
```

Custom code is managed per page in the CMS page settings. Use cases include page-specific analytics events, third-party widget scripts, or embedded content.

For site-wide scripts, use `BreaseSite.customCode` (available via `fetchSite()`).

---

## Page-Level SEO Fields

These fields are managed in the CMS page editor and drive the metadata generation:

### Core SEO

| Field | Type | Description |
|---|---|---|
| `metaTitle` | `string \| null` | The `<title>` tag. Falls back to page name if not set |
| `metaDescription` | `string \| null` | The meta description tag |
| `canonicalUrl` | `string \| null` | Canonical URL for the page |
| `indexing` | `boolean` | Controls `robots` meta tag. When `false`, page is noindex/nofollow |

### Open Graph

| Field | Type | Description |
|---|---|---|
| `openGraph.url` | `string \| null` | og:url |
| `openGraph.type` | `string \| null` | og:type (e.g. "website", "article") |
| `openGraph.image` | `string \| null` | og:image URL |
| `openGraph.title` | `string \| null` | og:title |
| `openGraph.description` | `string \| null` | og:description |

### Twitter Card

| Field | Type | Description |
|---|---|---|
| `twitterCard.site` | `string \| null` | twitter:site handle |
| `twitterCard.type` | `string \| null` | Card type (e.g. "summary_large_image") |
| `twitterCard.image` | `string \| null` | twitter:image URL |
| `twitterCard.title` | `string \| null` | twitter:title |
| `twitterCard.creator` | `string \| null` | twitter:creator handle |
| `twitterCard.description` | `string \| null` | twitter:description |

### Advanced

| Field | Type | Description |
|---|---|---|
| `structuredData` | `object[] \| null` | Array of JSON-LD objects for structured data |
| `customCode` | `string \| null` | Arbitrary HTML/script injection |
| `alternateLinks` | `Record<string, string> \| null` | Locale-to-URL mapping for hreflang tags |

---

## Complete Setup Example

Here is a full example with all SEO features configured:

**robots.ts:**

```typescript
// src/app/robots.ts
import { generateBreaseRobots } from 'brease-next'
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return generateBreaseRobots('https://example.com')
}
```

**sitemap.ts:**

```typescript
// src/app/sitemap.ts
import { generateSitemap } from 'brease-next'
import type { MetadataRoute } from 'next'

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const result = await generateSitemap()
  return result.success ? result.data : []
}
```

**Page with metadata:**

```typescript
// src/app/[[...slug]]/page.tsx
import {
  BreasePage,
  BreaseStructuredData,
  BreaseCustomCode,
  generateBreasePageMetadata,
  ensureSuccess,
} from 'brease-next'
import { sectionMap } from '@/lib/brease/brease-config'
import { getPage } from '@/lib/brease/get-page'
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'

type Props = { params: Promise<{ slug?: string[] }> }

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''
  const result = await getPage(pageSlug)

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data, {
    metadataBase: 'https://example.com',
  })
}

export default async function Page({ params }: Props) {
  const { slug } = await params
  const pageSlug = slug ? slug.join('/') : ''
  const result = await getPage(pageSlug)

  if (!result.success) {
    if (result.status === 404) return notFound()
    throw new Error(result.error)
  }

  const page = result.data

  return (
    <>
      <BreaseStructuredData page={page} />
      <BreasePage page={page} sectionMap={sectionMap} />
      <BreaseCustomCode page={page} />
    </>
  )
}
```

---

## Next Steps

- [API Reference](/docs/api-reference) -- full function signatures and types
- [Components](/docs/components) -- all component props and usage
- [Preview Integration](/docs/preview-integration) -- live preview from the CMS


---

# Preview Integration

Source: https://docs.brease.io/docs/preview-integration

Brease CMS includes a live preview feature that renders your Next.js site inside an iframe and sends real-time content updates as editors make changes. The `brease-next` package handles this automatically with no additional configuration required.

---

## How It Works

When a content editor opens the page preview in the Brease CMS, the following happens:

1. The CMS loads your site in an iframe
2. The `BreaseClientProvider` (included inside `BreaseContext`) mounts a `BreasePreviewListener` component
3. The listener detects it is running inside an iframe (`window.self !== window.top`)
4. A PostMessage handshake establishes communication between the CMS and your site
5. The CMS sends live page updates as the editor modifies content
6. The `page` object in `useBrease()` updates automatically, causing components to re-render

No code changes are needed to enable preview mode. It activates automatically when your site is loaded in the CMS iframe.

---

## PostMessage Protocol

Communication between the CMS (parent frame) and your site (child frame) uses the browser PostMessage API.

### Messages from Your Site to CMS

| Message | Payload | When |
|---|---|---|
| `brease:ready` | -- | Sent when the preview listener mounts inside the iframe |
| `brease:edit-section` | `{ uuid: string, scrollY: number }` | Sent when an editor clicks the edit button on a section toolbar |

### Messages from CMS to Your Site

| Message | Payload | When |
|---|---|---|
| `brease:init-page` | `{ page: BreasePage }` | Sent when the CMS initializes or updates page content |

When the listener receives a `brease:init-page` message, it updates the page state in the context. This causes all components using `useBrease().page` or `BreasePage` to re-render with the new content.

---

## Section Toolbar

When your site is running inside the CMS iframe, the `BreasePage` component automatically renders a **SectionToolbar** overlay on each section. The toolbar displays:

- The section name
- An **edit** button that, when clicked, sends a `brease:edit-section` message to the parent frame with the section's UUID and the current scroll position

This allows editors to click directly on a section in the preview to jump to that section's settings in the CMS editor.

---

## Styles

To get the correct styling for the section toolbar and preview overlays, import the `brease-next` styles in your root layout:

```typescript
// src/app/layout.tsx (or your slug layout)
import 'brease-next/styles'
```

This import adds a small CSS file with styles for the toolbar overlay. It does not affect your site's appearance outside of preview mode.

---

## iframe Detection

The preview listener uses a simple check to determine if the site is running inside an iframe:

```typescript
window.self !== window.top
```

When this condition is `true`, the listener:
- Sends the `brease:ready` message to the parent frame
- Starts listening for `brease:init-page` messages
- Enables the section toolbar overlays in `BreasePage`

When the site is loaded normally (not in an iframe), none of the preview functionality activates.

---

## CORS and Content Security Policy

For the CMS to load your site in an iframe, your Next.js application may need to allow framing from the CMS domain. If your site has a strict Content Security Policy or X-Frame-Options header, you may need to update your `next.config.ts`:

```typescript
// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "frame-ancestors 'self' https://app.brease.io",
          },
        ],
      },
    ]
  },
}

export default nextConfig
```

Replace `https://app.brease.io` with your CMS instance domain if you are using a custom deployment.

If you are using a hosting platform that sets its own headers (e.g. Vercel), you may need to configure these headers in the platform's settings as well.

---

## Summary

| Feature | How It Works |
|---|---|
| Live content updates | Automatic via PostMessage when in iframe |
| Section toolbar | Rendered by `BreasePage` when in iframe |
| Styles | `import 'brease-next/styles'` in layout |
| iframe detection | `window.self !== window.top` |
| Editor click-to-edit | Section toolbar sends `brease:edit-section` |
| No iframe | All preview features are inactive |

---

## Next Steps

- [Context & Hooks](/docs/context-and-hooks) -- how BreaseContext provides data to preview
- [Components](/docs/components) -- BreasePage and section rendering
- [Getting Started](/docs/getting-started) -- initial project setup


---

# CLI Scaffolding

Source: https://docs.brease.io/docs/cli

The `brease-next` CLI creates a fully configured Next.js project connected to your Brease CMS site. It is the fastest way to get started.

## Command

```bash
npx brease-next
```

No global installation is needed. The command runs directly via `npx`.

---

## Interactive Prompts

The CLI walks you through the following prompts:

| Prompt | Default | Description |
|---|---|---|
| Project name | `my-brease-app` | Directory name for the new project |
| Template | -- | Choose between **Starter** and **Base** |
| API token | -- | Your Brease API token (from Site Settings) |
| Environment ID | -- | Your Brease environment ID (from Site Settings) |
| Default locale | -- | Default locale code (e.g. `en`) |
| Install dependencies | Yes | Whether to run the package manager install step |
| Initialize git | Yes | Whether to run `git init` in the new project |

---

## Templates

### Starter

An opinionated, full-featured setup designed to work with the **Brease Starter Template** in the CMS.

**Requirements:** Your Brease site must be created from the "Brease Starter Template" in the CMS dashboard. This template provides pre-configured pages, sections, navigations, and collections that the Starter scaffold expects.

**What you get:**
- Pre-built section components matching the Starter Template sections
- Header and footer navigation wired up
- Styled layout with CSS
- Complete catch-all routing with metadata generation
- Ready to run immediately after scaffolding

Best for: Getting a working site quickly, learning how brease-next works, or using the Starter Template as a foundation.

### Base

A minimal scaffold with only the core CMS wiring. Slug-based routing is set up, but no section components, navigation, or styling is included.

**What you get:**
- Catch-all route with `BreasePage` rendering
- `BreaseContext` wired in the layout
- Section map file (empty, ready for your components)
- `.env.local` with your credentials
- No pre-built section components or styling

Best for: Experienced developers who want full control over their design and architecture, or projects that do not use the Starter Template.

---

## What Gets Generated

After running the CLI, your project directory contains:

```
my-brease-app/
  .env.local              # BREASE_TOKEN, BREASE_ENV, BREASE_DEFAULT_LOCALE
  next.config.ts          # Image patterns, redirects
  src/
    app/
      [[...slug]]/
        layout.tsx        # BreaseContext with config
        page.tsx          # BreasePage with sectionMap
      robots.ts           # generateBreaseRobots
      sitemap.ts          # generateSitemap
      layout.tsx          # Root layout with styles import
    lib/
      brease/
        brease-config.ts  # sectionMap + contextConfig
        get-page.ts       # Cached page fetcher
    sections/             # Section components (Starter only)
```

The `.env.local` file is populated with the credentials you entered during setup:

```env
BREASE_TOKEN=your_token_here
BREASE_ENV=your_env_id_here
BREASE_DEFAULT_LOCALE=en
```

---

## Package Manager Detection

The CLI automatically detects which package manager you are using based on your environment:

- **npm** (default)
- **pnpm**
- **yarn**
- **bun**

Dependencies are installed using the detected package manager. If detection fails, npm is used as the fallback.

---

## After Scaffolding

Navigate into the project and start the development server:

```bash
cd my-brease-app
npm run dev
```

Open `http://localhost:3000` to see your CMS content rendered.

If you chose the **Starter** template, the site should render fully with navigation, sections, and styling. If you chose **Base**, you will see an empty page until you create section components and map them in `brease-config.ts`.

---

## Next Steps

- [Getting Started](/docs/getting-started) -- manual setup and configuration details
- [Components](/docs/components) -- building section components
- [Context & Hooks](/docs/context-and-hooks) -- configuring BreaseContext
- [API Reference](/docs/api-reference) -- all available functions and types


---

# Project Setup Guide

Source: https://docs.brease.io/docs/project-setup

Two paths to get a Brease-powered Next.js site running: the CLI scaffold (recommended) or manual setup.

---

## Path A: CLI Scaffolding (Recommended)

Run the interactive scaffolding tool:

```bash
npx brease-next
```

The CLI walks you through the following prompts:

1. **Project name** — directory name for your new app
2. **Template** — choose `starter` (pre-built sections and layouts) or `base` (minimal skeleton)
3. **API token** — your Brease API token from the dashboard
4. **Environment ID** — the UUID of the Brease environment to connect to
5. **Default locale** — e.g. `en`, `sk`, `de`
6. **Install dependencies** — runs `npm install` automatically if confirmed
7. **Initialize git** — runs `git init` if confirmed

Once complete you will have a fully configured project. Skip to the [Verify Your Setup](#verify-your-setup) section below.

---

## Path B: Manual Setup

### 1. Create a Next.js App

```bash
npx create-next-app@latest my-brease-app --typescript
cd my-brease-app
```

### 2. Install brease-next

```bash
npm install brease-next
```

### 3. Configure Environment Variables

Create `.env.local` in the project root:

```env
BREASE_TOKEN=your_brease_api_token
BREASE_ENV=your_environment_uuid
BREASE_DEFAULT_LOCALE=en
BREASE_REVALIDATION_TIME=30
```

| Variable | Required | Description |
|---|---|---|
| `BREASE_TOKEN` | Yes | API authentication token from the Brease dashboard |
| `BREASE_ENV` | Yes | Environment UUID (e.g. production, staging) |
| `BREASE_DEFAULT_LOCALE` | Yes | Default locale code (e.g. `en`, `sk`) |
| `BREASE_REVALIDATION_TIME` | No | ISR revalidation interval in seconds (default `30`) |

{% callout title="Keep secrets out of version control" type="warning" %}
Add `.env.local` to your `.gitignore`. Never commit API tokens to your repository.
{% /callout %}

### 4. Configure next.config.ts

Add remote image patterns for Brease media and wire up CMS-managed redirects:

```typescript
// next.config.ts
import type { NextConfig } from 'next'
import { fetchRedirects } from 'brease-next/server'

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.brease.io',
        pathname: '/**',
      },
    ],
  },

  async redirects() {
    const result = await fetchRedirects()

    if (!result.success) {
      console.error('Failed to fetch redirects:', result.error)
      return []
    }

    return result.data.map((redirect) => ({
      source: redirect.source,
      destination: redirect.destination,
      permanent: redirect.type === '301' || redirect.type === '308',
    }))
  },
}

export default nextConfig
```

### 5. Create the Brease Config

This file defines your section component map and context configuration:

```typescript
// src/lib/brease/config.ts
import { ComponentType } from 'react'
import { SectionElementProps, BreaseContextConfig } from 'brease-next'

// Map section keys (from CMS) to React components
export const componentMap: Record<string, ComponentType<SectionElementProps>> = {
  // hero: HeroSection,
  // features: FeaturesSection,
}

// Context configuration — navigations and collections available globally
export const contextData: BreaseContextConfig = {
  navigations: [
    // { key: 'header', id: 'your-header-nav-uuid' },
    // { key: 'footer', id: 'your-footer-nav-uuid' },
  ],
  collections: [
    // { key: 'faqs', id: 'your-faq-collection-uuid' },
  ],
  userParams: {},
}
```

### 6. Create the Page Fetcher

Use React `cache` to deduplicate page fetches within a single render pass:

```typescript
// src/lib/brease/get-page.ts
import { cache } from 'react'
import { fetchPage } from 'brease-next/server'

export const getPage = cache(async (slug: string) => {
  return fetchPage(slug)
})
```

### 7. Create the Catch-All Layout

The layout wraps every page with `BreaseContext`, which provides navigation, collection, and locale data to all child components:

```typescript
// src/app/[[...slug]]/layout.tsx
import { BreaseContext } from 'brease-next'
import { contextData } from '@/lib/brease/config'
import { getPage } from '@/lib/brease/get-page'

export default async function CatchAllLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')

  return (
    <BreaseContext config={contextData} slug={slugStr} getPage={getPage}>
      {children}
    </BreaseContext>
  )
}
```

### 8. Create the Catch-All Page

This page handles static generation, metadata, and rendering:

```typescript
// src/app/[[...slug]]/page.tsx
import { notFound } from 'next/navigation'
import {
  BreasePage,
  generateBreasePageParams,
  generateBreasePageMetadata,
  ensureSuccess,
} from 'brease-next'
import { componentMap } from '@/lib/brease/config'
import { getPage } from '@/lib/brease/get-page'

export async function generateStaticParams() {
  return generateBreasePageParams()
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data, {
    metadataBase: 'https://example.com',
  })
}

export default async function Page({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) {
    notFound()
  }

  const page = ensureSuccess(result)

  return <BreasePage page={page} sectionMap={componentMap} />
}
```

### 9. Create a Sample Section Component

Section components are client components that receive their data via props. The props correspond to the element keys defined in the CMS:

```tsx
// src/sections/hero-section.tsx
'use client'

import { BreaseImage, type BreaseMedia } from 'brease-next'

interface HeroSectionProps {
  title: string
  subtitle: string
  backgroundImage: BreaseMedia
}

export default function HeroSection({
  title,
  subtitle,
  backgroundImage,
}: HeroSectionProps) {
  return (
    <section className="relative py-24 px-6">
      {backgroundImage && (
        <BreaseImage breaseImage={backgroundImage} variant="xl" />
      )}
      <h1 className="text-5xl font-bold">{title}</h1>
      {subtitle && <p className="mt-4 text-xl">{subtitle}</p>}
    </section>
  )
}
```

Then register it in your config:

```typescript
// src/lib/brease/config.ts
import HeroSection from '@/sections/hero-section'

export const componentMap = {
  hero: HeroSection as unknown as ComponentType<SectionElementProps>,
}
```

{% callout title="Section key matching" type="note" %}
The key in `componentMap` (e.g. `hero`) must match the section's `key` field in the CMS, not its display name. You can find the key in the Brease dashboard under the section settings.
{% /callout %}

---

## Verify Your Setup

Run the development server:

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000). If your Brease environment has published pages, you should see content rendered on screen. Check the terminal for any API errors.

You can also validate your environment variables programmatically:

```typescript
import { validateBreaseConfig } from 'brease-next/server'

const config = validateBreaseConfig()
// Throws if BREASE_TOKEN, BREASE_ENV, or BREASE_DEFAULT_LOCALE are missing
```

---

## Next Steps

- [Pages & Dynamic Routes](/docs/pages-and-routes) — deep dive into the catch-all route pattern
- [Navigation Patterns](/docs/navigation-patterns) — render header and footer navigations
- [Collection Patterns](/docs/collection-patterns) — work with FAQs, team members, and other collection data


---

# Pages & Dynamic Routes

Source: https://docs.brease.io/docs/pages-and-routes

Brease sites use a single **optional catch-all route** (`[[...slug]]`) to handle every page, including the homepage. This page explains the route structure, layout, page component, static generation, and section components in detail.

---

## Route Structure

```
app/
  [[...slug]]/
    layout.tsx    ← BreaseContext wrapper (server component)
    page.tsx      ← Page rendering + metadata (server component)
```

The double-bracket `[[...slug]]` syntax makes the `slug` parameter optional. This means:

- `/` matches with `slug` as `undefined`
- `/about` matches with `slug` as `['about']`
- `/sk/about-us` matches with `slug` as `['sk', 'about-us']`

{% callout title="No separate locale segment needed" type="note" %}
You do not need a `[locale]` route segment. Locale prefixes (e.g. `sk/about-us`) are part of the slug and handled automatically by `fetchPage` and `BreaseContext`.
{% /callout %}

---

## Layout (layout.tsx)

The layout is a **server component** that wraps every page with `BreaseContext`. It receives the slug from route params and passes it to the context provider.

```typescript
// src/app/[[...slug]]/layout.tsx
import { BreaseContext } from 'brease-next'
import { contextData } from '@/lib/brease/config'
import { getPage } from '@/lib/brease/get-page'

export default async function CatchAllLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')

  return (
    <BreaseContext config={contextData} slug={slugStr} getPage={getPage}>
      {children}
    </BreaseContext>
  )
}
```

### What BreaseContext does

When the layout renders, `BreaseContext`:

1. Fetches the page data using `getPage` (or `fetchPage` internally if `getPage` is not provided)
2. Fetches all configured navigations and collections (with the correct locale derived from the slug)
3. Fetches available locales and alternate links
4. Makes all of this data available to child client components via the `useBrease()` hook

### The getPage function

Using React `cache` ensures the page is only fetched once per render pass, even if both the layout and page component call it:

```typescript
// src/lib/brease/get-page.ts
import { cache } from 'react'
import { fetchPage } from 'brease-next/server'

export const getPage = cache(async (slug: string) => {
  return fetchPage(slug)
})
```

---

## Page (page.tsx)

The page component handles three concerns: static generation, metadata, and rendering.

```typescript
// src/app/[[...slug]]/page.tsx
import { notFound } from 'next/navigation'
import {
  BreasePage,
  BreaseStructuredData,
  BreaseCustomCode,
  generateBreasePageParams,
  generateBreasePageMetadata,
  ensureSuccess,
} from 'brease-next'
import { componentMap } from '@/lib/brease/config'
import { getPage } from '@/lib/brease/get-page'

// 1. Static generation — tell Next.js which pages to pre-render
export async function generateStaticParams() {
  return generateBreasePageParams()
  // Returns: [
  //   { locale: 'en', slug: ['about'] },
  //   { locale: 'sk', slug: ['sk', 'o-nas'] },
  //   ...
  // ]
}

// 2. Metadata — SEO tags, Open Graph, Twitter Cards
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data, {
    metadataBase: 'https://example.com',
  })
}

// 3. Rendering — fetch page and render sections
export default async function Page({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) {
    notFound()
  }

  const page = ensureSuccess(result)

  return (
    <>
      <BreaseStructuredData page={page} />
      <BreasePage page={page} sectionMap={componentMap} />
      <BreaseCustomCode page={page} />
    </>
  )
}
```

### generateStaticParams

`generateBreasePageParams()` iterates all locales and all pages, returning an array of `{ locale: string; slug: string[] }` objects. Next.js uses this to pre-render every page at build time.

### generateMetadata

`generateBreasePageMetadata` takes a **page object** (not a slug string) and returns a Next.js `Metadata` object containing:

- `title` and `description` from the page's meta fields
- `openGraph` data (title, description, image, type)
- `twitterCard` data
- `robots` indexing directives based on `page.indexing`
- `canonicalUrl` if set
- `alternates` for multi-locale sites

The optional `metadataBase` is prepended to relative URLs in Open Graph images and canonical URLs.

### 404 Handling

If `getPage` returns a failed response (page not found or API error), call `notFound()` from `next/navigation`. This triggers Next.js to render your `not-found.tsx` page with a 404 status code.

```typescript
// src/app/not-found.tsx
export default function NotFound() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <h1 className="text-4xl font-bold">404 — Page Not Found</h1>
    </div>
  )
}
```

---

## Section Components

`BreasePage` iterates through `page.sections` and renders a component for each one by matching `section.key` against the keys in your `sectionMap`.

{% callout title="Matching uses section.key" type="warning" %}
Sections are matched by their `key` field, not by `section.name` or any other property. Make sure the keys in your `componentMap` exactly match the keys assigned to sections in the CMS.
{% /callout %}

### Section component rules

1. Section components **must** be client components — add `'use client'` at the top of every section file. `BreasePage` renders sections inside a client component tree, so they cannot be server components.
2. They receive the section's `elements` spread as props
3. Type the props with a custom interface that matches your CMS schema

### Example: HeroSection

Suppose your CMS has a section with key `hero` and elements: `title` (text), `subtitle` (text), `image` (media).

```tsx
// src/sections/hero-section.tsx
'use client'

import { BreaseImage, type BreaseMedia } from 'brease-next'

interface HeroSectionProps {
  title: string
  subtitle: string
  image: BreaseMedia
}

export default function HeroSection({
  title,
  subtitle,
  image,
}: HeroSectionProps) {
  return (
    <section className="relative py-24 px-6 text-center">
      <h1 className="text-5xl font-bold">{title}</h1>
      {subtitle && <p className="mt-4 text-xl text-gray-600">{subtitle}</p>}
      {image && (
        <div className="mt-12 mx-auto max-w-4xl">
          <BreaseImage breaseImage={image} variant="xl" priority />
        </div>
      )}
    </section>
  )
}
```

### Registering sections

```typescript
// src/lib/brease/config.ts
import { ComponentType } from 'react'
import { SectionElementProps } from 'brease-next'
import HeroSection from '@/sections/hero-section'
import TextSection from '@/sections/text-section'
import CtaSection from '@/sections/cta-section'

export const componentMap: Record<string, ComponentType<SectionElementProps>> = {
  hero: HeroSection as unknown as ComponentType<SectionElementProps>,
  text: TextSection as unknown as ComponentType<SectionElementProps>,
  cta: CtaSection as unknown as ComponentType<SectionElementProps>,
}
```

### Handling rich text elements

Rich text fields from the CMS contain HTML. Render them with `dangerouslySetInnerHTML`:

```tsx
'use client'

interface TextSectionProps {
  heading: string
  body: string  // HTML from the CMS rich text editor
}

export default function TextSection({ heading, body }: TextSectionProps) {
  return (
    <section className="py-16 px-6 max-w-3xl mx-auto">
      <h2 className="text-3xl font-bold mb-6">{heading}</h2>
      <div
        className="prose prose-lg"
        dangerouslySetInnerHTML={{ __html: body }}
      />
    </section>
  )
}
```

### Missing section keys

If a section's `key` has no matching entry in `componentMap`, a warning is logged to the console and the section is skipped. Other sections continue rendering normally.

---

## Next Steps

- [Collection Patterns](/docs/collection-patterns) — working with FAQs, team members, and other collection data
- [Navigation Patterns](/docs/navigation-patterns) — rendering header and footer menus
- [Multi-Locale Sites](/docs/locale-patterns) — locale-aware routing and language switching


---

# Collection Patterns

Source: https://docs.brease.io/docs/collection-patterns

Collections in Brease represent structured, repeatable data — FAQs, team members, testimonials, partner logos, feature lists, pricing tiers, and similar content that shares the same schema across multiple entries. Collections are **not pages** — if content needs its own URL (like blog posts), it should be a page with a page type instead.

---

## Accessing Collections

For collections needed across your site (e.g., in a sidebar, footer, or shared component), configure them in `BreaseContextConfig`:

### 1. Register collections in config

```typescript
// src/lib/brease/config.ts
import { BreaseContextConfig } from 'brease-next'

export const contextData: BreaseContextConfig = {
  navigations: [{ key: 'header', id: 'your-header-nav-uuid' }],
  collections: [
    { key: 'faqs', id: 'your-faq-collection-uuid' },
    { key: 'team', id: 'your-team-collection-uuid' },
  ],
  userParams: {},
}
```

Collections are also retrived from page content but they are page-scoped in this way.

### 2. Access in client components

```tsx
'use client'

import { useBrease } from 'brease-next'

export default function FAQSection() {
  const { collections } = useBrease()
  const faqs = collections?.faqs

  if (!faqs || faqs.entries.length === 0) return null

  return (
    <section className="py-16">
      <h2 className="mb-8 text-3xl font-bold">Frequently Asked Questions</h2>
      <dl className="space-y-6">
        {faqs.entries.map((entry) => (
          <div key={entry.uuid}>
            <dt className="text-lg font-semibold">
              {entry.elements.question as string}
            </dt>
            <dd className="mt-2 text-gray-600">
              {entry.elements.answer as string}
            </dd>
          </div>
        ))}
      </dl>
    </section>
  )
}
```

{% callout title="Context collections are locale-aware" type="note" %}
`BreaseContext` automatically fetches collections using the locale derived from the current page slug. You do not need to pass locale manually when using the context pattern.
{% /callout %}

---

## Typing Collection Entry Elements

Collection entry elements are typed as `Record<string, unknown>` by default. Define an interface matching your CMS schema and cast the elements for type safety:

```typescript
import type { BreaseMedia } from 'brease-next'

interface TeamMemberElements {
  name: string
  role: string
  bio: string // Rich text HTML
  photo: BreaseMedia
  linkedIn: string
}

const el = entry.elements as unknown as TeamMemberElements
```

This gives you full autocomplete and type checking when rendering entry data.

---

## Fetching Collections Directly

When you need collection data outside of `BreaseContext` (e.g., in a server component or a route that doesn't use the catch-all layout), fetch directly:

```typescript
import { fetchCollectionById } from 'brease-next/server'

const TEAM_COLLECTION_ID = 'your-team-collection-uuid'

export default async function TeamPage() {
  const result = await fetchCollectionById(TEAM_COLLECTION_ID, 'en')

  if (!result.success) {
    return <p>Failed to load team members.</p>
  }

  return (
    <div className="grid gap-8 md:grid-cols-3">
      {result.data.entries.map((entry) => {
        const el = entry.elements as unknown as TeamMemberElements
        return (
          <div key={entry.uuid} className="text-center">
            <h3 className="text-lg font-semibold">{el.name}</h3>
            <p className="text-sm text-gray-500">{el.role}</p>
          </div>
        )
      })}
    </div>
  )
}
```

{% callout title="Locale parameter required" type="warning" %}
`fetchCollectionById` requires a locale parameter. When fetching directly (outside `BreaseContext`), you must supply it explicitly.
{% /callout %}

---

## Fetching a Single Entry

Use `fetchEntryById` when you need a specific entry by its UUID:

```typescript
import { fetchEntryById } from 'brease-next/server'

const result = await fetchEntryById(
  'your-collection-uuid',
  'entry-uuid-here',
  'en',
)

if (result.success) {
  const entry = result.data
  console.log(entry.uuid, entry.name)
  console.log(entry.elements)
}
```

---

## Example: Testimonials Section

A complete example rendering a testimonials collection with images:

```tsx
'use client'

import { useBrease, BreaseImage, type BreaseMedia } from 'brease-next'

interface TestimonialElements {
  quote: string
  author: string
  role: string
  avatar: BreaseMedia
}

export default function Testimonials() {
  const { collections } = useBrease()
  const testimonials = collections?.testimonials

  if (!testimonials || testimonials.entries.length === 0) return null

  return (
    <section className="py-24">
      <h2 className="mb-16 text-center text-3xl font-bold">
        What Our Clients Say
      </h2>
      <div className="grid gap-8 md:grid-cols-2 lg:grid-cols-3">
        {testimonials.entries.map((entry) => {
          const el = entry.elements as unknown as TestimonialElements
          return (
            <blockquote key={entry.uuid} className="rounded-xl border p-6">
              <p className="text-gray-700">&ldquo;{el.quote}&rdquo;</p>
              <footer className="mt-4 flex items-center gap-3">
                {el.avatar && (
                  <BreaseImage
                    breaseImage={el.avatar}
                    variant="sm"
                    className="h-10 w-10 rounded-full object-cover"
                  />
                )}
                <div>
                  <p className="font-semibold">{el.author}</p>
                  <p className="text-sm text-gray-500">{el.role}</p>
                </div>
              </footer>
            </blockquote>
          )
        })}
      </div>
    </section>
  )
}
```

---

## Multi-Locale Collections

When your site supports multiple locales, pass the locale to collection fetch functions:

```typescript
import { fetchCollectionById, fetchEntryById } from 'brease-next/server'

// Fetch the Slovak version of a collection
const result = await fetchCollectionById('your-collection-uuid', 'sk')

// Fetch a specific entry in Slovak
const entry = await fetchEntryById('your-collection-uuid', 'entry-uuid', 'sk')
```

When using `BreaseContext`, locale is handled automatically based on the page slug.

---

## Collections vs Pages

{% callout title="When to use which" type="note" %}
**Collections** are for structured data that lives within a page — FAQs, team members, testimonials, feature lists, pricing tiers, partner logos. Entries do not have their own URL.

**Pages** (with page types) are for content that needs its own URL — blog posts, case studies, product pages. Use a page type with a template to standardize their structure, and reference fields for page-level metadata like author or publish date. See [Templates & Page Types](/docs/templates-and-page-types).
{% /callout %}

---

## Best Practices

- **Type your elements.** Always create an interface for your entry elements and cast `entry.elements` to it. This catches typos and gives you IDE autocomplete.
- **Handle missing data gracefully.** Elements can be `null` or `undefined` if not filled in by the content editor. Use optional chaining and fallbacks.
- **Use context for global lists.** If you need collection data on every page (e.g., a testimonials widget in the sidebar), configure it in `contextData` so it is fetched once by `BreaseContext`.
- **Use direct fetches for isolated pages.** For pages that only need collection data in specific places, use `fetchCollectionById` directly in server components.

---

## Next Steps

- [Navigation Patterns](/docs/navigation-patterns) — rendering menus and handling nested items
- [Multi-Locale Sites](/docs/locale-patterns) — locale-aware collection fetching
- [Media & Images](/docs/media-patterns) — rendering images from collection entries


---

# Navigation Patterns

Source: https://docs.brease.io/docs/navigation-patterns

Navigations in Brease are managed in the CMS and fetched automatically by `BreaseContext`. Use the `BreaseLink` component to render navigation items — it handles internal vs external links, targets, and security attributes automatically.

---

## Accessing Navigation Data

Navigations are configured in your `BreaseContextConfig` and made available to client components through the `useBrease()` hook.

### 1. Register navigations in config

```typescript
// src/lib/brease/config.ts
import { BreaseContextConfig } from 'brease-next'

export const contextData: BreaseContextConfig = {
  navigations: [
    { key: 'header', id: 'your-header-nav-uuid' },
    { key: 'footer', id: 'your-footer-nav-uuid' },
  ],
  collections: [],
  userParams: {},
}
```

### 2. Access in client components

```tsx
'use client'

import { useBrease } from 'brease-next'

export default function Header() {
  const { navigations } = useBrease()
  const headerNav = navigations.header

  if (!headerNav) return null

  // headerNav is a BreaseNavigation object
  // headerNav.items is an array of BreaseNavigationItem
}
```

### Navigation data shape

Each navigation item implements `BreaseLinkData` with added `uuid` and `children`:

```typescript
interface BreaseNavigationItem {
  uuid: string
  label: string           // Display text
  isExternal: boolean     // true for external URLs
  value: string           // The full URL or path — use as href directly
  target: '_blank' | '_self' | null
  children: BreaseNavigationItem[]  // Nested items
}
```

The `value` field contains everything needed for the link — for internal links it's the path (e.g. `/about`), for external links it's the full URL (e.g. `https://example.com`). You never need to construct or manipulate it.

---

## Using BreaseLink

`BreaseLink` is the recommended way to render any navigation item. It reads `isExternal`, `value`, `target`, and `label` from the `linkData` prop and renders the correct element automatically:

- **Internal links** → Next.js `<Link>` (client-side navigation)
- **External links** → native `<a>` with `rel="noopener noreferrer"` when `target="_blank"`

```tsx
import { BreaseLink } from 'brease-next'

<BreaseLink linkData={item} className="text-sm font-medium">
  {item.label}
</BreaseLink>
```

Since `BreaseNavigationItem` extends `BreaseLinkData`, navigation items can be passed directly as `linkData`. Any extra props (className, onClick, etc.) are forwarded to the underlying element.

---

## Header Navigation

A complete header component with dropdown support:

```tsx
// src/components/header.tsx
'use client'

import { useState } from 'react'
import { useBrease, BreaseLink } from 'brease-next'
import type { BreaseNavigationItem } from 'brease-next'
import Link from 'next/link'

export default function Header() {
  const { navigations } = useBrease()
  const headerNav = navigations.header

  if (!headerNav) return null

  return (
    <header className="border-b bg-white">
      <div className="mx-auto flex h-16 max-w-7xl items-center justify-between px-6">
        <Link href="/" className="text-xl font-bold">
          My Site
        </Link>
        <nav className="flex items-center gap-8">
          {headerNav.items.map((item) => (
            <NavItem key={item.uuid} item={item} />
          ))}
        </nav>
      </div>
    </header>
  )
}

function NavItem({ item }: { item: BreaseNavigationItem }) {
  const [open, setOpen] = useState(false)
  const hasChildren = item.children && item.children.length > 0

  if (hasChildren) {
    return (
      <div
        className="relative"
        onMouseEnter={() => setOpen(true)}
        onMouseLeave={() => setOpen(false)}
      >
        <button className="flex items-center gap-1 text-sm font-medium text-gray-700 hover:text-gray-900">
          {item.label}
          <svg className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
          </svg>
        </button>

        {open && (
          <div className="absolute left-0 top-full mt-1 w-48 rounded-md border bg-white py-1 shadow-lg">
            {item.children.map((child) => (
              <BreaseLink
                key={child.uuid}
                linkData={child}
                className="block px-4 py-2 text-sm text-gray-700 hover:bg-gray-100"
              >
                {child.label}
              </BreaseLink>
            ))}
          </div>
        )}
      </div>
    )
  }

  return (
    <BreaseLink linkData={item} className="text-sm font-medium text-gray-700 hover:text-gray-900">
      {item.label}
    </BreaseLink>
  )
}
```

---

## Footer Navigation

Footer navigations typically use top-level items as column headings with their `children` as the links:

```tsx
// src/components/footer.tsx
'use client'

import { useBrease, BreaseLink } from 'brease-next'

export default function Footer() {
  const { navigations } = useBrease()
  const footerNav = navigations.footer

  if (!footerNav) return null

  return (
    <footer className="border-t bg-gray-50">
      <div className="mx-auto max-w-7xl px-6 py-12">
        <div className="grid gap-8 md:grid-cols-4">
          <div>
            <h3 className="text-lg font-bold">My Site</h3>
            <p className="mt-2 text-sm text-gray-600">
              {footerNav.description}
            </p>
          </div>

          {footerNav.items.map((group) => (
            <div key={group.uuid}>
              <h4 className="text-sm font-semibold uppercase tracking-wider text-gray-900">
                {group.label}
              </h4>
              {group.children && group.children.length > 0 && (
                <ul className="mt-4 space-y-3">
                  {group.children.map((child) => (
                    <li key={child.uuid}>
                      <BreaseLink
                        linkData={child}
                        className="text-sm text-gray-600 hover:text-gray-900"
                      >
                        {child.label}
                      </BreaseLink>
                    </li>
                  ))}
                </ul>
              )}
            </div>
          ))}
        </div>

        <div className="mt-12 border-t pt-8 text-center text-sm text-gray-500">
          &copy; {new Date().getFullYear()} My Site. All rights reserved.
        </div>
      </div>
    </footer>
  )
}
```

{% callout title="Footer navigation structure" type="note" %}
Structure your footer navigation in the CMS with top-level items as column headings (group type) and their children as the links within each column.
{% /callout %}

---

## Fetching Navigation Directly

If you need navigation data outside of `BreaseContext` (e.g. in a server component or a route that does not use the catch-all layout), fetch it directly:

```typescript
import { fetchNavigation } from 'brease-next/server'

const result = await fetchNavigation('your-nav-uuid', 'en')

if (result.success) {
  const nav = result.data
  // nav.items contains the navigation tree
}
```

{% callout title="Locale parameter required" type="warning" %}
`fetchNavigation` requires a locale parameter. When fetching directly (outside `BreaseContext`), you must supply it explicitly.
{% /callout %}

---

## Next Steps

- [Multi-Locale Sites](/docs/locale-patterns) — language switcher using navigation data
- [Pages & Dynamic Routes](/docs/pages-and-routes) — where to place Header and Footer components
- [Collection Patterns](/docs/collection-patterns) — working with collection data


---

# Multi-Locale Sites

Source: https://docs.brease.io/docs/locale-patterns

Brease supports multi-locale sites out of the box. Locale is embedded in the page slug (e.g. `sk/about-us`) and handled automatically by `fetchPage` and `BreaseContext`. No separate `[locale]` route segment is needed.

---

## How Locale Routing Works

The `[[...slug]]` catch-all route handles all locales:

| URL            | slug array           | Locale  | Page slug      |
| -------------- | -------------------- | ------- | -------------- |
| `/`            | `undefined`          | default | `/`            |
| `/about`       | `['about']`          | default | `/about`       |
| `/sk/o-nas`    | `['sk', 'o-nas']`    | `sk`    | `/sk/o-nas`    |
| `/de/uber-uns` | `['de', 'uber-uns']` | `de`    | `/de/uber-uns` |

When you pass the slug string to `fetchPage`, it automatically detects the locale prefix and returns the correct localized content.

### parseSlugAndLocale

The `parseSlugAndLocale` utility extracts the locale and remaining slug from a combined slug string:

```typescript
import { parseSlugAndLocale } from 'brease-next/server'

parseSlugAndLocale('sk/about-us')
// Returns: { slug: 'about-us', locale: 'sk' }

parseSlugAndLocale('about-us')
// Returns: { slug: 'about-us', locale: undefined }
// (falls back to BREASE_DEFAULT_LOCALE)
```

The function checks the first segment against known locale codes. If it matches a configured locale, it is extracted. Otherwise, the entire string is treated as the page slug with the default locale applied.

{% callout title="No [locale] segment needed" type="note" %}
Unlike many i18n setups in Next.js, Brease does not require a `[locale]` dynamic segment. The locale is part of the slug, and `BreaseContext` plus `fetchPage` handle locale derivation automatically.
{% /callout %}

---

## Static Generation for All Locales

`generateBreasePageParams()` already handles all locale/page combinations. It iterates every locale and every page, returning params for all of them:

```typescript
export async function generateStaticParams() {
  return generateBreasePageParams()
  // Returns:
  // [
  //   { locale: 'en', slug: ['about'] },
  //   { locale: 'en', slug: ['contact'] },
  //   { locale: 'sk', slug: ['sk', 'o-nas'] },
  //   { locale: 'sk', slug: ['sk', 'kontakt'] },
  //   ...
  // ]
}
```

No additional configuration is needed for multi-locale static generation.

---

## Fetching Locales

To get the list of all available locales for your site:

```typescript
import { fetchLocales } from 'brease-next/server'

const result = await fetchLocales()

if (result.success) {
  result.data.forEach((locale) => {
    console.log(locale.code) // 'en', 'sk', 'de'
    console.log(locale.name) // 'English', 'Slovak', 'German'
    console.log(locale.isDefault) // true for the default locale
  })
}
```

The return type is `BreaseResponse<BreaseLocale[]>` where:

```typescript
interface BreaseLocale {
  uuid: string
  code: string
  name: string
  isDefault: boolean
}
```

---

## Language Switcher Component

The `useBrease()` hook provides `availableLocales`, `locale`, and `alternateLinks` -- everything needed for a language switcher. The `alternateLinks` object maps locale codes to the corresponding URL for the current page in that language.

```tsx
// src/components/language-switcher.tsx
'use client'

import { useBrease } from 'brease-next'
import Link from 'next/link'

export function LanguageSwitcher() {
  const { availableLocales, locale, alternateLinks } = useBrease()

  return (
    <ul className="flex items-center gap-2">
      {availableLocales.map((loc) => (
        <li key={loc}>
          <Link
            href={alternateLinks[loc] || `/${loc}`}
            className={`rounded px-2 py-1 text-sm ${
              loc === locale
                ? 'bg-blue-600 font-bold text-white'
                : 'text-gray-600 hover:text-gray-900'
            }`}
          >
            {loc.toUpperCase()}
          </Link>
        </li>
      ))}
    </ul>
  )
}
```

### How alternateLinks works

For a page `/about` that has a Slovak translation at `/sk/o-nas`, the `alternateLinks` object looks like:

```typescript
{
  en: '/about',
  sk: '/sk/o-nas'
}
```

If the current page does not have a translation in a given locale, the switcher falls back to `/${loc}` (the locale's homepage).

### Placing the switcher

Add it to your header alongside the navigation:

```tsx
// src/components/header.tsx
'use client'

import { useBrease, BreaseLink } from 'brease-next'
import { LanguageSwitcher } from './language-switcher'

export default function Header() {
  const { navigations } = useBrease()
  const headerNav = navigations.header

  return (
    <header className="border-b bg-white">
      <div className="mx-auto max-w-7xl px-6">
        <div className="flex h-16 items-center justify-between">
          <nav className="flex items-center gap-6">
            {headerNav?.items.map((item) => (
              <BreaseLink key={item.uuid} linkData={item}>
                {item.label}
              </BreaseLink>
            ))}
          </nav>
          <LanguageSwitcher />
        </div>
      </div>
    </header>
  )
}
```

---

## Fetching Alternate Links

If you need alternate links outside of `BreaseContext` (e.g. for `<link rel="alternate">` tags), use `fetchAlternateLinks`:

```typescript
import { fetchAlternateLinks } from 'brease-next/server'

const result = await fetchAlternateLinks('about')

if (result.success) {
  // result.data contains alternate link data for the page
}
```

The `generateBreasePageMetadata` function automatically includes `alternates` in the returned metadata when alternate links are available, so you typically do not need to call this directly.

---

## Locale-Aware Data Fetching

When fetching data outside `BreaseContext` (e.g. in server components or API routes), you must pass the locale explicitly to functions that require it:

```typescript
import {
  fetchCollectionById,
  fetchEntryById,
  fetchNavigation,
  fetchAllPages,
} from 'brease-next/server'

// All require a locale parameter
const collection = await fetchCollectionById('col-uuid', 'sk')
const entry = await fetchEntryById('col-uuid', 'entry-uuid', 'sk')
const navigation = await fetchNavigation('nav-uuid', 'sk')
const pages = await fetchAllPages('sk')
```

{% callout title="fetchPage derives locale automatically" type="note" %}
`fetchPage` does not take a separate locale parameter. Instead, it derives the locale from the slug. For example, `fetchPage('sk/about-us')` will automatically fetch the Slovak version. All other fetch functions require an explicit locale.
{% /callout %}

---

## Next Steps

- [Navigation Patterns](/docs/navigation-patterns) — rendering locale-aware menus
- [Collection Patterns](/docs/collection-patterns) — multi-locale collection fetching
- [Deployment](/docs/deployment) — environment variables for locale configuration


---

# Media & Images

Source: https://docs.brease.io/docs/media-patterns

The `BreaseImage` component wraps Next.js `Image` with automatic Brease variant support, responsive `srcSet` generation, and smart fallbacks. This page covers all usage patterns for rendering media from the CMS.

---

## BreaseImage Overview

```tsx
import { BreaseImage } from 'brease-next'

<BreaseImage breaseImage={media} />
```

`BreaseImage` accepts a `BreaseMedia` object and renders an optimized Next.js `Image`. It handles variant selection, responsive images, alt text fallbacks, and null safety automatically.

### BreaseMedia Type

Media objects returned from the CMS have this structure:

```typescript
interface BreaseMedia {
  alt: string
  duration: number
  extension: string
  height: number
  mimeGroup: string
  mimeType: string
  name: string
  path: string
  size: string
  thumbnail: string
  uuid: string
  width: number
  variants: Record<string, BreaseMediaVariant>
}

interface BreaseMediaVariant {
  alt: string
  extension: string
  height: number
  mimeType: string
  path: string
  size: string
  type: string
  width: number
}
```

The `variants` object contains pre-generated sizes keyed by variant name: `sm`, `md`, `lg`, `xl`, `2xl`, `hd`, and `original`.

---

## Responsive Images (Default Behavior)

When no `variant` prop is provided, `BreaseImage` automatically builds a `srcSet` from all available variants, letting the browser pick the best size for the viewport:

```tsx
import { BreaseImage } from 'brease-next'

// Automatic srcSet from all variants (sm through original)
<BreaseImage breaseImage={elements.heroImage} priority />
```

The default `sizes` attribute is:

```
(max-width: 640px) 100vw, (max-width: 1024px) 50vw, (max-width: 1440px) 33vw, 25vw
```

This works well for typical content layouts. Override it with the `sizes` prop for different grid configurations.

---

## Single Variant

Pass a `variant` prop to use a specific pre-generated size instead of the full `srcSet`:

```tsx
// Use the "lg" variant only
<BreaseImage breaseImage={elements.thumbnail} variant="md" />

// Available variants: sm, md, lg, xl, 2xl, hd, original
<BreaseImage breaseImage={elements.banner} variant="xl" />
```

This is useful for thumbnails, avatars, or fixed-size images where you know exactly which size is appropriate.

---

## Custom Sizes

For grid layouts or other non-default sizing, override the `sizes` prop:

```tsx
// Two-column layout
<BreaseImage
  breaseImage={elements.photo}
  sizes="(max-width: 768px) 100vw, 50vw"
  className="rounded-lg"
/>

// Three-column grid
<BreaseImage
  breaseImage={elements.gridImage}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
/>

// Full-width hero
<BreaseImage
  breaseImage={elements.heroImage}
  sizes="100vw"
  priority
/>
```

---

## Alt Text Fallbacks

`BreaseImage` uses a fallback chain for alt text:

1. The `alt` prop passed directly to the component
2. `breaseImage.alt` from the CMS media object
3. `breaseImage.name` (the file name)
4. `"Image alt."` as a last resort

```tsx
// Uses alt from CMS media
<BreaseImage breaseImage={media} />

// Override with custom alt text
<BreaseImage breaseImage={media} alt="Custom description" />
```

{% callout title="Set alt text in the CMS" type="note" %}
For best accessibility, set the alt text in the Brease media library. This ensures every usage of the image across your site has meaningful alt text without needing per-component overrides.
{% /callout %}

---

## Width and Height

`BreaseImage` infers `width` and `height` from the largest available variant, falling back to the original image dimensions (`breaseImage.width` and `breaseImage.height`). This prevents layout shift without requiring you to specify dimensions manually.

---

## Priority Loading

For above-the-fold images (heroes, banners), add the `priority` prop to disable lazy loading and preload the image:

```tsx
<BreaseImage breaseImage={elements.heroBanner} priority />
```

---

## Additional Props

`BreaseImage` passes through standard Next.js `Image` props like `className`, `style`, and `priority`:

```tsx
<BreaseImage
  breaseImage={elements.photo}
  variant="lg"
  className="rounded-xl shadow-lg object-cover"
  priority
/>
```

---

## Configuring Remote Patterns

Next.js requires explicit allowlisting of external image domains. Add the Brease media CDN to your `next.config.ts`:

```typescript
// next.config.ts
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.brease.io',
        pathname: '/**',
      },
    ],
  },
}
```

{% callout title="Image loading errors" type="warning" %}
If images fail to load with a "hostname not configured" error, check that `remotePatterns` includes `assets.brease.io`.
{% /callout %}

---

## Handling Optional Media Fields

Media fields in sections or collection entries may be `null` or `undefined` if the content editor did not upload an image. `BreaseImage` returns `null` when `breaseImage` is falsy, so it is safe to render unconditionally:

```tsx
// Safe — renders nothing if featuredImage is null
<BreaseImage breaseImage={elements.featuredImage} variant="lg" />
```

For cases where you want to show a placeholder or conditional wrapper:

```tsx
{elements.featuredImage ? (
  <BreaseImage
    breaseImage={elements.featuredImage}
    variant="lg"
    className="rounded-lg"
  />
) : (
  <div className="bg-gray-200 rounded-lg aspect-video flex items-center justify-center">
    <span className="text-gray-400">No image</span>
  </div>
)}
```

---

## Using BreaseMedia Directly with Next.js Image

If you need more control than `BreaseImage` provides, use the `BreaseMedia` object with Next.js `Image` directly:

```tsx
import Image from 'next/image'
import type { BreaseMedia } from 'brease-next'

interface GalleryProps {
  images: BreaseMedia[]
}

export default function Gallery({ images }: GalleryProps) {
  return (
    <div className="grid grid-cols-3 gap-4">
      {images.map((img) => {
        const variant = img.variants?.lg ?? img.variants?.original
        return (
          <Image
            key={img.uuid}
            src={variant?.path ?? img.path}
            alt={img.alt || img.name || 'Image alt.'}
            width={variant?.width ?? img.width}
            height={variant?.height ?? img.height}
            className="rounded-lg object-cover"
          />
        )
      })}
    </div>
  )
}
```

---

## Next Steps

- [Pages & Dynamic Routes](/docs/pages-and-routes) — rendering sections that contain images
- [Collection Patterns](/docs/collection-patterns) — images in collection entries
- [Structured Data & Custom Code](/docs/structured-data-patterns) — Open Graph images and metadata


---

# Structured Data & Custom Code

Source: https://docs.brease.io/docs/structured-data-patterns

Brease provides two components for injecting page-level metadata into your rendered output: `BreaseStructuredData` for JSON-LD structured data and `BreaseCustomCode` for arbitrary scripts and HTML. This page covers both components plus site-level custom code.

---

## BreaseStructuredData

Renders JSON-LD `<script>` tags from the structured data configured on a page in the CMS.

### Usage

```tsx
import { BreaseStructuredData } from 'brease-next'

export default async function Page({ params }) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const page = ensureSuccess(await getPage(slugStr))

  return (
    <>
      <BreaseStructuredData page={page} />
      <BreasePage page={page} sectionMap={componentMap} />
    </>
  )
}
```

### How it works

- Reads `page.structuredData`, which is an array of structured data objects defined in the CMS
- Renders each object as a `<script type="application/ld+json">` tag
- Returns `null` if `page.structuredData` is `null`, `undefined`, or an empty array

### Example output

If the CMS has a page with an Organization schema configured, the component renders:

```html
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Acme Corp",
    "url": "https://acme.com"
  }
</script>
```

### Setting up structured data in the CMS

1. Open a page in the Brease editor
2. Navigate to the page's SEO settings
3. Add structured data entries using the JSON-LD editor
4. Choose from common schemas (Organization, Article, Product, FAQ, etc.) or write custom JSON-LD

{% callout title="Validate your structured data" type="note" %}
Use [Google's Rich Results Test](https://search.google.com/test/rich-results) to verify your JSON-LD output. Errors in structured data will not break rendering but will prevent rich results in search engines.
{% /callout %}

---

## BreaseCustomCode

Renders page-level custom code defined in the CMS. This is typically used for analytics snippets, tracking pixels, chat widgets, or inline HTML/CSS that applies to a specific page.

### Usage

```tsx
import { BreaseCustomCode } from 'brease-next'

export default async function Page({ params }) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const page = ensureSuccess(await getPage(slugStr))

  return (
    <>
      <BreaseStructuredData page={page} />
      <BreasePage page={page} sectionMap={componentMap} />
      <BreaseCustomCode page={page} />
    </>
  )
}
```

### How it works

- Reads `page.customCode`, which contains raw HTML/script content defined in the CMS
- Renders the content using `dangerouslySetInnerHTML`
- Returns `null` if `page.customCode` is `null`, `undefined`, or empty

### Common use cases

- Page-specific analytics events
- Embedded widgets (calendars, booking forms)
- Conversion tracking pixels
- Custom CSS overrides for a single page

---

## Full Page Component Example

Here is a complete page component with both structured data and custom code:

```typescript
// src/app/[[...slug]]/page.tsx
import { notFound } from 'next/navigation'
import {
  BreasePage,
  BreaseStructuredData,
  BreaseCustomCode,
  generateBreasePageParams,
  generateBreasePageMetadata,
  ensureSuccess,
} from 'brease-next'
import { componentMap } from '@/lib/brease/config'
import { getPage } from '@/lib/brease/get-page'

export async function generateStaticParams() {
  return generateBreasePageParams()
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data, {
    metadataBase: 'https://example.com',
  })
}

export default async function Page({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) {
    notFound()
  }

  const page = ensureSuccess(result)

  return (
    <>
      <BreaseStructuredData page={page} />
      <BreasePage page={page} sectionMap={componentMap} />
      <BreaseCustomCode page={page} />
    </>
  )
}
```

---

## Component Placement Summary

| Component              | Data source           | Where to place                                     |
| ---------------------- | --------------------- | -------------------------------------------------- |
| `BreaseStructuredData` | `page.structuredData` | Before or after `BreasePage` in the page component |
| `BreaseCustomCode`     | `page.customCode`     | After `BreasePage` in the page component           |

Both `BreaseStructuredData` and `BreaseCustomCode` are safe to include unconditionally. They render nothing when their data is empty.

---

## Next Steps

- [Deployment](/docs/deployment) — production checklist including SEO verification
- [Pages & Dynamic Routes](/docs/pages-and-routes) — the page component that hosts these components
- [Media & Images](/docs/media-patterns) — Open Graph images in metadata


---

# Deployment

Source: https://docs.brease.io/docs/deployment

This page covers building for production, configuring hosting platforms, ISR revalidation, robots.txt, sitemaps, and a pre-deployment checklist.

---

## Building for Production

Run the standard Next.js build:

```bash
npm run build
```

During the build, Next.js will:

1. Call `generateStaticParams()` to get all page paths across all locales
2. Pre-render every page by fetching content from the Brease API
3. Fetch and configure redirects from `next.config.ts`
4. Generate static HTML, CSS, and JS bundles

Then start the production server:

```bash
npm start
```

{% callout title="Build requires API access" type="warning" %}
The build process fetches all content from Brease. Make sure `BREASE_TOKEN` and `BREASE_ENV` are available as environment variables during the build step on your hosting platform.
{% /callout %}

---

## Incremental Static Regeneration (ISR)

Pages are revalidated on a timer controlled by the `BREASE_REVALIDATION_TIME` environment variable (in seconds). The default is `30`.

| Value | Behavior |
|---|---|
| `30` (default) | Pages revalidate every 30 seconds after first request |
| `60` | Revalidate every minute |
| `0` | Disable time-based revalidation (on-demand only) |
| `false` | Disable revalidation entirely (fully static) |

When a page is requested after the revalidation window, Next.js serves the cached version immediately and regenerates the page in the background. The next request receives the updated content.

---

## Environment Variables

All hosting platforms need these environment variables:

| Variable | Required | Description |
|---|---|---|
| `BREASE_TOKEN` | Yes | API authentication token |
| `BREASE_ENV` | Yes | Environment UUID |
| `BREASE_DEFAULT_LOCALE` | Yes | Default locale code (e.g. `en`) |
| `BREASE_REVALIDATION_TIME` | No | ISR revalidation in seconds (default `30`) |

---

## Deploying to Vercel

Vercel is the recommended hosting platform for Next.js projects.

### 1. Set environment variables

In your Vercel project dashboard, go to **Settings > Environment Variables** and add:

- `BREASE_TOKEN`
- `BREASE_ENV`
- `BREASE_DEFAULT_LOCALE`
- `BREASE_REVALIDATION_TIME` (optional)

Set them for **Production**, **Preview**, and **Development** environments as needed.

### 2. Deploy

Push to your git repository. Vercel automatically builds and deploys:

```bash
git push origin main
```

Vercel handles the Node.js runtime, ISR, and edge caching automatically.

---

## Deploying to Other Platforms

For platforms like Railway, Render, AWS, or self-hosted servers:

### Requirements

- Node.js 18+ runtime
- Environment variables set in the platform's configuration
- Ability to run `npm run build` and `npm start`

### Deploy steps

```bash
# Install dependencies
npm ci

# Build the application
npm run build

# Start the production server
npm start
```

The production server defaults to port 3000. Configure the `PORT` environment variable if your platform requires a different port.

---

## Robots.txt

Use `generateBreaseRobots` to create a `robots.txt` route based on your site configuration:

```typescript
// src/app/robots.ts
import { generateBreaseRobots } from 'brease-next/server'
import type { MetadataRoute } from 'next'

export default function robots(): MetadataRoute.Robots {
  return generateBreaseRobots('https://example.com')
}
```

`generateBreaseRobots` accepts a site URL and an optional options object:

```typescript
const robots = generateBreaseRobots('https://example.com', {
  // Additional options can be passed here
})
```

---

## Sitemap

Use `generateSitemap` to create a dynamic sitemap from all published pages:

```typescript
// src/app/sitemap.ts
import { generateSitemap } from 'brease-next/server'
import type { MetadataRoute } from 'next'

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const result = await generateSitemap()

  if (!result.success) {
    return []
  }

  return result.data
}
```

`generateSitemap` returns a `BreaseResponse<MetadataRoute.Sitemap>` containing URLs for all published pages across all locales.

---

## CORS and Preview Mode

If you use Brease's live preview feature (where the CMS editor iframes your site), configure Content Security Policy headers to allow framing from the CMS domain:

```typescript
// next.config.ts
const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "frame-ancestors 'self' https://app.brease.io",
          },
        ],
      },
    ]
  },
  // ... other config
}
```

{% callout title="Restrict frame-ancestors in production" type="warning" %}
Only allow framing from domains you trust. The example above allows the Brease CMS (`app.brease.io`) to embed your site for preview purposes. Do not use `frame-ancestors *` in production.
{% /callout %}

---

## Redirects

Redirects are fetched from the Brease API at build time and configured in `next.config.ts`:

```typescript
// next.config.ts
import { fetchRedirects } from 'brease-next/server'

const nextConfig = {
  async redirects() {
    const result = await fetchRedirects()

    if (!result.success) {
      console.error('Failed to fetch redirects:', result.error)
      return []
    }

    return result.data.map((redirect) => ({
      source: redirect.source,
      destination: redirect.destination,
      permanent: redirect.type === '301' || redirect.type === '308',
    }))
  },
}
```

Redirects are baked into the build output. To update redirects after changing them in the CMS, trigger a new build or redeploy.

---

## Deployment Checklist

Before going live, verify each item:

### Environment

- [ ] `BREASE_TOKEN` is set on the hosting platform
- [ ] `BREASE_ENV` is set and points to the production environment
- [ ] `BREASE_DEFAULT_LOCALE` is set to the correct default locale
- [ ] `BREASE_REVALIDATION_TIME` is set (or using the default of 30s)

### Configuration

- [ ] `next.config.ts` has `remotePatterns` for the Brease media CDN
- [ ] `next.config.ts` has the `redirects()` function using `fetchRedirects`
- [ ] `robots.ts` is configured with `generateBreaseRobots`
- [ ] `sitemap.ts` is configured with `generateSitemap`

### CMS

- [ ] Preview domain is set in the Brease CMS settings (if using live preview)
- [ ] All pages are published in the target environment
- [ ] Structured data is configured for key pages (homepage, about, etc.)

### Build

- [ ] `npm run build` completes without errors
- [ ] All expected pages are pre-rendered (check build output)
- [ ] No missing section key warnings in the build log
- [ ] Images load correctly from the CDN

### Verification

- [ ] Homepage renders correctly
- [ ] Navigation links work (internal and external)
- [ ] Multi-locale pages load the correct translations
- [ ] Redirects work as configured in the CMS
- [ ] Meta tags and Open Graph data appear in page source
- [ ] Structured data validates in Google's Rich Results Test
- [ ] 404 pages return the correct status code

---

## Next Steps

- [Project Setup Guide](/docs/project-setup) — review your initial configuration
- [Structured Data & Custom Code](/docs/structured-data-patterns) — verify SEO output
- [Multi-Locale Sites](/docs/locale-patterns) — ensure all locales deploy correctly


---

# Examples

Source: https://docs.brease.io/docs/examples

Complete, production-ready examples showing real implementations using `brease-next`.

---

## Configuration File

Central configuration for section mapping and context data.

### File: src/lib/brease/config.ts

```typescript
import { ComponentType } from 'react'
import { BreaseContextConfig } from 'brease-next'
import HeroSection from '@/sections/hero-section'
import SmallHeroSection from '@/sections/small-hero-section'
import TextContentSection from '@/sections/text-content-section'
import TestimonialsSection from '@/sections/testimonials-section'

type SectionProps = Record<string, unknown>

export const sectionMap: Record<string, ComponentType<SectionProps>> = {
  hero: HeroSection,
  smallHero: SmallHeroSection,
  text: TextContentSection,
  testimonials: TestimonialsSection,
}

export const contextData: BreaseContextConfig = {
  navigations: [
    { key: 'mainNavigation', id: 'nav-a01c4cbb-21f7-46d5-a89c-564307998128' },
  ],
  collections: [
    { key: 'testimonials', id: 'col-a01c8223-4e4a-40aa-90d9-70149e87322c' },
  ],
  userParams: {},
}
```

---

## Cached Page Fetcher

Deduplicate page fetches across layout, metadata, and page component.

### File: src/lib/brease/get-page.ts

```typescript
import { cache } from 'react'
import { fetchPage } from 'brease-next'

export const getPage = cache(async (slug: string) => fetchPage(slug))
```

---

## Catch-All Layout

Layout with `BreaseContext` wrapping the catch-all route.

### File: src/app/[[...slug]]/layout.tsx

```typescript
import { ReactNode } from 'react'
import { BreaseContext } from 'brease-next'
import { contextData } from '@/lib/brease/config'
import { getPage } from '@/lib/brease/get-page'
import Header from '@/components/header'
import Footer from '@/components/footer'

export default async function SlugLayout({
  children,
  params,
}: {
  children: ReactNode
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')

  return (
    <BreaseContext config={contextData} slug={slugStr} getPage={getPage}>
      <Header />
      <main>{children}</main>
      <Footer />
    </BreaseContext>
  )
}
```

---

## Dynamic Page

Page component with static generation and metadata.

### File: src/app/[[...slug]]/page.tsx

```typescript
import type { Metadata } from 'next'
import {
  BreasePage,
  generateBreasePageParams,
  generateBreasePageMetadata,
} from 'brease-next'
import { sectionMap } from '@/lib/brease/config'
import { getPage } from '@/lib/brease/get-page'
import { notFound } from 'next/navigation'

export async function generateStaticParams() {
  return generateBreasePageParams()
}

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}): Promise<Metadata> {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) return {}

  return generateBreasePageMetadata(result.data, {
    metadataBase: 'https://example.com',
  })
}

export default async function Page({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug } = await params
  const slugStr = (slug ?? []).join('/')
  const result = await getPage(slugStr)

  if (!result.success) {
    if (result.status === 404) return notFound()
    throw new Error(`Failed to load page: ${result.error}`)
  }

  return <BreasePage page={result.data} sectionMap={sectionMap} />
}
```

---

## Root Layout

Root layout with site-level metadata.

### File: src/app/layout.tsx

```typescript
import { ReactNode } from 'react'
import type { Metadata } from 'next'
import { fetchSite } from 'brease-next'
import 'brease-next/styles'
import './globals.css'

export async function generateMetadata(): Promise<Metadata> {
  const result = await fetchSite()

  if (result.success) {
    return {
      title: {
        template: `%s | ${result.data.name}`,
        default: result.data.name,
      },
    }
  }

  return { title: { template: '%s', default: 'My Site' } }
}

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}
```

---

## Section Components

### Hero Section

Full-featured hero section with responsive image.

#### File: src/sections/hero-section.tsx

```typescript
'use client'

import { BreaseImage, type BreaseMedia } from 'brease-next'

interface HeroSectionProps {
  title: string
  body: string
  heroMedia: BreaseMedia
}

export default function HeroSection({
  title,
  body,
  heroMedia,
}: HeroSectionProps) {
  return (
    <section className="relative py-24 sm:py-32">
      <div className="mx-auto max-w-7xl px-6 lg:flex lg:items-center lg:gap-x-10 lg:px-8">
        <div className="mx-auto max-w-2xl lg:mx-0 lg:flex-auto">
          <h1 className="text-5xl font-semibold tracking-tight sm:text-7xl">
            {title}
          </h1>
          <div
            className="mt-8 text-lg text-gray-500"
            dangerouslySetInnerHTML={{ __html: body }}
          />
        </div>
        <div className="mt-16 lg:mt-0 lg:shrink-0 lg:grow">
          {heroMedia && <BreaseImage breaseImage={heroMedia} priority />}
        </div>
      </div>
    </section>
  )
}
```

### Testimonials Section

Section that displays collection data passed via a collection-type element.

#### File: src/sections/testimonials-section.tsx

```typescript
'use client'

import { BreaseImage, type BreaseMedia, type BreaseCollection } from 'brease-next'

interface TestimonialsSectionProps {
  title: string
  testimonials: BreaseCollection
}

export default function TestimonialsSection({
  title,
  testimonials,
}: TestimonialsSectionProps) {
  return (
    <section className="py-24 sm:py-32">
      <div className="mx-auto max-w-7xl px-6 lg:px-8">
        <h2 className="text-4xl font-semibold tracking-tight text-center">
          {title}
        </h2>
        <div className="mt-16 grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
          {testimonials.entries.map((entry) => {
            const elements = entry.elements as Record<string, unknown>
            const avatar = elements.avatar as BreaseMedia | undefined

            return (
              <blockquote key={entry.uuid} className="rounded-2xl border p-8">
                <p className="text-gray-700">
                  &ldquo;{elements.quote as string}&rdquo;
                </p>
                <footer className="mt-6 flex items-center gap-4">
                  {avatar && (
                    <BreaseImage
                      breaseImage={avatar}
                      variant="sm"
                      className="h-12 w-12 rounded-full object-cover"
                    />
                  )}
                  <div>
                    <p className="font-semibold">{elements.author as string}</p>
                    <p className="text-sm text-gray-500">
                      {elements.role as string}
                    </p>
                  </div>
                </footer>
              </blockquote>
            )
          })}
        </div>
      </div>
    </section>
  )
}
```

---

## Navigation Component

Responsive navigation using the `useBrease` hook.

### File: src/components/header.tsx

```typescript
'use client'

import Link from 'next/link'
import { useState } from 'react'
import { useBrease, BreaseLink } from 'brease-next'

export default function Header() {
  const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
  const { navigations } = useBrease()
  const mainNav = navigations.mainNavigation

  if (!mainNav) return null

  return (
    <header className="absolute inset-x-0 top-0 z-50">
      <nav className="flex items-center justify-between p-6 lg:px-8">
        <Link href="/" className="text-xl font-bold">
          Logo
        </Link>

        {/* Desktop navigation */}
        <div className="hidden lg:flex lg:gap-x-8">
          {mainNav.items.map((item) => (
            <BreaseLink
              key={item.uuid}
              linkData={item}
              className="text-sm font-semibold"
            >
              {item.label}
            </BreaseLink>
          ))}
        </div>

        {/* Mobile toggle */}
        <button
          type="button"
          onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
          className="lg:hidden"
        >
          Menu
        </button>
      </nav>

      {/* Mobile menu */}
      {mobileMenuOpen && (
        <div className="fixed inset-0 z-50 bg-white p-6 lg:hidden">
          <button onClick={() => setMobileMenuOpen(false)}>Close</button>
          <div className="mt-6 space-y-2">
            {mainNav.items.map((item) => (
              <BreaseLink
                key={item.uuid}
                linkData={item}
                className="block rounded-lg px-3 py-2 text-base font-semibold"
              >
                {item.label}
              </BreaseLink>
            ))}
          </div>
        </div>
      )}
    </header>
  )
}
```

---

## Next.js Configuration

Complete configuration with redirects, images, and CORS.

### File: next.config.ts

```typescript
import type { NextConfig } from 'next'
import { fetchRedirects } from 'brease-next/server'

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.brease.io',
        pathname: '/**',
      },
    ],
  },
  async redirects() {
    const result = await fetchRedirects()

    if (!result.success) {
      console.error('Failed to fetch redirects:', result.error)
      return []
    }

    return result.data.map((redirect) => ({
      source: redirect.source,
      destination: redirect.destination,
      permanent: redirect.type === '301' || redirect.type === '308',
    }))
  },
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: "frame-ancestors 'self' https://app.brease.io https://dev.brease.io",
          },
        ],
      },
    ]
  },
}

export default nextConfig
```

---

## SEO Configuration

### File: src/app/robots.ts

```typescript
import type { MetadataRoute } from 'next'
import { generateBreaseRobots } from 'brease-next'

export default function robots(): MetadataRoute.Robots {
  return generateBreaseRobots('https://example.com')
}
```

### File: src/app/sitemap.ts

```typescript
import type { MetadataRoute } from 'next'
import { generateSitemap } from 'brease-next'

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const result = await generateSitemap()
  if (!result.success) return []
  return result.data
}
```

---

## Next Steps

For common issues and debugging, see [Troubleshooting](/docs/troubleshooting).
For more patterns, browse the [Implementation Patterns](/docs/project-setup) section.


---

# Troubleshooting

Source: https://docs.brease.io/docs/troubleshooting

Common issues and solutions when using `brease-next` package.

## Installation & Setup Issues

### Issue: Cannot find module 'brease-next'

**Symptoms:**

- Error: `Cannot find module 'brease-next'`
- TypeScript errors for brease-next imports

**Solutions:**

1. **Install the package**:

   ```bash
   npm install brease-next
   ```

2. **Verify installation**:

   ```bash
   npm list brease-next
   ```

3. **Restart development server**:

   ```bash
   # Stop the dev server (Ctrl+C)
   npm run dev
   ```

4. **Clear cache if needed**:
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

---

### Issue: TypeScript path alias not working

**Symptoms:**

- Error: `Cannot find module '@/lib/brease-config'`
- Import errors for `@/` paths

**Solutions:**

1. **Verify tsconfig.json**:

   ```json
   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   ```

2. **Restart TypeScript server** in your IDE:
   - VS Code: Cmd+Shift+P → "TypeScript: Restart TS Server"

---

## Environment & Configuration Issues

### Issue: Environment variables not loading

**Symptoms:**

- Error: `Failed to fetch from : Unauthorized`
- Empty or undefined environment variables

**Solutions:**

1. **Check file naming**:
   - Use `.env.local` for local development
   - Use `.env.production` for production builds
   - Never commit `.env.local` to version control

2. **Verify variable names** (note: `BREASE_DEFAULT_LOCALE` is required):

   ```env
   BREASE_TOKEN=your_token_here
   BREASE_ENV=your_environment_id
   BREASE_DEFAULT_LOCALE=en
   BREASE_REVALIDATION_TIME=30
   ```

3. **Restart development server**:

   ```bash
   # Stop the dev server (Ctrl+C)
   npm run dev
   ```

4. **Check Next.js environment variable access**:
   - Only variables prefixed with `NEXT_PUBLIC_` are available in client components
   - Server-side variables (without prefix) are only available in server components and API routes

---

### Issue: Config not found in context

**Symptoms:**

- Error: `Cannot read properties of undefined (reading 'navigations')`
- Context data is undefined

**Solutions:**

1. **Verify contextData is configured**:

   ```typescript
   // src/lib/brease-config.ts
   export const contextData = {
     navigations: [{ key: 'mainNavigation', id: 'nav-uuid...' }],
     collections: [{ key: 'news', id: 'col-uuid...' }],
   }
   ```

2. **Check BreaseContext receives config and slug**:

   ```typescript
   // src/app/[[...slug]]/layout.tsx
   import { BreaseContext } from 'brease-next';
   import { contextData } from '@/lib/brease/config';

   <BreaseContext config={contextData} slug={slugStr}>
     {children}
   </BreaseContext>
   ```

---

## API & Data Fetching Issues

### Issue: 401 Unauthorized error

**Symptoms:**

- Error: `Failed to fetch from https://...: Unauthorized`
- Status: 401

**Solutions:**

1. **Verify token is correct**:
   - Check Brease dashboard for valid API token
   - Ensure token has proper permissions

2. **Check token format**:

   ```env
   BREASE_TOKEN=your_actual_token  # No quotes or extra spaces
   ```

3. **Verify Authorization header** in brease-next package:
   - The package automatically adds `Bearer` prefix
   - Ensure `BREASE_TOKEN` environment variable is set

---

### Issue: 404 Not Found for pages

**Symptoms:**

- Pages return 404 in production
- `result.status === 404` from `fetchPage()`

**Solutions:**

1. **Verify page exists in Brease**:
   - Check Brease dashboard
   - Ensure page exists
   - Verify slug matches exactly (case-sensitive)

2. **Check environment**:
   - Ensure `BREASE_ENV` matches the environment where pages are published

---

### Issue: Stale content / cache not updating

**Symptoms:**

- Changes in Brease don't appear on site
- Content updates slowly or not at all

**Solutions:**

1. **Check revalidation time**:

   ```env
   BREASE_REVALIDATION_TIME=30  # Seconds
   ```

2. **Force revalidation** in development:

   ```bash
   rm -rf .next
   npm run dev
   ```

3. **For production**, use Next.js revalidation:
   ```typescript
   // In page component
   export const revalidate = 30 // Seconds
   ```

---

### Issue: Collection entries not found

**Symptoms:**

- Error: `Failed to load collection entry`
- Empty collection results

**Solutions:**

1. **Verify collection ID in config**:

   ```typescript
   // src/lib/brease-config.ts
   export const contextData = {
     navigations: [],
     collections: [
       { key: 'news', id: 'col-a01c8223-4e4a-40aa-90d9-70149e87322c' },
     ],
   }
   ```

2. **Verify entries are published**:
   - Check Brease dashboard
   - Ensure collection has published entries

---

## Build & Deployment Issues

### Issue: Build fails with "Failed to fetch pages"

**Symptoms:**

- Build error during `generateStaticParams()`
- Error: `Failed to fetch pages for static generation`

**Solutions:**

1. **Check environment variables in build environment**:
   - Vercel: Add variables in Project Settings → Environment Variables
   - Ensure variables are available for "Production" environment

2. **Verify network access**:
   - Ensure build environment can access Brease API
   - Check firewall rules

3. **Add error handling**:

   ```typescript
   export async function generateStaticParams() {
     const result = await generateBreasePageParams()

     if (!result || result.length === 0) {
       console.warn('No pages found, returning empty params')
       return []
     }

     return result
   }
   ```

---

### Issue: Redirects not working

**Symptoms:**

- Redirects from Brease don't work on site
- Build logs show "Failed to fetch redirects"

**Solutions:**

1. **Check import in next.config.ts**:

   ```typescript
   // Correct:
   import { fetchRedirects } from 'brease-next/server'

   // Incorrect (old approach):
   import { fetchRedirects } from '@/brease/server'
   ```

2. **Verify redirect format** in Brease:
   - Source: `/old-page`
   - Destination: `/new-page`
   - Both should include leading slashes

3. **Check build output**:
   ```bash
   npm run build
   # Look for "Redirects" section in output
   ```

---

### Issue: Images not loading in production

**Symptoms:**

- Images work locally but not in production
- Error: `Invalid src prop`

**Solutions:**

1. **Verify remote patterns in next.config.ts**:

   ```typescript
   images: {
     remotePatterns: [
       {
         protocol: 'https',
         hostname: 'assets.brease.io',
         pathname: '/**',
       },
     ]
   }
   ```

2. **Check image URLs** from Brease:

   ```typescript
   console.log('Image path:', breaseImage.path)
   // Should be full URL starting with https://assets.brease.io/
   ```

   ```

   ```

---

## Component & Rendering Issues

### Issue: Section not rendering

**Symptoms:**

- Console warning: `No component found for section type: {type}`
- Section missing from page

**Solutions:**

1. **Check section map** — keys must match the section `key` in Brease:

   ```typescript
   // In brease-config.ts
   export const sectionMap = {
     hero: HeroSection, // Key must match Brease section key exactly
   }
   ```

2. **Verify section key in Brease**:
   - Check the Editor in the CMS dashboard
   - The section `key` (not name) is what maps to `sectionMap`
   - Keys are case-sensitive

3. **Add section to map**:

   ```typescript
   import NewSection from '@/sections/new-section'

   export const sectionMap = {
     // ... existing sections
     newSection: NewSection, // Add new section
   }
   ```

---

### Issue: Rich text content not rendering

**Symptoms:**

- HTML shows as plain text
- Tags visible on page

**Solutions:**

1. **Use dangerouslySetInnerHTML**:

   ```typescript
   // Correct:
   <div dangerouslySetInnerHTML={{ __html: body }} />

   // Incorrect:
   <div>{body}</div>  // Renders as plain text
   ```

2. **Add CSS for rich text** (optional):
   ```typescript
   <div
     className="prose prose-lg"  // Tailwind Typography
     dangerouslySetInnerHTML={{ __html: content }}
   />
   ```

---

## Context & Hook Issues

### Issue: "useBrease must be used within a BreaseContext"

**Symptoms:**

- Runtime error when using `useBrease()` hook
- App crashes on load

**Solutions:**

1. **Verify BreaseContext wraps app**:

   ```typescript
   // In src/app/layout.tsx
   import { BreaseContext } from 'brease-next';
   import { contextData } from '@/lib/brease-config';

   export default function RootLayout({ children }) {
     return (
       <html>
         <body>
           <BreaseContext config={contextData}>
             {children}
           </BreaseContext>
         </body>
       </html>
     );
   }
   ```

2. **Check component is client component**:

   ```typescript
   'use client' // Must be at top of file

   import { useBrease } from 'brease-next'
   ```

---

### Issue: Cannot destructure navigation from useBrease

**Symptoms:**

- Error: `Cannot read property 'mainNavigation' of undefined`
- Navigation data not accessible

**Solutions:**

1. **Use new destructuring pattern**:

   ```typescript
   // Correct (new pattern):
   const { navigations } = useBrease()
   const { mainNavigation } = navigations

   // Incorrect (old pattern):
   const { navigation } = useBrease()
   ```

2. **Check for undefined**:

   ```typescript
   const { navigations } = useBrease()
   const { mainNavigation } = navigations

   if (!mainNavigation) {
     return null // Or loading state
   }
   ```

3. **Verify key matches config**:

   ```typescript
   // Config:
   export const contextData = {
     navigations: [
       { key: 'mainNavigation', id: 'nav-...' }, // Key here
     ],
   }

   // Usage:
   const { mainNavigation } = navigations // Must match key
   ```

---

## Type & TypeScript Issues

### Issue: Type errors with section props

**Symptoms:**

- TypeScript error: `Property 'title' does not exist`
- Section component has type errors

**Solutions:**

1. **Define proper interface**:

   ```typescript
   import type { BreaseMedia } from 'brease-next'

   interface HeroSectionProps {
     title: string
     body: string
     heroMedia: BreaseMedia
   }

   export default function HeroSection({
     title,
     body,
     heroMedia,
   }: HeroSectionProps) {
     // ...
   }
   ```

2. **Make fields optional** if they might not exist:
   ```typescript
   interface HeroSectionProps {
     title: string
     subtitle?: string // Optional
     heroMedia?: BreaseMedia // Optional
   }
   ```

---

### Issue: Collection element type errors

**Symptoms:**

- Error: `Type 'unknown' is not assignable to...`
- Can't access collection entry fields

**Solutions:**

1. **Cast collection elements**:

   ```typescript
   const title = entry.elements.title as string
   const content = entry.elements.content as string
   const image = entry.elements.featuredImage as BreaseMedia
   ```

2. **Create type for collection**:

   ```typescript
   interface BlogPostElements {
     title: string
     content: string
     excerpt: string
     featuredImage: BreaseMedia
     publishedAt: string
   }

   // Use in component:
   const elements = entry.elements as unknown as BlogPostElements
   const title = elements.title
   ```

---

## Image & Media Issues

### Issue: Images not optimized

**Symptoms:**

- Large image file sizes
- Slow page load times

**Solutions:**

1. **Use BreaseImage component**:

   ```typescript
   import { BreaseImage } from 'brease-next';

   <BreaseImage breaseImage={media} />  // Automatically optimized
   ```

2. **Add responsive sizes**:

   ```typescript
   <Image
     src={media.path}
     alt={media.alt}
     width={media.width}
     height={media.height}
     sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
   />
   ```

3. **Use priority for above-fold images**:
   ```typescript
   <Image
     src={media.path}
     alt={media.alt}
     width={media.width}
     height={media.height}
     priority  // Loads immediately
   />
   ```

---

### Issue: Missing alt text warning

**Symptoms:**

- Console warning: `Image elements must have an alt prop`

**Solutions:**

1. **BreaseImage handles this automatically**:

   ```typescript
   // Fallback chain: breaseImage.alt → breaseImage.name → 'Image alt.'
   <BreaseImage breaseImage={media} />
   ```

2. **For custom Image usage**:
   ```typescript
   <Image
     src={media.path}
     alt={media.alt || media.name || 'Descriptive alt text'}
     width={media.width}
     height={media.height}
   />
   ```

---

## Navigation & Routing Issues

### Issue: Navigation links not working

**Symptoms:**

- Navigation items don't link anywhere
- Clicking navigation does nothing

**Solutions:**

1. **Use BreaseLink component** — handles internal/external links automatically:

   ```typescript
   import { BreaseLink } from 'brease-next'

   {mainNavigation.items.map((item) => (
     <BreaseLink key={item.uuid} linkData={item}>
       {item.label}
     </BreaseLink>
   ))}
   ```

2. **Verify navigation UUID in config**:
   ```typescript
   // In brease-config.ts
   export const contextData = {
     navigations: [{ key: 'mainNavigation', id: 'nav-correct-uuid-here' }],
   }
   ```

---

### Issue: 404 on refresh for dynamic routes

**Symptoms:**

- Pages work when navigating via Link
- Pages 404 when refreshing or direct URL access

**Solutions:**

1. **Ensure generateStaticParams is called**:

   ```typescript
   export async function generateStaticParams() {
     return generateBreasePageParams()
   }
   ```

2. **Check build output**:

   ```bash
   npm run build
   # Look for list of generated static pages
   ```

3. **Use catch-all route** `[[...slug]]` instead of `[subpageSlug]`:
   ```
   src/app/
   └── [[...slug]]/
       ├── layout.tsx  # BreaseContext wrapper
       └── page.tsx    # Page rendering
   ```

---

## Performance Issues

### Issue: Slow page loads

**Symptoms:**

- Pages take long to load
- High Time to First Byte (TTFB)

**Solutions:**

1. **Implement static generation**:

   ```typescript
   export const dynamic = 'force-static'
   export async function generateStaticParams() {
     return generateBreasePageParams()
   }
   ```

2. **Reduce revalidation time**:

   ```env
   BREASE_REVALIDATION_TIME=3600  # 1 hour instead of 30 seconds
   ```

3. **Optimize images**:
   - Use BreaseImage component
   - Add appropriate sizes
   - Use priority for above-fold images

---

### Issue: Large bundle size

**Symptoms:**

- Slow initial page load
- Large JavaScript download

**Solutions:**

1. **Use dynamic imports** for heavy components:

   ```typescript
   import dynamic from 'next/dynamic';

   const HeavySection = dynamic(() => import('@/sections/heavy-section'), {
     loading: () => <div>Loading...</div>,
   });
   ```

2. **Check client components**:
   - Only use `'use client'` when necessary
   - Keep server components when possible

3. **Analyze bundle**:
   ```bash
   npm install @next/bundle-analyzer
   # Configure in next.config.ts
   ```

---

## Debugging Tips

### Enable verbose logging

Add logging to track data flow:

```typescript
export default async function Page() {
  const result = await fetchPage('/about')

  console.log('Fetch result:', {
    success: result.success,
    status: result.status,
    ...(result.success ? { pageData: result.data } : { error: result.error }),
  })

  // ... rest of component
}
```

### Check build output

Build output shows useful information:

```bash
npm run build

# Look for:
# - List of generated static pages
# - Redirects
# - Image optimization info
# - Route segments
```

### Use React DevTools

Install React DevTools to inspect:

- Component props
- Context values
- Render performance

### Network tab

Check browser Network tab:

- Verify API calls succeed
- Check response data
- Monitor cache headers

---

## Getting Help

If you're still experiencing issues:

1. **Check environment variables** - Most issues stem from incorrect configuration
2. **Review error messages carefully** - They often indicate the exact problem
3. **Compare with sample project** - Reference the working implementation
4. **Check Brease API directly** - Use tools like Postman to test API endpoints
5. **Review Next.js docs** - Many issues relate to Next.js concepts, not the package

---

## Common Gotchas

1. **Leading slashes**: Always include leading slashes in slugs (`/about`, not `about`)
2. **Server vs client**: Environment variables without `NEXT_PUBLIC_` only work server-side
3. **Type casting**: Collection elements are untyped, always cast them
4. **Client directive**: `'use client'` must be first line in file
5. **Case sensitivity**: Section keys and slugs are case-sensitive
6. **Build cache**: Delete `.next` folder if changes don't appear
7. **Import paths**: All imports from `'brease-next'` package, not local paths
8. **Context pattern**: Use `navigations` and `collections` objects with destructuring

---

## Preventive Best Practices

1. **Always check success before accessing data**:

   ```typescript
   if (!result.success) {
     // Handle error
   }
   ```

2. **Use TypeScript strictly**:
   - Enable `strict` mode in tsconfig.json
   - Define interfaces for all section props
   - Type cast collection elements

3. **Test error states**:
   - Test with invalid slugs
   - Test with missing environment variables
   - Test network failures

4. **Monitor build output**:
   - Check for warnings
   - Verify expected number of pages generated
   - Confirm redirects are applied

5. **Use static generation when possible**:
   - Better performance
   - Better SEO
   - Reduced API load

6. **Configure context data properly**:
   - Define all navigations and collections upfront
   - Use descriptive keys that match your usage
   - Verify UUIDs are correct

---

## Locale Issues

### Issue: Wrong locale content displayed

**Symptoms:**

- Content shows in default locale regardless of URL
- Locale prefix in URL is ignored

**Solutions:**

1. **Set `BREASE_DEFAULT_LOCALE`** in `.env.local`:

   ```env
   BREASE_DEFAULT_LOCALE=en
   ```

2. **Pass the full slug to BreaseContext** (including locale prefix):

   ```typescript
   const slugStr = (slug ?? []).join('/')
   // For URL /sk/about-us, slugStr = "sk/about-us"
   // Locale "sk" is auto-derived from the first segment
   <BreaseContext config={contextData} slug={slugStr}>
   ```

3. **Ensure locales are active** in the CMS environment settings.

---

### Issue: Language switcher shows no locales

**Symptoms:**

- `availableLocales` from `useBrease()` is empty
- Language switcher renders nothing

**Solutions:**

1. **Check the CMS**: ensure multiple locales are added and active in the environment.
2. **Verify `fetchLocales()` works**: test directly in a server component.
3. **Check console for errors**: BreaseContext logs `Failed to load locales` if the fetch fails.

---

## Preview Mode Issues

### Issue: Preview iframe is blank or blocked

**Symptoms:**

- CMS preview shows empty iframe
- Browser console shows CSP/framing errors

**Solutions:**

1. **Add CSP headers** in `next.config.ts`:

   ```typescript
   async headers() {
     return [{
       source: '/:path*',
       headers: [{
         key: 'Content-Security-Policy',
         value: "frame-ancestors 'self' https://app.brease.io https://dev.brease.io",
       }],
     }]
   }
   ```

2. **Set preview domain** in the CMS site settings to your deployed URL.

3. **Import toolbar styles** in your root layout:
   ```typescript
   import 'brease-next/styles'
   ```


---

# Changelog

Source: https://docs.brease.io/docs/changelog

Version history for the `brease-next` package.

---

## v0.2.2 (Current)

- Added **template selection** to CLI scaffolding — choose between Starter and Base templates when running `npx brease-next`
- Simplified **ISR caching configuration** for easier revalidation setup
- Added **BreaseLink** component for rendering link elements with proper internal/external handling
- Added **BreaseStructuredData** and **BreaseCustomCode** components for SEO and script injection
- Added **ensureSuccess** utility and **BreaseFetchError** class for streamlined error handling in fetch calls
- Added **fetchLocales** and **fetchAlternateLinks** functions for multi-locale support
- Added **generateBreaseRobots** and **generateSitemap** functions for SEO automation
- Added **validateBreaseConfig** for explicit configuration validation at startup

## v0.2.1

- Fixed **BreaseClientProvider** state sync for App Router navigation

{% callout title="Upgrade recommended" type="warning" %}
Without this fix, navigating between pages in a Next.js App Router application would show stale content. The client provider now correctly syncs state when the route changes.
{% /callout %}

## v0.2.0

- Added **preview mode** integration with PostMessage protocol
- Added **BreasePreviewListener** component for iframe communication between the CMS Builder and your frontend
- Added **SectionToolbar** component for in-preview section editing (click-to-edit from the preview iframe)
- Improved **revalidation handling** for more reliable ISR cache updates

## v0.1.0

Initial release of `brease-next`.

- Core fetch functions: **fetchPage**, **fetchAllPages**, **fetchSite**, **fetchCollectionById**, **fetchEntryById**, **fetchNavigation**, **fetchRedirects**
- **BreasePage** component with section mapping via `sectionMap`
- **BreaseImage** component with responsive variant support
- **BreaseContext** server component and **useBrease** hook for global data (navigations, collections)
- **generateBreasePageParams** for dynamic route generation and **generateBreasePageMetadata** for SEO metadata
- **CLI scaffolding tool** (`npx brease-next`) for bootstrapping a new Brease-powered Next.js project