ecopages 0.2.1 → 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 +109 -47
- package/bin/brand.js +42 -0
- package/bin/cli.js +348 -192
- package/bin/git-template-source-providers.js +56 -0
- package/bin/git-template-source-shared.js +7 -0
- package/bin/git-template-source.js +62 -0
- package/bin/init.js +392 -0
- package/bin/launch-plan.js +156 -60
- package/bin/node-require-preload.js +4 -0
- package/css/view-transitions.css +3 -6
- package/package.json +13 -12
- package/templates.json +115 -0
- package/bin/cli.test.ts +0 -136
- package/bin/launch-plan.test.ts +0 -160
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
|
|
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
|
|
9
|
+
Initialize a new project from the interactive template picker:
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
|
-
bunx ecopages init
|
|
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
|
|
21
|
-
|
|
|
22
|
-
| `ecopages init
|
|
23
|
-
| `ecopages dev
|
|
24
|
-
| `ecopages dev:watch
|
|
25
|
-
| `ecopages
|
|
26
|
-
| `ecopages
|
|
27
|
-
| `ecopages
|
|
28
|
-
| `ecopages
|
|
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
|
-
>
|
|
37
|
+
> The entry file defaults to `app.ts`. Override it with `--entry-file`.
|
|
32
38
|
|
|
33
|
-
|
|
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.
|
|
34
40
|
|
|
35
|
-
|
|
41
|
+
### Templates
|
|
36
42
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
|
53
|
+
|
|
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
|
|
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,38 +93,65 @@ ecopages build --runtime bun
|
|
|
58
93
|
```bash
|
|
59
94
|
# Debug dev server on custom port
|
|
60
95
|
ecopages dev --port 8080 --debug
|
|
61
|
-
|
|
62
|
-
# Dev server with React Fast Refresh enabled
|
|
63
|
-
ecopages dev -r
|
|
64
96
|
```
|
|
65
97
|
|
|
66
|
-
|
|
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:
|
|
67
112
|
|
|
68
|
-
|
|
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.
|
|
69
124
|
|
|
70
|
-
|
|
125
|
+
```bash
|
|
126
|
+
# Focused perf trace only
|
|
127
|
+
ECOPAGES_STARTUP_TRACE=true pnpm dev
|
|
71
128
|
|
|
72
|
-
|
|
73
|
-
|
|
129
|
+
# Full debug + trace
|
|
130
|
+
ecopages dev --debug
|
|
74
131
|
```
|
|
75
132
|
|
|
133
|
+
## Ecosystem & Plugins
|
|
134
|
+
|
|
135
|
+
Ecopages relies on a modular architecture. Core logic and framework integrations are published as `@ecopages/*` packages on [npm](https://www.npmjs.com/org/ecopages).
|
|
136
|
+
|
|
76
137
|
### Official Packages
|
|
77
138
|
|
|
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/
|
|
84
|
-
| `@ecopages/
|
|
85
|
-
| `@ecopages/
|
|
86
|
-
| `@ecopages/
|
|
87
|
-
| `@ecopages/
|
|
88
|
-
| `@ecopages/
|
|
89
|
-
| `@ecopages/
|
|
90
|
-
| `@ecopages/react
|
|
91
|
-
|
|
92
|
-
|
|
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. |
|
|
153
|
+
|
|
154
|
+
Explore all packages at [npmjs.com/org/ecopages](https://www.npmjs.com/org/ecopages).
|
|
93
155
|
|
|
94
156
|
## License
|
|
95
157
|
|
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
|
+
}
|