Build and Host
Ecopages separates core-owned build execution from host-managed dev/build boundaries.
Build ownership
| Mode | Who owns the bundler | Typical use |
|---|---|---|
| Rolldown (default) | @ecopages/core via the build adapter | CLI, Bun/Node runtime, production server bundles |
| Vite host | Vite + @ecopages/vite-plugin | Vite dev server, host-managed module graph |
Core uses Rolldown as the default bundled backend. Ecopages plugins are bridged to Rolldown through a single consolidated plugin to minimize FFI overhead.
What gets built
- Server entry — app bootstrap and request handling
- Route modules — page and layout server modules per integration
- Browser graphs — Page Browser Graph entries and chunks per route or route cohort
- Static HTML — build-time output for static cache strategies
Development uses one-shot Rolldown builds with shared HMR and invalidation services; route-module and browser builds can run in parallel.
Runtime entrypoint
Apps start through createApp() from @ecopages/core/create-app. It selects Bun when available and falls back to Node. Vite/Nitro hosts still use the same app config and app.fetch() contract.
Boot vs embed
| Mode | createApp() options | What app.start() does |
|---|---|---|
| Standalone (CLI, Bun/Node) | default | Binds the port and serves traffic |
| Embedded (Vite host) | runtime: { embedded: true } | Registers an optional readiness callback only; the host owns the port |
In embedded mode the host loads your app entry, wires app.fetch() into its middleware stack, and invokes the callback you pass to app.start() when the app can serve requests.
See Starting the server for a full app.ts example and the callback signature.
Further reading
- Architecture
- Vite Plugin
- Build layer README in the repository