ecopages 0.2.0-rc.9 → 0.2.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 +14 -12
- package/bin/cli.js +42 -10
- package/bin/launch-plan.js +56 -17
- package/package.json +2 -2
- package/templates.json +10 -0
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
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
|
|
|
@@ -23,15 +23,15 @@ bun dev
|
|
|
23
23
|
|
|
24
24
|
## Commands
|
|
25
25
|
|
|
26
|
-
| Command | Description
|
|
27
|
-
| :-------------------- |
|
|
28
|
-
| `ecopages init [dir]` | Scaffolds a new project (interactive without `dir`)
|
|
29
|
-
| `ecopages dev` | Starts the dev server
|
|
30
|
-
| `ecopages dev:watch` | Dev server + hard restarts on file changes
|
|
31
|
-
| `ecopages dev:hot` | Dev server + HMR (no hard restarts)
|
|
32
|
-
| `ecopages build` | Creates a production build
|
|
33
|
-
| `ecopages start` | Starts the production server
|
|
34
|
-
| `ecopages preview` | Previews the production build locally
|
|
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 dev:hot` | Dev server + HMR (no hard restarts) | `bun --hot run [entry] --dev` |
|
|
32
|
+
| `ecopages build` | Creates a production build | `bun run [entry] --build` |
|
|
33
|
+
| `ecopages start` | Starts the production server | `bun run [entry]` |
|
|
34
|
+
| `ecopages preview` | Previews the production build locally | `bun run [entry] --preview` |
|
|
35
35
|
|
|
36
36
|
> [!NOTE]
|
|
37
37
|
> The entry file defaults to `app.ts`. Override it with `--entry-file`.
|
|
@@ -45,7 +45,7 @@ ecopages init my-site --template jsx
|
|
|
45
45
|
ecopages init my-site --from github:acme/my-template#v1.0.0
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
-
The official template IDs are `jsx`, `react`, `lit-jsx`, `radiant`, `blog-jsx`, `blog-react`, `docs-starter`, `react-better-auth`, and `llm-wiki`.
|
|
48
|
+
The official template IDs are `jsx`, `react`, `react-shadcn`, `lit-jsx`, `radiant`, `blog-jsx`, `blog-react`, `docs-starter`, `react-better-auth`, and `llm-wiki`.
|
|
49
49
|
|
|
50
50
|
## Environment & Runtime Options
|
|
51
51
|
|
|
@@ -62,7 +62,7 @@ Server and build commands accept the following options. They automatically map t
|
|
|
62
62
|
|
|
63
63
|
### Runtime Detection
|
|
64
64
|
|
|
65
|
-
The CLI
|
|
65
|
+
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.
|
|
66
66
|
|
|
67
67
|
You can explicitly force the engine using the `--runtime` flag:
|
|
68
68
|
|
|
@@ -80,6 +80,8 @@ ecopages dev --port 8080 --debug
|
|
|
80
80
|
ecopages dev -r
|
|
81
81
|
```
|
|
82
82
|
|
|
83
|
+
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. 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`.
|
|
84
|
+
|
|
83
85
|
### Debug logging and startup trace
|
|
84
86
|
|
|
85
87
|
Set these in `.env` or on the command line when diagnosing slow dev startup or first page load.
|
package/bin/cli.js
CHANGED
|
@@ -5,6 +5,10 @@ import { spawn } from 'node:child_process';
|
|
|
5
5
|
import { parseArgs } from 'node:util';
|
|
6
6
|
import { Logger } from '@ecopages/logger';
|
|
7
7
|
import { createLaunchPlan } from './launch-plan.js';
|
|
8
|
+
import {
|
|
9
|
+
ECOPAGES_DEV_RESTART_EXIT_CODE,
|
|
10
|
+
ECOPAGES_DEV_RESTART_REASON_ENV,
|
|
11
|
+
} from '@ecopages/core/dev/development-restart';
|
|
8
12
|
import { withBrandBanner } from './brand.js';
|
|
9
13
|
|
|
10
14
|
const logger = new Logger('[ecopages:cli]', { debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true' });
|
|
@@ -39,6 +43,10 @@ const sharedServerOptionDefinitions = {
|
|
|
39
43
|
type: 'string',
|
|
40
44
|
short: 'e',
|
|
41
45
|
},
|
|
46
|
+
config: {
|
|
47
|
+
type: 'string',
|
|
48
|
+
short: 'c',
|
|
49
|
+
},
|
|
42
50
|
help: {
|
|
43
51
|
type: 'boolean',
|
|
44
52
|
short: 'h',
|
|
@@ -60,6 +68,7 @@ function getMainHelpText() {
|
|
|
60
68
|
'',
|
|
61
69
|
'Global options:',
|
|
62
70
|
' -e, --entry-file <file> Entry file (default: app.ts)',
|
|
71
|
+
' -c, --config <file> Ecopages config file (default: eco.config.ts)',
|
|
63
72
|
' -h, --help Show help',
|
|
64
73
|
' --version Show version',
|
|
65
74
|
].join('\n');
|
|
@@ -79,6 +88,7 @@ function getServerCommandHelpText(commandName, description) {
|
|
|
79
88
|
' -r, --react-fast-refresh Enable React Fast Refresh for Bun HMR',
|
|
80
89
|
' --runtime <runtime> Force bun or node',
|
|
81
90
|
' -e, --entry-file <file> Entry file (default: app.ts)',
|
|
91
|
+
' -c, --config <file> Ecopages config file (default: eco.config.ts)',
|
|
82
92
|
' -h, --help Show help',
|
|
83
93
|
].join('\n');
|
|
84
94
|
}
|
|
@@ -97,6 +107,7 @@ function getBuildCommandHelpText() {
|
|
|
97
107
|
' -r, --react-fast-refresh Enable React Fast Refresh for Bun HMR',
|
|
98
108
|
' --runtime <runtime> Force bun or node',
|
|
99
109
|
' -e, --entry-file <file> Entry file (default: app.ts)',
|
|
110
|
+
' -c, --config <file> Ecopages config file (default: eco.config.ts)',
|
|
100
111
|
' -h, --help Show help',
|
|
101
112
|
].join('\n');
|
|
102
113
|
}
|
|
@@ -135,11 +146,12 @@ function parseServerCommandArgs(rawArgs, commandName, description, mode = 'serve
|
|
|
135
146
|
debug: values.debug,
|
|
136
147
|
reactFastRefresh: values['react-fast-refresh'],
|
|
137
148
|
runtime: values.runtime,
|
|
149
|
+
configFile: values.config,
|
|
138
150
|
},
|
|
139
151
|
};
|
|
140
152
|
}
|
|
141
153
|
|
|
142
|
-
function runLaunchPlan(launchPlan) {
|
|
154
|
+
function runLaunchPlan(launchPlan, options = {}) {
|
|
143
155
|
if (Object.keys(launchPlan.envOverrides).length > 0) {
|
|
144
156
|
logger.debug(`Environment overrides: ${JSON.stringify(launchPlan.envOverrides)}`);
|
|
145
157
|
}
|
|
@@ -167,6 +179,11 @@ function runLaunchPlan(launchPlan) {
|
|
|
167
179
|
});
|
|
168
180
|
|
|
169
181
|
child.on('exit', (code) => {
|
|
182
|
+
if (options.superviseDevRestarts && code === ECOPAGES_DEV_RESTART_EXIT_CODE) {
|
|
183
|
+
options.onDevRestart?.();
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
|
|
170
187
|
process.exit(code || 0);
|
|
171
188
|
});
|
|
172
189
|
}
|
|
@@ -179,23 +196,38 @@ function runLaunchPlan(launchPlan) {
|
|
|
179
196
|
* @param {string} entryFile - Entry file to run
|
|
180
197
|
*/
|
|
181
198
|
async function runEntryCommand(args, options = {}, entryFile = 'app.ts', launchMode = 'start') {
|
|
182
|
-
let launchPlan;
|
|
183
199
|
const requiresBuiltBundle = launchMode === 'start';
|
|
200
|
+
const superviseDevRestarts = launchMode === 'dev';
|
|
184
201
|
|
|
185
202
|
if (!requiresBuiltBundle && !existsSync(entryFile)) {
|
|
186
203
|
logger.error(`Error: Entry file "${entryFile}" not found in the current directory.`);
|
|
187
204
|
process.exit(1);
|
|
188
205
|
}
|
|
189
206
|
|
|
190
|
-
|
|
191
|
-
launchPlan
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
207
|
+
const launchChild = async (restartReason) => {
|
|
208
|
+
let launchPlan;
|
|
209
|
+
try {
|
|
210
|
+
launchPlan = await createLaunchPlan(args, options, entryFile, launchMode);
|
|
211
|
+
} catch (error) {
|
|
212
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
213
|
+
logger.error(message);
|
|
214
|
+
process.exit(1);
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
if (restartReason) {
|
|
218
|
+
launchPlan.env[ECOPAGES_DEV_RESTART_REASON_ENV] = restartReason;
|
|
219
|
+
launchPlan.envOverrides[ECOPAGES_DEV_RESTART_REASON_ENV] = restartReason;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
runLaunchPlan(launchPlan, {
|
|
223
|
+
superviseDevRestarts,
|
|
224
|
+
onDevRestart: () => {
|
|
225
|
+
void launchChild('configuration or environment change');
|
|
226
|
+
},
|
|
227
|
+
});
|
|
228
|
+
};
|
|
197
229
|
|
|
198
|
-
|
|
230
|
+
await launchChild();
|
|
199
231
|
}
|
|
200
232
|
|
|
201
233
|
async function runServerCommand(rawArgs, definition) {
|
package/bin/launch-plan.js
CHANGED
|
@@ -2,6 +2,12 @@ import { existsSync, readFileSync } from 'node:fs';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { parseEnv } from 'node:util';
|
|
4
4
|
import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from '@ecopages/core/utils/resolve-entry-file';
|
|
5
|
+
import {
|
|
6
|
+
resolveEcoConfigPath,
|
|
7
|
+
resolveEmittedEcoConfigPath,
|
|
8
|
+
assertProductionConfigIdentity,
|
|
9
|
+
} from '@ecopages/core/config';
|
|
10
|
+
import { ECOPAGES_ENTRY_WATCH_ENV, getDevEnvFileNames } from '@ecopages/core/dev/development-restart';
|
|
5
11
|
|
|
6
12
|
const SERVER_BUNDLE_MANIFEST_FILENAME = 'manifest.json';
|
|
7
13
|
|
|
@@ -9,13 +15,7 @@ const nodeRequirePreload = import.meta.resolve('./node-require-preload.js');
|
|
|
9
15
|
const tsxLoader = import.meta.resolve('tsx/esm');
|
|
10
16
|
|
|
11
17
|
function getEnvFilePaths(nodeEnv) {
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
if (nodeEnv) {
|
|
15
|
-
envFiles.push(`.env.${nodeEnv}`, `.env.${nodeEnv}.local`);
|
|
16
|
-
}
|
|
17
|
-
|
|
18
|
-
return envFiles.filter((envFile) => existsSync(envFile));
|
|
18
|
+
return getDevEnvFileNames(nodeEnv).filter((envFile) => existsSync(envFile));
|
|
19
19
|
}
|
|
20
20
|
|
|
21
21
|
export function buildEnvOverrides(options) {
|
|
@@ -26,9 +26,26 @@ export function buildEnvOverrides(options) {
|
|
|
26
26
|
if (options.debug) env.ECOPAGES_LOGGER_DEBUG = 'true';
|
|
27
27
|
if (options.nodeEnv) env.NODE_ENV = options.nodeEnv;
|
|
28
28
|
if (options.entryFile) env.ECOPAGES_ENTRY_FILE = options.entryFile;
|
|
29
|
+
if (options.configFile) {
|
|
30
|
+
env.ECOPAGES_CONFIG_FILE = path.isAbsolute(options.configFile)
|
|
31
|
+
? options.configFile
|
|
32
|
+
: path.resolve(process.cwd(), options.configFile);
|
|
33
|
+
}
|
|
34
|
+
if (options.watch) {
|
|
35
|
+
env[ECOPAGES_ENTRY_WATCH_ENV] = '1';
|
|
36
|
+
}
|
|
29
37
|
return env;
|
|
30
38
|
}
|
|
31
39
|
|
|
40
|
+
export function resolveEcoConfigFilePath(options = {}, cwd = process.cwd(), resolverOptions = {}) {
|
|
41
|
+
return resolveEcoConfigPath({
|
|
42
|
+
configFile: options.configFile,
|
|
43
|
+
cwd,
|
|
44
|
+
required: false,
|
|
45
|
+
preferEmitted: resolverOptions.preferEmitted,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
|
|
32
49
|
export function buildLaunchEnv(options) {
|
|
33
50
|
const envOverrides = buildEnvOverrides(options);
|
|
34
51
|
const envFileValues = getEnvFilePaths(options.nodeEnv).reduce((env, envFile) => {
|
|
@@ -41,6 +58,16 @@ export function buildLaunchEnv(options) {
|
|
|
41
58
|
};
|
|
42
59
|
}
|
|
43
60
|
|
|
61
|
+
/**
|
|
62
|
+
* Picks the runtime for the app process.
|
|
63
|
+
*
|
|
64
|
+
* @remarks
|
|
65
|
+
* Bun runs the app when the command was launched through Bun (`bun dev`,
|
|
66
|
+
* `bun run dev`, `bunx ecopages`), when the CLI itself runs on Bun, or with
|
|
67
|
+
* `--runtime bun`. Every other launcher gets Node. The user-agent check is
|
|
68
|
+
* needed because Bun honours the CLI's `node` shebang, so the CLI process is
|
|
69
|
+
* Node even when Bun launched it.
|
|
70
|
+
*/
|
|
44
71
|
export function detectRuntime(options = {}) {
|
|
45
72
|
if (options.runtime === 'bun' || options.runtime === 'node') {
|
|
46
73
|
return options.runtime;
|
|
@@ -48,18 +75,14 @@ export function detectRuntime(options = {}) {
|
|
|
48
75
|
|
|
49
76
|
const userAgent = process.env.npm_config_user_agent || '';
|
|
50
77
|
|
|
51
|
-
if (userAgent.startsWith('bun/')) {
|
|
52
|
-
return 'bun';
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
if (typeof Bun !== 'undefined') {
|
|
78
|
+
if (userAgent.startsWith('bun/') || typeof Bun !== 'undefined') {
|
|
56
79
|
return 'bun';
|
|
57
80
|
}
|
|
58
81
|
|
|
59
82
|
return 'node';
|
|
60
83
|
}
|
|
61
84
|
|
|
62
|
-
export function buildBunArgs(args, options, entryFile,
|
|
85
|
+
export function buildBunArgs(args, options, entryFile, configFilePath) {
|
|
63
86
|
const bunArgs = [];
|
|
64
87
|
|
|
65
88
|
if (options.watch) bunArgs.push('--watch');
|
|
@@ -67,8 +90,8 @@ export function buildBunArgs(args, options, entryFile, hasConfig) {
|
|
|
67
90
|
|
|
68
91
|
bunArgs.push('run');
|
|
69
92
|
|
|
70
|
-
if (
|
|
71
|
-
bunArgs.push('--preload',
|
|
93
|
+
if (configFilePath) {
|
|
94
|
+
bunArgs.push('--preload', configFilePath);
|
|
72
95
|
}
|
|
73
96
|
|
|
74
97
|
bunArgs.push(entryFile, ...args);
|
|
@@ -157,6 +180,10 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
|
|
|
157
180
|
const { envOverrides, env } = buildLaunchEnv(resolvedOptions);
|
|
158
181
|
const runtime = detectRuntime(resolvedOptions);
|
|
159
182
|
const resolvedLaunchMode = inferLaunchMode(args, launchMode);
|
|
183
|
+
const isExplicitConfig = Boolean(resolvedOptions.configFile || process.env.ECOPAGES_CONFIG_FILE);
|
|
184
|
+
const resolvedConfigFile = resolveEcoConfigFilePath(resolvedOptions, process.cwd(), {
|
|
185
|
+
preferEmitted: usesProductionBundle(resolvedLaunchMode) && !isExplicitConfig,
|
|
186
|
+
});
|
|
160
187
|
|
|
161
188
|
const distServerApp = resolveProductionServerEntry(process.cwd());
|
|
162
189
|
const shouldUseBundle = usesProductionBundle(resolvedLaunchMode);
|
|
@@ -167,6 +194,12 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
|
|
|
167
194
|
}
|
|
168
195
|
|
|
169
196
|
if (useBundle) {
|
|
197
|
+
assertProductionConfigIdentity(process.cwd(), resolvedConfigFile, { isExplicitOverride: isExplicitConfig });
|
|
198
|
+
const runtimeConfigFile = resolveEmittedEcoConfigPath(process.cwd()) ?? resolvedConfigFile;
|
|
199
|
+
if (runtimeConfigFile) {
|
|
200
|
+
envOverrides.ECOPAGES_CONFIG_FILE = runtimeConfigFile;
|
|
201
|
+
env.ECOPAGES_CONFIG_FILE = runtimeConfigFile;
|
|
202
|
+
}
|
|
170
203
|
if (runtime === 'node') {
|
|
171
204
|
return {
|
|
172
205
|
runtime,
|
|
@@ -187,10 +220,16 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
|
|
|
187
220
|
}
|
|
188
221
|
|
|
189
222
|
if (runtime === 'node') {
|
|
223
|
+
const commandArgs = ['--import', nodeRequirePreload, '--import', tsxLoader];
|
|
224
|
+
if (resolvedOptions.watch) {
|
|
225
|
+
commandArgs.push('--watch');
|
|
226
|
+
}
|
|
227
|
+
commandArgs.push(resolvedEntryFile, ...args);
|
|
228
|
+
|
|
190
229
|
return {
|
|
191
230
|
runtime,
|
|
192
231
|
command: process.execPath,
|
|
193
|
-
commandArgs
|
|
232
|
+
commandArgs,
|
|
194
233
|
envOverrides,
|
|
195
234
|
env,
|
|
196
235
|
};
|
|
@@ -199,7 +238,7 @@ export function createLaunchPlan(args, options, entryFile, launchMode) {
|
|
|
199
238
|
return {
|
|
200
239
|
runtime,
|
|
201
240
|
command: 'bun',
|
|
202
|
-
commandArgs: buildBunArgs(args, resolvedOptions, resolvedEntryFile,
|
|
241
|
+
commandArgs: buildBunArgs(args, resolvedOptions, resolvedEntryFile, resolvedConfigFile),
|
|
203
242
|
envOverrides,
|
|
204
243
|
env,
|
|
205
244
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ecopages",
|
|
3
|
-
"version": "0.2.0
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "CLI utilities for Ecopages",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
},
|
|
37
37
|
"dependencies": {
|
|
38
38
|
"@clack/prompts": "^1.7.0",
|
|
39
|
-
"@ecopages/core": "0.2.0
|
|
39
|
+
"@ecopages/core": "0.2.0",
|
|
40
40
|
"@ecopages/logger": "^0.2.3",
|
|
41
41
|
"giget": "^2.0.0",
|
|
42
42
|
"tsx": "^4.22.3"
|
package/templates.json
CHANGED
|
@@ -21,6 +21,16 @@
|
|
|
21
21
|
"packageDirectory": ".",
|
|
22
22
|
"integrations": ["react"]
|
|
23
23
|
},
|
|
24
|
+
{
|
|
25
|
+
"id": "react-shadcn",
|
|
26
|
+
"displayName": "React shadcn",
|
|
27
|
+
"description": "A React application styled with shadcn/ui on React Aria.",
|
|
28
|
+
"category": "integration",
|
|
29
|
+
"order": 25,
|
|
30
|
+
"source": "react-shadcn",
|
|
31
|
+
"packageDirectory": ".",
|
|
32
|
+
"integrations": ["react"]
|
|
33
|
+
},
|
|
24
34
|
{
|
|
25
35
|
"id": "lit-jsx",
|
|
26
36
|
"displayName": "Lit JSX",
|