@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

bash

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

1. Define Your Spec

typescript

// 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

typescript

// 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

tsx

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

tsx

// 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.

typescript

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)

next

NPX Install

Tags

SKILL.md Content

@json-render/next

Quick Start

1. Define Your Spec

2. Create the App

3. Wire Up Route Files

Key Concepts

NextAppSpec

Route Patterns

Layouts

Built-in Components

Built-in Actions

Data Loaders

SSR

Entry Points

API Reference

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

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

next

NPX Install

Tags

SKILL.md Content

@json-render/next

Quick Start

1. Define Your Spec

2. Create the App

3. Wire Up Route Files

Key Concepts

NextAppSpec

Route Patterns

Layouts

Built-in Components

Built-in Actions

Data Loaders

SSR

Entry Points

API Reference

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

Client Exports (@json-render/next)

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

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