ecopages 0.2.1-beta.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,14 +2,20 @@
2
2
 
3
3
  The official CLI for the Ecopages framework.
4
4
 
5
- It provides scaffolding and development commands to streamline your workflow. It prefers Bun when available, falls back to Node otherwise, and applies runtime-specific launch behavior for each engine.
5
+ It provides scaffolding and development commands to streamline your workflow. It runs your app on Bun when you launch it through Bun, on Node otherwise, and applies runtime-specific launch behavior for each engine.
6
6
 
7
7
  ## Quick Start
8
8
 
9
- Initialize a new project from the default template:
9
+ Initialize a new project from the interactive template picker:
10
10
 
11
11
  ```bash
12
- bunx ecopages init my-app
12
+ bunx ecopages init
13
+ ```
14
+
15
+ For a deterministic invocation, select a template explicitly:
16
+
17
+ ```bash
18
+ bunx ecopages init my-app --template react
13
19
  cd my-app
14
20
  bun install
15
21
  bun dev
@@ -17,35 +23,64 @@ bun dev
17
23
 
18
24
  ## Commands
19
25
 
20
- | Command | Description | Equivalent (Bun) |
21
- | :--------------------------- | :----------------------------------------- | :------------------------------ |
22
- | `ecopages init <dir>` | Scaffolds a new project | N/A |
23
- | `ecopages dev [entry]` | Starts the dev server | `bun run [entry] --dev` |
24
- | `ecopages dev:watch [entry]` | Dev server + hard restarts on file changes | `bun --watch run [entry] --dev` |
25
- | `ecopages dev:hot [entry]` | Dev server + HMR (no hard restarts) | `bun --hot run [entry] --dev` |
26
- | `ecopages build [entry]` | Creates a production build | `bun run [entry] --build` |
27
- | `ecopages start [entry]` | Starts the production server | `bun run [entry]` |
28
- | `ecopages preview [entry]` | Previews the production build locally | `bun run [entry] --preview` |
26
+ | Command | Description | Equivalent (Bun) |
27
+ | :-------------------- | :------------------------------------------------------ | :------------------------------------------------------------------- |
28
+ | `ecopages init [dir]` | Scaffolds a new project (interactive without `dir`) | N/A |
29
+ | `ecopages dev` | Starts the dev server (supervises config/.env restarts) | `bun run [entry] --dev` |
30
+ | `ecopages dev:watch` | Dev server + hard restarts on file changes | Bun: `bun --watch run [entry] --dev`; Node: `node --watch …` |
31
+ | `ecopages build` | Creates a production build | `bun run [entry] --build` |
32
+ | `ecopages start` | Starts the production server from the built output | Runs the emitted server bundle |
33
+ | `ecopages preview` | Previews the production build locally | `bun run [entry] --preview` |
34
+ | `ecopages types` | Writes virtual-module types for `tsc`, then exits | Loads `eco.config.ts` and sets processors up; the entry does not run |
29
35
 
30
36
  > [!NOTE]
31
- > `[entry]` defaults to `app.ts` if not provided.
37
+ > The entry file defaults to `app.ts`. Override it with `--entry-file`.
32
38
 
33
- ## Environment & Runtime Options
39
+ `ecopages start` does not load `eco.config.ts`, so it finds the build output by looking for `.server/manifest.json` one level below the app root (dot-prefixed directories included). It uses the only match, fails with the matches listed when there are several, and fails with "run `ecopages build`" when there is none. Pass `--dist-dir <dir>` to select a directory, which is required for nested (`out/web`) and symlinked outputs and whenever the app builds several outputs, such as `dist-<scope>` per build target.
40
+
41
+ ### Templates
34
42
 
35
- Server and build commands accept the following options. They automatically map to the equivalent environment variables for the underlying process:
43
+ Official templates are versioned with the CLI release. Use `--template <id>` for an official template or `--from <source>` for a community Git template. Community sources support giget provider notation and GitHub, GitLab, Bitbucket, and SourceHut repository URLs.
44
+
45
+ ```bash
46
+ ecopages init my-site --template jsx
47
+ ecopages init my-site --from github:acme/my-template#v1.0.0
48
+ ```
49
+
50
+ The official template IDs are `jsx`, `html`, `react`, `react-shadcn`, `lit-jsx`, `radiant`, `blog-jsx`, `blog-react`, `docs-starter`, `react-better-auth`, and `llm-wiki`.
51
+
52
+ ## Environment & Runtime Options
36
53
 
37
- | Option | Env Var | Description |
38
- | :------------------------- | :---------------------- | :---------------------------------- |
39
- | `-p, --port <port>` | `ECOPAGES_PORT` | Server port (default 3000) |
40
- | `-n, --hostname <host>` | `ECOPAGES_HOSTNAME` | Server hostname |
41
- | `-b, --base-url <url>` | `ECOPAGES_BASE_URL` | Base URL string |
42
- | `-d, --debug` | `ECOPAGES_LOGGER_DEBUG` | Enables debug-level logging |
43
- | `-r, --react-fast-refresh` | | Enables React Fast Refresh |
44
- | `--runtime <runtime>` | | Force execution via `bun` or `node` |
54
+ Server and build commands accept the following shared options. They automatically map to the equivalent environment variables for the underlying process. `--keep-going` is specific to `ecopages build`:
55
+
56
+ | Option | Env Var | Description |
57
+ | :---------------------- | :---------------------- | :-------------------------------------------------------- |
58
+ | `-p, --port <port>` | `ECOPAGES_PORT` | Server port (default 3000) |
59
+ | `-n, --hostname <host>` | `ECOPAGES_HOSTNAME` | Server hostname |
60
+ | `-b, --base-url <url>` | `ECOPAGES_BASE_URL` | Base URL string |
61
+ | `-d, --debug` | `ECOPAGES_LOGGER_DEBUG` | Enables debug logging and startup phase trace (see below) |
62
+ | `--keep-going` | | Continue exporting pages after a Page render fails |
63
+ | `--runtime <runtime>` | | Force execution via `bun` or `node` |
64
+
65
+ Boolean environment settings accept `true` or `1` to enable, and `false` or `0` to disable.
66
+
67
+ | Environment variable | Description |
68
+ | :------------------------------------------------- | :--------------------------------------------------------------------- |
69
+ | `ECOPAGES_CONFIG_FILE` | Config path, equivalent to `--config`. |
70
+ | `ECOPAGES_PREVIEW_SERVE_ONLY` | For `ecopages preview`, serve existing output without rebuilding. |
71
+ | `ECOPAGES_DEV_TOOLBAR=false` | Disable the configured development toolbar for this process. |
72
+ | `ECOPAGES_WATCH_CHANGE_DEBOUNCE_MS=<milliseconds>` | Set the quiet period used to batch development file changes. |
73
+ | `ECOPAGES_DEV_PREWARM_STATIC_ROUTES_PARALLELISM` | Limit concurrent development prewarm renders to this positive integer. |
74
+ | `ECOPAGES_UNIFIED_PAGES_GRAPH=0` | Opt out of the shared production static-page browser build. |
75
+ | `ECOPAGES_REQUEST_PIPELINE_METRICS=1` | Add request-pipeline measurements to development responses. |
76
+ | `ECOPAGES_ROLLDOWN_BUILD_METRICS=1` | Log Rolldown build invocation counts. |
77
+ | `ECOPAGES_PROFILE_BUILD=1` | Include build profiling data in debug output. |
78
+ | `ECOPAGES_STARTUP_TRACE_JSON=<path>` | Write the startup trace report to this JSON file. |
79
+ | `ECOPAGES_DEBUG=1` | Log when SSR skips a browser-only custom-element script preload. |
45
80
 
46
81
  ### Runtime Detection
47
82
 
48
- The CLI prefers Bun when the package manager already indicates Bun, when the `Bun` global is available, or when you force it with `--runtime bun`. Otherwise it falls back to Node.
83
+ The CLI runs your app on Bun when you launch the command through Bun (`bun dev`, `bun run dev`, `bunx ecopages …`) or pass `--runtime bun`. Any other launcher (`pnpm`, `npm`, `npx`, `node`) runs it on Node.
49
84
 
50
85
  You can explicitly force the engine using the `--runtime` flag:
51
86
 
@@ -58,9 +93,41 @@ ecopages build --runtime bun
58
93
  ```bash
