API Reference

Complete reference for all brease-next package functions.

Import

All functions are exported from the main package:

import {
  fetchPage,
  fetchAllPages,
  fetchSite,
  fetchCollectionById,
  fetchEntryBySlug,
  fetchNavigation,
  fetchRedirects,
  generateBreasePageParams,
  generateBreaseCollectionParams,
  generateBreasePageMetadata,
} from 'brease-next';

Types can also be imported:

import type {
  BreaseResponse,
  BreasePage,
  BreaseRedirect,
  BreaseMedia
} from 'brease-next';

Page Functions

fetchPage

Fetches a single page by slug.

Signature:

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

Parameters:

• pageSlug (string): The page slug including leading slash (e.g., /, /about, /contact)

Returns: BreaseResponse<BreasePage> - Page data including sections and metadata

Example:

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

if (result.success) {
  console.log('Page name:', result.data.name);
  console.log('Sections:', result.data.sections.length);
} else {
  console.error('Error:', result.error);
}

Common Use Cases:

• Rendering individual pages
• Fetching page metadata
• Building dynamic routes

fetchAllPages

Fetches all page slugs in the site.

Signature:

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

Parameters: None

Returns: BreaseResponse<{ slug: string }[]> - Array of objects containing page slugs

Example:

const result = await fetchAllPages();

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

Common Use Cases:

• Generating static params for all pages
• Building sitemaps
• Navigation generation

fetchSite

Fetches site-level information.

Signature:

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

Parameters: None

Returns: BreaseResponse<BreaseSite> - Site data including name, domain, and settings

Example:

const result = await fetchSite();

if (result.success) {
  console.log('Site name:', result.data.name);
  console.log('Domain:', result.data.domain);
  console.log('Sitemap indexing:', result.data.sitemapIndexing);
}

Common Use Cases:

• Setting site-wide metadata
• Displaying site name in title tags
• Conditional sitemap generation

Collection Functions

fetchCollectionById

Fetches all entries in a collection.

Signature:

async function fetchCollectionById(
  collectionId: string
): Promise<BreaseResponse<BreaseCollectionEntry[]>>

Parameters:

• collectionId (string): The collection UUID (e.g., col-a01c8223-4e4a-40aa-90d9-70149e87322c)

Returns: BreaseResponse<BreaseCollectionEntry[]> - Array of collection entries

Example:

const result = await fetchCollectionById('col-123');

if (result.success) {
  console.log('Total entries:', result.data.length);
  result.data.forEach(entry => {
    console.log('Entry slug:', entry.slug);
    console.log('Entry elements:', entry.elements);
  });
}

Common Use Cases:

• Listing blog posts
• Generating collection entry routes
• Building archive pages

fetchEntryBySlug

Fetches a specific collection entry by slug.

Signature:

async function fetchEntryBySlug(
  collectionId: string,
  entrySlug: string
): Promise<BreaseResponse<BreaseCollectionEntry>>

Parameters:

• collectionId (string): The collection UUID
• entrySlug (string): The entry slug including leading slash (e.g., /my-blog-post)

Returns: BreaseResponse<BreaseCollectionEntry> - Single collection entry data

Example:

const result = await fetchEntryBySlug('col-123', '/my-blog-post');

if (result.success) {
  const entry = result.data;
  console.log('Entry slug:', entry.slug);

  // Access custom fields
  const title = entry.elements.title as string;
  const content = entry.elements.content as string;
  const image = entry.elements.featuredImage as BreaseMedia;

  console.log('Title:', title);
}

Common Use Cases:

• Rendering individual blog posts
• Product detail pages
• Dynamic collection entry routes

Note: Collection entry elements are untyped (Record<string, unknown>). Cast to appropriate types based on your collection schema.

Navigation Functions

fetchNavigation

Fetches navigation data by UUID.

Signature:

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

Parameters:

• navigationId (string): The navigation UUID (e.g., nav-a01c4cbb-21f7-46d5-a89c-564307998128)

Returns: BreaseResponse<BreaseNavigation> - Navigation structure with items

Example:

const result = await fetchNavigation('nav-123');

if (result.success) {
  console.log('Navigation name:', result.data.name);

  result.data.items.forEach(item => {
    console.log('Item:', item.value);
    console.log('Type:', item.type);

    if (item.target) {
      console.log('Internal link:', item.target.slug);
    }

    if (item.url) {
      console.log('External link:', item.url);
    }
  });
}

Navigation Item Structure:

{
  value: string;           // Display text
  target?: {               // Internal link (optional)
    slug: string;
  };
  type: string;            // "internal" or "external"
  url?: string;            // External URL (optional)
}

Common Use Cases:

• Header navigation menus
• Footer links
• Sidebar navigation

fetchRedirects

Fetches all redirect rules.

