Nano-Forge Framework

README.md

Nano-Forge Framework

A React Server Components (RSC) meta-framework that implements federated architecture using Rspack and Module Federation. Inspired by Jacob Ebey's federated RSC work, nano-forge enables composable server-side rendering with cross-container component sharing.

Overview

Nano-forge implements the federated RSC architecture where:

• HTTP is the API for the server layer
• RSC payloads are composable across different remote containers
• Client references have global IDs that work across federated boundaries
• Module Federation enables runtime loading of components from remote containers

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Nano-Forge Framework                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Host App      │  │   Remote App    │  │   Remote App    │ │
│  │  (Orchestrator) │  │  (Micro-frontend│  │  (Micro-frontend│ │
│  │                 │  │   Component)    │  │   Component)    │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│           │                     │                     │         │
│           └─────────────────────┼─────────────────────┘         │
│                                 │                               │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Module Federation Layer                        │ │
│  │   • Shared Dependencies (React, etc.)                      │ │
│  │   • Global Client Reference IDs                            │ │
│  │   • Runtime Component Loading                              │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                   RSC Streaming Layer                       │ │
│  │   • Server Components render to RSC streams                │ │
│  │   • Client boundaries encoded as references                │ │
│  │   • Cross-container component composition                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                  Build System (Rspack)                      │ │
│  │   • Multi-environment builds (browser/ssr/server)          │ │
│  │   • Module federation configuration                        │ │
│  │   • Client component detection and chunking                │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Packages

1. nano-forge-framework-cli

The build system and development tooling

Provides Rspack-based build configuration with Module Federation support for creating federated RSC applications.

2. nano-forge-framework-core

The runtime framework primitives

Core RSC runtime, client/server boundaries, remote component loading, and streaming infrastructure.

3. nano-forge-framework-examples

Reference implementations

Working examples of host (orchestrator) and remote (micro-frontend) applications demonstrating federated RSC patterns.

Package Details

nano-forge-framework-cli

The CLI package provides the build system integration and development tools for creating federated RSC applications.

Key Files

src/index.ts

Main plugin entry point - Configures Rspack with three build environments:

• browser - Client-side bundle with module federation
• ssr - Server-side rendering bundle
• server - React Server Components bundle

Sets up module federation configuration and remote container definitions.

src/plugins.ts

Rspack plugin system - Core build plugins:

• FrameworkPlugin - Detects "use client" and "use server" directives
• FrameworkClientPlugin - Configures module federation for client bundles
• FrameworkServerPlugin - Handles server-side remote definitions
• RspackCircularDependencyPlugin - Prevents circular dependencies

src/cli.ts

Command-line interface - Development server and build commands.

src/runtime.client.ts

Client-side runtime - Module federation runtime configuration for browser environments.

src/rsc-loader.ts

RSC webpack loader - Processes React Server Components and client boundaries during build.

nano-forge-framework-core

The core runtime that implements the federated RSC architecture.

Key Files

src/server.tsx

Server-side RSC framework - Core server functionality:

• defineApp() - Creates RSC application with route definitions
• defaultRenderMatch() - Default route matching and rendering logic
• URL pattern matching - File-system based routing
• RSC streaming - Renders components to RSC payload streams

src/client.tsx

Client-side RSC framework - Client runtime:

• RemoteContextProvider - Context for managing remote RSC streams
• RemoteComponent - Renders RSC streams as React components
• OutletProvider/Outlet - Layout and nested routing system

src/remote.tsx

Remote component system - Federated component loading:

• RemoteRoute - Loads and renders components from remote containers
• FrameworkRemote - Configuration for remote container endpoints
• Cross-container communication - Fetches RSC streams from remote servers

src/ssr.tsx

Server-side rendering - SSR implementation:

• renderToReadableStream() - Renders React components to HTML streams
• createFromReadableStream() - Reconstructs React elements from RSC streams
• InlinePayload - Inlines RSC data for client hydration

src/bootstrap.browser.tsx

Browser hydration - Client-side application bootstrap:

• ClientRouter - Client-side navigation with RSC streaming
• Navigation API integration - Modern browser navigation
• Progressive enhancement - Works with or without SSR

src/bootstrap.ssr.tsx

SSR bootstrap - Server-side rendering entry point:

• handleRequest() - Processes HTTP requests for SSR
• RSC to HTML conversion - Transforms RSC streams to HTML
• Hydration data injection - Embeds RSC data for client pickup

React Server DOM Integration

Platform-specific RSC implementations:

