ecopages 0.2.1 → 0.3.1

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,50 +2,88 @@
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 automatically detects your `eco.config.ts`.
5
+ It provides scaffolding and development commands to streamline your workflow. It runs your app on Node by default and on Bun when you launch it through Bun or pass `--runtime bun`, 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
+ npx ecopages init
13
+ # or: pnpm dlx ecopages init
14
+ ```
15
+
16
+ For a deterministic invocation, select a template explicitly:
17
+
18
+ ```bash
19
+ npx ecopages init my-app --template react
13
20
  cd my-app
14
- bun install
15
- bun dev
21
+ pnpm install
22
+ pnpm dev
16
23
  ```
17
24
 
25
+ The commands above run on Node. Bun is optional: launch them through Bun (`bunx ecopages init`, `bun dev`) or pass `--runtime bun` to run the app on Bun.
26
+
18
27
  ## Commands
19
28
 
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` |
29
+ | Command | Description | What it runs |
30
+ | :-------------------- | :------------------------------------------------------ | :------------------------------------------------------------------- |
31
+ | `ecopages init [dir]` | Scaffolds a new project (interactive without `dir`) | N/A |
32
+ | `ecopages dev` | Starts the dev server (supervises config/.env restarts) | `[entry] --dev` through tsx on Node, `bun run [entry] --dev` on Bun |
33
+ | `ecopages dev:watch` | Dev server + hard restarts on file changes | Node: `node --watch …`; Bun: `bun --watch run [entry] --dev` |
34
+ | `ecopages build` | Creates a production build | `[entry] --build` through tsx on Node, `bun run [entry] --build` |
35
+ | `ecopages start` | Starts the production server from the built output | Runs the emitted server bundle |
36
+ | `ecopages preview` | Previews the production build locally | `[entry] --preview` through tsx on Node, `bun run [entry] --preview` |
37
+ | `ecopages types` | Writes virtual-module types for `tsc`, then exits | Loads `eco.config.ts` and sets processors up; the entry does not run |
29
38
 
30
39
  > [!NOTE]
31
- > `[entry]` defaults to `app.ts` if not provided.
40
+ > The entry file defaults to `app.ts`. Override it with `--entry-file`.
32
41
 
33
- ## Environment & Runtime Options
42
+ `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. Only apps that register API or WebSocket handlers build a server bundle. For a static-only app, `start` instead reports that the build has no server bundle when `dist` (or the `--dist-dir` directory) holds built HTML; serve that output with `ecopages preview` or deploy `dist/` to a static host. 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.
43
+
44
+ ### Templates
34
45
 
35
- Server and build commands accept the following options. They automatically map to the equivalent environment variables for the underlying process:
46
+ 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.
47
+
48
+ ```bash
49
+ ecopages init my-site --template jsx
50
+ ecopages init my-site --from github:acme/my-template#v1.0.0
51
+ ```
52
+
53
+ 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`.
54
+
55
+ ## Environment & Runtime Options
36
56
 
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` |
57
+ 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`:
58
+
59
+ | Option | Env Var | Description |
60
+ | :---------------------- | :---------------------- | :-------------------------------------------------------- |
61
+ | `-p, --port <port>` | `ECOPAGES_PORT` | Server port (default 3000) |
62
+ | `-n, --hostname <host>` | `ECOPAGES_HOSTNAME` | Server hostname |
63
+ | `-b, --base-url <url>` | `ECOPAGES_BASE_URL` | Base URL string |
64
+ | `-d, --debug` | `ECOPAGES_LOGGER_DEBUG` | Enables debug logging and startup phase trace (see below) |
65
+ | `--keep-going` | | Continue exporting pages after a Page render fails |
66
+ | `--runtime <runtime>` | | Force execution via `bun` or `node` |
67
+
68
+ Boolean environment settings accept `true` or `1` to enable, and `false` or `0` to disable.
69
+
70
+ | Environment variable | Description |
71
+ | :------------------------------------------------- | :--------------------------------------------------------------------- |
72
+ | `ECOPAGES_CONFIG_FILE` | Config path, equivalent to `--config`. |
73
+ | `ECOPAGES_PREVIEW_SERVE_ONLY` | For `ecopages preview`, serve existing output without rebuilding. |
74
+ | `ECOPAGES_DEV_TOOLBAR=false` | Disable the configured development toolbar for this process. |
75
+ | `ECOPAGES_WATCH_CHANGE_DEBOUNCE_MS=<milliseconds>` | Set the quiet period used to batch development file changes. |
76
+ | `ECOPAGES_DEV_PREWARM_STATIC_ROUTES_PARALLELISM` | Limit concurrent development prewarm renders to this positive integer. |
77
+ | `ECOPAGES_UNIFIED_PAGES_GRAPH=0` | Opt out of the shared production static-page browser build. |
78
+ | `ECOPAGES_REQUEST_PIPELINE_METRICS=1` | Add request-pipeline measurements to development responses. |
79
+ | `ECOPAGES_ROLLDOWN_BUILD_METRICS=1` | Log Rolldown build invocation counts. |
80
+ | `ECOPAGES_PROFILE_BUILD=1` | Include build profiling data in debug output. |
81
+ | `ECOPAGES_STARTUP_TRACE_JSON=<path>` | Write the startup trace report to this JSON file. |
82
+ | `ECOPAGES_DEBUG=1` | Log when SSR skips a browser-only custom-element script preload. |
45
83
 
46
84
  ### Runtime Detection
47
85
 
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.
86
+ 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
87
 
