Connect a site
What a site needs, and what Brease sets up during onboarding.
Requirements
- GitHub. The repository is connected through the Brease GitHub App. Brease reads it, opens draft pull requests and pushes published changes straight to the production branch. Branch rules that block a direct push (required pull requests, status checks, signed commits) stop setup, unless the Brease app may bypass them. Rules Brease can't read show as a warning and don't block; a push that really is refused shows when publishing.
- Hosting, chosen first in onboarding:
- Vercel. A Vercel project linked to the same repository, connected through the Brease Vercel integration. Brease takes the production branch and the root directory (for monorepos) from it, reads its environment variables for the preview, and writes its own variables into it. Best for Next.js: content changes go live in seconds.
- Cloudflare (experimental). The site is built to static files and served by a Cloudflare Worker on Cloudflare's free plan. Every publish rebuilds the site, which takes a minute or two. Next.js runs there through an adapter that doesn't support every feature, so Vercel is the safer choice for Next.js. Custom domains need the domain's zone on the connected Cloudflare account, active (its nameservers point at Cloudflare) and on a full setup.
- A JavaScript site with a
package.json, using npm, pnpm, Yarn or Bun. The dev server must listen on the port in thePORTenvironment variable.
Note
GitHub is the only git host Brease supports at the moment.
Frameworks
Brease detects the framework from the repository. The framework decides how the live site picks up a content-only release:
| Framework | Content refresh |
|---|---|
| Next.js on Vercel | Revalidate: Brease calls the site's revalidate route with the changed URLs. |
| Every other framework (Nuxt, Remix / React Router, Astro, SvelteKit, Vite, static sites) | Redeploy: Brease triggers a new build on the host. |
| Any framework on Cloudflare | Redeploy, always. |
brease-client ships a ready revalidate route only for Next.js. Another server-rendered framework can add its own with verifyRevalidate() and then switch the site to Revalidate under Developer settings › Connections.
brease-client works in any runtime. Its Next.js helpers (brease-client/next: cached fetch, revalidate route, redirects, metadata) make Next.js the most complete integration.
Onboarding steps
Creating a site needs credits on the team; a team without them is told before any setup starts.
- Your site: the site's name and locales.
- GitHub: choose where the site is hosted (Vercel or Cloudflare), then pick the repository, or create a new one from the starter for that host. GitHub opens in a new tab to install the Brease app; setup picks it up when you come back. If GitHub shows the app's settings instead, it was already installed on that account: use Already installed? Connect it. The GitHub account can be changed later with Change.
- Hosting: link the Vercel project, or connect the Cloudflare account. Brease detects the framework, package manager and dev command, and writes its environment variables. On Vercel, the project is found by its repository in the account or team you picked when connecting. If there's none, Brease asks before creating one in that scope, so a project never lands in the wrong team. If a project with the same name exists but the integration wasn't given access to it, Brease says so instead of creating a second one.
- Prepare the editor: Brease builds a sandbox snapshot with dependencies installed, so later editor sessions start faster. If the site can't start there (a failing install, a dev server that crashes), Fix it in the editor opens the editor anyway: the preview shows the error and the AI can fix the code. Setup finishes once that fix is published. When editing sandboxes are busy, the step retries by itself.
- Google (optional): connect Search Console and Google Analytics, or skip and connect later under Connections. See SEO & analytics.
- Open the editor: the first release goes live and the editor opens. A site that doesn't read its content from Brease yet (no
brease-clientin itspackage.json, or noBREASE.md, in the root folder) gets two choices first: set it up yourself with Integrate a site and click Check again, or Convert with Brease, which shows an estimated credit range for the site's size and has the AI in the editor convert it.
Domains are managed from Connections › Domains; the first working custom domain is the site's address in Brease.
Environment variables
Brease writes these into the hosting project (on Cloudflare, its build variables, plus Worker secrets for BREASE_TOKEN and BREASE_API_URL when the site is Next.js, since build variables don't reach pages rendered on request) and then redeploys production:
| Variable | Environments | Purpose |
|---|---|---|
BREASE_TOKEN | production | Read-only production token (brs_live_…): it identifies the site and reads only published content. |
BREASE_TOKEN | preview, development | Read-only preview token: it also reads drafts, so draft previews show their content. |
BREASE_API_URL | production, preview, development | Only when the delivery API isn't https://api.brease.io, the address brease-client uses by default (for example on a test environment). Set it yourself to point a site at another environment. |
BREASE_REVALIDATE_SECRET | production | Revalidating sites only (not on Cloudflare). Signs the revalidate webhook. |
NEXT_PUBLIC_SITE_URL | production, preview | Next.js sites on Vercel that don't set it yet, once a domain is known. When the site's main domain changes, Brease updates it, as long as it still holds the address Brease wrote. |
Rotating the tokens writes new ones and redeploys production; the old ones keep working for 24 hours so the running deployment isn't cut off. If the redeploy can't start, the old ones stay valid until you revoke them. A site set up before tokens had scopes has one preview token in every environment; it gets the pair the next time Brease rewrites its variables (Connections › Rewrite env vars), and the dashboard reminds you until then.
On Cloudflare, production builds get the production token and non-production branch builds the preview token (Workers Builds keeps separate build variables for each). Next.js sites there keep one preview token everywhere: Worker secrets also reach preview versions, so the live Worker holds a token that can read drafts. Keep its variables private.
For local development, pull them with vercel env pull or copy them into .env.local. On Vercel that gives you the preview token.
Inside the editor's sandbox the site runs with its own hosting variables, except that BREASE_API_URL points at a local content server that reads .brease/, BREASE_TOKEN is sandbox, and BREASE_PREVIEW=1 is set. Your code doesn't need to do anything different there.
Keeping connections working
- GitHub. A renamed repository is followed by itself. A repository moved to another account switches to the Brease app's installation there, if the team has one; otherwise the site shows as disconnected and setup offers to reconnect it. Brease also checks the app's installations every six hours, so a removed or suspended installation disconnects its sites even if GitHub's notice was lost.
- Vercel. Brease doesn't keep a long-lived Vercel token: it gets a short-lived one for the integration's installation when it needs one. If the integration is removed or disabled on Vercel (for example when the person who installed it leaves the Vercel team), the site shows the connection as lost. Connecting Vercel again restores it and writes back any variables Vercel removed with the integration.