Plugin Lifecycle
Ecopages keeps lifecycle ordering in core. Integrations and processors declare contributions, but they do not decide startup order or manifest assembly themselves.
Phase 1: Config Finalization
Users author configuration with defineConfig(). When createApp() starts, Ecopages loads that object and finalizes it into the app-owned configuration.
During this phase Ecopages:
- appends the built-in HTML Pages Integration, unless an Integration already registers
.html - validates integration names and extensions
- validates processor names
- derives absolute paths and semantic template paths
- reads
plugins(app)of each processor, then of each integration, once, and seals the build manifest from them - creates the app-owned build adapter, the server invalidation counter, and the build-input index that development invalidation reads
plugins(app) is the only plugin method that runs here, and it must be a pure read: no file access, generation or config loading. A processor whose setup() throws does not fail finalization. State that a plugin needs, such as generated collection modules or the PostCSS plugin list, is created in setup() or by the plugin's own callbacks when a build can run first.
This ordering is core-owned because processors often provide generic asset capabilities that integrations depend on indirectly. This is where app-owned build/runtime state becomes stable.
Phase 2: Processor Setup and Integration Activation
Runtime setup happens after the build manifest has already been sealed. Development, build, and regular preview prepare Processors by calling setup(). The ecopages types command also calls setup() to let Processors write virtual-module declarations.
Production ecopages start follows the emitted build instead:
- Core imports the server modules recorded by the production build.
- Core gives each Processor its app config and calls
restoreProductionRuntime(); it does not callsetup()or scan the source tree. - Core activates Integrations with
setup(ctx)before their renderers are created. Request-onlyapp.fetch()activates the Integrations used by the requested render, including owners of foreign children.
For development and non-production startup, the ordering is:
- Core gives each Processor its app config, then runs its
setup(). - In watch mode, core puts the HMR manager on
AppRuntimeand calls each Integration'shmr(ctx)once. - Core calls each Integration's
setup(ctx)with{ appConfig, runtime }before creating its renderer. Static export activates the Integrations it needs.preview --serve-onlyskips Processor setup and serves the existing client output.
setup(ctx) stores the app runtime; it does not resolve the Integration's global dependencies (integrationDependencies). In development, ecopages start and request-only app.fetch(), core resolves them right after each successful setup(ctx). ecopages build and ecopages preview resolve them once, after the app-wide browser build, so each one is served from that build instead of being bundled on its own. Do not read getResolvedIntegrationDependencies() inside setup(ctx): the list is empty there and fills after it. getRenderer() lazily calls createRenderer(base) once per setup activation. Each Integration can add renderer options without receiving services through setters. Network watch startup attempts warmup for every configured Integration before releasing requests; setup failures are logged after all attempts settle and do not prevent startup. Request-only app.fetch() leaves Integrations unrelated to its render inactive.
Phase 3: Request-Time Rendering
For each request, core owns routing and dispatch:
- route resolution picks the matching page or API handler
- the owning integration is selected from the file extension
- the integration renderer handles framework-specific rendering
- shared HTML/document finalization runs before the response is returned
Integrations own rendering semantics here. Core still owns orchestration and shared post-processing.
Phase 4: Development Invalidation And HMR
Development invalidation is classified in core and then routed to the appropriate participant.
The main model is:
- core classifies file changes through
DevelopmentInvalidationService - processor-owned watch paths are handled through processor watch configuration
- integration-owned HMR behavior runs through registered HMR strategies
- full reloads remain a core decision when the change category requires it
This keeps generic invalidation policy out of individual integrations.
Static Export
Before generating pages, core activates each Integration with setup(ctx), then calls its optional staticExport(ctx).
A hook can start resources shared across the export and return a release function. Core awaits the releases in reverse
order, then calls teardown() for each activated Integration after export finishes, including when route discovery or
generation fails.
Ownership Summary
Use this rule when deciding where new behavior belongs:
- put it in core when it affects orchestration, lifecycle ordering, server loading, browser bundling coordination, or invalidation policy
- put it in an integration when it affects rendering semantics, hydration behavior, framework-specific HMR, or cross-integration ownership behavior
- put it in a processor when it affects asset transformation, emitted assets, asset-specific caching, or watch behavior for owned files