Architecture

These pages explain how Ecopages works inside, for people who change the framework. Building an app does not need them: start with the documentation.

Lifecycle

Three commands share one config and one set of plugins, and differ in when they compile.

eco.config.tsFinalize config, seal buildmanifestecopages devecopages buildServer modules, app-widebrowser build, static exportdist: server modules,assets, ledgerecopages startTransform server compilesmodules on requestWatcher, invalidation, HMRRender Pages per requestRestore and seal ledgerRender Pages per request,no compiling

The ecopages command only plans a launch and spawns the app process for each of them; see CLI. ecopages init creates projects from the templates described in Templates and init. Build performance is measured by the kitchen-sink benches and the pull request stats comment; see Benchmarks and CI. The suites that guard all of this, and which of them the commit hook and CI run, are in Testing.

Every path renders a Page the same way: route preparation collects its assets into a Page Package before the first Component renders; see From graph to HTML. How a config becomes the per-app state all three share is in App runtime.

Packages

PackageWhat it is for
packages/coreThe framework: config, routing, rendering, asset processing, build, dev server and HMR. Every other package plugs into it.
packages/ecopagesThe CLI: dev, build, start, preview and project templates. CLI, Templates and init
packages/file-systemThe file system access and the path operations every package goes through. See Paths and File system.
packages/browser-routerClient navigation for server-rendered documents. Browser router
packages/react-routerClient navigation for React pages. React router
packages/dev-toolbarThe development toolbar client. Dev toolbar client, and core's side in Dev toolbar
packages/codemodCodemods for migrating to current patterns. Codemod
packages/integrations/reactReact
packages/integrations/litLit
packages/integrations/kitajsKita
packages/integrations/ecopages-jsxEcopages JSX
packages/integrations/mdxMDX
packages/processors/content-processorContent processor
packages/processors/image-processorImage processor
packages/processors/lightningcss-processorLightning CSS processor
packages/processors/postcss-processorPostCSS processor
packages/__internals/testingPrivate test helpers shared by the packages.

Integrations render files and own a JSX runtime; Processors own asset semantics. Both contribute build plugins through the contracts in Plugin pipeline and Integrations and foreign children.

Core source layers

packages/core/src is ordered in layers. A module may import from its own layer or an earlier one, never from a later one.

LayerFolders and root files
Foundationtypes/, errors/, global/, utils/, html/, client/, islands/, validation/, constants.ts, env.ts, browser-env.ts, the .d.ts declarations
Contractsplugins/, eco/
Buildbuild/, assets/, cache/, diagnostics/
Renderingrouter/, route-renderer/, html-pages/, page-cache/, static-site-generator/
Development and HMRdev/, dev-toolbar/, hmr/, watchers/
Application assemblyadapters/, config/, index.ts, index.browser.ts, integration.ts, processor.ts, processor-contract.ts, build.ts, cli.ts, client.ts

The error classes and shared utilities of this layer are listed in Errors and utilities. Foundation code knows nothing of the systems that use it: types/ holds contracts only, error classes do not depend on what reports them, client/ browser helpers stay independent of rendering and dev services, and per-app state lives on the AppRuntime, not in module globals.

pnpm check:portability (scripts/check-portability.ts, also run by pnpm typecheck) enforces the order on runtime module references, including import(), require() and resolver calls. An inline type modifier counts, since verbatimModuleSyntax keeps the import; import type and export type are erased and skipped, and so are tests and fixtures. A new source folder or root file fails the check until it is added to the layer map in the script. Existing upward references are listed in scripts/core-layering-allowlist.json with the issue that removes each one. The list only shrinks: the check fails for an unlisted upward reference and for an entry whose reference is gone.

Paths

Every path Ecopages holds uses forward slashes, on every host. An absolute path keeps its Windows drive letter as Node or the user spelled it (D:/app/src/pages/index.tsx); on POSIX it is the usual /app/src/pages/index.tsx. Paths therefore split on / and become URLs, cache keys and route names without a separator check.

The drive letter is not upper-cased on purpose: Node's ESM loader keys modules by URL and keeps the drive case, so a process started from a lower-case cwd loads its config as file:///d:/..., and an upper-cased path would load the same module a second time. Containment goes through path.isWithin, which compares drives without regard to case.

Package code takes its path operations from @ecopages/file-system/path, never from node:path (or its posix and win32 subpaths), and takes file: URL conversion from it rather than from node:url. It also reads the working directory with path.cwd() rather than process.cwd(), and a module's own location with path.fromFileUrl(import.meta.url) rather than import.meta.dirname or import.meta.filename. Lint rules enforce all of this in packages/: no-restricted-imports for static imports, no-restricted-properties for process.cwd, and the JS plugin scripts/oxlint-path-convention.ts for node:path loaded through require, a createRequire result or import(), and for the import.meta paths. App fixtures under test/fixtures/ keep import.meta.dirname, as an app's config does. packages/codemod is exempt: its jscodeshift transforms run on their own and do not depend on Ecopages packages. The module mirrors the node:path operations Ecopages uses and returns every result in this form. Node's file system APIs accept forward slashes on Windows, so most code never needs the native form.

A native path is converted once, where it enters Ecopages:

Where a path entersConversion
fileSystem.realpath, glob, readdir, readlink, mkdtemp, tempDir and watcher eventsConverted inside @ecopages/file-system
Config directories and additionalWatchPathspath.resolve while the config is finalized; path.fromNative for a glob
import.meta.url, import.meta.resolve and other file: URLspath.fromFileUrl
process.cwd(), require.resolve and oxc-resolver resultspath.cwd(), or path.fromNative
Rolldown module ids in hooks and build outputfromRolldownModuleId

On the way out, import() of a file takes path.toFileUrl(file).href. A path a resolve hook hands back to Rolldown goes through toRolldownModuleId, which returns the native form on Windows: Rolldown keys modules by id, and its own resolver produces native paths, so a forward-slash id for the same file would become a second module. path.toNative is for any other consumer that needs backslashes.

Real paths

Forward slashes are one contract; real paths are another. Rolldown module ids and the resolvers' results are real paths: symbolic links already followed, so one file has one spelling, the way Rolldown keys modules. The oxc resolvers behind resolvePackageModulePath and resolveProjectModulePath follow links themselves, and a hook receives the id Rolldown resolved. Code that handles such a path compares it as it arrives and canonicalises a path only where it enters from elsewhere, once:

oxc resolvers:resolvePackageModulePath,resolveProjectModulePathReal, forward-slash pathRolldown module id in ahook, viafromRolldownModuleIdCompared as is:component identityattribution, importdiscovery, React boundaryApp root, once per buildrealpath ineco-component-meta-pluginRequested build entries,once per buildresolveRequestedBuildEntriesA path from elsewhere:Project Watcher event,config pathrealpath where it entersrecordBuildEntryOutputmatches chunk facadesagainst them

The sites that used to resolve a real path on every call (eco-component-meta-plugin, component-import-discovery, tsconfig-import-resolver, build-graph) now take the real path as given or canonicalise once per build. A path that skips the contract, such as a native backslash id compared to a forward-slash one, or a symlinked spelling beside its real one, makes one file two modules or two cache keys.

A test that needs Windows behaviour on any host mocks @ecopages/file-system/path with createPath('win32'), as route-registry.windows-paths.test.ts does.

Sources

This page describes the code below.