Framework Readiness Investigation: Next.js, Eleventy, Nuxt

Next.js (App Router + React Server Components)

Verdict: Ready

The architecture maps naturally onto Next.js App Router. The key insight: since renderToHtml() exists and the component registry is empty, React Server Components can render all content as static HTML with zero hydration cost. No recursive React component tree needed.

1. Rendering: RSC + renderToHtml()

React Server Components run on the server only and can call any pure function. renderToHtml() is synchronous, pure, and produces complete HTML. The output is injected via dangerouslySetInnerHTML — no hydration, no client JS for content.

This completely sidesteps React's well-known issues with custom elements, since renderToHtml() outputs <rf-diagram>, <rf-nav>, etc. as raw HTML strings that React never processes as components.

// packages/next/src/RefraktContent.tsx (Server Component — no 'use client')
import { renderToHtml } from '@refrakt-md/transform';
import type { RendererNode } from '@refrakt-md/types';

export function RefraktContent({ tree }: { tree: RendererNode }) {
  const html = renderToHtml(tree);
  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

Alternative: A recursive Renderer.tsx using React.createElement() (~80 lines, equivalent to Renderer.svelte). Only needed if the component registry becomes non-empty in the future.

2. App Router Integration

Catch-all route at app/[...slug]/page.tsx. Content loading in the server component via loadContent().

// app/[...slug]/page.tsx
import { loadContent } from '@refrakt-md/content';
import { createTransform, layoutTransform, renderToHtml } from '@refrakt-md/transform';
import { serializeTree } from '@refrakt-md/transform';
import { baseConfig, defaultLayout } from '@refrakt-md/theme-base';
import { RefraktContent } from '@refrakt-md/next';
import { BehaviorInit } from '@refrakt-md/next/client';

export async function generateStaticParams() {
  const site = await loadContent('./content');
  return site.pages
    .filter(p => !p.draft)
    .map(p => ({ slug: p.url.split('/').filter(Boolean) }));
}

export default async function Page({ params }: { params: { slug: string[] } }) {
  const site = await loadContent('./content');
  const url = '/' + params.slug.join('/');
  const page = site.pages.find(p => p.url === url);

  const transform = createTransform(baseConfig);
  const tree = layoutTransform(defaultLayout, page, 'rf');

  return (
    <>
      <RefraktContent tree={tree} />
      <BehaviorInit pages={site.pages} currentUrl={url} />
    </>
  );
}

3. SEO: generateMetadata()

Maps directly to the SEO data already produced by the content system. Replaces <svelte:head> in ThemeShell.svelte (lines 94-122).

// app/[...slug]/page.tsx (alongside the component)
import type { Metadata } from 'next';

export async function generateMetadata({ params }): Promise<Metadata> {
  const page = /* load page */;
  return {
    title: page.seo?.og.title ?? page.title,
    description: page.seo?.og.description ?? page.description,
    openGraph: {
      title: page.seo?.og.title,
      description: page.seo?.og.description,
      images: page.seo?.og.image ? [page.seo.og.image] : undefined,
      url: page.seo?.og.url,
      type: page.seo?.og.type,
    },
  };
}

4. Behavior Initialization

Behaviors and web components need client-side DOM access. A thin client component handles this:

// packages/next/src/BehaviorInit.tsx
'use client';
import { useEffect } from 'react';
import { initRuneBehaviors, initLayoutBehaviors, registerElements, RfContext } from '@refrakt-md/behaviors';

export function BehaviorInit({ pages, currentUrl }: { pages: any[]; currentUrl: string }) {
  useEffect(() => {
    RfContext.pages = pages;
    RfContext.currentUrl = currentUrl;
    registerElements();
    const cleanupRunes = initRuneBehaviors();
    const cleanupLayout = initLayoutBehaviors();
    return () => { cleanupRunes(); cleanupLayout(); };
  }, [currentUrl]);

  return null;
}

5. CSS Injection

Import Lumina CSS in the root layout. No virtual modules needed — Next.js handles global CSS imports natively.

// app/layout.tsx
import '@refrakt-md/lumina';  // index.css with tokens + all rune styles

export default function RootLayout({ children }) {
  return <html><body>{children}</body></html>;
}

CSS tree-shaking (importing only CSS for used runes) can be added in Phase 2 as a custom Webpack/Turbopack plugin, reusing the analyzeRuneUsage() logic from the SvelteKit plugin.

6. Content HMR

The SvelteKit plugin uses Vite's server.watcher API (packages/sveltekit/src/content-hmr.ts). Next.js doesn't expose Vite.

Phase 1: No custom HMR — rely on Next.js dev server. Changes to content files trigger re-rendering on next request. Acceptable for initial implementation.

Phase 2: Custom Webpack plugin watching the content directory, invalidating page modules on .md file changes. Same logic, different watcher API.

7. ISR / On-Demand Revalidation

For sites that update content without full rebuilds:

export const revalidate = 3600; // re-render every hour
// or on-demand via API route:
// revalidatePath('/docs/getting-started');

loadContent() re-reads the content directory on each call, so ISR "just works".

8. Package Shape

packages/next/
├── src/
│   ├── RefraktContent.tsx     # Server Component — renderToHtml wrapper
│   ├── BehaviorInit.tsx       # Client Component — behavior + web component init
│   ├── metadata.ts            # generateMetadata() helper
│   ├── loader.ts              # loadContent wrapper for Next.js patterns
│   └── index.ts               # Public exports
├── package.json               # peer dep: next@^14.0.0 || ^15.0.0
└── tsconfig.json

Estimated New Code