Brease Docs

Integrate a site

Step by step, from an existing site to one whose content is edited in Brease.

This is the whole path for a site you already have. Starting fresh? The starter has all of it done. The AI in the editor can also do these steps for you; this page is for doing them yourself, or for checking its work.

Two ways to get there

Brease counts a site as integrated once its package.json uses brease-client (or the @brease/client alias) and it has a BREASE.md, both in the site's root folder. Until then:

  • Setup's last step offers both paths: Open the guide (this page), then Check again once your changes are pushed; or Convert with Brease, which shows an estimate of the AI credits the conversion takes (a range, from the number of pages and the size of the site's source code) next to your team's balance.
  • The editor shows a banner in the chat with the same two choices. It can't be dismissed, and it goes away as soon as the working tree uses brease-client and has a BREASE.md.
  • The AI only converts. Asked for anything else, it says the site has to be converted first and offers to do it. It can read the code, but it changes code only once the conversion has started, and it doesn't touch content, SEO or media until the site reads them from Brease. Only developers on the site can start the conversion.

The AI follows the same steps as this page and checks what's already done, so a conversion that stopped halfway can be continued.

The examples use Next.js (App Router). Other frameworks use the same calls; see the Astro and static sites notes at the end.

1. Connect the site

Add the site in Brease and go through onboarding. It connects the repository and the hosting project, and writes BREASE_TOKEN (and, for Next.js, BREASE_REVALIDATE_SECRET) into the hosting project. brease-client reads content from https://api.brease.io by default; BREASE_API_URL is only set when a site should use another address. For local development, copy the variables into .env.local.

2. Create the client

pnpm add brease-client
src/lib/brease.ts
import { createBrease } from 'brease-client'
import { breaseFetch } from 'brease-client/next'

// Reads BREASE_TOKEN (and BREASE_API_URL if set); tags every request with 'brease' for revalidation.
export const brease = createBrease({ fetch: breaseFetch() })

Keep the token on the server: call brease from server components, route handlers and build scripts, never from the browser.

3. Route pages

One catch-all route renders every page in every locale. brease.route() turns the URL into a page and a locale for whichever URL strategy the site uses.

src/app/[[...path]]/page.tsx
import { notFound } from 'next/navigation'
import { toMetadata } from 'brease-client/next'
import { brease } from '@/lib/brease'

export const revalidate = 60

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

async function load(params: Props['params']) {
  const route = await brease.route((await params).path)
  return route ? brease.getPage<{ title: string; body: string }>(route.slug, { locale: route.locale }) : null
}

export async function generateStaticParams() {
  // The build goes on without pre-rendered pages if the content API has a hiccup; pages then render on first request.
  try {
    return await brease.routes()
  } catch (err) {
    console.warn(`Brease pages unavailable at build time: ${(err as Error).message}`)
    return []
  }
}

export async function generateMetadata({ params }: Props) {
  const page = await load(params)
  return page ? toMetadata(page.resolvedSeo) : {}
}

export default async function Page({ params }: Props) {
  const page = await load(params)
  if (!page) notFound()
  return (
    <main>
      <h1 data-brease="title">{page.content.title}</h1>
      <div data-brease="body" dangerouslySetInnerHTML={{ __html: page.content.body }} />
    </main>
  )
}

Remove the routes this one replaces (app/page.tsx, app/[slug]/page.tsx): two dynamic folders side by side break routing. With more than one page layout, pick the template from page.content.template; see the recommended structure.

4. Move content into Brease

Every text, image and link an editor should change comes from page.content instead of the code. Decide each page's shape (the content model) and use the shared shapes for special values:

ValueShape
Image{ assetId, url, alt, width?, height? }
Link{ label, href }; a link to another page also has pageId, and href is filled in per locale
Rich textan HTML string

Things every page shares (header and footer texts, contact details) go on the site-wide page, slug _global. Read it with empty defaults so the site renders without it, and read menus with getNavigation:

const global = await brease.getPage<Global>('_global', { locale })
const main = await brease.getNavigation('main', { locale })

