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.
- Dev compiles each browser module when the browser asks for it and rebuilds dirty results on the next request. See Dev server and Watcher and invalidation.
- Build does all compiling once and records what it processed. See Build pipeline.
- Start restores those records and compiles nothing. See Ledger and start.
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
| Package | What it is for |
|---|---|
packages/core | The framework: config, routing, rendering, asset processing, build, dev server and HMR. Every other package plugs into it. |
packages/ecopages | The CLI: dev, build, start, preview and project templates. CLI, Templates and init |
packages/file-system | The file system access and the path operations every package goes through. See Paths and File system. |
packages/browser-router | Client navigation for server-rendered documents. Browser router |
packages/react-router | Client navigation for React pages. React router |
packages/dev-toolbar | The development toolbar client. Dev toolbar client, and core's side in Dev toolbar |
packages/codemod | Codemods for migrating to current patterns. Codemod |
packages/integrations/react | React |
packages/integrations/lit | Lit |
packages/integrations/kitajs | Kita |
packages/integrations/ecopages-jsx | Ecopages JSX |
packages/integrations/mdx | MDX |
packages/processors/content-processor | Content processor |
packages/processors/image-processor | Image processor |
packages/processors/lightningcss-processor | Lightning CSS processor |
packages/processors/postcss-processor | PostCSS processor |
packages/__internals/testing | Private 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.
| Layer | Folders and root files |
|---|---|
| Foundation | types/, errors/, global/, utils/, html/, client/, islands/, validation/, constants.ts, env.ts, browser-env.ts, the .d.ts declarations |
| Contracts | plugins/, eco/ |
| Build | build/, assets/, cache/, diagnostics/ |
| Rendering | router/, route-renderer/, html-pages/, page-cache/, static-site-generator/ |
| Development and HMR | dev/, dev-toolbar/, hmr/, watchers/ |
| Application assembly | adapters/, 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 enters | Conversion |
|---|---|
fileSystem.realpath, glob, readdir, readlink, mkdtemp, tempDir and watcher events | Converted inside @ecopages/file-system |
Config directories and additionalWatchPaths | path.resolve while the config is finalized; path.fromNative for a glob |
import.meta.url, import.meta.resolve and other file: URLs | path.fromFileUrl |
process.cwd(), require.resolve and oxc-resolver results | path.cwd(), or path.fromNative |
| Rolldown module ids in hooks and build output | fromRolldownModuleId |
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:
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.
packages/ecopages/bin/packages/core/src/build/packages/core/src/dev/packages/core/src/adapters/packages/file-system/src/path.tspackages/core/src/build/rolldown/rolldown-module-id.tspackages/core/src/build/build-graph.tspackages/core/src/plugins/eco-component-meta-plugin.tspackages/core/src/plugins/component-import-discovery.tspackages/core/src/plugins/tsconfig-import-resolver.tsscripts/check-portability.tsscripts/core-layering-allowlist.json