Next.js (App Router)

Source: examples/frameworks/with-nextjs/ | Output: Live Demo

The Next.js example keeps Next.js in charge of routing, layouts, metadata, and static export while using @pagesmith/site as the app-facing Pagesmith package. @pagesmith/site owns the imports for collection definitions, markdown rendering, headings, and read time in this shape, while the underlying implementation still builds on @pagesmith/core.

The diagram highlights the boundary: the App Router stays in charge of the shell while @pagesmith/site supplies rendered markdown data plus the shared prose/code-block layer.

When to Choose This Pattern

• You already have a Next.js App Router project.
• You want createContentLayer() instead of Pagesmith’s Vite plugins.
• You want to keep the site shell and most styling decisions in Next.js.
• You still want Pagesmith’s markdown pipeline, headings, and optional code-block UI.

Package Split

If you own all markdown styling and browser behavior yourself, you can use @pagesmith/core on its own.

Dependencies

1{2  "dependencies": {3    "@pagesmith/site": "*",4    "next": "^16.2.3",5    "react": "^19.2.5",6    "react-dom": "^19.2.5"7  }8}

Content Config

Define collections exactly as you would in any other Pagesmith content integration:

1import { defineCollection, defineCollections, z } from "@pagesmith/site";23export const posts = defineCollection({4  loader: "markdown",5  directory: "./content/posts",6  schema: z.object({7    title: z.string(),8    description: z.string().optional(),9    date: z.coerce.date(),10    tags: z.array(z.string()).default([]),11  }),12});1314export default defineCollections({ posts });

Server-Side Content Helpers

Keep the content layer in normal server-side app code. The Next.js example creates the layer once at module scope and reuses it across lookups:

1import { createContentLayer, defineConfig } from "@pagesmith/site";2import collections from "../content.config.js";34let layer;56function getLayer() {7  if (!layer) {8    layer = createContentLayer(9      defineConfig({10        root: process.cwd(),11        collections,12      }),13    );14  }15  return layer;16}1718export async function getPostBySlug(slug) {19  const entry = await getLayer().getEntry("posts", slug);20  if (!entry) return null;2122  const rendered = await entry.render();23  return {24    slug: entry.slug,25    title: entry.data.title,26    html: rendered.html,27    headings: rendered.headings,28    readTime: rendered.readTime,29  };30}

The same helper can power getAllPosts() from the cached layer:

1export async function getAllPosts() {2  const entries = await getLayer().getCollection("posts");3  return Promise.all(4    entries.map(async (entry) => {5      const rendered = await entry.render();6      return {7        slug: entry.slug,8        title: entry.data.title,9        html: rendered.html,10        headings: rendered.headings,11        readTime: rendered.readTime,12      };13    }),14  );15}

This is the heart of the integration: Next.js receives rendered HTML and metadata-friendly data, not raw markdown files. @pagesmith/site stays the one package surface for both content loading and the shared presentation/runtime layer.

Layout and Runtime

When you want the shipped Pagesmith prose and code-block UI, import the shared CSS once in the app layout:

1import "@pagesmith/site/css/content";2import "./globals.css";

Mount the browser runtime once through a tiny client component:

1"use client";23import "@pagesmith/site/runtime/content";45export function PagesmithContentRuntime() {6  return null;7}

That runtime wires copy buttons, code tabs, and collapse toggles for the HTML produced by entry.render().

Routes and Metadata

The App Router keeps all of the routing and metadata logic:

1import { notFound } from "next/navigation";2import { getAllPosts, getPostBySlug } from "../../../lib/content";34export async function generateStaticParams() {5  const posts = await getAllPosts();6  return posts.map((post) => ({ slug: post.slug }));7}89export default async function PostPage({ params }) {10  const { slug } = await params;11  const post = await getPostBySlug(slug);1213  if (!post) notFound();1415  return <div className="prose" dangerouslySetInnerHTML={{ __html: post.html }} />;16}

Use generateMetadata() for page titles and descriptions, and build your own shell exactly as you would in any other Next.js app.

Build and Export Notes

• The example uses next build --output=export semantics to produce static HTML under out/.
• basePath and assetPrefix are set so the example can publish under /pagesmith/examples/nextjs.
• In this monorepo, the example currently uses Next 16’s webpack mode because Turbopack trips over Pagesmith’s package-relative Node resolution during the server build.

What You Can Skip

This pattern does not require:

• pagesmithContent from @pagesmith/site/vite
• pagesmithSsg from @pagesmith/site/vite
• @pagesmith/site/jsx-runtime
• the pagesmith-site or pagesmith-docs CLIs

Use those only when Pagesmith is also responsible for the site build itself.

Read Next

• Getting Started — collections, schemas, and createContentLayer()
• Runtime — @pagesmith/site/css/* and @pagesmith/site/runtime/*
• Framework Integrations — compare Vite, template-engine, docs, and Next.js patterns