@webiny/build-tools 0.0.0-unstable.0d717d18dd

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Webiny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @webiny/build-tools
+
+> [!NOTE]
+> This package is part of the [Webiny](https://www.webiny.com) monorepo.
+> It’s **included in every Webiny project by default** and is not meant to be used as a standalone package.
+
+📘 **Documentation:** [https://www.webiny.com/docs](https://www.webiny.com/docs)
+
+---
+
+_This README file is automatically generated during the publish process._

package/bundling/admin/createBuildAdmin.js

@@ -0,0 +1,18 @@
+import { createRsbuildConfig } from "./createRsbuildConfig.js";
+import { printBuildStats } from "../printBuildStats.js";
+
+export const createBuildAdmin =
+    () =>
+    async ({ cwd }) => {
+        process.env.NODE_ENV = "production";
+
+        // Must be a dynamic import — see rslibCompile.js for the reason.
+        const { createRsbuild } = await import("@rsbuild/core");
+        const rsbuildConfig = createRsbuildConfig({ cwd });
+
+        const rsbuild = await createRsbuild({ rsbuildConfig });
+
+        rsbuild.onAfterBuild(printBuildStats({ cwd, label: "admin", extensions: [".js", ".css"] }));
+
+        await rsbuild.build();
+    };

package/bundling/admin/createRsbuildConfig.js

@@ -0,0 +1,174 @@
+import fs from "fs";
+import path from "path";
+import { pluginReact } from "@rsbuild/plugin-react";
+import { pluginSvgr } from "@rsbuild/plugin-svgr";
+import { pluginSass } from "@rsbuild/plugin-sass";
+import { pluginTypeCheck } from "@rsbuild/plugin-type-check";
+import tailwindcss from "@tailwindcss/postcss";
+import { createImportValidatorPlugin } from "../importValidatorPlugin.js";
+
+export const createRsbuildConfig = ({ cwd }) => {
+    const paths = getPaths(cwd);
+    const envVars = getEnvVars();
+    const mode = getMode();
+
+    return /** @type {import("@rsbuild/core").RsbuildConfig} */ ({
+        source: {
+            entry: {
+                index: paths.admin.entryFile
+            },
+            define: envVars
+        },
+        output: { distPath: { root: paths.admin.outputFolder } },
+        mode,
+        dev: { hmr: true },
+        performance: {
+            printFileSize: false
+        },
+        tools: {
+            postcss: (_, { addPlugins }) => {
+                addPlugins([
+                    createInjectTailwindSourcePlugin(
+                        path.join(paths.projectRootFolder, "extensions")
+                    ),
+                    tailwindcss({
+                        base: getTailwindBasePath(paths.projectRootFolder)
+                    }),
+                    createStripTailwindSourceLeftoverPlugin()
+                ]);
+            },
+            rspack: {
+                watchOptions: {
+                    // Wait for dependency builds to finish before triggering a recompilation.
+                    aggregateTimeout: 500,
+                    ignored: ["**/node_modules/**", "**/.git/**"]
+                }
+            }
+        },
+        server: { port: process.env.PORT || 3001, host: "0.0.0.0" },
+        html: {
+            template: paths.projectRootFolder + "/public/index.html"
+        },
+        plugins: [
+            createImportValidatorPlugin(),
+            pluginTypeCheck({
+                tsCheckerOptions: {
+                    typescript: { configFile: paths.admin.tsConfig },
+                    async: mode === "development"
+                }
+            }),
+            pluginReact({
+                splitChunks: false
+            }),
+            pluginSass(),
+            pluginSvgr({
+                mixedImport: true,
+                svgrOptions: {
+                    exportType: "named",
+                    svgoConfig: {
+                        plugins: [
+                            {
+                                name: "pres" + "et-default",
+                                params: { overrides: { removeViewBox: false } }
+                            }
+                        ]
+                    }
+                }
+            })
+        ]
+    });
+};
+
+const getPaths = cwd => {
+    const adminRootFolderPath = cwd;
+    const adminOutputFolderPath = path.join(adminRootFolderPath, "build");
+    const adminEntryFilePath = path.join(adminRootFolderPath, "src", "index.tsx");
+
+    const adminTsConfigFilePath = path.join(adminRootFolderPath, "tsconfig.json");
+
+    return {
+        projectRootFolder: process.cwd(),
+        admin: {
+            rootFolder: adminRootFolderPath,
+            tsConfig: adminTsConfigFilePath,
+            outputFolder: adminOutputFolderPath,
+            entryFile: adminEntryFilePath
+        }
+    };
+};
+
+const getTailwindBasePath = projectRootFolderPath => {
+    const adminUiPkgPath = path.join(projectRootFolderPath, "packages", "admin-ui");
+
+    const isWebinyJsRepo = fs.existsSync(adminUiPkgPath);
+
+    if (isWebinyJsRepo) {
+        return path.join(projectRootFolderPath, "packages");
+    }
+
+    return path.join(projectRootFolderPath, "node_modules", "@webiny");
+};
+
+/*
+    Injects an `@source` directive into the Tailwind CSS AST at build time, pointing to the
+    given absolute path. https://tailwindcss.com/docs/functions-and-directives#source-directive
+*/
+const createInjectTailwindSourcePlugin = sourcePath => ({
+    postcssPlugin: "inject-tailwind-source",
+    Once(root) {
+        root.prepend(`@source "${sourcePath}";`);
+    }
+});
+
+/*
+    Removes any leftover `@source` at-rule from the output. Tailwind v4 strips the
+    directive from files it processes, but `@tailwindcss/postcss` only processes
+    files containing one of its trigger at-rules; for other files (e.g., pre-bundled
+    component CSS imported through JS), the injected directive would otherwise
+    survive into the production bundle, exposing the absolute build-machine path.
+*/
+const createStripTailwindSourceLeftoverPlugin = () => ({
+    postcssPlugin: "strip-tailwind-source-leftover",
+    Once(root) {
+        root.walkAtRules("source", node => node.remove());
+    }
+});
+
+const getEnvVars = () => {
+    const raw = Object.keys(process.env)
+        .filter(key => {
+            if (new RegExp(/^REACT_APP_/i).test(key)) {
+                return true;
+            }
+
+            return new RegExp(/^WEBINY_ADMIN_/i).test(key);
+        })
+        .reduce(
+            (env, key) => {
+                env[key] = process.env[key];
+                return env;
+            },
+            {
+                // Useful for determining whether we're running in production mode.
+                // Most importantly, it switches React into the correct mode.
+                NODE_ENV: process.env.NODE_ENV || "development"
+            }
+        );
+
+    // Stringify all values so we can feed into Webpack DefinePlugin.
+    // Provide values one by one, not as a single process.env object,
+    // because otherwise plugin will put a big JSON object every time process.env is used in code.
+    // This way minifier also removes redundant code on prod (like if(process.env.NODE_ENV === 'development')).
+    const envVarsAsStrings = {
+        "process.env": "{}"
+    };
+    for (const key of Object.keys(raw)) {
+        envVarsAsStrings[`process.env.${key}`] = JSON.stringify(raw[key]);
+    }
+
+    return envVarsAsStrings;
+};
+
+const getMode = () => {
+    return process.env.NODE_ENV === "production" ? "production" : "development";
+};

package/bundling/admin/createWatchAdmin.js

@@ -0,0 +1,15 @@
+import { createRsbuildConfig } from "./createRsbuildConfig.js";
+
+export const createWatchAdmin =
+    () =>
+    async ({ cwd }) => {
+        process.env.NODE_ENV = "development";
+
+        // Must be a dynamic import — see rslibCompile.js for the reason.
+        const { createRsbuild } = await import("@rsbuild/core");
+        const rsbuildConfig = createRsbuildConfig({ cwd });
+
+        const rsbuild = await createRsbuild({ rsbuildConfig });
+
+        await rsbuild.startDevServer();
+    };

package/bundling/admin/index.js

@@ -0,0 +1,3 @@
+export { createBuildAdmin } from "./createBuildAdmin.js";
+export { createWatchAdmin } from "./createWatchAdmin.js";
+export { printBuildStats } from "../printBuildStats.js";

package/bundling/function/createBuildFunction.js

@@ -0,0 +1,18 @@
+import { createRsbuildConfig } from "./createRsbuildConfig.js";
+import { printBuildStats } from "../printBuildStats.js";
+
+export const createBuildFunction =
+    () =>
+    async ({ cwd }) => {
+        process.env.NODE_ENV = "production";
+
+        // Must be a dynamic import — see rslibCompile.js for the reason.
+        const { createRsbuild } = await import("@rsbuild/core");
+        const rsbuildConfig = await createRsbuildConfig({ cwd, enforceMaxBundleSize: true });
+
+        const rsbuild = await createRsbuild({ rsbuildConfig });
+
+        rsbuild.onAfterBuild(printBuildStats({ cwd, label: "node", extensions: [".mjs"] }));
+
+        await rsbuild.build();
+    };

package/bundling/function/createRsbuildConfig.js

@@ -0,0 +1,126 @@
+import path from "path";
+import { pluginTypeCheck } from "@rsbuild/plugin-type-check";
+import { createImportValidatorPlugin } from "../importValidatorPlugin.js";
+
+const DEFAULT_WEBINY_INFRA_API_MAX_BUNDLE_SIZE = 6_291_456; // 6 MB
+
+export const createRsbuildConfig = async ({ cwd, enforceMaxBundleSize }) => {
+    // Must be a dynamic import — see rslibCompile.js for the reason.
+    const { default: rspack } = await import("@rspack/core");
+    const paths = getPaths(cwd);
+    const mode = getMode();
+    const isDebugEnabled = process.env.DEBUG === "true";
+    // NOTE: dirty for now — sniffing the hosting type off an env var here. Ideally the build config
+    // wouldn't know about hosting types at all: the caller (createBuildFunction, or the flavour's own
+    // build layer) would pass in the externals policy + assetPrefix as options, keeping this file
+    // hosting-agnostic. Good enough while the server hosting type is ALPHA; revisit when it settles.
+    const isServer = process.env.WEBINY_HOSTING_TYPE === "server";
+
+    // Configurable via WEBINY_INFRA_API_MAX_BUNDLE_SIZE (bytes).
+    // Only enforced during build — watch mode skips size checks.
+    const maxBundleSize =
+        parseInt(process.env.WEBINY_INFRA_API_MAX_BUNDLE_SIZE) ||
+        DEFAULT_WEBINY_INFRA_API_MAX_BUNDLE_SIZE;
+
+    return /** @type {import("@rsbuild/core").RsbuildConfig} */ ({
+        source: { entry: { index: paths.fn.entryFile } },
+        // Resolve chunk/asset URLs relative to the running module, not from an absolute root. The
+        // server's bg-tasks worker chunk is spawned via `new Worker(new URL("...", import.meta.url))`
+        // and rsbuild's default publicPath "/" turns that into an ABSOLUTE url ("/xyz.mjs"), which
+        // resolves to the filesystem root and can't be found. "auto" resolves it relative to the module
+        // (handler.mjs) instead, so the chunk loads from build/. publicPath comes from
+        // `output.assetPrefix` in production and `dev.assetPrefix` in development (watch runs
+        // `rsbuild.build({ watch: true })` under NODE_ENV=development), so set BOTH. Not gated to the
+        // server hosting type: AWS has no worker chunks so it's a no-op there, and for any other
+        // (async import) chunks "auto" is at least as correct as "/" (Lambda runs from its own dir too).
+        dev: { assetPrefix: "auto" },
+        output: {
+            module: true,
+            target: "node",
+            assetPrefix: "auto",
+            minify: true,
+            sourceMap: {
+                js: isDebugEnabled || mode === "development" ? "source-map" : false
+            },
+            filename: {
+                js: pathData => {
+                    if (pathData.chunk?.name === "index") {
+                        return "handler.mjs";
+                    }
+                    return "[name].mjs";
+                }
+            },
+            distPath: { root: paths.fn.outputFolder }
+        },
+        performance: {
+            printFileSize: false
+        },
+        tools: {
+            rspack: {
+                ...(enforceMaxBundleSize && {
+                    performance: {
+                        hints: "error",
+                        maxEntrypointSize: maxBundleSize,
+                        maxAssetSize: maxBundleSize
+                    }
+                }),
+                // Both hosting types bundle; externalize only what genuinely can't be bundled.
+                // sharp is a native .node binary; knex statically require()s a driver for every SQL
+                // dialect (bundling pulls in uninstalled ones) and lazily loads only the configured
+                // one at runtime (e.g. better-sqlite3). AWS additionally externalizes aws-sdk (the
+                // Lambda runtime provides it). Server ships these in build/node_modules — the build's
+                // packaging step (CI/Linux) copies them, natives included.
+                externals: isServer
+                    ? [/^sharp$/, /^knex(\/|$)/]
+                    : [/^@aws-sdk/, /^aws-sdk$/, /^sharp$/, /^knex(\/|$)/],
+                plugins: [
+                    // Ignore optional `canvas` native module required by jsdom.
+                    // https://rspack.dev/plugins/webpack/ignore-plugin
+                    new rspack.IgnorePlugin({
+                        resourceRegExp: /^canvas$/,
+                        contextRegExp: /jsdom/
+                    })
+                ],
+                resolve: {
+                    fallback: {
+                        // Disable optional native dependency used by 'ws' package for performance optimizations.
+                        // Not needed in Lambda environment and can cause bundling/deployment issues.
+                        bufferutil: false
+                    }
+                }
+            }
+        },
+        mode,
+        plugins: [
+            createImportValidatorPlugin(),
+            pluginTypeCheck({
+                tsCheckerOptions: {
+                    typescript: { configFile: paths.fn.tsConfig },
+                    async: mode === "development"
+                }
+            })
+        ]
+    });
+};
+
+const getPaths = cwd => {
+    const fnRootFolderPath = cwd;
+    const fnOutputFolderPath = path.join(fnRootFolderPath, "build");
+    const fnEntryFilePath = path.join(fnRootFolderPath, "src", "index.ts");
+
+    const fnTsConfigFilePath = path.join(fnRootFolderPath, "tsconfig.json");
+
+    return {
+        projectRootFolder: process.cwd(),
+        fn: {
+            rootFolder: fnRootFolderPath,
+            tsConfig: fnTsConfigFilePath,
+            outputFolder: fnOutputFolderPath,
+            entryFile: fnEntryFilePath
+        }
+    };
+};
+
+const getMode = () => {
+    return process.env.NODE_ENV === "production" ? "production" : "development";
+};

package/bundling/function/createWatchFunction.js

@@ -0,0 +1,15 @@
+import { createRsbuildConfig } from "./createRsbuildConfig.js";
+
+export const createWatchFunction =
+    () =>
+    async ({ cwd }) => {
+        process.env.NODE_ENV = "development";
+
+        // Must be a dynamic import — see rslibCompile.js for the reason.
+        const { createRsbuild } = await import("@rsbuild/core");
+        const rsbuildConfig = await createRsbuildConfig({ cwd, enforceMaxBundleSize: false });
+
+        const rsbuild = await createRsbuild({ rsbuildConfig });
+
+        await rsbuild.build({ watch: true });
+    };

package/bundling/function/index.js

@@ -0,0 +1,3 @@
+export { createBuildFunction } from "./createBuildFunction.js";
+export { createWatchFunction } from "./createWatchFunction.js";
+export { printBuildStats } from "../printBuildStats.js";

package/bundling/importValidatorPlugin.js

@@ -0,0 +1,93 @@
+// ANSI color codes
+const red = "\x1b[31m";
+const yellow = "\x1b[33m";
+const cyan = "\x1b[36m";
+const reset = "\x1b[0m";
+const bold = "\x1b[1m";
+
+const whitelist = [
+    "@webiny/cognito",
+    "@webiny/auth0",
+    "@webiny/okta",
+    "@webiny/self-hosted-auth",
+    "@webiny/plugins",
+    "@webiny/sdk",
+    "@webiny/stdlib",
+    "@webiny/lexical-converter",
+    "@webiny/lexical-nodes",
+    "@webiny/lexical-theme"
+];
+
+export const createImportValidatorPlugin = () => {
+    return {
+        name: "extensions-import-validator",
+        setup(api) {
+            api.modifyRspackConfig(config => {
+                config.plugins = config.plugins || [];
+                config.plugins.push({
+                    name: "ExtensionsImportValidatorPlugin",
+                    apply(compiler) {
+                        compiler.hooks.compilation.tap(
+                            "ExtensionsImportValidatorPlugin",
+                            (compilation, { normalModuleFactory }) => {
+                                normalModuleFactory.hooks.beforeResolve.tap(
+                                    "ExtensionsImportValidatorPlugin",
+                                    resolveData => {
+                                        const request = resolveData.request;
+                                        const contextInfo = resolveData.contextInfo;
+                                        const issuer = contextInfo?.issuer;
+
+                                        // Check if the import request is a @webiny/* package
+                                        if (!request?.startsWith("@webiny/")) {
+                                            return;
+                                        }
+
+                                        // Allow whitelisted packages
+                                        if (whitelist.some(pkg => request.startsWith(pkg))) {
+                                            return;
+                                        }
+
+                                        // Check if the import originates from extensions folder
+                                        if (!issuer) {
+                                            return;
+                                        }
+
+                                        const normalizedIssuer = issuer.replace(/\\/g, "/");
+
+                                        // Check if the issuer is within the extensions folder
+                                        if (!normalizedIssuer.includes("/extensions/")) {
+                                            return;
+                                        }
+
+                                        // Check if the import is coming through the webiny parent package
+                                        // by checking if the issuer is from node_modules/webiny
+                                        const issuerModule = contextInfo?.issuerModule;
+                                        if (issuerModule) {
+                                            const moduleIdentifier =
+                                                issuerModule.identifier?.() || "";
+                                            if (
+                                                moduleIdentifier.includes("/node_modules/webiny/")
+                                            ) {
+                                                return; // Allow imports through webiny package
+                                            }
+                                        }
+
+                                        const error = new Error(
+                                            `${red}Direct imports of @webiny/* packages are not allowed. Import from "webiny" package instead.${reset}\n\n` +
+                                                `${bold}Location:${reset} ${cyan}${issuer.replace(process.cwd(), "")}${reset}\n` +
+                                                `${bold}Import:${reset} ${yellow}${request}${reset}\n`
+                                        );
+                                        error.name = "ExtensionsImportError";
+                                        error.hideStack = true;
+
+                                        compilation.errors.push(error);
+                                    }
+                                );
+                            }
+                        );
+                    }
+                });
+            });
+        }
+    };
+};

package/bundling/printBuildStats.js

@@ -0,0 +1,46 @@
+import path from "path";
+import chalk from "chalk";
+
+export const printBuildStats =
+    ({ cwd, label = "build", extensions = [".js", ".mjs", ".css"] }) =>
+    ({ stats }) => {
+        if (!stats) {
+            return;
+        }
+
+        const statsJson = stats.toJson({ assets: true, children: false });
+        const assets = statsJson.assets || [];
+
+        // Compute cleaner display path
+        const projectRoot = process.cwd();
+        const outputPath = statsJson.outputPath || path.join(cwd, "build");
+        const webinyWorkspacePrefix = ".webiny/workspace/";
+        let displayPath = path.relative(projectRoot, outputPath);
+
+        if (displayPath.startsWith(webinyWorkspacePrefix)) {
+            displayPath = displayPath.slice(webinyWorkspacePrefix.length);
+        }
+
+        // Sort assets by size for better readability
+        const sortedAssets = assets
+            .filter(asset => extensions.some(ext => asset.name.endsWith(ext)))
+            .sort((a, b) => a.size - b.size);
+
+        // Print header with blue color
+        console.log(
+            `\n${chalk.blue(`File (${label})`.padEnd(50))}${chalk.blue("Size".padStart(11))}`
+        );
+
+        let totalSize = 0;
+        for (const asset of sortedAssets) {
+            const fileName = path.basename(asset.name);
+            const sizeKB = (asset.size / 1024).toFixed(1);
+            totalSize += asset.size;
+
+            // Print filename in cyan
+            console.log(`${chalk.cyan(fileName.padEnd(50))}${sizeKB.padStart(10)} kB`);
+        }
+
+        const totalSizeKB = (totalSize / 1024).toFixed(1);
+        console.log(`\n${chalk.magenta("Total:".padEnd(50))}${totalSizeKB.padStart(10)} kB\n`);
+    };

package/index.d.ts

@@ -0,0 +1,69 @@
+import { Configuration as RspackConfig } from "@rspack/core";
+
+export { RspackConfig };
+
+// Build commands.
+export type BuildCommand<TOptions = Record<string, any>> = (options: TOptions) => Promise<void>;
+
+export interface SwcConfig {
+    [key: string]: any;
+}
+
+export interface DefinePluginOptions {
+    [key: string]: any;
+}
+
+export interface BuildAppConfigOverrides {
+    entry?: string;
+    openBrowser?: boolean;
+}
+// Build commands - apps.
+export interface BuildAppConfig {
+    cwd: string;
+    openBrowser?: boolean;
+    overrides?: BuildAppConfigOverrides;
+}
+
+export function createBuildAdmin(options: BuildAppConfig): BuildCommand;
+export function createWatchAdmin(options: BuildAppConfig): BuildCommand;
+
+// Build commands - functions.
+interface BuildFunctionConfig {
+    [key: string]: any;
+    cwd: string;
+    logs?: boolean;
+    debug?: boolean;
+    /**
+     * Enables or disables source map generation for the function.
+     * By default is set to `true`
+     */
+    sourceMaps?: boolean;
+    overrides?: {
+        entry?: string;
+        output?: {
+            path?: string;
+            filename?: string;
+        };
+        define?: DefinePluginOptions;
+        rspack?: (config: RspackConfig) => RspackConfig;
+        swc?: (config: SwcConfig) => SwcConfig;
+    };
+}
+
+export function createBuildFunction(options: BuildFunctionConfig): BuildCommand;
+export function createWatchFunction(options: BuildFunctionConfig): BuildCommand;
+
+// Build commands - packages.
+interface BuildPackageConfig {
+    [key: string]: any;
+    cwd: string;
+    logs?: boolean;
+    debug?: boolean;
+
+    overrides?: {
+        tsConfig?: Record<string, any> | ((tsConfig: Record<string, any>) => Record<string, any>);
+    };
+}
+
+export function createBuildPackage(options: BuildPackageConfig): BuildCommand;
+export function createWatchPackage(options: BuildPackageConfig): BuildCommand;

package/index.js

@@ -0,0 +1,3 @@
+export { createWatchAdmin, createBuildAdmin } from "./bundling/admin/index.js";
+export { createBuildFunction, createWatchFunction } from "./bundling/function/index.js";
+export { createWatchPackage, createBuildPackage } from "./packages/index.js";