@ecopages/react 0.2.0-rc.1 → 0.2.0-rc.2

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
@@ -268,7 +268,7 @@ The fallback exists for backward compatibility. Ecopages logs a debug message wh
268
268
  #### What gets discovered
269
269
 
270
270
  1. Select layout entry files using the mode above.
271
- 2. From each root layout's **`render` client graph** (reachability analysis), follow relative imports and tsconfig path aliases. Type-only imports and `.server.ts` modules are skipped.
271
+ 2. From each root layout's **`render` client graph** (reachability analysis), follow relative imports and tsconfig path aliases. Type-only imports, side-effect-only imports (for example `import "mobx"`), and `.server.ts` modules are skipped.
272
272
  3. Collect npm package roots (for example `@tanstack/react-query`, not `@tanstack/react-query/devtools`).
273
273
  4. Register each discovered package as a shared vendor.
274
274
 
@@ -336,18 +336,48 @@ reactPlugin({
336
336
  });
337
337
  ```
338
338
 
339
- Manual entries **override** auto-discovered entries for the same specifier.
339
+ Manual entries **override** auto-discovered entries for the same specifier. Discovery normalizes package subpaths to package roots; import rewrite matches **exact** specifiers registered in `runtimeModules`.
340
+
341
+ `externals` on a library vendor must already be shared vendors (React, the router bundle, or another `runtimeModules` specifier). Unmapped externals throw at plugin setup instead of emitting a bare specifier the browser cannot resolve.
342
+
343
+ #### Singleton packages (MobX, Redux, Query client, audio engines)
344
+
345
+ Some npm packages must exist as **one browser module** across layout vendors, page chunks, and dev lazy prebundles. React context, MobX observables, Redux stores, TanStack Query clients, and audio runtimes (for example Tone.js) all break when two copies load.
346
+
347
+ Layout auto-discovery only walks `eco.layout()` render graphs. Page-level imports of a singleton that is not registered in `runtimeModules` may be lazily prebundled into a **second** vendor in dev, or inlined into page chunks in production. If a shared library vendor also bundles that singleton internally, you get duplicate instances even though both sides "import the same package name."
348
+
349
+ **Library packaging:** ship singleton deps as `peerDependencies` and keep them external in the library build so `dist/` retains `import … from "mobx"` (or equivalent) instead of inlining a private copy.
350
+
351
+ **Ecopages app config:** register each singleton as its own `runtimeModules` entry and list it in `externals` on any library vendor that imports it:
352
+
353
+ ```ts
354
+ reactPlugin({
355
+ router: ecoRouter(),
356
+ runtimeModules: [
357
+ { specifier: 'mobx', outputName: 'mobx' },
358
+ { specifier: 'mobx-react-lite', outputName: 'mobx-react-lite' },
359
+ {
360
+ specifier: '@acme/store-ui',
361
+ outputName: 'acme-store-ui',
362
+ externals: ['mobx', 'mobx-react-lite', 'react', 'react-dom'],
363
+ },
364
+ ],
365
+ });
366
+ ```
367
+
368
+ Registering only the library vendor, or only the singleton, is not enough when the published library still inlines the singleton. Rebuild vendors (and clear `.eco` / `dist/assets/vendors` in dev) after changing package entry points or `runtimeModules`.
340
369
 
341
370
  #### Troubleshooting
342
371
 
343
- | Symptom | Likely cause | Fix |
344
- | ------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
345
- | `No QueryClient set` after SPA navigation | Provider library bundled per page chunk | Ensure `router` is enabled; add `runtimeProvider: true` on the provider layout; rebuild vendors |
346
- | Duplicate React context / Tone init logs | Provider package is bundled through multiple client entrypoints | Import through the package root and register that root in `runtimeModules` |
347
- | Wrong packages vendored (slow dev startup) | Shell layout scanned as discovery root | Set `runtimeProvider: true` only on provider roots; keep shell layouts unflagged |
348
- | Package not discovered | Layout outside `layouts/` / `components/`, or import not reachable from `render` | Move layout file or add explicit `runtimeModules` entry |
349
- | `@/` alias not followed | Missing or invalid tsconfig paths | Add `compilerOptions.paths`; ensure `include` globs are valid JSON (not broken by comment stripping) |
350
- | Stale bootstrap script hash in dev | Rendered HTML cached before runtime vendors/bootstrap scripts changed | Rebuild or touch a route file; development HTML cache keys include browser-runtime generation |
372
+ | Symptom | Likely cause | Fix |
373
+ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
374
+ | `No QueryClient set` after SPA navigation | Provider library bundled per page chunk | Ensure `router` is enabled; add `runtimeProvider: true` on the provider layout; rebuild vendors |
375
+ | Duplicate React context / Tone init logs | Provider package is bundled through multiple client entrypoints | Import through the package root and register that root in `runtimeModules` |
376
+ | Store updates / `reaction` / `observer` no-op | Duplicate singleton (for example MobX) — layout vendor inlines one copy, page or dev prebundle loads another | Peer the singleton in the library; add explicit `runtimeModules` for it; list it in `externals` on the library vendor; rebuild vendors |
377
+ | Wrong packages vendored (slow dev startup) | Shell layout scanned as discovery root | Set `runtimeProvider: true` only on provider roots; keep shell layouts unflagged |
378
+ | Package not discovered | Layout outside `layouts/` / `components/`, or import not reachable from `render` | Move layout file or add explicit `runtimeModules` entry |
379
+ | `@/` alias not followed | Missing or invalid tsconfig paths | Add `compilerOptions.paths`; ensure `include` globs are valid JSON (not broken by comment stripping) |
380
+ | Stale bootstrap script hash in dev | Rendered HTML cached before runtime vendors/bootstrap scripts changed | Rebuild or touch a route file; development HTML cache keys include browser-runtime generation |
351
381
 
352
382
  #### Tests
353
383
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ecopages/react",
3
- "version": "0.2.0-rc.1",
3
+ "version": "0.2.0-rc.2",
4
4
  "description": "React integration for Ecopages",
5
5
  "keywords": [
6
6
  "ecopages",
@@ -93,16 +93,16 @@
93
93
  "directory": "packages/integrations/react"
94
94
  },
95
95
  "peerDependencies": {
96
- "@ecopages/core": "0.2.0-rc.1",
96
+ "@ecopages/core": "0.2.0-rc.2",
97
97
  "@types/react": "^19",
98
98
  "@types/react-dom": "^19",
99
99
  "react": "^19",
100
100
  "react-dom": "^19"
101
101
  },
102
102
  "dependencies": {
103
- "@ecopages/file-system": "0.2.0-rc.1",
103
+ "@ecopages/file-system": "0.2.0-rc.2",
104
104
  "@ecopages/logger": "^0.2.3",
105
- "@ecopages/mdx": "0.2.0-rc.1",
105
+ "@ecopages/mdx": "0.2.0-rc.2",
106
106
  "@mdx-js/mdx": "^3.1.1",
107
107
  "oxc-parser": "^0.141.0",
108
108
  "oxc-transform": "^0.141.0",
@@ -6,7 +6,6 @@ export type BuildReactRuntimeManifestOptions = {
6
6
  routerImportPath?: string;
7
7
  };
8
8
  export declare const REACT_RUNTIME_SPECIFIERS: readonly ["react", "react-dom", "react/jsx-runtime", "react/jsx-dev-runtime", "react-dom/client"];
9
- export declare function buildReactRuntimeAliasMap(runtimeImports: ReactRuntimeImports): Record<string, string>;
10
9
  export declare function buildConfiguredRuntimeModuleManifestEntries(modules: readonly ResolvedReactPluginRuntimeModule[], getPublicPath: (outputName: string) => string): BrowserRuntimeAssetDeclaration[];
11
10
  export declare function buildReactRuntimeManifest(runtimeImports: ReactRuntimeImports, configuredRuntimeModules?: readonly ResolvedReactPluginRuntimeModule[], getConfiguredRuntimeModulePublicPath?: (outputName: string) => string, options?: BuildReactRuntimeManifestOptions): BrowserRuntimeManifest;
12
11
  export declare function getReactRuntimeExternalSpecifiers(): string[];
@@ -1,4 +1,4 @@
1
- import { createBrowserRuntimeManifest, getBrowserRuntimeSpecifierMap, } from '@ecopages/core/build/browser-runtime-manifest';
1
+ import { createBrowserRuntimeManifest, } from '@ecopages/core/build/browser-runtime-manifest';
2
2
  import { LAYOUT_COMPOSE_PACKAGE } from './bootstrap-package-paths.js';
3
3
  export const REACT_RUNTIME_SPECIFIERS = [
4
4
  'react',
@@ -7,9 +7,6 @@ export const REACT_RUNTIME_SPECIFIERS = [
7
7
  'react/jsx-dev-runtime',
8
8
  'react-dom/client',
9
9
  ];
10
- export function buildReactRuntimeAliasMap(runtimeImports) {
11
- return Object.fromEntries(getBrowserRuntimeSpecifierMap(buildReactRuntimeManifest(runtimeImports)));
12
- }
13
10
  export function buildConfiguredRuntimeModuleManifestEntries(modules, getPublicPath) {
14
11
  return modules.map((module) => ({
15
12
  specifier: module.specifier,
@@ -9,7 +9,7 @@
9
9
  import type { EcoBuildPlugin } from '@ecopages/core/plugins/integration-plugin';
10
10
  import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
11
11
  import type { ReactRouterAdapter } from '../contracts/router-adapter.js';
12
- import type { ResolvedReactPluginRuntimeModule } from './runtime-modules.js';
12
+ import { type ResolvedReactPluginRuntimeModule } from './runtime-modules.js';
13
13
  import { type BrowserRuntimeManifest } from '@ecopages/core/build/browser-runtime-manifest';
14
14
  export type ReactRuntimeImports = {
15
15
  react: string;
@@ -65,6 +65,13 @@ export declare class RuntimeBundleService {
65
65
  getPageLayoutNormalizationDependencies(options?: {
66
66
  modes?: RuntimeMode[];
67
67
  }): AssetDefinition[];
68
- createRuntimeAliasPlugin(mode?: RuntimeMode): EcoBuildPlugin;
68
+ /**
69
+ * Builds the vendor import-rewrite plugin for one runtime asset.
70
+ *
71
+ * @remarks
72
+ * `omitSpecifiers` drops the module being bundled so a self-import cannot
73
+ * rewrite to the file currently being emitted.
74
+ */
75
+ createRuntimeAliasPlugin(mode?: RuntimeMode, omitSpecifiers?: readonly string[]): EcoBuildPlugin;
69
76
  }
70
77
  export {};
@@ -10,8 +10,9 @@ import { createBrowserRuntimePlugin } from '@ecopages/core/build/browser-runtime
10
10
  import { DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME } from '@ecopages/core/build/browser-runtime-plugin';
11
11
  import { buildBrowserRuntimeAssetUrl, createBrowserRuntimeModuleAsset, createBrowserRuntimeScriptAsset, } from '@ecopages/core/services/asset-processing-service';
12
12
  import { createReactDomRuntimeInteropPlugin } from './runtime-interop-plugin.js';
13
- import { buildReactRuntimeAliasMap, buildReactRuntimeManifest, getReactRuntimeExternalSpecifiers, } from './runtime-alias-map.js';
14
- import { createBrowserRuntimeManifest, } from '@ecopages/core/build/browser-runtime-manifest';
13
+ import { buildReactRuntimeManifest, getReactRuntimeExternalSpecifiers } from './runtime-alias-map.js';
14
+ import { assertReactRuntimeModuleExternalsAreVendored, } from './runtime-modules.js';
15
+ import { createBrowserRuntimeManifest, getBrowserRuntimeSpecifierMap, } from '@ecopages/core/build/browser-runtime-manifest';
15
16
  import { LAYOUT_COMPOSE_PACKAGE, PAGE_LAYOUT_NORMALIZATION_PACKAGE } from './bootstrap-package-paths.js';
16
17
  export class RuntimeBundleService {
17
18
  config;
@@ -114,7 +115,7 @@ export class RuntimeBundleService {
114
115
  return runtimeImports;
115
116
  }
116
117
  getRuntimeAliasMap(mode = this.getCurrentRuntimeMode()) {
117
- return buildReactRuntimeAliasMap(this.getRuntimeImports(mode));
118
+ return Object.fromEntries(getBrowserRuntimeSpecifierMap(this.getRuntimeManifest(mode)));
118
119
  }
119
120
  getRuntimeManifest(mode = this.getCurrentRuntimeMode()) {
120
121
  return buildReactRuntimeManifest(this.getRuntimeImports(mode), this.getConfiguredRuntimeModules(), (outputName) => buildBrowserRuntimeAssetUrl(this.getConfiguredRuntimeModuleFileName(outputName, mode)), { routerImportPath: this.config.routerAdapter?.bundle.importPath });
@@ -139,8 +140,7 @@ export class RuntimeBundleService {
139
140
  ]),
140
141
  });
141
142
  const reactDomBundlePlugins = [reactRuntimeAliasPlugin, reactDomRuntimeInteropPlugin].filter((plugin) => plugin !== null);
142
- const runtimeAliasPlugin = this.createRuntimeAliasPlugin(mode);
143
- const mappedSpecifiers = new Set(Object.keys(this.getRuntimeAliasMap(mode)));
143
+ const mappedSpecifiers = new Set(this.getRuntimeManifest(mode).bySpecifier.keys());
144
144
  dependencies.push(createBrowserRuntimeModuleAsset({
145
145
  modules: [
146
146
  { specifier: 'react', defaultExport: true },
@@ -196,11 +196,17 @@ export class RuntimeBundleService {
196
196
  bundleOptions: {
197
197
  define: this.createRuntimeDefines(mode),
198
198
  external: unresolvedExternals,
199
- plugins: [runtimeAliasPlugin],
199
+ plugins: [
200
+ this.createRuntimeAliasPlugin(mode, [
201
+ this.config.routerAdapter.bundle.importPath,
202
+ '@ecopages/react-router',
203
+ ]),
204
+ ],
200
205
  },
201
206
  }));
202
207
  }
203
208
  for (const runtimeModule of this.getConfiguredRuntimeModules()) {
209
+ assertReactRuntimeModuleExternalsAreVendored(runtimeModule, mappedSpecifiers);
204
210
  dependencies.push(createBrowserRuntimeModuleAsset({
205
211
  modules: [{ specifier: runtimeModule.specifier, defaultExport: true }],
206
212
  name: runtimeModule.outputName,
@@ -212,7 +218,7 @@ export class RuntimeBundleService {
212
218
  define: this.createRuntimeDefines(mode),
213
219
  external: this.getRuntimeModuleBundleExternals(runtimeModule, mappedSpecifiers),
214
220
  excludeAppBuildPlugins: [DEFAULT_BROWSER_RUNTIME_PLUGIN_NAME],
215
- plugins: [runtimeAliasPlugin],
221
+ plugins: [this.createRuntimeAliasPlugin(mode, [runtimeModule.specifier])],
216
222
  },
217
223
  }));
218
224
  }
@@ -242,17 +248,22 @@ export class RuntimeBundleService {
242
248
  }
243
249
  return dependencies;
244
250
  }
245
- createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode()) {
246
- const aliasMap = this.getRuntimeAliasMap(mode);
247
- const manifest = createBrowserRuntimeManifest(Object.entries(aliasMap).map(([specifier, publicPath]) => ({
248
- specifier,
249
- owner: '',
250
- importPath: specifier,
251
- publicPath,
252
- })));
251
+ /**
252
+ * Builds the vendor import-rewrite plugin for one runtime asset.
253
+ *
254
+ * @remarks
255
+ * `omitSpecifiers` drops the module being bundled so a self-import cannot
256
+ * rewrite to the file currently being emitted.
257
+ */
258
+ createRuntimeAliasPlugin(mode = this.getCurrentRuntimeMode(), omitSpecifiers = []) {
259
+ const manifest = this.getRuntimeManifest(mode);
260
+ const omitted = new Set(omitSpecifiers);
261
+ const pluginManifest = omitted.size === 0
262
+ ? manifest
263
+ : createBrowserRuntimeManifest(manifest.assets.filter((asset) => !omitted.has(asset.specifier)));
253
264
  return createBrowserRuntimePlugin({
254
265
  name: `react-plugin-runtime-alias-${mode}`,
255
- manifest,
266
+ manifest: pluginManifest,
256
267
  });
257
268
  }
258
269
  }
@@ -6,6 +6,14 @@
6
6
  export type ReactPluginRuntimeModule = string | {
7
7
  specifier: string;
8
8
  outputName?: string;
9
+ /**
10
+ * Packages left unbundled in this vendor chunk.
11
+ *
12
+ * @remarks
13
+ * Each entry must already be a shared vendor — React, the router bundle, or
14
+ * another `runtimeModules` specifier — so import rewrite can emit
15
+ * `/assets/vendors/*.js`. Unmapped externals throw at plugin setup.
16
+ */
9
17
  externals?: string[];
