Next

@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.tsimport 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.tsimport { 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.tsxexport { Page as default, generateMetadata, generateStaticParams } from "@/lib/app";

// app/[[...slug]]/layout.tsximport { 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:

1. Matches the route from the spec
2. Runs server-side data loaders
3. Generates metadata
4. 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)