Package Architecture

Understand package boundaries and what belongs in each entrypoint.

The workspace publishes seven packages:

chakra-email - main application-facing package.
@chakra-email/chakra-v2 - adapter for Chakra UI v2-style theme objects.
@chakra-email/core - shared components, renderer, style system, theme resolver, and tests.
@chakra-email/preview - development-only CLI, template runner, local server, and bundled browser UI.
@chakra-email/react-email - optional React Email renderer adapter for preview and export tooling.
@chakra-email/code-block - optional themeable code rendering with a pluggable syntax highlighter.
@chakra-email/markdown - optional GFM rendering through the email-safe component layer.

Why Rendering Lives In Core

The renderer is shared by both public adapters. Keeping it in @chakra-email/core avoids duplicating render behavior and keeps versioning simple.

The runtime packages expose render utilities through their root exports and ./render subpaths:

import { render } from 'chakra-email/render';
import { renderPlainText } from 'chakra-email/render';
import { EmailRenderError } from 'chakra-email/security';

The focused ./security subpaths keep URL policy, output limits, and typed operational errors available without coupling shared configuration code to component declarations.

Why Preview Is A Separate Package

Previewing is a development workflow, not part of a delivered email or an application runtime. @chakra-email/preview depends on the core renderer but keeps Vite, file watching, the local HTTP server, and browser UI out of the component packages. It works from npm scripts in any repository; Nx consumers can attach the same CLI to a continuous, non-cacheable target.

These seven packages keep runtime adapters, shared rendering, and development tooling behind clear boundaries.

Local Package Testing With Yalc

Use the root Nx yalc targets when you want to test the publishable packages in another local app:

npx nx run chakra-email-monorepo:yalc-publish

That target builds the seven publishable packages, then publishes them to your local yalc store in dependency-safe order:

@chakra-email/core
@chakra-email/code-block
@chakra-email/markdown
@chakra-email/preview
@chakra-email/react-email
chakra-email
@chakra-email/chakra-v2

If the packages are already installed in a consumer app with yalc and you want to push updates immediately, run:

npx nx run chakra-email-monorepo:yalc-push

In the consumer app, add whichever packages you want to test:

yalc add chakra-email @chakra-email/core
yalc add @chakra-email/chakra-v2
yalc add --dev @chakra-email/preview
yalc add --dev @chakra-email/react-email
yalc add @chakra-email/code-block @chakra-email/markdown

The root npm aliases are available too:

npm run yalc:publish
npm run yalc:push