Content processor
ContentProcessorPlugin is a Processor (see /dev/plugin-pipeline) that turns configured collection directories into generated TypeScript modules and exposes them as ecopages:content/<collection> virtual specifiers. Collection names must match ^[a-z][a-z0-9-]*$.
Scanning
One ContentScanner per collection globs **/*<ext> under srcDir/<contentDir> for the collection's extensions (default ['.mdx']). For each file it:
- Reads frontmatter with
vfile-matterand validates it withvalidateStandardSchema, so any Standard Schema library works. An invalid file fails the generation, which failsecopages buildinstead of the first request. - Derives
slugby stripping the longest matching extension from the path relative to the content root, using/separators, andsegmentsasslug.split('/'). Extensions are matched longest-first so.react.mdxstrips cleanly when.mdxis also declared. - Sorts entries with
orderBy, defaulting to slug order.
A rejected scan is not cached, so fixing the file and saving recovers without a restart.
Generated modules
Per collection, regenerateCollectionModule writes three files under the Processor's cache directory (<workDir>/cache/ecopages-content-processor/) and mirrors them into .d.ts files under node_modules/@types/ecopages-content-processor:
| Specifier | Generated file | Contents |
|---|---|---|
ecopages:content/<c> | <c>.ts | entries, getEntry(slug), getEntryBySegments(segments). Metadata only, so route preparation loads it cheaply. |
ecopages:content/<c>/server | <c>.server.ts | Per-slug lazy import() of each MDX file, getComponent(slug), getEntryDependencies(slug). |
ecopages:content/<c>/component | <c>.server.ts or <c>.browser.ts | loadComponent(slug) with a collection property. |
/component is one specifier with two resolutions. The server graph backs it with the same module as /server, so a Page importing both shares one component cache per slug. The Page Browser Graph backs it with the browser module, which loads a browser-compiled entry and returns the module's own default export.
Server and client boundary
plugins() returns one server plugin and the browser plugins (environments: ['browser']), declared separately so registration order cannot pick the wrong implementation.
- Server: resolves all three specifiers. For
/serverand/componentit first builds a compiled collection artifact, then externalizes it so Node loads one instance. In the unified production graph (shouldBuildPagesUnifiedGraph()) the generated files are inlined instead and emitted todist/server/. - Browser: resolves entries and
/componentto generated files on disk (not a virtual namespace, so relative MDX imports resolve), and omits/server.createContentServerBoundaryPluginthrows if/serveris still reached, with a message to move the import into a server-only Page option.
Every resolve awaits ensureCollectionsGenerated(), which setup() also calls. setup() and every resolve share one generation promise, so a build that starts before setup() waits for the generated modules instead of finding none. A failed generation is dropped so the next caller retries.
The compiled artifact (ensureCollectionServerArtifact) is built lazily, single-flight per collection, because it bundles every entry's MDX. It is named from a hash of the generated file plus entry sources and the app module loader's development generation, and discarded when a source changes during the build.
Ownership at render time
Each entry component is wrapped by invokeContentEntry, which compares the entry's identity.integration with the active render context. When they differ and a foreign-child runtime exists, the entry is handed off to its owning renderer; otherwise it throws an ownership error. See /dev/integrations-foreign-children. The generated module also throws if the MDX config lacks identity, since the MDX loader must attribute it (see /dev/mdx).
Joining route preparation
getEntryDependencies(slug) returns { components: [entryComponent] }. A Page passes it as its dependencies function, and collectPageDependencyComponents expands the result into collector roots like any other Component. The collector walks the entry's MDX identity. It does not copy config.dependencies or set ownerFile. See /dev/pages-layouts-components.
Setup, watch and production
setup()generates every collection and types, then addsroutePrefix/<slug>pathnames todevPrewarmPathsfor collections withdevPrewarmandroutePrefix. They are read from the manifest at startup.- Watch paths are the collections' content roots. A body-only edit leaves the manifest unchanged (
no-op), so generated files are not rewritten, but the compiled artifact is invalidated. A created or deleted entry, or a changed slug, regenerates the collection; a frontmatter change rewrites only the entries module. A collection whose regeneration failed stays stale and regenerates on the next change. ecopages buildemits the entries and server modules;listProductionServerModuleEntries()names them forserver-modules.json.restoreProductionRuntime()points the module maps at the emitted files and throws if one is missing. Productionstartcalls it instead ofsetup().
Sources
This page describes the code below.
packages/processors/content-processor/src/plugin.tspackages/processors/content-processor/src/content-scanner.tspackages/processors/content-processor/src/content-plugins.tspackages/processors/content-processor/src/content-server-boundary-plugin.tspackages/processors/content-processor/src/collection-server-module-build.service.tspackages/processors/content-processor/src/codegen.tspackages/processors/content-processor/src/ownership.tspackages/processors/content-processor/src/types.tspackages/core/src/plugins/processor.tspackages/core/src/route-renderer/page-loading/file-scoped-dependency-components.ts