Describe each template in a content.schema.json so Brease can check content before saving it.

5. Add editor markers

Mark every element that shows content, so editors can click it in the preview and the AI can confirm its changes:

import { fieldPath, navPath } from 'brease-client'

<h1 data-brease="hero.title">{content.hero.title}</h1>
<nav data-brease={navPath('main')}>{/* items */}</nav>
<p data-brease={fieldPath('footer.copyright', global.pageId)}>{global.content.footer.copyright}</p>

See Editor markers for paths in lists and on other pages.

6. Render SEO

toMetadata(page.resolvedSeo) covers titles, descriptions, canonicals, hreflang, Open Graph and robots. Two parts need elements of their own, in the page or layout:

import { customTags, jsonLd } from 'brease-client'

{jsonLd(page.resolvedSeo).map((item, i) => (
  <script key={i} type="application/ld+json" dangerouslySetInnerHTML={{ __html: item.json }} />
))}
{customTags(page.resolvedSeo).map(({ tag: Tag, attrs, content }, i) => {
  const props = Object.fromEntries(Object.entries(attrs).map(([k, v]) => [k, v === '' ? true : v]))
  return content ? <Tag key={i} {...props} dangerouslySetInnerHTML={{ __html: content }} /> : <Tag key={i} {...props} />
})}

Use site.url (from getSite()) for metadataBase, and brease.sitemap(site.url) in app/sitemap.ts.

7. Refresh on publish

A content-only publish calls the site's revalidate route, so new content shows within seconds and without a build:

src/app/api/brease/revalidate/route.ts
import { revalidateHandler } from 'brease-client/next'

export const POST = revalidateHandler() // checks BREASE_REVALIDATE_SECRET

8. Apply redirects

Redirects managed in Brease apply per request, so a new one works as soon as it's published:

src/proxy.ts
import { type NextRequest, NextResponse } from 'next/server'
import { matchRedirect } from 'brease-client'
import { brease } from '@/lib/brease'

export async function proxy(req: NextRequest) {
  const hit = matchRedirect(await brease.getRedirects().catch(() => []), req.nextUrl.pathname)
  return hit ? NextResponse.redirect(new URL(hit.destination, req.url), hit.status) : NextResponse.next()
}

export const config = { matcher: ['/((?!_next|api|.*\\..*).*)'] }

9. Images

Brease serves files as they are. To resize them, allow the media host in next/image:

next.config.ts
export default {
  images: { remotePatterns: [{ protocol: 'https', hostname: '*.supabase.co', pathname: '/storage/v1/object/public/**' }] }
}

10. Add BREASE.md

Add a BREASE.md at the repository root that tells the AI how the site is built. Brease counts the site as integrated only when the repository has both BREASE.md and brease-client in package.json.

  • Sections: let editors add, move and delete page sections themselves.
  • GA4: render ga4Tag(site) in the root layout; see brease-client.

Check it

npx brease-client check

It checks the sections setup and the content in .brease/ or brease-seed/. Then open the site in the Brease editor: every marked element should be clickable with the Edit tool, and a publish should show on the live site within a minute.

Astro and static sites

Static sites (Astro, or anything else built to files, for example on Cloudflare) read content at build time, and every publish rebuilds the site. The differences:

  • Client: createBrease() picks up the commit being built on Vercel, Cloudflare Workers Builds and Cloudflare Pages by itself, so a build reads the content released with its commit. On brease-client 0.8.2 or older, pass commit: process.env.WORKERS_CI_COMMIT_SHA on Cloudflare.
  • Routing: a catch-all page (src/pages/[...path].astro) with getStaticPaths from brease.routes(); see the Astro example.
  • SEO: breaseHead(page.resolvedSeo) from brease-client/astro, or headTags() from brease-client/html, includes structured data and custom code.
  • No revalidate route: Brease rebuilds the site instead.
  • Redirects: there's no server to apply them per request, so write them to a _redirects file at build time. The Astro starter has a script for it.

On this page