• react-server-dom.client.*.ts - Client-side RSC stream processing
• react-server-dom.server.*.ts - Server-side RSC stream generation
• react-dom.server.*.ts - Server-side HTML rendering

Entry Points

• entry.browser.ts - Browser application entry
• entry.ssr.ts - SSR application entry
• client.internal.ts - Internal client utilities
• utils.ts - Shared utilities
• runtime.client.ts - Client runtime configuration
• runtime.server.ts - Server runtime configuration

nano-forge-framework-examples

Reference implementations demonstrating federated RSC patterns.

Host Application (examples/host)

The orchestrator application that composes remote micro-frontends.

src/bootstrap.server.tsx

Server configuration - Defines the host application routing:

• Layout routes - Provides shared UI shell
• Remote route delegation - Delegates specific routes to remote containers
• 404 handling - Fallback for unmatched routes

src/routes/layout.tsx

Shared layout - Common UI shell with navigation that wraps remote content.

src/entry.server.ts

Server entry point - Exports the configured RSC application.

server.mjs

Development server - Node.js server for development with hot reload.

rsbuild.config.ts

Build configuration - Rspack configuration with:

• Module federation setup - Configures remote container consumption
• Multi-environment builds - Browser, SSR, and server builds
• Remote definitions - Points to remote container endpoints

Remote Application (examples/remote)

A micro-frontend that exposes components for consumption by host applications.

src/bootstrap.server.tsx

Server configuration - Defines routes exposed by this remote:

• / route - Home page component
• /about route - About page component

src/routes/home.tsx

Server component - React Server Component that imports client components.

src/routes/home.client.tsx

Client component - Interactive React component marked with "use client":

• Counter - Stateful counter component demonstrating client-side interactivity

src/routes/about.tsx

Server component - Simple about page component.

server.mjs

Development server - Standalone server that can run independently.

rsbuild.config.ts

Build configuration - Rspack configuration with:

• Module federation exposure - Exposes components for consumption
• Client component chunking - Separates client components into federated chunks

How It Works

1. Development Flow

# Start remote micro-frontend
cd examples/remote
npm run dev  # Runs on localhost:3001

# Start host application
cd examples/host
npm run dev  # Runs on localhost:3000

2. Request Flow

1. Browser requests http://localhost:3000/
2. Host application matches route and delegates to remote
3. Remote container fetches RSC stream from http://localhost:3001/.data
4. RSC stream contains server-rendered content + client boundaries
5. Client boundaries are resolved via module federation
6. Final rendering composes host layout + remote content + federated client components

3. Build Process

1. Client components are detected via "use client" directive
2. Module federation exposes client components as shared chunks
3. Three builds are generated:
   • Browser bundle - Client-side code with module federation
   • SSR bundle - Server-side rendering with module federation
   • Server bundle - React Server Components (no module federation)

4. Runtime Architecture

• Server components run on the server and stream RSC payloads
• Client components are loaded via module federation at runtime
• RSC streams are cached and shared between server and client
• Navigation is handled client-side with RSC streaming

Key Concepts

Federated RSC

Unlike traditional RSC frameworks, nano-forge enables cross-container composition:

• Multiple RSC servers can be composed together
• Client references work across container boundaries
• Shared dependencies are deduplicated via module federation

Global Client Reference IDs

Client components get globally unique IDs in the format:

rsc/remote/client/{container}/{module}#{export}

HTTP-based Server Composition

Servers expose RSC endpoints that other servers can consume:

GET /about.data
Accept: text/x-component

Module Federation Integration

• Shared scope - React and other dependencies shared between containers
• Runtime loading - Components loaded on-demand from remote containers
• Development isolation - Each container can be developed independently

Benefits

1. Micro-frontend Architecture - Independent deployment and development
2. Server-side Composition - SEO-friendly, fast initial page loads
3. Progressive Enhancement - Works with and without JavaScript
4. Shared Dependencies - Efficient bundle sizes via module federation
5. Type Safety - Full TypeScript support across container boundaries
6. Developer Experience - Hot reload, fast builds with Rspack

Comparison to Other Frameworks

Feature	Nano-Forge	Next.js	Remix
RSC Support	✅ Full	✅ Full	❌ No
Module Federation	✅ Native	❌ No	❌ No
Micro-frontends	✅ Built-in	⚠️ Manual	⚠️ Manual
Server Composition	✅ HTTP-based	❌ No	❌ No
Build System	Rspack	Webpack/Turbopack	Vite/esbuild

Nano-forge is specifically designed for federated RSC architectures where multiple teams need to compose server-rendered React applications with shared client-side interactivity.