59
94
  # Debug dev server on custom port
60
95
  ecopages dev --port 8080 --debug
96
+ ```
97
+
98
+ During `ecopages dev`, adding, changing, or removing `eco.config.ts` (or `--config`) and supported project `.env` files restarts the dev server automatically. The CLI supervises that restart and reloads dotenv files. If the restarted dev server exits with an error, for example because of an invalid config, `ecopages dev` logs the exit code and waits for the next change in the project or a linked workspace package, then starts again. When the preferred port is busy, development startup uses the same fallback flow as preview: TTY sessions show a Clack confirmation, while non-interactive sessions scan automatically only when the port was not pinned with `--port` or `ECOPAGES_PORT`.
99
+
100
+ `SIGTERM` and `SIGINT` sent to `ecopages` are forwarded to the server it started, and `ecopages` exits once that server has.
101
+
102
+ ### Debug logging and startup trace
103
+
104
+ Set these in `.env` or on the command line when diagnosing slow dev startup or first page load.
105
+
106
+ | Env var | CLI | What you get |
107
+ | :----------------------------------- | :--------------------- | :--------------------------------------------------------------------------------------------- |
108
+ | `ECOPAGES_LOGGER_DEBUG=true` or `1` | `ecopages dev --debug` | Verbose `[@ecopages/core]` logs across the stack, plus **startup phase trace** lines on stderr |
109
+ | `ECOPAGES_STARTUP_TRACE=true` or `1` | — | **Only** the phase trace (no extra debug noise). Useful when measuring first-open latency |
110
+
111
+ Trace lines are prefixed with `[ecopages:startup-trace]` and look like:
112
+
113
+ ```text
114
+ [ecopages:startup-trace] phase=config-ready wallMs=1271
115
+ [ecopages:startup-trace] phase=setupAppRuntimePlugins durationMs=714 wallMs=1999
116
+ [ecopages:startup-trace] phase=route-registry durationMs=1 wallMs=2000
117
+ [ecopages:startup-trace] phase=server-listen durationMs=45 wallMs=2046
118
+ [ecopages:startup-trace] phase=dev-client-transform durationMs=42 wallMs=2100
119
+ [ecopages:startup-trace] phase=first-request-ssr durationMs=5296 wallMs=12495
120
+ [ecopages:startup-trace] summary path=/docs/getting-started/introduction bundleCount=13 clientBundleBytes=858396 wallMs=12496
121
+ ```
122
+
123
+ Phases: config ready → runtime plugins → route registry → server listening → first request SSR (with per-module `dev-client-transform` on demand for `/assets/__eco_dev__/` modules). The summary includes bundle count and total client JS bytes for that first request.
124
+
125
+ ```bash
126
+ # Focused perf trace only
127
+ ECOPAGES_STARTUP_TRACE=true pnpm dev
61
128
 
