CapsuleRSC: Safe Server/Client Boundary Enforcement for React Server Components

#webdev #programming #reactjsdevelopment #react

Overview

CapsuleRSC is a minimal framework that enforces safe server/client boundaries for React Server Components (RSC) with strong, mechanical guarantees.

It does not rely on conventions or developer discipline. Instead, CapsuleRSC enforces correctness through three explicit layers of defense:

Type-level – TypeScript types prevent non-serializable data from crossing boundaries at compile time
Build-time – An ESLint plugin detects boundary violations during development
Runtime – assertSerializable provides a final line of defense at execution time

Why Boundaries Matter

React Server Components introduce a new constraint: data must cross from server to client in a safe, serializable form.

Without strict boundaries, subtle but serious problems appear:

Functions passed to client components cause runtime failures
Date objects silently become strings
Class instances lose their methods
Circular references crash serialization

CapsuleRSC prevents these issues by enforcing boundaries at every layer, not by assuming developers will remember the rules.

Core Principle

Do not assume boundaries are respected — enforce them mechanically.

CapsuleRSC exists to validate this principle through implementation, not theory.

How CapsuleRSC Differs from tRPC

CapsuleRSC and tRPC solve different problems at different layers.

tRPC focuses on type-safe API communication between server and client. It assumes the execution boundary already exists (HTTP/RPC).
CapsuleRSC focuses on mechanically enforcing the server/client execution boundary itself, which is especially fragile in React Server Components.

In short: