Maintenance Guide
Internal documentation for plugin maintainers and contributors.
Test Status
Run the full suite with npm test (unit) and the e2e specs under test/e2e/. The current counts move with the codebase — see CI for the canonical numbers.
Documentation Index
Filenames are in backticks so markdown doesn't italicize the _ in names like
DEV_CACHING_ISSUE.md / MESSAGE_PORTS_ANALYSIS.md.
| File | Description |
|---|---|
architecture.md | Internal architecture and design |
transformer.md | The transform/loader system |
workers.md | Worker system (RSC + HTML workers) |
advanced-topics.md | Custom workers, message system, extending the plugin |
module-resolution-escape-hatches.md | Module-resolution escape hatches |
MESSAGE_PORTS_ANALYSIS.md | Worker communication architecture |
COMMON_ISSUES.md | Frequently encountered problems and solutions |
DEBUGGING.md | Debugging techniques and tools |
DEV_CACHING_ISSUE.md | Dev mode caching issue (resolved) |
ERROR_HANDLING.md | Error handling patterns and recovery |
TESTING.md | Test infrastructure and commands |
Architecture Overview
The plugin has two execution modes:
Dev Mode (default)
- RSC rendering on main thread via Vite's Environment API (
server.environments['server'].runner) - No workers or MessagePorts
- HMR via
hotUpdatehook (Vite 6 Environment API) - Client components →
@vitejs/plugin-reactFast Refresh - Server components → RSC refetch via custom WS event
- CSS → RSC refetch (inlined in stream)
Production Build
- Worker-based parallel rendering (batch size 8 by default)
react-server-dom-esmvendored (symlink auto-created inconfigResolved)- Static HTML + RSC output per page
Releasing
See ../releasing.md for the full release process.