10
18
  };
11
19
  export type ResolvedReactPluginRuntimeModule = {
@@ -27,3 +35,16 @@ export declare function resolveReactPluginRuntimeModules(modules: ReactPluginRun
27
35
  * @remarks Manual entries win when both sources declare the same specifier.
28
36
  */
29
37
  export declare function mergeReactPluginRuntimeModules(manualModules: ResolvedReactPluginRuntimeModule[], autoSpecifiers: string[]): ResolvedReactPluginRuntimeModule[];
38
+ /**
39
+ * Thrown when a `runtimeModules` entry lists an `externals` specifier that is
40
+ * not a shared browser vendor.
41
+ */
42
+ export declare class UnmappedReactRuntimeModuleExternalError extends Error {
43
+ readonly moduleSpecifier: string;
44
+ readonly unmappedExternals: string[];
45
+ constructor(moduleSpecifier: string, unmappedExternals: string[]);
46
+ }
47
+ /**
48
+ * Ensures every `externals` specifier on a runtime module is already a vendor.
49
+ */
50
+ export declare function assertReactRuntimeModuleExternalsAreVendored(module: ResolvedReactPluginRuntimeModule, vendoredSpecifiers: ReadonlySet<string>): void;
@@ -47,3 +47,28 @@ export function mergeReactPluginRuntimeModules(manualModules, autoSpecifiers) {
47
47
  }
48
48
  return [...merged.values()];
49
49
  }
50
+ /**
51
+ * Thrown when a `runtimeModules` entry lists an `externals` specifier that is
52
+ * not a shared browser vendor.
53
+ */
54
+ export class UnmappedReactRuntimeModuleExternalError extends Error {
55
+ moduleSpecifier;
56
+ unmappedExternals;
57
+ constructor(moduleSpecifier, unmappedExternals) {
58
+ super(`reactPlugin runtimeModules entry "${moduleSpecifier}" lists externals that are not shared vendors: ${unmappedExternals.join(', ')}. ` +
59
+ 'Register each as its own runtimeModules entry (React and the router bundle are already vendored) so browser imports rewrite to /assets/vendors/*.js.');
60
+ this.name = 'UnmappedReactRuntimeModuleExternalError';
61
+ this.moduleSpecifier = moduleSpecifier;
62
+ this.unmappedExternals = unmappedExternals;
63
+ }
64
+ }
65
+ /**
66
+ * Ensures every `externals` specifier on a runtime module is already a vendor.
67
+ */
68
+ export function assertReactRuntimeModuleExternalsAreVendored(module, vendoredSpecifiers) {
69
+ const unmappedExternals = module.externals.filter((external) => !vendoredSpecifiers.has(external));
70
+ if (unmappedExternals.length === 0) {
71
+ return;
72
+ }
73
+ throw new UnmappedReactRuntimeModuleExternalError(module.specifier, unmappedExternals);
74
+ }
@@ -89,6 +89,11 @@ export type ReactPluginOptions = {
89
89
  * `query-provider.tsx` or modules using `QueryClientProvider` / `createContext`).
90
90
  * It does not vendor every npm dependency reachable from shell or page UI.
91
91
  *
92
+ * Singleton libraries (MobX, Redux, TanStack Query, audio engines) must be
93
+ * peer dependencies in shared state/UI packages and registered here explicitly
94
+ * when page code imports them outside the layout graph. List each singleton in
95
+ * `externals` on library vendors that import it so one shared vendor URL is used.
96
+ *
92
97
  * Layouts that mount shared runtime state should set `runtimeProvider: true` in
93
98
  * `eco.layout({ ... })`. Flagged layouts become the only discovery roots and
94
99
  * vendor every reachable npm package in that layout graph. When no layout opts
@@ -108,8 +113,12 @@ export type ReactPluginOptions = {
108
113
  * ```
109
114
  *
110
115
  * Manual entries override auto-discovered entries for the same specifier.
111
- * Subpath imports such as `@acme/ui/button` dedupe to the registered package
112
- * root vendor URL when `@acme/ui` is configured here or auto-discovered.
116
+ * Discovery normalizes package subpaths to package roots when collecting
117
+ * vendors. Import rewrite matches exact specifiers only — register subpaths
118
+ * separately in `runtimeModules` when page code imports them directly.
119
+ *
120
+ * `externals` on a library vendor must already be shared vendors (React, the
121
+ * router, or another `runtimeModules` specifier). Unmapped externals throw.
113
122
  *
114
123
  * @example Advanced vendor config
115
124
  * ```ts