@eserstack/laroux-bundler 0.0.0-stage → 5.0.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.
Files changed (103) hide show
  1. package/LICENSE +13 -0
  2. package/README.md +431 -2
  3. package/dist/adapters/fonts/font-optimizer.d.ts +28 -0
  4. package/dist/adapters/fonts/font-optimizer.js +74 -0
  5. package/dist/adapters/fonts/index.d.ts +18 -0
  6. package/dist/adapters/fonts/index.js +78 -0
  7. package/dist/adapters/fonts/mod.d.ts +6 -0
  8. package/dist/adapters/fonts/mod.js +7 -0
  9. package/dist/adapters/lightningcss/css-processor.d.ts +39 -0
  10. package/dist/adapters/lightningcss/css-processor.js +103 -0
  11. package/dist/adapters/lightningcss/mod.d.ts +5 -0
  12. package/dist/adapters/lightningcss/mod.js +6 -0
  13. package/dist/adapters/mod.d.ts +13 -0
  14. package/dist/adapters/mod.js +21 -0
  15. package/dist/adapters/prebuilt-bundler/mod.d.ts +5 -0
  16. package/dist/adapters/prebuilt-bundler/mod.js +6 -0
  17. package/dist/adapters/prebuilt-bundler/prebuilt-bundler.d.ts +22 -0
  18. package/dist/adapters/prebuilt-bundler/prebuilt-bundler.js +60 -0
  19. package/dist/adapters/react/mod.d.ts +10 -0
  20. package/dist/adapters/react/mod.js +16 -0
  21. package/dist/adapters/react/plugin.d.ts +17 -0
  22. package/dist/adapters/react/plugin.js +62 -0
  23. package/dist/adapters/react/rsc-analyze.d.ts +29 -0
  24. package/dist/adapters/react/rsc-analyze.js +116 -0
  25. package/dist/adapters/react/rsc-client-entry.d.ts +26 -0
  26. package/dist/adapters/react/rsc-client-entry.js +145 -0
  27. package/dist/adapters/react/rsc-module-map.d.ts +41 -0
  28. package/dist/adapters/react/rsc-module-map.js +81 -0
  29. package/dist/adapters/react/rsc-rewrite-imports.d.ts +38 -0
  30. package/dist/adapters/react/rsc-rewrite-imports.js +409 -0
  31. package/dist/adapters/react/rsc-transform.d.ts +26 -0
  32. package/dist/adapters/react/rsc-transform.js +101 -0
  33. package/dist/adapters/runtime-bundler/mod.d.ts +6 -0
  34. package/dist/adapters/runtime-bundler/mod.js +6 -0
  35. package/dist/adapters/runtime-bundler/runtime-bundler.d.ts +85 -0
  36. package/dist/adapters/runtime-bundler/runtime-bundler.js +244 -0
  37. package/dist/adapters/sharp/image-optimizer.d.ts +52 -0
  38. package/dist/adapters/sharp/image-optimizer.js +261 -0
  39. package/dist/adapters/sharp/mod.d.ts +6 -0
  40. package/dist/adapters/sharp/mod.js +6 -0
  41. package/dist/adapters/tailwindcss/compile.d.ts +22 -0
  42. package/dist/adapters/tailwindcss/compile.js +29 -0
  43. package/dist/adapters/tailwindcss/critical-css-config.d.ts +46 -0
  44. package/dist/adapters/tailwindcss/critical-css-config.js +78 -0
  45. package/dist/adapters/tailwindcss/critical-page-css.d.ts +61 -0
  46. package/dist/adapters/tailwindcss/critical-page-css.js +431 -0
  47. package/dist/adapters/tailwindcss/critical-universal-css.d.ts +68 -0
  48. package/dist/adapters/tailwindcss/critical-universal-css.js +250 -0
  49. package/dist/adapters/tailwindcss/mod.d.ts +10 -0
  50. package/dist/adapters/tailwindcss/mod.js +11 -0
  51. package/dist/adapters/tailwindcss/plugin.d.ts +16 -0
  52. package/dist/adapters/tailwindcss/plugin.js +107 -0
  53. package/dist/adapters/tailwindcss/stylesheet-loader.d.ts +15 -0
  54. package/dist/adapters/tailwindcss/stylesheet-loader.js +83 -0
  55. package/dist/config.d.ts +27 -0
  56. package/dist/config.js +31 -0
  57. package/dist/css-modules.d.ts +49 -0
  58. package/dist/css-modules.js +146 -0
  59. package/dist/domain/build-cache.d.ts +107 -0
  60. package/dist/domain/build-cache.js +128 -0
  61. package/dist/domain/build-validator.d.ts +68 -0
  62. package/dist/domain/build-validator.js +207 -0
  63. package/dist/domain/bundler.d.ts +136 -0
  64. package/dist/domain/bundler.js +225 -0
  65. package/dist/domain/chunk-manifest.d.ts +40 -0
  66. package/dist/domain/chunk-manifest.js +188 -0
  67. package/dist/domain/client-action-stub.d.ts +30 -0
  68. package/dist/domain/client-action-stub.js +167 -0
  69. package/dist/domain/copy-path.d.ts +15 -0
  70. package/dist/domain/copy-path.js +29 -0
  71. package/dist/domain/css-plugin.d.ts +91 -0
  72. package/dist/domain/css-plugin.js +6 -0
  73. package/dist/domain/css-processor.d.ts +57 -0
  74. package/dist/domain/css-processor.js +33 -0
  75. package/dist/domain/font-optimizer.d.ts +46 -0
  76. package/dist/domain/font-optimizer.js +17 -0
  77. package/dist/domain/framework-plugin.d.ts +106 -0
  78. package/dist/domain/framework-plugin.js +20 -0
  79. package/dist/domain/image-optimizer.d.ts +74 -0
  80. package/dist/domain/image-optimizer.js +16 -0
  81. package/dist/domain/import-map.d.ts +90 -0
  82. package/dist/domain/import-map.js +187 -0
  83. package/dist/domain/mod.d.ts +32 -0
  84. package/dist/domain/mod.js +20 -0
  85. package/dist/domain/route-generator.d.ts +34 -0
  86. package/dist/domain/route-generator.js +305 -0
  87. package/dist/domain/route-scanner.d.ts +72 -0
  88. package/dist/domain/route-scanner.js +282 -0
  89. package/dist/domain/server-action-transform.d.ts +28 -0
  90. package/dist/domain/server-action-transform.js +147 -0
  91. package/dist/domain/virtual-source.d.ts +63 -0
  92. package/dist/domain/virtual-source.js +238 -0
  93. package/dist/import-map-resolver-plugin.d.ts +47 -0
  94. package/dist/import-map-resolver-plugin.js +109 -0
  95. package/dist/mod.d.ts +57 -0
  96. package/dist/mod.js +56 -0
  97. package/dist/server-externals-plugin.d.ts +29 -0
  98. package/dist/server-externals-plugin.js +63 -0
  99. package/dist/system.d.ts +157 -0
  100. package/dist/system.js +1401 -0
  101. package/dist/types.d.ts +60 -0
  102. package/dist/types.js +38 -0
  103. package/package.json +83 -3
