@eserstack/laroux-bundler 0.0.0-bootstrap.0 → 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 +432 -0
  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 +86 -1
@@ -0,0 +1,167 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Client Action Stub Generator
4
+ *
5
+ * Transforms "use server" files into client-side stubs for the client bundle.
6
+ * When the client bundle imports from a "use server" file, it gets stub functions
7
+ * that call the server through globalThis.__callServer with the action ID;
8
+ * the client bootstrap's __callServer posts to /_rsc with an RSC-Action header.
9
+ *
10
+ * This allows users to:
11
+ * 1. Write server actions in files with "use server" directive
12
+ * 2. Import and call those functions directly from client components
13
+ * 3. The bundler handles the RPC bridging automatically
14
+ *
15
+ * @module
16
+ */
17
+ import { runtime } from "@eserstack/standards/cross-runtime";
18
+ import * as logging from "@eserstack/logging";
19
+ import * as directiveAnalysis from "@eserstack/codebase/directive-analysis";
20
+ const stubLogger = logging.logger.getLogger([
21
+ "laroux-bundler",
22
+ "client-action-stub",
23
+ ]);
24
+ /**
25
+ * Generate action ID from file path and export name.
26
+ * Must match the server-side generateActionId format.
27
+ */
28
+ function generateActionId(relativePath, exportName) {
29
+ // Strip file extension for cleaner IDs
30
+ const pathWithoutExt = relativePath.replace(/\.[cm]?[jt]sx?$/, "");
31
+ return `${pathWithoutExt}#${exportName}`;
32
+ }
33
+ /**
34
+ * Generate a client-side stub function for a server action.
35
+ *
36
+ * The stub:
37
+ * 1. Creates an async function that calls the global __callServer
38
+ * 2. Marks it with React's server reference symbols ($$typeof, $$id, $$bound)
39
+ * 3. React recognizes these markers and handles form binding automatically
40
+ */
41
+ function generateStubFunction(relativePath, exportName) {
42
+ const actionId = generateActionId(relativePath, exportName);
43
+ // Create a function with server reference markers
44
+ // The global __callServer is provided by the client bootstrap
45
+ return `export const ${exportName} = Object.assign(
46
+ async function ${exportName}(...args) {
47
+ if (typeof globalThis.__callServer !== "function") {
48
+ throw new Error("Server actions not initialized. Ensure client bootstrap provides __callServer.");
49
+ }
50
+ return globalThis.__callServer("${actionId}", args);
51
+ },
52
+ {
53
+ $$typeof: Symbol.for("react.server.reference"),
54
+ $$id: "${actionId}",
55
+ $$bound: null
56
+ }
57
+ );`;
58
+ }
59
+ /**
60
+ * Generate client stub content for a "use server" file.
61
+ *
62
+ * @param relativePath - Relative path of the file (for action ID generation)
63
+ * @param exports - List of exported function names
64
+ * @returns Generated stub file content
65
+ */
66
+ function generateStubContent(relativePath, exports) {
67
+ const header = `/**
68
+ * Auto-generated client stubs for server actions
69
+ * Original file: ${relativePath}
70
+ *
71
+ * These stubs call globalThis.__callServer, which posts to /_rsc with the action ID.
72
+ * Action ID format: path/to/file#exportName
73
+ */
74
+
75
+ `;
76
+ const stubs = exports
77
+ .map((exportName) => generateStubFunction(relativePath, exportName))
78
+ .join("\n\n");
79
+ return header + stubs + "\n";
80
+ }
81
+ /**
82
+ * Transform a single "use server" file into client stubs.
83
+ *
84
+ * @param filePath - Absolute path to the file
85
+ * @param relativePath - Relative path for action ID generation
86
+ * @returns List of exported action names, or null if not a "use server" file
87
+ */
88
+ export async function generateClientStub(filePath, relativePath) {
89
+ // Read file content
90
+ let content;
91
+ try {
92
+ content = await runtime.fs.readTextFile(filePath);
93
+ }
94
+ catch (error) {
95
+ stubLogger
96
+ .with({ error })
97
+ .warn(`read ${filePath}; skipping its client action stubs`);
98
+ return null;
99
+ }
100
+ // Check if file has "use server" directive at the top
101
+ if (!directiveAnalysis.hasDirective(content, "use server")) {
102
+ return null;
103
+ }
104
+ // Extract exports
105
+ const exports = directiveAnalysis.extractExports(content);
106
+ if (exports.length === 0) {
107
+ stubLogger.debug(`Skipping ${filePath} - no exports found`);
108
+ return null;
109
+ }
110
+ // Filter out "default" export - we only handle named exports for now
111
+ const namedExports = exports.filter((e) => e !== "default");
112
+ if (namedExports.length === 0) {
113
+ stubLogger.debug(`Skipping ${filePath} - only default export`);
114
+ return null;
115
+ }
116
+ stubLogger.debug(`Generating stubs for ${filePath} with ${namedExports.length} export(s)`);
117
+ // Generate stub content
118
+ const stubContent = generateStubContent(relativePath, namedExports);
119
+ // Overwrite the file with stubs (in virtual source, not original)
120
+ await runtime.fs.writeTextFile(filePath, stubContent);
121
+ stubLogger.debug(`Generated client stubs: ${namedExports.join(", ")}`);
122
+ return namedExports;
123
+ }
124
+ /**
125
+ * Transform all "use server" files in a directory into client stubs.
126
+ *
127
+ * This is used during client bundling to replace server action files
128
+ * with client-side stubs that call the server through __callServer.
129
+ *
130
+ * @param virtualSrcDir - Virtual source directory (e.g., dist/_bundle_src/src)
131
+ * @param projectRoot - Project root for relative path calculation
132
+ * @returns Array of stub generation results
133
+ */
134
+ export async function generateClientActionStubs(virtualSrcDir, projectRoot) {
135
+ stubLogger.debug(`Scanning for server actions in: ${virtualSrcDir}`);
136
+ // Check if directory exists
137
+ const exists = await runtime.fs.exists(virtualSrcDir);
138
+ if (!exists) {
139
+ stubLogger.debug(`Directory does not exist: ${virtualSrcDir}`);
140
+ return [];
141
+ }
142
+ // Find all server action files
143
+ const actionMatches = await directiveAnalysis.analyzeServerActions(virtualSrcDir, {
144
+ projectRoot,
145
+ });
146
+ if (actionMatches.length === 0) {
147
+ stubLogger.debug("No server action files found");
148
+ return [];
149
+ }
150
+ stubLogger.info(`Found ${actionMatches.length} server action file(s) to generate stubs for`);
151
+ const results = [];
152
+ for (const match of actionMatches) {
153
+ // One file at a time keeps open file handles bounded; a project can have
154
+ // more action files than the open-file limit.
155
+ // oxlint-disable-next-line no-await-in-loop
156
+ const exportedActions = await generateClientStub(match.filePath, match.relativePath);
157
+ if (exportedActions !== null && exportedActions.length > 0) {
158
+ results.push({
159
+ filePath: match.filePath,
160
+ relativePath: match.relativePath,
161
+ exportedActions,
162
+ });
163
+ }
164
+ }
165
+ stubLogger.info(`Generated stubs for ${results.length} server action file(s)`);
166
+ return results;
167
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Recursive copy on top of the runtime file system, which copies single
3
+ * files only.
4
+ *
5
+ * @module
6
+ */
7
+ /**
8
+ * Copy a file or a directory tree to dest, overwriting files that exist
9
+ * there. Symbolic links are followed, so their targets are copied. Copying a
10
+ * file onto a directory, or a directory onto a file, fails.
11
+ *
12
+ * @param src - File or directory to copy
13
+ * @param dest - Path the copy is written to
14
+ */
15
+ export declare function copyPath(src: string, dest: string): Promise<void>;
@@ -0,0 +1,29 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Recursive copy on top of the runtime file system, which copies single
4
+ * files only.
5
+ *
6
+ * @module
7
+ */
8
+ import { runtime } from "@eserstack/standards/cross-runtime";
9
+ /**
10
+ * Copy a file or a directory tree to dest, overwriting files that exist
11
+ * there. Symbolic links are followed, so their targets are copied. Copying a
12
+ * file onto a directory, or a directory onto a file, fails.
13
+ *
14
+ * @param src - File or directory to copy
15
+ * @param dest - Path the copy is written to
16
+ */
17
+ export async function copyPath(src, dest) {
18
+ const info = await runtime.fs.stat(src);
19
+ if (!info.isDirectory) {
20
+ await runtime.fs.ensureDir(runtime.path.dirname(dest));
21
+ await runtime.fs.copyFile(src, dest);
22
+ return;
23
+ }
24
+ await runtime.fs.ensureDir(dest);
25
+ for await (const entry of runtime.fs.readDir(src)) {
26
+ // One entry at a time keeps open file handles bounded in a large tree
27
+ await copyPath(runtime.path.join(src, entry.name), runtime.path.join(dest, entry.name));
28
+ }
29
+ }
@@ -0,0 +1,91 @@
1
+ /**
2
+ * CSS Plugin Types
3
+ * Defines the interface for pluggable CSS processors (Tailwind, UnoCSS, etc.)
4
+ */
5
+ /** The stylesheet a CSS plugin hook is called for. */
6
+ export type CssPluginContext = {
7
+ /** Project root directory */
8
+ projectRoot: string;
9
+ /** Path to the CSS file being processed */
10
+ cssPath: string;
11
+ /** Whether this is a CSS module (.module.css) */
12
+ isModule: boolean;
13
+ /**
14
+ * Whether the plugin may add an @reference to the global stylesheet to a
15
+ * CSS module that has none, so its @apply rules see the app's theme. The
16
+ * build sets it to false when the app config sets noCssModuleAutoReference.
17
+ * Default: true.
18
+ */
19
+ injectReference?: boolean;
20
+ };
21
+ /**
22
+ * Result of critical CSS extraction
23
+ */
24
+ export type CriticalCssResult = {
25
+ /** Critical CSS to inline in <head> */
26
+ critical: string;
27
+ /** Deferred CSS to load asynchronously */
28
+ deferred: string;
29
+ /** Statistics about extraction */
30
+ stats?: {
31
+ /** Original CSS size in bytes */
32
+ originalSize: number;
33
+ /** Critical CSS size in bytes */
34
+ criticalSize: number;
35
+ /** Deferred CSS size in bytes */
36
+ deferredSize: number;
37
+ };
38
+ };
39
+ /**
40
+ * Result of universal CSS extraction
41
+ */
42
+ export type UniversalCssResult = {
43
+ /** The generated universal CSS */
44
+ css: string;
45
+ /** CSS variables extracted from theme (if applicable) */
46
+ themeVariables?: Record<string, string>;
47
+ };
48
+ /**
49
+ * CSS framework hooks, such as Tailwind's: preprocessing CSS modules,
50
+ * compiling the global stylesheet and splitting critical CSS from the rest.
51
+ * Every hook is optional; the build skips a step whose hook is missing.
52
+ */
53
+ export type CssPlugin = {
54
+ /** Plugin name for logging/debugging */
55
+ name: string;
56
+ /**
57
+ * Pre-process CSS before compilation
58
+ * Use this to expand framework-specific directives (e.g., @apply for CSS Modules)
59
+ */
60
+ preprocess?: (css: string, context: CssPluginContext) => Promise<string> | string;
61
+ /**
62
+ * Compile CSS with framework-specific logic
63
+ * This replaces the default Lightning CSS processing
64
+ * For Tailwind: CLI handles scanning + compilation + minification
65
+ */
66
+ compile?: (css: string, context: CssPluginContext) => Promise<string>;
67
+ /**
68
+ * Check if this plugin should handle the given CSS file
69
+ * Return false to skip this file (use default Lightning CSS processing)
70
+ */
71
+ shouldProcess?: (css: string, context: CssPluginContext) => boolean;
72
+ /**
73
+ * Extract critical page-specific CSS from compiled CSS based on HTML content
74
+ * Returns critical CSS for inlining and deferred CSS for async loading
75
+ */
76
+ extractCriticalCss?: (compiledCss: string, html: string, options?: {
77
+ forceInclude?: (string | RegExp)[];
78
+ forceExclude?: (string | RegExp)[];
79
+ }) => CriticalCssResult;
80
+ /**
81
+ * Extract universal/base CSS from compiled CSS
82
+ * Returns minimal CSS needed for initial render (e.g., theme variables, base styles)
83
+ */
84
+ extractUniversalCss?: (compiledCss: string) => UniversalCssResult;
85
+ };
86
+ export type CssPluginOptions = {
87
+ /** Path to global CSS file (for @reference injection) */
88
+ globalCssPath?: string;
89
+ /** Whether to auto-inject @reference directive in CSS modules */
90
+ autoInjectReference?: boolean;
91
+ };
@@ -0,0 +1,6 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * CSS Plugin Types
4
+ * Defines the interface for pluggable CSS processors (Tailwind, UnoCSS, etc.)
5
+ */
6
+ export {};
@@ -0,0 +1,57 @@
1
+ /**
2
+ * CSS Processor Port
3
+ *
4
+ * Transforms compiled CSS for the browser. The build runs it on the global
5
+ * stylesheet when no CSS plugin compiles that stylesheet. The Lightning CSS
6
+ * adapter (adapters/lightningcss) implements it.
7
+ */
8
+ import type { CssPlugin, CssPluginContext } from "./css-plugin.ts";
9
+ /** Options for one {@link CssProcessor} call. */
10
+ export type CssProcessorOptions = {
11
+ /** Path of the stylesheet the CSS came from, for error messages */
12
+ readonly filename: string;
13
+ /** Minify the output */
14
+ readonly minify: boolean;
15
+ };
16
+ /**
17
+ * Transforms compiled CSS for the target browsers, for example by lowering
18
+ * nesting and minifying.
19
+ */
20
+ export type CssProcessor = {
21
+ /** Processor name for logs */
22
+ readonly name: string;
23
+ /**
24
+ * Transform one stylesheet and return the result.
25
+ *
26
+ * @param css - The stylesheet source
27
+ * @param options - The file name and whether to minify
28
+ * @returns The transformed stylesheet
29
+ */
30
+ process: (css: string, options: CssProcessorOptions) => Promise<string> | string;
31
+ };
32
+ /**
33
+ * CSS processor for builds that pass none: it returns the CSS unchanged, so
34
+ * the stylesheet is neither lowered for older browsers nor minified.
35
+ */
36
+ export declare const noopCssProcessor: CssProcessor;
37
+ /** Inputs of {@link compileStylesheet}. */
38
+ export type CompileStylesheetOptions = {
39
+ /** CSS plugin, such as Tailwind; null when the build has none */
40
+ readonly plugin: CssPlugin | null;
41
+ /** Processor for a stylesheet the plugin does not compile */
42
+ readonly processor: CssProcessor;
43
+ /** The stylesheet's path and project root, passed to the plugin */
44
+ readonly context: CssPluginContext;
45
+ /** Minify the output */
46
+ readonly minify: boolean;
47
+ };
48
+ /**
49
+ * Compile one stylesheet: the CSS plugin compiles it when the plugin claims
50
+ * it (its shouldProcess hook, true when the hook is missing) and has a
51
+ * compile hook; otherwise the CSS processor transforms it.
52
+ *
53
+ * @param css - The stylesheet source
54
+ * @param options - The plugin, the processor and the stylesheet's context
55
+ * @returns The compiled stylesheet
56
+ */
57
+ export declare function compileStylesheet(css: string, options: CompileStylesheetOptions): Promise<string>;
@@ -0,0 +1,33 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * CSS Processor Port
4
+ *
5
+ * Transforms compiled CSS for the browser. The build runs it on the global
6
+ * stylesheet when no CSS plugin compiles that stylesheet. The Lightning CSS
7
+ * adapter (adapters/lightningcss) implements it.
8
+ */
9
+ /**
10
+ * CSS processor for builds that pass none: it returns the CSS unchanged, so
11
+ * the stylesheet is neither lowered for older browsers nor minified.
12
+ */
13
+ export const noopCssProcessor = {
14
+ name: "noop",
15
+ process: (css) => css,
16
+ };
17
+ /**
18
+ * Compile one stylesheet: the CSS plugin compiles it when the plugin claims
19
+ * it (its shouldProcess hook, true when the hook is missing) and has a
20
+ * compile hook; otherwise the CSS processor transforms it.
21
+ *
22
+ * @param css - The stylesheet source
23
+ * @param options - The plugin, the processor and the stylesheet's context
24
+ * @returns The compiled stylesheet
25
+ */
26
+ export async function compileStylesheet(css, options) {
27
+ const { plugin, processor, context, minify } = options;
28
+ const pluginClaimsFile = plugin !== null && (plugin.shouldProcess?.(css, context) ?? true);
29
+ if (pluginClaimsFile && plugin.compile !== undefined) {
30
+ return await plugin.compile(css, context);
31
+ }
32
+ return await processor.process(css, { filename: context.cssPath, minify });
33
+ }
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Font Optimizer Port
3
+ *
4
+ * Self-hosts the fonts an app configures: downloads the font files and
5
+ * returns the @font-face rules and preload hints that point at them. The
6
+ * Google Fonts adapter (adapters/fonts) implements it.
7
+ */
8
+ import type { FontDefinition } from "@eserstack/laroux/config";
9
+ /** Where a {@link FontOptimizer} writes the font files. */
10
+ export type FontOptimizationOptions = {
11
+ /** Directory the font files are written to */
12
+ readonly outputDir: string;
13
+ /** URL path the files are served under, such as "/fonts" */
14
+ readonly publicPath: string;
15
+ };
16
+ /** Self-hosted fonts, as the build writes them next to the client bundle. */
17
+ export type OptimizedFonts = {
18
+ /** @font-face rules that load the downloaded files */
19
+ readonly fontFaceCss: string;
20
+ /** HTML preload tags for the fonts the first render needs */
21
+ readonly preloadHints: readonly string[];
22
+ /** Number of font files written */
23
+ readonly fileCount: number;
24
+ /** Total size of the font files in bytes */
25
+ readonly totalSize: number;
26
+ };
27
+ /** Downloads the configured fonts so the app serves them itself. */
28
+ export type FontOptimizer = {
29
+ /** Optimizer name for logs */
30
+ readonly name: string;
31
+ /**
32
+ * Download the fonts and return the CSS and preload hints for them.
33
+ *
34
+ * @param fonts - The fonts from the app config
35
+ * @param options - Where the files go and the URL path they are served under
36
+ * @returns The optimized fonts, or null when none of the fonts is one this
37
+ * optimizer handles
38
+ */
39
+ optimize: (fonts: readonly FontDefinition[], options: FontOptimizationOptions) => Promise<OptimizedFonts | null>;
40
+ };
41
+ /**
42
+ * Font optimizer for builds that pass none: it handles no font, so the build
43
+ * writes no font files or @font-face rules, and pages use whatever fonts the
44
+ * app's own CSS loads.
45
+ */
46
+ export declare const noopFontOptimizer: FontOptimizer;
@@ -0,0 +1,17 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Font Optimizer Port
4
+ *
5
+ * Self-hosts the fonts an app configures: downloads the font files and
6
+ * returns the @font-face rules and preload hints that point at them. The
7
+ * Google Fonts adapter (adapters/fonts) implements it.
8
+ */
9
+ /**
10
+ * Font optimizer for builds that pass none: it handles no font, so the build
11
+ * writes no font files or @font-face rules, and pages use whatever fonts the
12
+ * app's own CSS loads.
13
+ */
14
+ export const noopFontOptimizer = {
15
+ name: "noop",
16
+ optimize: () => Promise.resolve(null),
17
+ };
@@ -0,0 +1,106 @@
1
+ /**
2
+ * Framework Plugin Interface
3
+ *
4
+ * This interface defines hooks that framework adapters (React, Vue, etc.)
5
+ * can implement to provide framework-specific build functionality.
6
+ *
7
+ * The bundler is framework-agnostic - it calls these hooks without
8
+ * knowing which framework is being used.
9
+ */
10
+ import type { ClientComponentCache } from "./build-cache.ts";
11
+ /**
12
+ * Client component metadata
13
+ * Framework-agnostic representation of a component that runs on the client
14
+ */
15
+ export type ClientComponent = {
16
+ /** Absolute file path */
17
+ filePath: string;
18
+ /** Relative path from project root (ES Module path) */
19
+ relativePath: string;
20
+ /** Export names (default or named) */
21
+ exportNames: string[];
22
+ };
23
+ /**
24
+ * Module map entry for a single client component
25
+ */
26
+ export type ModuleMapEntry = {
27
+ /** Module ID/path for the client component */
28
+ id: string;
29
+ /** Chunk names that contain this component */
30
+ chunks: string[];
31
+ /** Export name (default, named export, or * for all exports) */
32
+ name: string;
33
+ };
34
+ /**
35
+ * Module map for client component resolution
36
+ * Maps module paths to their bundle information
37
+ */
38
+ export type ModuleMap = Record<string, ModuleMapEntry>;
39
+ /**
40
+ * Transform result for a single component
41
+ */
42
+ export type TransformResult = {
43
+ /** Original file path */
44
+ originalPath: string;
45
+ /** Path to the transformed proxy file */
46
+ transformedPath: string;
47
+ };
48
+ /**
49
+ * Framework plugin interface
50
+ *
51
+ * Frameworks like React, Vue, Solid can implement this interface
52
+ * to provide their specific build hooks.
53
+ */
54
+ export type FrameworkPlugin = {
55
+ /** Plugin name for logging */
56
+ name: string;
57
+ /**
58
+ * Analyze source directory and find client components
59
+ * For React: finds "use client" directives
60
+ * The cache, present in watch mode, keeps the analysis of unchanged files.
61
+ */
62
+ analyzeClientComponents?: (srcDir: string, projectRoot: string, cache?: ClientComponentCache) => Promise<ClientComponent[]>;
63
+ /**
64
+ * Get all component files in the source directory
65
+ */
66
+ getAllComponents?: (srcDir: string) => Promise<string[]>;
67
+ /**
68
+ * Transform client components to server-side proxies
69
+ * For React RSC: creates client references
70
+ */
71
+ transformClientComponents?: (components: ClientComponent[], outputDir: string, projectRoot: string) => Promise<TransformResult[]>;
72
+ /**
73
+ * Generate transform manifest for tracking
74
+ */
75
+ generateTransformManifest?: (transformResults: TransformResult[], outputPath: string, projectRoot: string) => Promise<void>;
76
+ /**
77
+ * Create module map for client component resolution
78
+ */
79
+ createModuleMap?: (components: ClientComponent[]) => Promise<ModuleMap>;
80
+ /**
81
+ * Save module map to disk
82
+ */
83
+ saveModuleMap?: (moduleMap: ModuleMap, outputPath: string) => Promise<void>;
84
+ /**
85
+ * Create client manifest for component metadata
86
+ */
87
+ createClientManifest?: (components: ClientComponent[]) => Promise<ModuleMap>;
88
+ /**
89
+ * Rewrite server component imports
90
+ */
91
+ rewriteServerComponents?: (serverComponentPaths: string[], transformResults: TransformResult[], cssModulePaths: string[], outputDir: string, projectRoot: string) => Promise<void>;
92
+ /**
93
+ * Rewrite CSS module imports in source files
94
+ */
95
+ rewriteCssModuleImports?: (srcDir: string, cssModulePaths: string[], projectRoot: string) => Promise<void>;
96
+ /**
97
+ * Create the client entry point for bundling
98
+ * Returns the path to the generated entry file
99
+ */
100
+ createClientEntry?: (components: ClientComponent[], projectRoot: string, distDir: string) => Promise<string>;
101
+ };
102
+ /**
103
+ * No-op plugin for when no framework is configured
104
+ * Returns empty arrays and does nothing for all hooks
105
+ */
106
+ export declare const noopPlugin: FrameworkPlugin;
@@ -0,0 +1,20 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Framework Plugin Interface
4
+ *
5
+ * This interface defines hooks that framework adapters (React, Vue, etc.)
6
+ * can implement to provide framework-specific build functionality.
7
+ *
8
+ * The bundler is framework-agnostic - it calls these hooks without
9
+ * knowing which framework is being used.
10
+ */
11
+ /**
12
+ * No-op plugin for when no framework is configured
13
+ * Returns empty arrays and does nothing for all hooks
14
+ */
15
+ export const noopPlugin = {
16
+ name: "noop",
17
+ analyzeClientComponents: () => Promise.resolve([]),
18
+ getAllComponents: () => Promise.resolve([]),
19
+ transformClientComponents: () => Promise.resolve([]),
20
+ };
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Image Optimizer Port
3
+ *
4
+ * Turns the images under public/images into responsive variants in modern
5
+ * formats, with optional blur placeholders, and describes them in an image
6
+ * manifest. The sharp adapter (adapters/sharp) implements it.
7
+ */
8
+ import type { ResolvedImageConfig } from "@eserstack/laroux/config";
9
+ /** One encoded variant of an image. */
10
+ export type ImageVariant = {
11
+ /** Output file path */
12
+ path: string;
13
+ /** Format (webp, avif, jpeg, png) */
14
+ format: string;
15
+ /** Width in pixels */
16
+ width: number;
17
+ /** Height in pixels */
18
+ height: number;
19
+ /** File size in bytes */
20
+ size: number;
21
+ };
22
+ /** The variants and metadata of one optimized image. */
23
+ export type OptimizedImage = {
24
+ /** Original image path */
25
+ originalPath: string;
26
+ /** Public URL path (without extension for format selection) */
27
+ publicPath: string;
28
+ /** Original width */
29
+ originalWidth: number;
30
+ /** Original height */
31
+ originalHeight: number;
32
+ /** Generated variants */
33
+ variants: ImageVariant[];
34
+ /** Blur placeholder data URL (if generated) */
35
+ blurDataUrl?: string;
36
+ /** Aspect ratio (width / height) */
37
+ aspectRatio: number;
38
+ };
39
+ /** Image manifest for runtime */
40
+ export type ImageManifest = {
41
+ /** Build timestamp */
42
+ timestamp: number;
43
+ /** Map of original paths to optimized images */
44
+ images: Record<string, OptimizedImage>;
45
+ };
46
+ /** What a {@link ImageOptimizer} optimizes and where it writes the result. */
47
+ export type ImageOptimizationRequest = {
48
+ /** Directory the source images are read from, such as public/images */
49
+ readonly inputDir: string;
50
+ /** Directory the variants are written to */
51
+ readonly outputDir: string;
52
+ /** URL path the variants are served under, such as "/images" */
53
+ readonly publicPath: string;
54
+ /** Formats, widths, quality and placeholder from the app config */
55
+ readonly config: ResolvedImageConfig;
56
+ };
57
+ /** Optimizes the app's images at build time. */
58
+ export type ImageOptimizer = {
59
+ /** Optimizer name for logs */
60
+ readonly name: string;
61
+ /**
62
+ * Optimize every image under request.inputDir.
63
+ *
64
+ * @param request - Input and output directories and the image config
65
+ * @returns The manifest of the optimized images, or null when this
66
+ * optimizer does not optimize images
67
+ */
68
+ optimize: (request: ImageOptimizationRequest) => Promise<ImageManifest | null>;
69
+ };
70
+ /**
71
+ * Image optimizer for builds that pass none: it optimizes nothing, so the
72
+ * images are served as they are in public/images.
73
+ */
74
+ export declare const noopImageOptimizer: ImageOptimizer;