50
88
  You can explicitly force the engine using the `--runtime` flag:
51
89
 
@@ -58,38 +96,65 @@ ecopages build --runtime bun
58
96
  ```bash
59
97
  # Debug dev server on custom port
60
98
  ecopages dev --port 8080 --debug
61
-
62
- # Dev server with React Fast Refresh enabled
63
- ecopages dev -r
64
99
  ```
65
100
 
66
- ## Ecosystem & Plugins
101
+ 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`.
102
+
103
+ `SIGTERM` and `SIGINT` sent to `ecopages` are forwarded to the server it started, and `ecopages` exits once that server has. `ecopages` exits with the server's exit code, or with 128 plus the signal number when a signal ended the server, for example 137 when the build is killed (SIGKILL).
104
+
105
+ ### Debug logging and startup trace
67
106
 
68
- Ecopages relies on a modular architecture. Core logic and framework integrations are published separately to [JSR](https://jsr.io/@ecopages).
107
+ Set these in `.env` or on the command line when diagnosing slow dev startup or first page load.
69
108
 
70
- Configure your project to use JSR by adding a `.npmrc` file:
109
+ | Env var | CLI | What you get |
110
+ | :----------------------------------- | :--------------------- | :--------------------------------------------------------------------------------------------- |
111
+ | `ECOPAGES_LOGGER_DEBUG=true` or `1` | `ecopages dev --debug` | Verbose `[@ecopages/core]` logs across the stack, plus **startup phase trace** lines on stderr |
112
+ | `ECOPAGES_STARTUP_TRACE=true` or `1` | — | **Only** the phase trace (no extra debug noise). Useful when measuring first-open latency |
71
113
 
72
- ```ini
73
- @jsr:registry=https://npm.jsr.io
114
+ Trace lines are prefixed with `[ecopages:startup-trace]` and look like:
115
+
116
+ ```text
117
+ [ecopages:startup-trace] phase=config-ready wallMs=1271
118
+ [ecopages:startup-trace] phase=setupAppRuntimePlugins durationMs=714 wallMs=1999
119
+ [ecopages:startup-trace] phase=route-registry durationMs=1 wallMs=2000
120
+ [ecopages:startup-trace] phase=server-listen durationMs=45 wallMs=2046
121
+ [ecopages:startup-trace] phase=dev-client-transform durationMs=42 wallMs=2100
122
+ [ecopages:startup-trace] phase=first-request-ssr durationMs=5296 wallMs=12495
123
+ [ecopages:startup-trace] summary path=/docs/getting-started/introduction bundleCount=13 clientBundleBytes=858396 wallMs=12496
74
124
  ```
75
125
 
126
+ 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.
127
+
128
+ ```bash
129
+ # Focused perf trace only
130
+ ECOPAGES_STARTUP_TRACE=true pnpm dev
131
+
132
+ # Full debug + trace
133
+ ecopages dev --debug
134
+ ```
135
+
136
+ ## Ecosystem & Plugins
137
+
138
+ Ecopages relies on a modular architecture. Core logic and framework integrations are published as `@ecopages/*` packages on [npm](https://www.npmjs.com/org/ecopages).
139
+
76
140
  ### Official Packages
77
141
 
78
- | Package | Description |
79
- | :---------------------------- | :----------------------------------------- |
80
- | `@ecopages/browser-router` | Client-side navigation & view transitions. |
81
- | `@ecopages/codemod` | AST migrations for codebase upgrades. |
82
- | `@ecopages/core` | The foundational SSG engine. |
83
- | `@ecopages/file-system` | Runtime-agnostic file system utilities. |
84
- | `@ecopages/image-processor` | Asset pipeline for responsive images. |
85
- | `@ecopages/kitajs` | Integration for KitaJS. |
86
- | `@ecopages/lit` | Integration for Lit SSR/Islands. |
87
- | `@ecopages/mdx` | Integration for standalone MDX routes. |
88
- | `@ecopages/postcss-processor` | CSS processing pipeline using PostCSS. |
89
- | `@ecopages/react` | Integration for React 19 SSR/Islands. |
90
- | `@ecopages/react-router` | SPA routing for React. |
91
-
92
- Explore all packages at [jsr.io/@ecopages](https://jsr.io/@ecopages).
142
+ | Package | Description |
143
+ | :---------------------------- | :------------------------------------------- |
144
+ | `@ecopages/browser-router` | Client-side navigation & view transitions. |
145
+ | `@ecopages/core` | The foundational SSG engine. |
146
+ | `@ecopages/dev-toolbar` | Development-only browser toolbar. |
147
+ | `@ecopages/ecopages-jsx` | Ecopages-owned JSX routes and hydration. |
148
+ | `@ecopages/file-system` | Runtime-agnostic file system utilities. |
149
+ | `@ecopages/image-processor` | Asset pipeline for responsive images. |
150
+ | `@ecopages/kitajs` | Integration for KitaJS. |
151
+ | `@ecopages/lit` | Integration for Lit SSR/Islands. |
152
+ | `@ecopages/mdx` | Integration for standalone MDX routes. |
153
+ | `@ecopages/postcss-processor` | CSS processing pipeline using PostCSS. |
154
+ | `@ecopages/react` | Integration for React 19 SSR/Islands. |
155
+ | `@ecopages/react-router` | React SPA routing falls back on HTTP errors. |
156
+
157
+ Explore all packages at [npmjs.com/org/ecopages](https://www.npmjs.com/org/ecopages).
93
158
 
94
159
  ## License
95
160
 
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
+ }