ecopages 0.4.0 → 0.6.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
@@ -32,14 +32,14 @@ The commands above run on Node. Bun is optional: launch them through Bun (`bunx
32
32
  | `ecopages dev` | Starts the dev server (supervises config/.env restarts) | `[entry] --dev` through tsx on Node, `bun run [entry] --dev` on Bun |
33
33
  | `ecopages dev:watch` | Dev server + hard restarts on file changes | Node: `node --watch …`; Bun: `bun --watch run [entry] --dev` |
34
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 |
35
+ | `ecopages start` | Starts the production server from the built output | Runs the emitted server bundle and imports `dist/server/` modules |
36
36
  | `ecopages preview` | Previews the production build locally | `[entry] --preview` through tsx on Node, `bun run [entry] --preview` |
37
37
  | `ecopages types` | Writes virtual-module types for `tsc`, then exits | Loads `eco.config.ts` and sets processors up; the entry does not run |
38
38
 
39
39
  > [!NOTE]
40
40
  > The entry file defaults to `app.ts`. Override it with `--entry-file`.
41
41
 
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 or have endpoint files 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.
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 output 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. Pages, Layouts, Html shells, Endpoints, `app.static` views, error pages, and `ssr: true` scripts load from `server/server-modules.json`; a missing entry names the source file and says to run `ecopages build`. Only apps that register API or WebSocket handlers or have endpoint files build a server bundle. Public files are in the sibling `client/` directory. For a static-only app, `start` reports that the build has no server bundle when `client/` holds built HTML; serve that output with `ecopages preview` or deploy `<distDir>/client/` to a static host. Pass `--dist-dir <dir>` to select an output root, 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
43
 
44
44
  ### Templates
45
45
 
@@ -67,19 +67,19 @@ Server and build commands accept the following shared options. They automaticall
67
67
 
68
68
  Boolean environment settings accept `true` or `1` to enable, and `false` or `0` to disable.
69
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. |
70
+ | Environment variable | Description |
71
+ | :------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
72
+ | `ECOPAGES_CONFIG_FILE` | Config path, equivalent to `--config`. |
73
+ | `ECOPAGES_PREVIEW_SERVE_ONLY` | For `ecopages preview`, serve existing `client/` 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` | During `ecopages build`, skip emitting `dist/server/server-modules.json`; the bench oracle uses this for per-Page compilation. `ecopages start` always requires and loads the emitted map, regardless of this variable. |
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. |
83
83
 
84
84
  ### Runtime Detection
85
85
 
package/bin/cli.js CHANGED
@@ -390,7 +390,7 @@ const SERVER_COMMANDS = {
390
390
  optionOverrides: { nodeEnv: 'production' },
391
391
  },
392
392
  preview: {
393
- description: 'Build the project for production, then serve dist locally to preview it.',
393
+ description: 'Build the project for production, then serve dist/client locally to preview it.',
394
394
  entryArgs: ['--preview'],
395
395
  optionOverrides: { nodeEnv: 'production' },
396
396
  },
@@ -1,4 +1,5 @@
1
1
  import path from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
2
3
  import { parseEnv } from 'node:util';
3
4
  import { fileSystem } from '@ecopages/file-system';
4
5
  import {
@@ -12,6 +13,8 @@ import { ECOPAGES_ENTRY_WATCH_ENV, getDevEnvFileNames, getEcopagesEnv } from '@e
12
13
 
13
14
  const nodeRequirePreload = import.meta.resolve('./node-require-preload.js');
14
15
  const tsxLoader = import.meta.resolve('tsx/esm');
16
+ const viewReferencePreload = import.meta.resolve('./view-reference-preload.js');
17
+ const viewReferencePreloadPath = fileURLToPath(viewReferencePreload);
15
18
 
16
19
  function getEnvFilePaths(nodeEnv) {
17
20
  return getDevEnvFileNames(nodeEnv).filter((envFile) => fileSystem.exists(envFile));
@@ -110,7 +113,7 @@ function inferLaunchMode(args, launchMode) {
110
113
  *
111
114
  * In `start` mode, the server bundle of one build output directory is used
112
115
  * directly: `options.distDir` names it, otherwise the only directory below the
113
- * working directory that holds `.server/manifest.json`. A missing or ambiguous
116
+ * working directory that holds `server/manifest.json`. A missing or ambiguous
114
117
  * bundle throws an error that says how to fix it.
115
118
  *
116
119
  * In `build`, `dev`, `preview`, and `types` modes, the source entry file is executed via tsx
@@ -129,6 +132,8 @@ export async function createLaunchPlan(args, options, entryFile, launchMode) {
129
132
  const resolvedOptions = options ?? {};
130
133
  const resolvedEntryFile = entryFile ?? 'app.ts';
131
134
  const { envOverrides, env } = buildLaunchEnv(resolvedOptions);
135
+ envOverrides.ECOPAGES_ENTRY_FILE = resolvedEntryFile;
136
+ env.ECOPAGES_ENTRY_FILE = resolvedEntryFile;
132
137
  const runtime = detectRuntime(resolvedOptions);
133
138
  const resolvedLaunchMode = inferLaunchMode(args, launchMode);
134
139
  const shouldUseBundle = usesProductionBundle(resolvedLaunchMode);
@@ -148,11 +153,10 @@ export async function createLaunchPlan(args, options, entryFile, launchMode) {
148
153
  `Production server entry not found in ${path.relative(process.cwd(), distDir) || '.'}. Run \`ecopages build\` again.`,
149
154
  );
150
155
  }
151
- assertProductionConfigIdentity(process.cwd(), resolvedConfigFile, {
152
- isExplicitOverride: isExplicitConfig,
156
+ const runtimeConfigFile = resolveEmittedEcoConfigPath(process.cwd(), distDir) ?? resolvedConfigFile;
157
+ assertProductionConfigIdentity(process.cwd(), runtimeConfigFile, {
153
158
  distDir,
154
159
  });
155
- const runtimeConfigFile = resolveEmittedEcoConfigPath(process.cwd(), distDir) ?? resolvedConfigFile;
156
160
  if (runtimeConfigFile) {
157
161
  envOverrides.ECOPAGES_CONFIG_FILE = runtimeConfigFile;
158
162
  env.ECOPAGES_CONFIG_FILE = runtimeConfigFile;
@@ -177,7 +181,7 @@ export async function createLaunchPlan(args, options, entryFile, launchMode) {
177
181
  }
178
182
 
179
183
  if (runtime === 'node') {
180
- const commandArgs = ['--import', nodeRequirePreload, '--import', tsxLoader];
184
+ const commandArgs = ['--import', nodeRequirePreload, '--import', tsxLoader, '--import', viewReferencePreload];
181
185
  if (resolvedOptions.watch) {
182
186
  commandArgs.push('--watch');
183
187
  }
@@ -196,7 +200,7 @@ export async function createLaunchPlan(args, options, entryFile, launchMode) {
196
200
  if (resolvedOptions.watch) {
197
201
  commandArgs.push('--watch');
198
202
  }
199
- commandArgs.push('run', resolvedEntryFile, ...args);
203
+ commandArgs.push('run', '--preload', viewReferencePreloadPath, resolvedEntryFile, ...args);
200
204
 
201
205
  return {
202
206
  runtime,
@@ -0,0 +1,130 @@
1
+ import path from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { loadEcoPagesUserConfig } from '@ecopages/core/config';
4
+ import {
5
+ collectViewIntegrations,
6
+ findViewOwner,
7
+ isExemptFromViewReference,
8
+ viewExtensionFilter,
9
+ viewReferenceModuleSource,
10
+ } from '@ecopages/core/view-reference';
11
+
12
+ const IMPORTED_VIEW_NAMESPACE = 'ecopages-imported-view';
13
+
14
+ async function loadViewRewriteContext() {
15
+ try {
16
+ const { config } = await loadEcoPagesUserConfig();
17
+ return {
18
+ integrations: collectViewIntegrations(config.integrations ?? []),
19
+ appRoot: config.rootDir ?? process.cwd(),
20
+ };
21
+ } catch {
22
+ return {
23
+ integrations: collectViewIntegrations([]),
24
+ appRoot: process.cwd(),
25
+ };
26
+ }
27
+ }
28
+
29
+ function resolvePreloadEntryPath() {
30
+ const fromEnv = process.env.ECOPAGES_ENTRY_FILE;
31
+ if (fromEnv) {
32
+ return path.resolve(fromEnv);
33
+ }
34
+ const bunMain = globalThis.Bun?.main;
35
+ if (typeof bunMain === 'string' && bunMain.length > 0) {
36
+ return bunMain;
37
+ }
38
+ return path.resolve('app.ts');
39
+ }
40
+
41
+ function importerFilePath(importer) {
42
+ if (!importer || typeof importer !== 'string') {
43
+ return null;
44
+ }
45
+ if (importer.startsWith('file:')) {
46
+ try {
47
+ return fileURLToPath(importer);
48
+ } catch {
49
+ return null;
50
+ }
51
+ }
52
+ return importer;
53
+ }
54
+
55
+ function resolveImportedPath(specifier, importer, appRoot) {
56
+ if (path.isAbsolute(specifier)) {
57
+ return specifier;
58
+ }
59
+ const importerPath = importerFilePath(importer);
60
+ const fromDir = importerPath ? path.dirname(importerPath) : appRoot;
61
+ return path.resolve(fromDir, specifier);
62
+ }
63
+
64
+ function viewOwnerToRewrite(filePath, entryPath, appRoot) {
65
+ if (isExemptFromViewReference(filePath, { entryPath, appRoot })) {
66
+ return undefined;
67
+ }
68
+ return findViewOwner(integrations, filePath);
69
+ }
70
+
71
+ function viewModuleLoadResult(filePath, integrationName) {
72
+ return {
73
+ format: 'module',
74
+ source: viewReferenceModuleSource(filePath, integrationName),
75
+ shortCircuit: true,
76
+ };
77
+ }
78
+
79
+ const { integrations, appRoot } = await loadViewRewriteContext();
80
+ const entryPath = resolvePreloadEntryPath();
81
+
82
+ if (process.versions.bun) {
83
+ const bun = globalThis.Bun;
84
+ const extensions = [...new Set(integrations.flatMap((integration) => [...integration.extensions]))];
85
+ if (typeof bun?.plugin === 'function' && extensions.length > 0) {
86
+ bun.plugin({
87
+ name: 'ecopages-imported-views',
88
+ setup(builder) {
89
+ builder.onResolve({ filter: viewExtensionFilter(extensions) }, (args) => {
90
+ const filePath = resolveImportedPath(args.path, args.importer, appRoot);
91
+ const owner = viewOwnerToRewrite(filePath, entryPath, appRoot);
92
+ if (!owner) {
93
+ return undefined;
94
+ }
95
+ return { path: filePath, namespace: IMPORTED_VIEW_NAMESPACE };
96
+ });
97
+ builder.onLoad({ filter: /.*/, namespace: IMPORTED_VIEW_NAMESPACE }, (args) => {
98
+ const owner = findViewOwner(integrations, args.path);
99
+ return {
100
+ contents: viewReferenceModuleSource(args.path, owner?.name),
101
+ loader: 'js',
102
+ };
103
+ });
104
+ },
105
+ });
106
+ }
107
+ } else {
108
+ const { registerHooks } = await import('node:module');
109
+ registerHooks({
110
+ load(url, context, nextLoad) {
111
+ if (!url.startsWith('file:')) {
112
+ return nextLoad(url, context);
113
+ }
114
+
115
+ let filePath;
116
+ try {
117
+ filePath = fileURLToPath(url);
118
+ } catch {
119
+ return nextLoad(url, context);
120
+ }
121
+
122
+ const owner = viewOwnerToRewrite(filePath, entryPath, appRoot);
123
+ if (!owner) {
124
+ return nextLoad(url, context);
125
+ }
126
+
127
+ return viewModuleLoadResult(filePath, owner.name);
128
+ },
129
+ });
130
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ecopages",
3
- "version": "0.4.0",
3
+ "version": "0.6.0",
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.4.0",
40
- "@ecopages/file-system": "0.4.0",
39
+ "@ecopages/core": "0.6.0",
40
+ "@ecopages/file-system": "0.6.0",
41
41
  "@ecopages/logger": "^0.2.3",
42
42
  "giget": "^2.0.0",
43
43
  "tsx": "^4.22.3"