ecopages 0.3.0 → 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 +16 -13
- package/bin/cli.js +36 -14
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -2,41 +2,44 @@
|
|
|
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 runs your app on Bun when you launch it through Bun
|
|
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
9
|
Initialize a new project from the interactive template picker:
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
|
-
|
|
12
|
+
npx ecopages init
|
|
13
|
+
# or: pnpm dlx ecopages init
|
|
13
14
|
```
|
|
14
15
|
|
|
15
16
|
For a deterministic invocation, select a template explicitly:
|
|
16
17
|
|
|
17
18
|
```bash
|
|
18
|
-
|
|
19
|
+
npx ecopages init my-app --template react
|
|
19
20
|
cd my-app
|
|
20
|
-
|
|
21
|
-
|
|
21
|
+
pnpm install
|
|
22
|
+
pnpm dev
|
|
22
23
|
```
|
|
23
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
|
+
|
|
24
27
|
## Commands
|
|
25
28
|
|
|
26
|
-
| Command | Description |
|
|
29
|
+
| Command | Description | What it runs |
|
|
27
30
|
| :-------------------- | :------------------------------------------------------ | :------------------------------------------------------------------- |
|
|
28
31
|
| `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
|
|
31
|
-
| `ecopages build` | Creates a production build | `bun run [entry] --build`
|
|
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` |
|
|
32
35
|
| `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`
|
|
36
|
+
| `ecopages preview` | Previews the production build locally | `[entry] --preview` through tsx on Node, `bun run [entry] --preview` |
|
|
34
37
|
| `ecopages types` | Writes virtual-module types for `tsc`, then exits | Loads `eco.config.ts` and sets processors up; the entry does not run |
|
|
35
38
|
|
|
36
39
|
> [!NOTE]
|
|
37
40
|
> The entry file defaults to `app.ts`. Override it with `--entry-file`.
|
|
38
41
|
|
|
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.
|
|
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.
|
|
40
43
|
|
|
41
44
|
### Templates
|
|
42
45
|
|
|
@@ -97,7 +100,7 @@ ecopages dev --port 8080 --debug
|
|
|
97
100
|
|
|
98
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`.
|
|
99
102
|
|
|
100
|
-
`SIGTERM` and `SIGINT` sent to `ecopages` are forwarded to the server it started, and `ecopages` exits once that server has.
|
|
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).
|
|
101
104
|
|
|
102
105
|
### Debug logging and startup trace
|
|
103
106
|
|
|
@@ -139,8 +142,8 @@ Ecopages relies on a modular architecture. Core logic and framework integrations
|
|
|
139
142
|
| Package | Description |
|
|
140
143
|
| :---------------------------- | :------------------------------------------- |
|
|
141
144
|
| `@ecopages/browser-router` | Client-side navigation & view transitions. |
|
|
142
|
-
| `@ecopages/codemod` | AST migrations for codebase upgrades. |
|
|
143
145
|
| `@ecopages/core` | The foundational SSG engine. |
|
|
146
|
+
| `@ecopages/dev-toolbar` | Development-only browser toolbar. |
|
|
144
147
|
| `@ecopages/ecopages-jsx` | Ecopages-owned JSX routes and hydration. |
|
|
145
148
|
| `@ecopages/file-system` | Runtime-agnostic file system utilities. |
|
|
146
149
|
| `@ecopages/image-processor` | Asset pipeline for responsive images. |
|
package/bin/cli.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
import { existsSync, readFileSync } from 'node:fs';
|
|
4
4
|
import { spawn } from 'node:child_process';
|
|
5
|
+
import os from 'node:os';
|
|
5
6
|
import path from 'node:path';
|
|
6
7
|
import { fileURLToPath } from 'node:url';
|
|
7
8
|
import { parseArgs } from 'node:util';
|
|
@@ -75,20 +76,26 @@ function getMainHelpText() {
|
|
|
75
76
|
].join('\n');
|
|
76
77
|
}
|
|
77
78
|
|
|
78
|
-
|
|
79
|
+
const SHARED_SERVER_OPTION_HELP = {
|
|
80
|
+
port: ' -p, --port <port> Override ECOPAGES_PORT',
|
|
81
|
+
hostname: ' -n, --hostname <hostname> Override ECOPAGES_HOSTNAME',
|
|
82
|
+
'base-url': ' -b, --base-url <baseUrl> Override ECOPAGES_BASE_URL',
|
|
83
|
+
debug: ' -d, --debug Enable debug logging',
|
|
84
|
+
runtime: ' --runtime <runtime> Force bun or node',
|
|
85
|
+
'entry-file': ' -e, --entry-file <file> Entry file (default: app.ts)',
|
|
86
|
+
config: ' -c, --config <file> Ecopages config file (default: eco.config.ts)',
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
function getServerCommandHelpText(commandName, description, extraOptionLines = [], ignoredOptions = []) {
|
|
79
90
|
return [
|
|
80
91
|
`Usage: ecopages ${commandName} [options]`,
|
|
81
92
|
'',
|
|
82
93
|
description,
|
|
83
94
|
'',
|
|
84
95
|
'Options:',
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
' -d, --debug Enable debug logging',
|
|
89
|
-
' --runtime <runtime> Force bun or node',
|
|
90
|
-
' -e, --entry-file <file> Entry file (default: app.ts)',
|
|
91
|
-
' -c, --config <file> Ecopages config file (default: eco.config.ts)',
|
|
96
|
+
...Object.entries(SHARED_SERVER_OPTION_HELP)
|
|
97
|
+
.filter(([option]) => !ignoredOptions.includes(option))
|
|
98
|
+
.map(([, line]) => line),
|
|
92
99
|
...extraOptionLines,
|
|
93
100
|
' -h, --help Show help',
|
|
94
101
|
].join('\n');
|
|
@@ -115,10 +122,12 @@ function parseServerCommandArgs(rawArgs, definition) {
|
|
|
115
122
|
|
|
116
123
|
if (values.help) {
|
|
117
124
|
console.log(
|
|
118
|
-
getServerCommandHelpText(
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
125
|
+
getServerCommandHelpText(
|
|
126
|
+
commandName,
|
|
127
|
+
definition.description,
|
|
128
|
+
[...Object.values(valueOptions), ...(definition.optionHelpLines ?? [])],
|
|
129
|
+
definition.ignoredOptions,
|
|
130
|
+
),
|
|
122
131
|
);
|
|
123
132
|
return { help: true };
|
|
124
133
|
}
|
|
@@ -155,6 +164,18 @@ function parseServerCommandArgs(rawArgs, definition) {
|
|
|
155
164
|
*/
|
|
156
165
|
const FORWARDED_SIGNALS = ['SIGTERM', 'SIGINT'];
|
|
157
166
|
|
|
167
|
+
/**
|
|
168
|
+
* Exit code for a child that a signal terminated.
|
|
169
|
+
*
|
|
170
|
+
* @remarks
|
|
171
|
+
* Node reports such a child with a null exit code, which `process.exit(code || 0)` turned into success, so a
|
|
172
|
+
* build killed by the OOM killer (SIGKILL) looked like it had passed. Shells report the same case as 128 plus
|
|
173
|
+
* the signal number, and so does this.
|
|
174
|
+
*/
|
|
175
|
+
function getSignalExitCode(signal) {
|
|
176
|
+
return 128 + (os.constants.signals[signal] ?? 0);
|
|
177
|
+
}
|
|
178
|
+
|
|
158
179
|
function runLaunchPlan(launchPlan, options = {}) {
|
|
159
180
|
if (Object.keys(launchPlan.envOverrides).length > 0) {
|
|
160
181
|
logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
|
|
@@ -189,7 +210,7 @@ function runLaunchPlan(launchPlan, options = {}) {
|
|
|
189
210
|
process.exit(1);
|
|
190
211
|
});
|
|
191
212
|
|
|
192
|
-
child.on('exit', (code) => {
|
|
213
|
+
child.on('exit', (code, signal) => {
|
|
193
214
|
for (const signal of FORWARDED_SIGNALS) {
|
|
194
215
|
process.off(signal, forwardSignal);
|
|
195
216
|
}
|
|
@@ -205,7 +226,7 @@ function runLaunchPlan(launchPlan, options = {}) {
|
|
|
205
226
|
return;
|
|
206
227
|
}
|
|
207
228
|
|
|
208
|
-
process.exit(code || 0);
|
|
229
|
+
process.exit(signal ? getSignalExitCode(signal) : code || 0);
|
|
209
230
|
});
|
|
210
231
|
}
|
|
211
232
|
|
|
@@ -366,6 +387,7 @@ const SERVER_COMMANDS = {
|
|
|
366
387
|
'Load eco.config.ts so processors write the types for virtual modules such as ecopages:images, then exit. The app entry does not run. Run it before tsc.',
|
|
367
388
|
entryArgs: [],
|
|
368
389
|
resolveEntry: () => fileURLToPath(import.meta.resolve('@ecopages/core/config/write-types')),
|
|
390
|
+
ignoredOptions: ['port', 'hostname', 'base-url', 'entry-file'],
|
|
369
391
|
optionOverrides: { nodeEnv: 'production' },
|
|
370
392
|
},
|
|
371
393
|
preview: {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ecopages",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "CLI utilities for Ecopages",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
@@ -36,8 +36,8 @@
|
|
|
36
36
|
},
|
|
37
37
|
"dependencies": {
|
|
38
38
|
"@clack/prompts": "^1.7.0",
|
|
39
|
-
"@ecopages/core": "0.3.
|
|
40
|
-
"@ecopages/file-system": "0.3.
|
|
39
|
+
"@ecopages/core": "0.3.1",
|
|
40
|
+
"@ecopages/file-system": "0.3.1",
|
|
41
41
|
"@ecopages/logger": "^0.2.3",
|
|
42
42
|
"giget": "^2.0.0",
|
|
43
43
|
"tsx": "^4.22.3"
|