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:

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:

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.

function validateBreaseConfig(): BreaseConfig

Environment variables read:

Returns: BreaseConfig

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

Example:

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.

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

Parameters:

Returns: Promise<BreaseResponse<BreasePage>>

Example:

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.

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

Parameters:

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

Example:

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.

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

Parameters:

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

Example:

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.

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

Parameters:

Returns: Promise<BreaseResponse<BreaseCollection>>

Example:

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.

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

Parameters:

Returns: Promise<BreaseResponse<BreaseCollectionEntry>>

Example:

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.

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

Parameters:

Returns: Promise<BreaseResponse<BreaseNavigation>>

Example:

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.

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

Returns: Promise<BreaseResponse<BreaseSite>>

Example:

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.

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

Returns: Promise<BreaseResponse<BreaseRedirect[]>>

Example:

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:

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.

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

Returns: Promise<BreaseResponse<BreaseLocale[]>>

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

Example:

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.

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

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

Example:

// 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.

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

Parameters:

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:

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.

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

Parameters:

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

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

Example:

// 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.

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

Returns: Promise<BreaseResponse<MetadataRoute.Sitemap>>

Example:

// 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.

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

Parameters:

Returns: T -- the unwrapped data

Throws: BreaseFetchError if result.success is false

Example:

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.

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

Properties:

Example:

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.

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

Pattern:

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

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

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

SectionElementProps

type SectionElementProps = Record<string, unknown>

BreaseMedia

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

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

BreaseNavigation

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

BreaseNavigationItem

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

BreaseLinkData

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

BreaseSite

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

BreaseCollection

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

BreaseCollectionEntry

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

BreaseRedirect

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

BreaseLocale

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

BreaseContextConfig

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

BreaseGetPage

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

GenerateBreaseRobotsOptions

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

Next Steps

• Components -- BreasePage, BreaseImage, BreaseLink, and more
• Context & Hooks -- BreaseContext and useBrease()
• SEO & Metadata -- metadata generation, robots, sitemap