Brease - API Documentation

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

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:

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:

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 -- manual setup and configuration details
Components -- building section components
Context & Hooks -- configuring BreaseContext
API Reference -- all available functions and types