Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The React Email project utilizes a monorepo architecture to manage a suite of interconnected packages and applications within a single repository. This structure centralizes the development of the core component library, rendering engines, visual editor, and the official web documentation.
By centralizing these assets, the project ensures consistent versioning and facilitates seamless internal dependency management. Developers contribute to different parts of the ecosystem—such as the CLI or the React components—within a unified environment that shares configuration for linting, testing, and building.
Sources: README.md:10-50, package.json:1-5, CONTRIBUTING.md:17-25
Workspace Management and Orchestration
The monorepo uses pnpm as the package manager to handle dependencies and Turbo (Turborepo) to orchestrate tasks across the workspace.
Task Orchestration
Turborepo automates the execution of scripts across all packages. It manages build pipelines, runs tests in parallel, and caches successful results to speed up the development workflow. Key scripts defined in the root package.json include:
build: Runs the build command across the workspace.test: Executes the test suite for all packages.typecheck: Runs TypeScript compiler checks.lint: Performs code linting using Biome.
Sources: package.json:7-16, package.json:54
Internal Dependencies
Packages within the monorepo reference each other using the workspace:* protocol. This allows the Next.js web application or the Editor package to utilize the latest local changes from the core react-email or render packages without requiring a public registry release.
Sources: apps/web/package.json:20-22, packages/editor/package.json:115
Monorepo Structure
The project divides its code into two primary directories: apps/ for consumer-facing applications and packages/ for reusable libraries.
Primary Directories
apps/web: The official React Email website, built with Next.js, which hosts documentation, component previews, and template galleries.packages/editor: An embeddable rich-text editor for building email templates.packages/render: Logic for converting React components into email-ready HTML and plain text.packages/react-email: The core CLI and the base component library.
Sources: apps/web/package.json:1-5, packages/editor/package.json:1-3, skills/react-email/SKILL.md:255-275
Workspace Relationship Diagram
The following diagram illustrates how different entities within the monorepo interact through workspace dependencies.
The diagram shows the hierarchical structure and the flow of dependencies where the web application and editor consume core library packages.
Sources: apps/web/package.json:20-40, packages/editor/package.json:115-120
Tooling and Configuration
The monorepo architecture establishes a standardized toolchain for all sub-projects to maintain high code quality and developer productivity.
Standardized Scripts
The following table summarizes the core commands used to manage the monorepo environment:
| Script | Command | Purpose |
|---|---|---|
build | turbo run build | Compiles all packages and apps |
test | turbo run test | Runs Vitest suites across the workspace |
lint | biome check | Validates code style and quality |
typecheck | turbo run typecheck | Validates TypeScript types |
release | node ./scripts/release.mts | Handles versioning and publishing |
Sources: package.json:7-16, CONTRIBUTING.md:22-26
Development Workflow
Developers interact with the monorepo by installing dependencies at the root and then running targeted scripts.
- Run
pnpm iat the root to link workspace packages. - Use
pnpm buildto compile the library components. - Move into specific directories like
apps/webto run the development server withpnpm dev.
Sources: apps/web/README.md:1-12, package.json:17
Conclusion
The monorepo architecture of React Email enables a highly integrated development experience. By using Turborepo and pnpm workspaces, the project maintains a clear separation of concerns between its CLI, visual editor, and web documentation while ensuring that all components share a unified and performant build pipeline.
Sources: package.json:7-16, CONTRIBUTING.md:17-25