62
- # Dev server with React Fast Refresh enabled
63
- ecopages dev -r
129
+ # Full debug + trace
130
+ ecopages dev --debug
64
131
  ```
65
132
 
66
133
  ## Ecosystem & Plugins
@@ -69,20 +136,20 @@ Ecopages relies on a modular architecture. Core logic and framework integrations
69
136
 
70
137
  ### Official Packages
71
138
 
72
- | Package | Description |
73
- | :---------------------------- | :----------------------------------------- |
74
- | `@ecopages/browser-router` | Client-side navigation & view transitions. |
75
- | `@ecopages/codemod` | AST migrations for codebase upgrades. |
76
- | `@ecopages/core` | The foundational SSG engine. |
77
- | `@ecopages/ecopages-jsx` | Ecopages-owned JSX routes and hydration. |
78
- | `@ecopages/file-system` | Runtime-agnostic file system utilities. |
79
- | `@ecopages/image-processor` | Asset pipeline for responsive images. |
80
- | `@ecopages/kitajs` | Integration for KitaJS. |
81
- | `@ecopages/lit` | Integration for Lit SSR/Islands. |
82
- | `@ecopages/mdx` | Integration for standalone MDX routes. |
83
- | `@ecopages/postcss-processor` | CSS processing pipeline using PostCSS. |
84
- | `@ecopages/react` | Integration for React 19 SSR/Islands. |
85
- | `@ecopages/react-router` | SPA routing for React. |
139
+ | Package | Description |
140
+ | :---------------------------- | :------------------------------------------- |
141
+ | `@ecopages/browser-router` | Client-side navigation & view transitions. |
142
+ | `@ecopages/codemod` | AST migrations for codebase upgrades. |
143
+ | `@ecopages/core` | The foundational SSG engine. |
144
+ | `@ecopages/ecopages-jsx` | Ecopages-owned JSX routes and hydration. |
145
+ | `@ecopages/file-system` | Runtime-agnostic file system utilities. |
146
+ | `@ecopages/image-processor` | Asset pipeline for responsive images. |
147
+ | `@ecopages/kitajs` | Integration for KitaJS. |
148
+ | `@ecopages/lit` | Integration for Lit SSR/Islands. |
149
+ | `@ecopages/mdx` | Integration for standalone MDX routes. |
150
+ | `@ecopages/postcss-processor` | CSS processing pipeline using PostCSS. |
151
+ | `@ecopages/react` | Integration for React 19 SSR/Islands. |
152
+ | `@ecopages/react-router` | React SPA routing falls back on HTTP errors. |
86
153
 
87
154
  Explore all packages at [npmjs.com/org/ecopages](https://www.npmjs.com/org/ecopages).
88
155
 
package/bin/brand.js ADDED
@@ -0,0 +1,42 @@
1
+ import { styleText } from 'node:util';
2
+
3
+ /**
4
+ * Terminal mark rasterized from `assets/brand/logo-on-light.svg`.
5
+ * @remarks Half-blocks keep rows flush; a thin stroke leaves the spiral's inner gaps open.
6
+ */
7
+ const BRAND_MARK_LINES = [
8
+ ' ▄▄▄▄',
9
+ ' ▄▄▄▄█▀▀▀▀▄█',
10
+ ' ▄▄▀▀▀ ██',
11
+ ' ▄█▀ ▄▄▄▄ █',
12
+ '▄█ █▀ ██ █',
13
+ '█▄ ▀█▄ ██ ▄█ ██',
14
+ ' █▄ ▀▀██▀▀▀ █',
15
+ ' ▀▀█▄ ▀█ ▄█▀',
16
+ ' ▄█▀ ▀▀▀▀▀',
17
+ ' █▀',
18
+ '▀',
19
+ ];
20
+
21
+ export function formatBrandBanner(version, stream = process.stdout) {
22
+ const markWidth = Math.max(...BRAND_MARK_LINES.map((line) => [...line].length));
23
+ const versionLabel = stream.hasColors?.() ? styleText('dim', version) : version;
24
+ const labels = ['ecopages', versionLabel];
25
+ const labelStart = Math.max(0, Math.floor((BRAND_MARK_LINES.length - labels.length) / 2));
26
+
27
+ return BRAND_MARK_LINES.map((line, index) => {
28
+ const padded = `${line}${' '.repeat(markWidth - [...line].length)}`;
29
+ const label = labels[index - labelStart];
30
+ return label === undefined ? padded : `${padded} ${label}`;
31
+ }).join('\n');
32
+ }
33
+
34
+ export function withBrandBanner(version, text) {
35
+ if (!process.stdout.isTTY) return text;
36
+ return `${formatBrandBanner(version)}\n\n${text}`;
37
+ }
38
+
39
+ export function printBrandBanner(version) {
40
+ if (!process.stderr.isTTY) return;
41
+ process.stderr.write(`${formatBrandBanner(version, process.stderr)}\n\n`);
42
+ }