next

One JSON file can describe a whole site — several pages, a shared layout, the wording search engines pick up — and this turns it into a working Next.js app.

WHEN TO USE

SCOPE

USE FOR

Turn one JSON spec into a multi-page Next.js app with shared layouts and navigation.
Generate SEO metadata and OpenGraph tags per route directly from the spec.
Run server-side data loaders that populate a page's initial state before it renders.
Support dynamic and catch-all routes like /blog/[slug] or /docs/[...path] from the spec.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (4)

@json-render/next

Next.js renderer that converts JSON specs into full Next.js applications with routes, pages, layouts, metadata, and SSR support.

Quick Start

npm install @json-render/core @json-render/react @json-render/next

1. Define Your Spec

// lib/spec.ts
import type { NextAppSpec } from "@json-render/next";

export const spec: NextAppSpec = {
  metadata: {
    title: { default: "My App", template: "%s | My App" },
    description: "A json-render Next.js application",
  },
  layouts: {
    main: {
      root: "shell",
      elements: {
        shell: { type: "Container", props: {}, children: ["nav", "slot"] },
        nav: { type: "NavBar", props: { links: [
          { href: "/", label: "Home" },
          { href: "/about", label: "About" },
        ]}, children: [] },
        slot: { type: "Slot", props: {}, children: [] },
      },
    },
  },
  routes: {
    "/": {
      layout: "main",
      metadata: { title: "Home" },
      page: {
        root: "hero",
        elements: {
          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
        },
      },
    },
    "/about": {
      layout: "main",
      metadata: { title: "About" },
      page: {
        root: "content",
        elements: {
          content: { type: "Card", props: { title: "About Us" }, children: [] },
        },
      },
    },
  },
};

2. Create the App

// lib/app.ts
import { createNextApp } from "@json-render/next/server";
import { spec } from "./spec";

export const { Page, generateMetadata, generateStaticParams } = createNextApp({
  spec,
  loaders: {
    // Server-side data loaders (optional)
    loadPost: async ({ slug }) => {
      const post = await getPost(slug as string);
      return { post };
    },
  },
});

3. Wire Up Route Files

// app/[[...slug]]/page.tsx
export { Page as default, generateMetadata, generateStaticParams } from "@/lib/app";

// app/[[...slug]]/layout.tsx
import { NextAppProvider } from "@json-render/next";
import { registry, handlers } from "@/lib/registry";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NextAppProvider registry={registry} handlers={handlers}>
          {children}
        </NextAppProvider>
      </body>
    </html>
  );
}

Key Concepts

NextAppSpec

The top-level spec defines an entire Next.js application:

metadata: Root-level SEO metadata (title template, description, OpenGraph)
layouts: Reusable layout element trees (each must include a Slot component)
routes: Route definitions keyed by URL pattern
state: Global initial state shared across all routes

Route Patterns

Routes use Next.js URL conventions:

"/" -- home page
"/about" -- static route
"/blog/[slug]" -- dynamic segment
"/docs/[...path]" -- catch-all segment
"/settings/[[...path]]" -- optional catch-all segment

Layouts

Layouts wrap page content. Every layout MUST include a Slot component where page content will be rendered. Layouts are defined once in spec.layouts and referenced by routes via the layout field.

Built-in Components

Slot: Placeholder in layouts where page content is rendered
Link: Client-side navigation link (wraps next/link)

Built-in Actions

setState: Update state value. Params: { statePath, value }
pushState: Append to array. Params: { statePath, value, clearStatePath? }
removeState: Remove from array by index. Params: { statePath, index }
navigate: Client-side navigation. Params: { href }

Data Loaders

Server-side async functions that run in the Server Component before rendering. Results are merged into the page's initial state.

createNextApp({
  spec,
  loaders: {
    loadPost: async ({ slug }) => {
      const post = await db.post.findUnique({ where: { slug } });
      return { post };
    },
  },
});

SSR

Pages are server-rendered automatically. The createNextApp Page component is an async Server Component that:

Matches the route from the spec
Runs server-side data loaders
Generates metadata
Passes the resolved spec to the client renderer for hydration

Entry Points

@json-render/next -- Client components (NextAppProvider, PageRenderer, Link)
@json-render/next/server -- Server utilities (createNextApp, matchRoute, schema)

API Reference

Server Exports (`@json-render/next/server`)

createNextApp(options) -- Create Page, generateMetadata, generateStaticParams
schema -- Custom schema for Next.js apps (for AI catalog generation)
matchRoute(spec, pathname) -- Match a URL to a route spec
resolveMetadata(spec, route) -- Resolve metadata for a route
slugToPath(slug) -- Convert catch-all slug array to pathname
collectStaticParams(spec) -- Collect static params for all routes

Client Exports (`@json-render/next`)

NextAppProvider -- Context provider for registry and handlers
PageRenderer -- Renders a page spec with optional layout
NextErrorBoundary -- Error boundary component
NextLoading -- Loading state component
NextNotFound -- Not-found component
Link -- Built-in navigation component (wraps next/link)

Local tool required

1 FOR THE AGENT

01
Install the json-render Next.js package
Run npm install @json-render/core @json-render/react @json-render/next in a Next.js project so JSON specs can drive full routes, layouts, SSR, and metadata.

Listed as free: Connected services may require an account or charge fees.
Installation: One command — usually under 2 minutes.

Not standalone. This skill ships with vercel-labs/json-render and only works together with that tool — install the tool first, then add this skill.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add vercel-labs/json-render --skill "next" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub

The repository is licensed under Apache-2.0 — use, modification, and redistribution are allowed under that license’s terms.

View the repository’s license file on GitHub →