package/LICENSE ADDED
@@ -0,0 +1,13 @@
1
+ Copyright 2023-present Eser Ozvataf and other contributors.
2
+
3
+ Licensed under the Apache License, Version 2.0 (the "License");
4
+ you may not use this file except in compliance with the License.
5
+ You may obtain a copy of the License at
6
+
7
+ http://www.apache.org/licenses/LICENSE-2.0
8
+
9
+ Unless required by applicable law or agreed to in writing, software
10
+ distributed under the License is distributed on an "AS IS" BASIS,
11
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ See the License for the specific language governing permissions and
13
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,432 @@
1
- # Temporary Holding Version
1
+ # 🏗️ [@eserstack/laroux-bundler](./)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Note:** JSR is frozen at 4.5.x. From 5.0.0, `@eserstack/laroux-bundler` is
4
+ > published on npm under the same name (`pnpm add @eserstack/laroux-bundler`);
5
+ > the JSR versions stay available but get no updates.
6
+
7
+ > **eserstack Product-Candidate** — build pipeline for laroux ·
8
+ > [eser/stack](https://github.com/eser/stack) **Install:**
9
+ > `pnpm add @eserstack/laroux-bundler`
10
+
11
+ Build system and bundler for [laroux.js](https://github.com/eser/stack), a React
12
+ Server Components framework. It turns the `src/` directory of a laroux app into
13
+ `dist/client/` (browser bundles, styles, fonts and images) and `dist/server/`
14
+ (server components, routes and server actions), as a one-off build or in watch
15
+ mode. The core is framework-agnostic: the framework (React) and the CSS tooling
16
+ (Tailwind CSS) are adapters that you import and pass to the build.
17
+
18
+ ## Overview
19
+
20
+ This package provides the build system for laroux.js:
21
+
22
+ - File-based routes: pages, layouts, API routes and proxies under
23
+ `src/app/routes`
24
+ - Transform pipeline: TypeScript and JSX, `"use client"` components turned into
25
+ client references, server component imports rewritten to point at them, and
26
+ `"use server"` actions marked for React
27
+ - Module map: client component discovery and the mapping React uses to resolve
28
+ them
29
+ - Chunk manifest: code splitting and lazy loading per client component
30
+ - Client entry with the laroux-react bootstrap: HMR client and the
31
+ development-mode error overlay
32
+ - CSS processing: Tailwind CSS v4, Lightning CSS, CSS modules and critical CSS
33
+ extraction
34
+ - Import resolution: bare specifiers stay as written and resolve from the app's
35
+ `node_modules`, with browser shims for server-only packages
36
+ - Font self-hosting for Google Fonts and image optimization with sharp
37
+ - Client and server bundles on Rolldown
38
+ - Runtime bundler that bundles in memory during development, and prebuilt
39
+ bundler that serves the output of a build
40
+
41
+ ## Installation
42
+
43
+ ```bash
44
+ pnpm add @eserstack/laroux-bundler
45
+ ```
46
+
47
+ ## Quick Start
48
+
49
+ Build a laroux app once. The project needs `src/app/routes/` and, for Tailwind,
50
+ `src/app/styles/global.css`. The default values for images, browser shims and
51
+ server externals come from `@eserstack/laroux`.
52
+
53
+ ```typescript
54
+ import * as laroux from "@eserstack/laroux";
55
+ import * as larouxBundler from "@eserstack/laroux-bundler";
56
+ import * as react from "@eserstack/laroux-bundler/adapters/react";
57
+ import * as tailwindcss from "@eserstack/laroux-bundler/adapters/tailwindcss";
58
+ import { runtime } from "@eserstack/standards/cross-runtime";
59
+
60
+ const projectRoot = runtime.process.cwd();
61
+ const config: larouxBundler.BuildConfig = {
62
+ projectRoot,
63
+ srcDir: runtime.path.resolve(projectRoot, "src"),
64
+ distDir: runtime.path.resolve(projectRoot, "dist"),
65
+ logLevel: "info",
66
+ fonts: [],
67
+ images: laroux.DEFAULT_IMAGES,
68
+ cssModuleTypes: false,
69
+ noCssModuleAutoReference: false,
70
+ browserShims: laroux.DEFAULT_BROWSER_SHIMS,
71
+ serverExternals: laroux.DEFAULT_SERVER_EXTERNALS,
72
+ };
73
+
74
+ const context = larouxBundler.createBuildContext(config, {
75
+ framework: react.reactPlugin,
76
+ css: tailwindcss.createTailwindPlugin(),
77
+ bundlerBackend: "rolldown",
78
+ });
79
+
80
+ const result = await larouxBundler.build(context);
81
+ ```
82
+
83
+ `build()` logs a failure and returns `success: false` instead of throwing, so
84
+ check `result.success` before serving the output. A failed build still removes
85
+ the copy of the source it bundles from (`dist/_bundle_src`).
86
+
87
+ This build compiles `global.css` with Tailwind but leaves out the stylesheet,
88
+ font and image adapters: a stylesheet Tailwind does not compile is written
89
+ unchanged, no fonts are self-hosted and images are served as they are. The
90
+ [Adapters](#adapters) section shows how to pass them.
91
+
92
+ ## Usage
93
+
94
+ The examples in this section continue the Quick Start and reuse its imports,
95
+ `config`, `context` and `result`.
96
+
97
+ ### Building Only When Needed
98
+
99
+ `ensureBuildIsReady()` runs `build()` only when the output is stale, and
100
+ otherwise returns the existing build: its build id, timestamp, module map and
101
+ client bundle, with a `duration` of 0. The output is stale when
102
+ `dist/client/manifest.json` is missing or when a build input changed after the
103
+ timestamp in it. The inputs are every file under the source directory and
104
+ `public/` at any depth (except `node_modules` and hidden entries), plus
105
+ `laroux.config.ts` and `package.json`. `build()`
106
+ writes the chunk manifest as its last step, so a build that failed halfway
107
+ leaves none behind and the next call builds again:
108
+
109
+ ```typescript
110
+ const ready = await larouxBundler.ensureBuildIsReady(context);
111
+
112
+ if (ready.duration === 0) {
113
+ console.log(`Reusing the build from ${new Date(ready.timestamp)}`);
114
+ }
115
+ ```
116
+
117
+ ### Watch Mode
118
+
119
+ `watch()` rebuilds when a `.ts`, `.tsx`, `.js`, `.jsx` or `.css` file under the
120
+ source directory changes. It waits 50 ms to batch the changes of one save, runs
121
+ one build at a time, and passes each result with its changed files to your
122
+ callback, failed builds included. When the callback returns a promise, the next
123
+ rebuild waits for it, so the callback can load the rebuilt output before `dist/`
124
+ changes again. A failed build keeps its changed files, so the next save rebuilds
125
+ them too. Each watcher keeps its own `BuildCache` of client component analyses,
126
+ CSS module results and route scans, unless `context.cache` holds one to share.
127
+
128
+ A change to CSS files alone rebuilds only the stylesheets, and writes them as a
129
+ full build does: `styles.css` from the global stylesheet followed by the CSS
130
+ module styles, then the critical, deferred and universal CSS derived from it.
131
+ The JavaScript in `dist/` stays, so the result reports the build id of the build
132
+ before it. A change to scripts alone keeps `styles.css` and skips the global
133
+ stylesheet, but still compiles the CSS modules, because the bundles import their
134
+ class names.
135
+
136
+ Each result carries the `buildId` of the code in `dist/`. The generated routes
137
+ file imports every page and layout with it as a query, `page.js?v=` and the id,
138
+ so a server that imports the routes file under a new build id gets the rebuilt
139
+ pages instead of the ones the runtime cached by URL; laroux dev loads each
140
+ rebuild this way.
141
+
142
+ ```typescript
143
+ let lastGoodBuild = result;
144
+
145
+ const watcher = larouxBundler.watch(context, (rebuilt) => {
146
+ if (rebuilt.success) {
147
+ lastGoodBuild = rebuilt;
148
+ console.log(`Serving build ${rebuilt.buildId}`);
149
+ }
150
+ });
151
+
152
+ // Stop watching
153
+ watcher.close();
154
+ ```
155
+
156
+ ### Serving Bundles
157
+
158
+ The server reads bundles through the `Bundler` interface, whose `getBundle()`
159
+ returns the client code, the module map, the chunk manifest and the entrypoint
160
+ URL.
161
+
162
+ `PrebuiltBundler` serves the output of `build()`. It reads
163
+ `dist/client/manifest.json` and `dist/client/module-map.json`, and its client
164
+ code is `null` because the server serves the built files as static assets:
165
+
166
+ ```typescript
167
+ import * as prebuilt from "@eserstack/laroux-bundler/adapters/prebuilt-bundler";
168
+
169
+ const bundler = new prebuilt.PrebuiltBundler({ distDir: config.distDir });
170
+ const bundle = await bundler.getBundle();
171
+
172
+ // Reload the manifest after a rebuild
173
+ await bundler.reload();
174
+ ```
175
+
176
+ `RuntimeBundler` bundles in memory for development, with no `dist/`. It uses
177
+ `DEVELOPMENT_SETTINGS` (unminified, one bundle), caches the result for one
178
+ second, and its entrypoint is `/__runtime_bundle.js`, with HMR enabled in its
179
+ chunk manifest. It bundles with rolldown and applies `browserShims` like a
180
+ production build; without the option it uses `laroux.DEFAULT_BROWSER_SHIMS`:
181
+
182
+ ```typescript
183
+ import * as runtimeBundler from "@eserstack/laroux-bundler/adapters/runtime-bundler";
184
+
185
+ const devBundler = new runtimeBundler.RuntimeBundler({
186
+ srcDir: config.srcDir,
187
+ projectRoot: config.projectRoot,
188
+ plugin: react.reactPlugin,
189
+ browserShims: config.browserShims,
190
+ });
191
+
192
+ const devBundle = await devBundler.getBundle();
193
+
194
+ // After a change
195
+ await devBundler.rebuild();
196
+ ```
197
+
198
+ ### Adapters
199
+
200
+ Each adapter has its own entry point, and the build uses only the adapters you
201
+ pass to `createBuildContext()`. This is the set `eser laroux build` passes:
202
+
203
+ ```typescript
204
+ import * as fonts from "@eserstack/laroux-bundler/adapters/fonts";
205
+ import * as lightningcss from "@eserstack/laroux-bundler/adapters/lightningcss";
206
+ import * as sharp from "@eserstack/laroux-bundler/adapters/sharp";
207
+
208
+ const fullContext = larouxBundler.createBuildContext(config, {
209
+ framework: react.reactPlugin,
210
+ css: tailwindcss.createTailwindPlugin(),
211
+ cssProcessor: lightningcss.lightningCssProcessor,
212
+ fontOptimizer: fonts.googleFontOptimizer,
213
+ imageOptimizer: sharp.sharpImageOptimizer,
214
+ bundlerBackend: "rolldown",
215
+ });
216
+
217
+ const fullResult = await larouxBundler.build(fullContext);
218
+ ```
219
+
220
+ | Entry point | Provides |
221
+ | ----------------------------------------------------- | -------------------------------------------------------------------------- |
222
+ | `@eserstack/laroux-bundler/adapters/react` | `reactPlugin`, the React Server Components framework plugin |
223
+ | `@eserstack/laroux-bundler/adapters/tailwindcss` | `createTailwindPlugin()`, Tailwind CSS v4 and critical CSS |
224
+ | `@eserstack/laroux-bundler/adapters/lightningcss` | `lightningCssProcessor`, Lightning CSS lowering and minification |
225
+ | `@eserstack/laroux-bundler/adapters/sharp` | `sharpImageOptimizer`, WebP, AVIF, responsive widths and blur placeholders |
226
+ | `@eserstack/laroux-bundler/adapters/fonts` | `googleFontOptimizer`, self-hosted Google Fonts |
227
+ | `@eserstack/laroux-bundler/adapters/runtime-bundler` | `RuntimeBundler`, in-memory development bundles |
228
+ | `@eserstack/laroux-bundler/adapters/prebuilt-bundler` | `PrebuiltBundler`, bundles read from `dist/` |
229
+
230
+ The Lightning CSS, sharp and fonts entry points also export the functions their
231
+ adapters are built on (`processCss()`, `optimizeImages()` and
232
+ `optimizeGoogleFonts()`) for use outside a build.
233
+
234
+ Each port has a no-op default for the adapter you leave out:
235
+
236
+ | Option | Port | Without it |
237
+ | ---------------- | ----------------- | ------------------------------------------------------------------------------- |
238
+ | `framework` | `FrameworkPlugin` | `noopPlugin`: no framework hooks, so `build()` fails at the client entry step |
239
+ | `css` | `CssPlugin` | No global CSS processing, no critical CSS, CSS modules compiled as written |
240
+ | `cssProcessor` | `CssProcessor` | `noopCssProcessor`: a stylesheet the CSS plugin does not compile stays as it is |
241
+ | `fontOptimizer` | `FontOptimizer` | `noopFontOptimizer`: no font files, no `fonts.css` |
242
+ | `imageOptimizer` | `ImageOptimizer` | `noopImageOptimizer`: `public/images/` is served as it is |
243
+
244
+ To write your own adapter, implement the port type from the package root and
245
+ pass it the same way. A font optimizer returns `null` for fonts it does not
246
+ handle, and an image optimizer returns `null` when it optimizes nothing.
247
+
248
+ ## Configuration
249
+
250
+ `createBuildContext()` takes a `BuildConfig`. The paths are absolute.
251
+
252
+ | Field | Type | Purpose |
253
+ | -------------------------- | ---------------------------- | ------------------------------------------------------------------- |
254
+ | `projectRoot` | `string` | Project root directory |
255
+ | `srcDir` | `string` | Source directory that holds `app/` |
256
+ | `distDir` | `string` | Output directory; a full build deletes it first |
257
+ | `logLevel` | `LogLevel` | Log level for the client, written into the chunk manifest |
258
+ | `fonts` | `FontDefinition[]` | Google Fonts to self-host |
259
+ | `images` | `ResolvedImageConfig` | Formats, widths, quality and placeholder for `public/images/` |
260
+ | `cssModuleTypes` | `boolean` | Write `.d.ts` files for CSS modules |
261
+ | `noCssModuleAutoReference` | `boolean` | Do not inject `@reference` into CSS modules |
262
+ | `browserShims` | `ResolvedBrowserShimsConfig` | Browser replacements for server-only packages and Node.js built-ins |
263
+ | `serverExternals` | `string[]` | Packages left out of the server bundle and loaded at run time |
264
+
265
+ The second argument picks the plugins and the adapters. Both bundles use
266
+ Rolldown (`bundlerBackend` accepts only `"rolldown"`); `browserShims` and the
267
+ import map resolution run as Rolldown plugins on the client bundle, so
268
+ server-only packages such as the native `@eserstack/logging` stay out of the
269
+ browser.
270
+
271
+ ## Build Modes
272
+
273
+ `eser laroux dev` builds with Rolldown, then watches `src/` and sends HMR
274
+ updates after each rebuild that succeeds. `eser laroux build` builds once. In
275
+ both, `build()` bundles the client with `PRODUCTION_SETTINGS`: minified, split
276
+ into chunks, without source maps.
277
+
278
+ ```bash
279
+ npx eser laroux dev # build, watch, HMR
280
+ npx eser laroux build # one production build
281
+ ```
282
+
283
+ ## How It Works
284
+
285
+ A full `build()` runs these steps:
286
+
287
+ 1. Route scanning: `src/app/routes/` is scanned for `page.tsx`, `layout.tsx`,
288
+ `route.ts` and `proxy.ts`, and the route, API route and proxy registries are
289
+ generated into `dist/server/`; the route registry imports the pages and
290
+ layouts with the build id as a query. A `home` directory maps to `/`. Test
291
+ files and any file or directory whose name starts with `_` are skipped, so
292
+ nothing under `_private/` becomes a route. A one-off build scans every time;
293
+ in watch mode the scan is kept per routes directory until a file under it
294
+ changes.
295
+ 2. Module discovery: files with `"use client"` become client components.
296
+ 3. Transform: each client component gets a `createClientReference()` proxy in
297
+ `dist/server/`, server component imports are rewritten to those proxies, and
298
+ `"use server"` files get React server reference markers.
299
+ 4. Module map: `dist/client/module-map.json` maps each client component to its
300
+ chunk, so the server can reference client components in the RSC stream.
301
+ 5. CSS: the CSS plugin compiles `src/app/styles/global.css` into
302
+ `dist/client/styles.css`, or the CSS processor transforms it when the plugin
303
+ does not claim it. CSS modules go through the CSS plugin's preprocessing
304
+ (Tailwind expands `@apply`) and compile to JSON class maps, and the styles
305
+ split into critical, deferred and universal files.
306
+ 6. Client bundle: `src/` is copied to `dist/_bundle_src/`, server action files
307
+ in the copy are replaced by stubs that `POST` to `/_rsc` with an `RSC-Action`
308
+ header through the client bootstrap's `__callServer`, and the client bundle
309
+ is built from the copy, so `src/` is never modified. The laroux-react client
310
+ bootstrap is copied to `dist/_laroux-react/` and bundled from there, so the
311
+ packages it imports (`react`, `react-dom` and `@eserstack/laroux`) resolve
312
+ from the app, as its own client components' imports do. `browserShims`
313
+ replace server-only packages: by default `@eserstack/logging` becomes
314
+ laroux's browser logger.
315
+ 7. Assets: the font optimizer self-hosts the configured fonts, the image
316
+ optimizer processes `public/images/`, translation files are copied, and
317
+ `public/` is copied to `dist/`.
318
+ 8. Server bundle: server components are bundled into `dist/server/`, the
319
+ packages in `serverExternals` stay external, and an actions manifest lists
320
+ the server action files.
321
+ 9. Chunk manifest: `dist/client/manifest.json` is written last, so it marks a
322
+ build that finished.
323
+
324
+ ## Upgrading from 4.x
325
+
326
+ These changes since 4.5.2 need a change in code, commands or files that use this
327
+ package. The [changelog](https://github.com/eser/stack/blob/main/CHANGELOG.md)
328
+ lists the changes in every package.
329
+
330
+ - A `page.tsx`, `layout.tsx`, `route.ts` or `proxy.ts` in or below a directory
331
+ whose name starts with `_` is no longer routed; only `_` file names were
332
+ skipped. Rename `src/app/routes/_private/` to `src/app/routes/private/` if it
333
+ was meant to be public.
334
+ - `build()` uses only the adapters you pass. `BuildPlugins` has optional
335
+ `cssProcessor`, `fontOptimizer` and `imageOptimizer` with no-op defaults, and
336
+ `BuildContext` requires them (`createBuildContext` fills them in). CSS modules
337
+ go through the CSS plugin you pass, so without one `@apply` in a CSS module is
338
+ not expanded:
339
+
340
+ ```typescript
341
+ import * as fonts from "@eserstack/laroux-bundler/adapters/fonts";
342
+ import * as lightningcss from "@eserstack/laroux-bundler/adapters/lightningcss";
343
+ import * as sharp from "@eserstack/laroux-bundler/adapters/sharp";
344
+ import * as tailwind from "@eserstack/laroux-bundler/adapters/tailwindcss";
345
+
346
+ // After: add these to the plugins you pass to build()
347
+ const plugins = {
348
+ css: tailwind.createTailwindPlugin({
349
+ globalCssPath: "src/app/styles/global.css",
350
+ }),
351
+ cssProcessor: lightningcss.lightningCssProcessor,
352
+ fontOptimizer: fonts.googleFontOptimizer,
353
+ imageOptimizer: sharp.sharpImageOptimizer,
354
+ };
355
+ ```
356
+
357
+ - `scanRoutes(routesDir, projectRoot, forceRescan?)` is
358
+ `scanRoutes(routesDir, projectRoot, { cache? })` and keeps no module-level
359
+ cache. `invalidateRouteCache`, `getGlobalBuildCache` and
360
+ `resetGlobalBuildCache` are removed, and `BuildCache` keys route scans by
361
+ directory (`getRouteScan(routesDir, mtime)`,
362
+ `setRouteScan(routesDir, scan, mtime)`):
363
+
364
+ ```typescript
365
+ import * as larouxBundler from "@eserstack/laroux-bundler";
366
+
367
+ // Before
368
+ invalidateRouteCache();
369
+ const routes = await scanRoutes(routesDir, projectRoot, true);
370
+ // After
371
+ const cache = new larouxBundler.BuildCache();
372
+ cache.invalidateFile(changedPath);
373
+ const routes = await larouxBundler.scanRoutes(routesDir, projectRoot, {
374
+ cache,
375
+ });
376
+ ```
377
+
378
+ - Client bundles always use rolldown; `bundlerBackend` selects only the server
379
+ bundle's backend. `RuntimeBundler` bundles with rolldown, applies the new
380
+ `browserShims` option (default `DEFAULT_BROWSER_SHIMS`), and resolves from
381
+ `config.projectRoot` instead of the working directory. Pass the real
382
+ `projectRoot`, and `browserShims` to match a custom production setting.
383
+ - `BuildConfig.noCssModuleAutoReference`, which was ignored, is honoured: with
384
+ it, the Tailwind plugin adds no `@reference` to CSS modules. Remove the
385
+ setting if you relied on the injection.
386
+ - The chunk manifest is `<distDir>/client/manifest.json`, written after every
387
+ other step, so a running or failed build has none. Read
388
+ `dist/client/manifest.json` instead of `dist/manifest.json`.
389
+ - `createClientEntry` copies the laroux-react bootstrap to
390
+ `<distDir>/_laroux-react/` with its package layout, and `_client-entry.tsx`
391
+ imports `./_laroux-react/client/bootstrap/entry.ts`. Code that read
392
+ `<distDir>/entry.ts` reads the new path.
393
+ - `BuildResult` has a required `buildId: string`. Code that builds a
394
+ `BuildResult` itself, such as a test fake, sets it; `build()` and
395
+ `ensureBuildIsReady()` fill it in.
396
+ - `build()` writes `_generated-routes.ts` with page and layout imports that end
397
+ in `?v=<buildId>`. A tool that reads that file as text allows the query;
398
+ `generateRouteFile()` without the new `moduleVersion` option still writes
399
+ plain specifiers.
400
+ - The bundler reads no `deno.json` or `deno.jsonc`. Client bundles resolve
401
+ bare imports from the app's `node_modules`, so declare every package the app
402
+ imports in `package.json`; a `deno.json` import map, `npm:` or `jsr:`
403
+ specifier, or `@/` alias is no longer resolved. A change to `deno.json` no
404
+ longer makes a build stale.
405
+ - `createClientEntry` copies the laroux-react bootstrap only from an installed
406
+ `@eserstack/laroux-react` in `node_modules`; fetching it from JSR is removed.
407
+ - `ImportMapEntry` is `{ specifier, target, version }`, where `target` is the
408
+ bare specifier itself, and `ImportMap` has no `hasDenoJson`.
409
+ `resolveSpecifier()` returns the specifier for a declared package instead of
410
+ an `npm:` target. `ImportMapResolverOptions` has no `importMap` field:
411
+
412
+ ```typescript
413
+ import * as larouxBundler from "@eserstack/laroux-bundler";
414
+
415
+ const map = await larouxBundler.loadImportMap(projectRoot);
416
+ const react = map.entries.get("react");
417
+ // Before: react.target was "npm:react@^19.0.0"
418
+ // After: react.target is "react" and react.version is "^19.0.0"
419
+ ```
420
+
421
+ ## 🔗 Links
422
+
423
+ - [@eserstack/cli](https://www.npmjs.com/package/@eserstack/cli):
424
+ main CLI tool (`eser laroux` commands)
425
+ - [@eserstack/laroux-server](https://www.npmjs.com/package/@eserstack/laroux-server):
426
+ server runtime (SSR, routing, actions)
427
+ - [@eserstack/laroux](https://www.npmjs.com/package/@eserstack/laroux):
428
+ framework-agnostic core utilities
429
+ - [npm package](https://www.npmjs.com/package/@eserstack/laroux-bundler)
430
+ - [Architecture decision records](https://github.com/eser/stack/tree/main/docs/adr)
431
+
432
+ Apache-2.0 © [Eser Ozvataf](https://github.com/eser)
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Font Optimizer
3
+ * Re-exports @eserstack/bundler/css font optimization utilities with logging.
4
+ */
5
+ import type { FontFile, FontOptimizationResult } from "@eserstack/bundler/css";
6
+ import type { FontOptimizer } from "../../domain/font-optimizer.ts";
7
+ export type { FontFile, FontOptimizationResult };
8
+ /**
9
+ * Optimizes Google Fonts for self-hosting
10
+ *
11
+ * @param fontUrl - Google Fonts URL (e.g., "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500")
12
+ * @param outputDir - Directory to save font files (e.g., "dist/fonts")
13
+ * @param publicPath - Public path for font URLs (e.g., "/fonts")
14
+ * @returns Font optimization result with CSS, preload hints, and metadata
15
+ */
16
+ export declare function optimizeGoogleFonts(fontUrl: string, outputDir: string, publicPath?: string): Promise<FontOptimizationResult>;
17
+ /**
18
+ * Optimizes multiple Google Fonts URLs
19
+ * Useful when you have separate font imports
20
+ */
21
+ export declare function optimizeMultipleGoogleFonts(fontUrls: string[], outputDir: string, publicPath?: string): Promise<FontOptimizationResult>;
22
+ /**
23
+ * Font optimizer that self-hosts Google Fonts: it downloads every font whose
24
+ * provider is "google" into the output directory and returns the @font-face
25
+ * rules and preload hints for them. Fonts with another provider are left to
26
+ * the app. Pass it to the build as `fontOptimizer`.
27
+ */
28
+ export declare const googleFontOptimizer: FontOptimizer;
@@ -0,0 +1,74 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Font Optimizer
4
+ * Re-exports @eserstack/bundler/css font optimization utilities with logging.
5
+ */
6
+ import * as logging from "@eserstack/logging";
7
+ import * as css from "@eserstack/bundler/css";
8
+ import * as fontUrls from "./index.js";
9
+ const fontLogger = logging.logger.getLogger([
10
+ "laroux-bundler",
11
+ "font-optimizer",
12
+ ]);
13
+ /**
14
+ * Optimizes Google Fonts for self-hosting
15
+ *
16
+ * @param fontUrl - Google Fonts URL (e.g., "https://fonts.googleapis.com/css2?family=Roboto:wght@400;500")
17
+ * @param outputDir - Directory to save font files (e.g., "dist/fonts")
18
+ * @param publicPath - Public path for font URLs (e.g., "/fonts")
19
+ * @returns Font optimization result with CSS, preload hints, and metadata
20
+ */
21
+ export async function optimizeGoogleFonts(fontUrl, outputDir, publicPath = "/fonts") {
22
+ const families = css.extractFontFamilies(fontUrl);
23
+ const familyList = families.length > 0 ? families.join(", ") : "unknown";
24
+ fontLogger.info(`🔤 Optimizing Google Fonts: ${familyList}`);
25
+ fontLogger.debug(` URL: ${fontUrl}`);
26
+ fontLogger.debug(` Output: ${outputDir}`);
27
+ fontLogger.debug(` Public path: ${publicPath}`);
28
+ const result = await css.optimizeGoogleFonts(fontUrl, {
29
+ outputDir,
30
+ publicPath,
31
+ maxPreloadFonts: 2,
32
+ });
33
+ fontLogger.info(` ✅ Downloaded ${result.files.length} font file(s)`);
34
+ fontLogger.debug(` Total size: ${(result.totalSize / 1024).toFixed(2)} KB`);
35
+ fontLogger.debug(` Generated ${result.preloadHints.length} preload hint(s) for critical fonts`);
36
+ return result;
37
+ }
38
+ /**
39
+ * Optimizes multiple Google Fonts URLs
40
+ * Useful when you have separate font imports
41
+ */
42
+ export async function optimizeMultipleGoogleFonts(fontUrls, outputDir, publicPath = "/fonts") {
43
+ fontLogger.info(`🔤 Optimizing ${fontUrls.length} Google Fonts URL(s)`);
44
+ const result = await css.optimizeMultipleGoogleFonts(fontUrls, {
45
+ outputDir,
46
+ publicPath,
47
+ maxPreloadFonts: 2,
48
+ });
49
+ fontLogger.info(` ✅ Optimized ${result.files.length} total font file(s)`);
50
+ fontLogger.debug(` Total size: ${(result.totalSize / 1024).toFixed(2)} KB`);
51
+ return result;
52
+ }
53
+ /**
54
+ * Font optimizer that self-hosts Google Fonts: it downloads every font whose
55
+ * provider is "google" into the output directory and returns the @font-face
56
+ * rules and preload hints for them. Fonts with another provider are left to
57
+ * the app. Pass it to the build as `fontOptimizer`.
58
+ */
59
+ export const googleFontOptimizer = {
60
+ name: "google-fonts",
61
+ optimize: async (fonts, options) => {
62
+ const [fontUrl] = fontUrls.getFontUrls(fonts);
63
+ if (fontUrl === undefined) {
64
+ return null;
65
+ }
66
+ const result = await optimizeGoogleFonts(fontUrl, options.outputDir, options.publicPath);
67
+ return {
68
+ fontFaceCss: result.fontFaceCSS,
69
+ preloadHints: result.preloadHints,
70
+ fileCount: result.files.length,
71
+ totalSize: result.totalSize,
72
+ };
73
+ },
74
+ };
@@ -0,0 +1,18 @@
1
+ import type { FontDefinition, FontDisplay, FontStyle, FontWeight } from "../../types.ts";
2
+ export type { FontDefinition, FontDisplay, FontStyle, FontWeight };
3
+ /**
4
+ * Generate Google Fonts URL from configuration
5
+ */
6
+ export declare function generateGoogleFontsUrl(fonts: readonly FontDefinition[]): string;
7
+ /**
8
+ * Generate CSS variables from font configuration
9
+ */
10
+ export declare function generateFontVariables(fonts: FontDefinition[]): string;
11
+ /**
12
+ * Get all configured font families for optimization
13
+ */
14
+ export declare function getFontFamilies(fonts: FontDefinition[]): string[];
15
+ /**
16
+ * Get font URLs for optimization (used by build system)
17
+ */
18
+ export declare function getFontUrls(fonts: readonly FontDefinition[]): string[];
@@ -0,0 +1,78 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ // Font utilities for laroux.js build system
3
+ /**
4
+ * Filter fonts by provider
5
+ */
6
+ function getGoogleFonts(fonts) {
7
+ return fonts.filter((font) => font.provider === "google");
8
+ }
9
+ /**
10
+ * Generate Google Fonts URL from configuration
11
+ */
12
+ export function generateGoogleFontsUrl(fonts) {
13
+ const googleFonts = getGoogleFonts(fonts);
14
+ if (googleFonts.length === 0) {
15
+ return "";
16
+ }
17
+ const families = googleFonts.map((font) => {
18
+ let family = font.family.replace(/\s+/g, "+");
19
+ // Add weights and styles
20
+ if (font.weights && font.weights.length > 0) {
21
+ const styles = font.styles ?? ["normal"];
22
+ if (styles.includes("italic") && styles.includes("normal")) {
23
+ // Both italic and normal: use ital,wght@0,400;0,700;1,400;1,700 format
24
+ const combinations = [];
25
+ for (const style of styles) {
26
+ const italValue = style === "italic" ? "1" : "0";
27
+ for (const weight of font.weights) {
28
+ combinations.push(`${italValue},${weight}`);
29
+ }
30
+ }
31
+ family += `:ital,wght@${combinations.join(";")}`;
32
+ }
33
+ else if (styles.includes("italic")) {
34
+ // Only italic
35
+ family += `:ital,wght@${font.weights.map((w) => `1,${w}`).join(";")}`;
36
+ }
37
+ else {
38
+ // Only normal (most common)
39
+ family += `:wght@${font.weights.join(";")}`;
40
+ }
41
+ }
42
+ return family;
43
+ });
44
+ // Manually construct URL to avoid double-encoding special characters
45
+ const familyParams = families.map((f) => `family=${f}`).join("&");
46
+ const display = googleFonts[0]?.display ?? "swap";
47
+ return `https://fonts.googleapis.com/css2?${familyParams}&display=${display}`;
48
+ }
49
+ /**
50
+ * Generate CSS variables from font configuration
51
+ */
52
+ export function generateFontVariables(fonts) {
53
+ const variables = fonts
54
+ .filter((font) => font.variable)
55
+ .map((font) => {
56
+ const fallbacks = font.fallback ? `, ${font.fallback.join(", ")}` : "";
57
+ return ` ${font.variable}: "${font.family}"${fallbacks};`;
58
+ })
59
+ .join("\n");
60
+ return `:root {\n${variables}\n }`;
61
+ }
62
+ /**
63
+ * Get all configured font families for optimization
64
+ */
65
+ export function getFontFamilies(fonts) {
66
+ return fonts.map((font) => font.family);
67
+ }
68
+ /**
69
+ * Get font URLs for optimization (used by build system)
70
+ */
71
+ export function getFontUrls(fonts) {
72
+ const googleFonts = getGoogleFonts(fonts);
73
+ if (googleFonts.length === 0) {
74
+ return [];
75
+ }
76
+ // Generate a single URL with all Google fonts
77
+ return [generateGoogleFontsUrl(fonts)];
78
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Fonts Adapter
3
+ * Font optimization and utilities
4
+ */
5
+ export { type FontFile, type FontOptimizationResult, googleFontOptimizer, optimizeGoogleFonts, optimizeMultipleGoogleFonts, } from "./font-optimizer.ts";
6
+ export { type FontDefinition, type FontDisplay, type FontStyle, type FontWeight, generateFontVariables, generateGoogleFontsUrl, getFontFamilies, getFontUrls, } from "./index.ts";
@@ -0,0 +1,7 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Fonts Adapter
4
+ * Font optimization and utilities
5
+ */
6
+ export { googleFontOptimizer, optimizeGoogleFonts, optimizeMultipleGoogleFonts, } from "./font-optimizer.js";
7
+ export { generateFontVariables, generateGoogleFontsUrl, getFontFamilies, getFontUrls, } from "./index.js";