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:

  1. appends the built-in HTML Pages Integration, unless an Integration already registers .html
  2. validates integration names and extensions
  3. validates processor names
  4. derives absolute paths and semantic template paths
  5. reads plugins(app) of each processor, then of each integration, once, and seals the build manifest from them
  6. 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:

  1. Core imports the server modules recorded by the production build.
  2. Core gives each Processor its app config and calls restoreProductionRuntime(); it does not call setup() or scan the source tree.
  3. Core activates Integrations with setup(ctx) before their renderers are created. Request-only app.fetch() activates the Integrations used by the requested render, including owners of foreign children.

For development and non-production startup, the ordering is:

  1. Core gives each Processor its app config, then runs its setup().
  2. In watch mode, core puts the HMR manager on AppRuntime and calls each Integration's hmr(ctx) once.
  3. Core calls each Integration's setup(ctx) with { appConfig, runtime } before creating its renderer. Static export activates the Integrations it needs. preview --serve-only skips 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:

  1. route resolution picks the matching page or API handler
  2. the owning integration is selected from the file extension
  3. the integration renderer handles framework-specific rendering
  4. 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:

  1. core classifies file changes through DevelopmentInvalidationService
  2. processor-owned watch paths are handled through processor watch configuration
  3. integration-owned HMR behavior runs through registered HMR strategies
  4. 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:

  1. put it in core when it affects orchestration, lifecycle ordering, server loading, browser bundling coordination, or invalidation policy
  2. put it in an integration when it affects rendering semantics, hydration behavior, framework-specific HMR, or cross-integration ownership behavior
  3. put it in a processor when it affects asset transformation, emitted assets, asset-specific caching, or watch behavior for owned files