RSC to JSON

A TypeScript library for parsing React Server Components (RSC) network payloads into JSON.

Features

• 🚀 Full RSC Support: Parse all RSC chunk types (imports, models, errors, hints)
• 🔗 Reference Resolution: Automatically resolve $L references into nested JSON
• 📦 Dual Module Support: Works with both CommonJS and ES Modules
• 🎯 Type Safe: Written in TypeScript with full type definitions
• 🧪 Well Tested: Comprehensive test suite with real-world examples

Installation

npm install rsc-to-json

# For global CLI usage
npm install -g rsc-to-json

Quick Start

import { parseRSC } from 'rsc-to-json';

const rscPayload = `
170:["John Doe - Software Engineer"]
1d7:[{"name":"Global Cybersecurity Advisor","title":"CISSP, CCSP","bio":"$L170"}]
0:[["$","div",null,{"className":"profile","children":"$L1d7"}]]
`;

const result = parseRSC(rscPayload);
console.log(JSON.stringify(result.root, null, 2));

Output:

{
  "type": "div",
  "props": {
    "className": "profile",
    "children": {
      "name": "Global Cybersecurity Advisor",
      "title": "CISSP, CCSP",
      "bio": "John Doe - Software Engineer"
    }
  }
}

CLI Usage

Convert RSC files to JSON from the command line:

# Basic usage
rsc-to-json input.rsc output.json

# With options
rsc-to-json input.rsc output.json --no-pretty

# Show help
rsc-to-json --help

CLI Options

• --pretty - Pretty print JSON output (default: true)
• --no-pretty - Output compact JSON
• --help, -h - Show help message

Example

# Create an RSC file
echo '170:["John Doe"]
0:[["$","div",null,{"children":"$L170"}]]' > test.rsc

# Convert to JSON
rsc-to-json test.rsc output.json

# View the result
cat output.json

API Reference

parseRSC(payload: string): ResolvedRSCData

Parse and resolve an RSC payload in one step.

const result = parseRSC(rscPayload);

RSCParser

For more control, use the parser class directly:

import { RSCParser, resolveReferences } from 'rsc-to-json';

const parser = new RSCParser();
const parsed = parser.parse(rscPayload);
const resolved = resolveReferences(parsed);

Types

interface ImportInfo {
  id: string;
  moduleId: string;
  exports: string[];
  name: string;
}

interface ComponentInfo {
  id: string;
  type: 'ReactElement' | 'ComplexComponent' | 'Unknown';
  element?: string;
  props?: Record<string, any>;
  children?: any;
  metadata?: any;
}

interface ParsedRSCData {
  imports: Map<string, ImportInfo>;
  components: Map<string, ComponentInfo>;
  references: Map<string, string>;
  rootComponent?: ComponentInfo;
}

interface ResolvedRSCData {
  imports: Record<string, ImportInfo>;
  components: Record<string, any>;
  root?: any;
  references?: Record<string, string>;
}

Understanding RSC Format

React Server Components use a line-based format for streaming UI:

Import Chunks

1:I["moduleId",[],"ComponentName"]

• Imports a component for use in the payload

Model Chunks

0:[["$","div",null,{"children":"Hello"}]]

• Defines UI components and data

References

$L170  // References component with ID 170
$L1    // References import with ID 1

Special Values

$undefined  // Represents undefined value

Advanced Usage

Parsing Without Resolution

const parser = new RSCParser();
const parsed = parser.parse(rscPayload);

// Access raw parsed data
console.log(parsed.imports);     // Map of imports
console.log(parsed.components);  // Map of components
console.log(parsed.references);  // Map of references

Handling Complex Payloads

// Complex application RSC payload with imports
const complexPayload = `
1:I["030d6035cb3a997efb1cff7a008d2f89",[],"default"]
17:I["b55b61101826bcdf8a734370f7480e4e",[],"VisibleItemsProvider"]
2:["$","div",null,{"className":"container","children":["$","$L17",null,{"items":[]}]}]
0:[["$","$L1",null,{"modelStates":[]}]]
`;

const result = parseRSC(complexPayload);

Error Handling

try {
  const result = parseRSC(malformedPayload);
} catch (error) {
  console.error('Failed to parse RSC:', error);
}

Use Cases

• Development Tools: Build RSC inspectors and debuggers
• Testing: Parse and analyze RSC payloads in tests
• Documentation: Generate documentation from RSC payloads
• Migration: Convert RSC payloads to other formats
• Analysis: Analyze component usage and dependencies

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Related

• React Server Components RFC
• React Documentation