next

@json-render/next

JSON 仕様を、ルート、ページ、レイアウト、メタデータ、SSR 対応を備えた Next.js アプリケーション全体に変換する Next.js レンダラーです。

クイックスタート

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

1. 仕様を定義する

// 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. アプリを作成する

// 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. ルートファイルを接続する

// 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>
  );
}

主な概念

NextAppSpec

最上位の仕様で、Next.js アプリケーション全体を定義します。

• metadata: ルートレベルの SEO メタデータ（タイトルテンプレート、説明、OpenGraph）
• layouts: 再利用可能なレイアウト要素ツリー（それぞれに Slot コンポーネントが必要です）
• routes: URL パターンをキーとするルート定義
• state: すべてのルートで共有されるグローバルな初期状態

ルートパターン

ルートでは、Next.js の URL 規則を使用します。

• "/" -- ホームページ
• "/about" -- 静的ルート
• "/blog/[slug]" -- 動的セグメント
• "/docs/[...path]" -- キャッチオールセグメント
• "/settings/[[...path]]" -- オプションのキャッチオールセグメント

レイアウト

レイアウトはページコンテンツを囲みます。すべてのレイアウトには、ページコンテンツをレンダリングする Slot コンポーネントを含める必要があります。レイアウトは spec.layouts で一度定義し、ルートから layout フィールドを使って参照します。

組み込みコンポーネント

• Slot: ページコンテンツをレンダリングするレイアウト内のプレースホルダー
• Link: クライアントサイドのナビゲーションリンク（next/link をラップします）

組み込みアクション

• setState: 状態の値を更新します。パラメーター: { statePath, value }
• pushState: 配列に追加します。パラメーター: { statePath, value, clearStatePath? }
• removeState: インデックスを指定して配列から削除します。パラメーター: { statePath, index }
• navigate: クライアントサイドでナビゲーションします。パラメーター: { href }

データローダー

レンダリング前にサーバーコンポーネントで実行される、サーバーサイドの非同期関数です。戻り値はページの初期状態にマージされます。

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

SSR

ページは自動的にサーバーレンダリングされます。createNextApp の Page コンポーネントは非同期のサーバーコンポーネントで、次の処理を行います。

1. 仕様からルートを照合します
2. サーバーサイドのデータローダーを実行します
3. メタデータを生成します
4. 解決済みの仕様をクライアントレンダラーに渡してハイドレーションします

エントリーポイント

• @json-render/next -- クライアントコンポーネント（NextAppProvider、PageRenderer、Link）
• @json-render/next/server -- サーバーユーティリティ（createNextApp、matchRoute、schema）

API リファレンス

サーバーエクスポート（@json-render/next/server）

• createNextApp(options) -- Page、generateMetadata、generateStaticParams を作成します
• schema -- Next.js アプリ向けのカスタムスキーマ（AI カタログの生成用）
• matchRoute(spec, pathname) -- URL をルート仕様に照合します
• resolveMetadata(spec, route) -- ルートのメタデータを解決します
• slugToPath(slug) -- キャッチオールのスラッグ配列をパス名に変換します
• collectStaticParams(spec) -- すべてのルートの静的パラメーターを収集します

クライアントエクスポート（@json-render/next）

• NextAppProvider -- レジストリとハンドラーのコンテキストプロバイダー
• PageRenderer -- オプションのレイアウトとともにページ仕様をレンダリングします
• NextErrorBoundary -- エラーバウンダリーコンポーネント
• NextLoading -- 読み込み状態コンポーネント
• NextNotFound -- 見つからない場合のコンポーネント
• Link -- 組み込みのナビゲーションコンポーネント（next/link をラップします）