Signature:

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

Parameters: None

Returns: BreaseResponse<BreaseRedirect[]> - Array of redirect rules

Example:

const result = await fetchRedirects();

if (result.success) {
  result.data.forEach(redirect => {
    console.log('From:', redirect.source);
    console.log('To:', redirect.destination);
    console.log('Type:', redirect.type); // '301' | '302' | '307' | '308'
  });
}

Common Use Cases:

• Next.js redirects() configuration
• Building redirect middleware
• SEO redirect management

Note: This function is typically used in next.config.ts:

import { fetchRedirects, type BreaseRedirect } from 'brease-next';

Helper Functions

generateBreasePageParams

Generates static params for all pages (used in generateStaticParams).

Signature:

async function generateBreasePageParams(): Promise<{ subpageSlug: string }[]>

Parameters: None

Returns: Array of param objects for Next.js generateStaticParams

Example:

// In a dynamic route: src/app/[subpageSlug]/page.tsx
export async function generateStaticParams() {
  return generateBreasePageParams();
  // Returns: [
  //   { subpageSlug: "about" },
  //   { subpageSlug: "contact" },
  //   { subpageSlug: "services" }
  // ]
}

Behavior:

• Fetches all pages using fetchAllPages()
• Filters out the root page (/)
• Removes leading slashes from slugs
• Returns array suitable for Next.js static generation

generateBreaseCollectionParams

Generates static params for collection entries (used in generateStaticParams).

Signature:

async function generateBreaseCollectionParams(
  collectionId: string
): Promise<{ slug: string }[]>

Parameters:

• collectionId (string): The collection UUID

Returns: Array of param objects for Next.js generateStaticParams

Example:

// In a dynamic route: src/app/blog/[slug]/page.tsx
const BLOG_COLLECTION_ID = 'col-123';

export async function generateStaticParams() {
  return generateBreaseCollectionParams(BLOG_COLLECTION_ID);
  // Returns: [
  //   { slug: "my-first-post" },
  //   { slug: "another-post" }
  // ]
}

Behavior:

• Fetches all entries in the collection
• Filters out entries with / slug
• Removes leading slashes from slugs
• Returns array suitable for Next.js static generation

generateBreasePageMetadata

Generates Next.js metadata from Brease page data.

Signature:

async function generateBreasePageMetadata(pageSlug: string): Promise<Metadata>

Parameters:

• pageSlug (string): The page slug including leading slash

Returns: Next.js Metadata object with SEO tags

Example:

// In a page component
export async function generateMetadata(): Promise<Metadata> {
  return generateBreasePageMetadata('/about');
}

Generated Metadata:

{
  title: "Page Title",
  description: "Meta description",
  robots: {
    index: false,    // Based on page.indexing setting
    follow: false
  },
  openGraph: {
    title: "OG Title",
    description: "OG Description",
    type: "website",
    url: "https://example.com/page",
    images: [{
      url: "https://..."
    }]
  }
}

Fallback Behavior:

• Uses page title if OpenGraph title not set
• Uses meta description for OpenGraph if OG description not set
• Returns empty object if page fetch fails
• Defaults to type: 'website' if not specified

Common Use Cases:

• Automatic SEO metadata generation
• OpenGraph social sharing tags
• Dynamic page titles and descriptions

Type Definitions

BreaseResponse<T>

Generic response wrapper for all API calls:

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

BreasePage

interface BreasePage {
  name: string | null;
  slug: string | null;
  uuid: string | null;
  parent: null;
  indexing: boolean;
  variables: string | null;
  customCode: string | null;
  openGraphUrl: string | null;
  openGraphType: string | null;
  openGraphImage: string | null;
  openGraphTitle: string | null;
  metaDescription: string | null;
  openGraphDescription: string | null;
  sections: BreaseSection[];
}

BreaseSection

interface BreaseSection {
  name: string;
  page_section_uuid: string;
  type: string;
  uuid: string;
  elements: Record<string, unknown>;
}

BreaseMedia

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: BreaseMediaVariant[];
}

BreaseMediaVariant

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

BreaseNavigation

interface BreaseNavigation {
  name: string;
  uuid: string;
  description?: string;
  items: {
    value: string;
    target?: {
      slug: string;
    };
    type: string;
    url?: string;
  }[];
}

BreaseSite

interface BreaseSite {
  uuid: string;
  name: string;
  domain: string;
  sitemapIndexing: boolean;
}

BreaseCollectionEntry

interface BreaseCollectionEntry {
  slug: string;
  elements: Record<string, unknown>;
}

BreaseRedirect

interface BreaseRedirect {
  source: string;
  destination: string;
  permanent: '301' | '302' | '307' | '308';
}

Next Steps

Now that you understand the API functions, learn about the Components for rendering Brease content.