Next.js

@blokcms/next connects a Next.js site (App Router, Next.js 16): every URL is a page in BlokCms, cached until editors publish, with unpublished changes in the visual editor and in share links. You write the components; the package does the rest. For TanStack Start, see TanStack Start.

Set up

npx create-next-app@latest my-site    # or your existing app
cd my-site
npx @blokcms/cli init
npm run dev

init signs you in through the browser, asks which space has the content (or makes one with starter content), and then:

• writes .env.local with the space's keys (and keeps it out of git), and adds your dev server (http://localhost:3000, or the port your dev script sets) as a Local website of the visual editor;
• adds the routes (below) and blokcms/: a component for every block type in your space, a header and footer, and the site that ties them together;
• installs @blokcms/next, @blokcms/client and @blokcms/react.

Files that are there already are left alone, so it's safe to run again. create-next-app's welcome page (app/page.tsx) is renamed: your home page comes from BlokCms now.

Going live

npx @blokcms/cli connect https://www.example.com

It adds the site as a Live website of the visual editor, makes its keys and the publish webhook, and prints the environment variables for your host. On Vercel, paste them all at once under Project → Settings → Environment Variables, then deploy. When editors publish, the site shows it within seconds.

Your code

One file says how the site looks. init writes it from your space's types; change it as you like.

// blokcms/site.tsx
"use client";
import { createSite } from "@blokcms/react";
import { HeroBlock, TextBlock } from "./blocks";
import { Layout } from "./layout";

export const Site = createSite({
  blocks: { hero: HeroBlock, text: TextBlock }, // one component per block type
  layout: Layout,                               // header and footer
  pages: { page: "body" },                      // a page shows its blocks field
});

A block component gets the block and its fields. Spread editable(block) on its root element, so editors can click it in the visual editor:

import { type BlockProps, editable, editableField } from "@blokcms/react";

export function HeroBlock({ block, fields }: BlockProps<{ headline?: string }>) {
  return (
    <section {...editable(block)}>
      <h1 {...editableField(block, "headline")}>{fields.headline}</h1>
    </section>
  );
}

Any component inside reads the globals, menus and page with useSite(). Globals and the page update while editors type in the visual editor. Sites set up before @blokcms/react had them import createSite and useSite from @blokcms/next/client, which still works.

The routes

Each is a few lines that call blok (blokcms/index.ts: createBlok({ Site })):

With Cache Components (create-next-app's default), the page route also exports ensureStatic = "navigation" and instant = false: a page's first visit waits for the whole page, so a page not found answers 404 and an old address redirects. init adds them when next.config turns Cache Components on; remove them if you turn them off. Next.js reads route settings from the file itself, so they can't come from the package.

Options

export const blok = createBlok({
  Site,
  types: ["page", "blog_post"],      // content types with pages (default: all)
  metadata: (metadata, data) => ({ ...metadata, description: metadata.description ?? summaryOf(data) }),
  load: async ({ page, client }) => ({
    companies: (await client.listEntries({ type: "company", sort: "name" })).items,
  }),
});

Environment variables

The build reads the home page, so it needs them too (a missing one fails the build with its name).

Your own proxy

When the app has a proxy of its own, call BlokCms's first and use its answer when there is one:

import { blokProxy } from "@blokcms/next/proxy";
import { type NextRequest, NextResponse } from "next/server";

export async function proxy(request: NextRequest) {
  const blok = await blokProxy(request);
  if (blok) return blok;
  // … your own
  return NextResponse.next();
}