@moku-labs/web 2.3.3 → 2.4.0

package/dist/index.cjs

@@ -2357,10 +2357,11 @@ const CSS_EXTERNAL_FONT_GLOBS = [
 * @param options.naming.chunk - Naming template for lazy split chunks.
 * @param options.naming.asset - Naming template for additional emitted assets.
 * @param options.external - Import/url() globs left unresolved in the output.
+* @param options.define - Global names replaced with constant expressions.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [] });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {} });
 * ```
 */
 async function defaultRunner(options) {
@@ -2372,6 +2373,33 @@ async function defaultRunner(options) {
 	return bun.build(options);
 }
 /**
+* The bundle-time constants for the `build.env` names. Each name becomes `process.env.<NAME>` and
+* `import.meta.env.<NAME>`, and the whole `import.meta.env` object is set too, because
+* `browserEnv()` spreads it. The value is the build process's own variable, or `""` when unset.
+* With `minify`, a branch on an unset flag is removed together with the dynamic `import()` chunk
+* it guards, so developer-only code never ships in a build without the flag.
+*
+* @param names - The `build.env` names.
+* @param source - Where the values come from; the build process's environment by default.
+* @returns The `define` map for `Bun.build`; empty without names.
+* @example
+* ```ts
+* envDefines(["IS_DEVELOPMENT"], { IS_DEVELOPMENT: "true" });
+* // { "process.env.IS_DEVELOPMENT": "\"true\"", "import.meta.env.IS_DEVELOPMENT": "\"true\"",
+* //   "import.meta.env": "{\"IS_DEVELOPMENT\":\"true\"}" }
+* ```
+*/
+function envDefines(names, source = process.env) {
+	if (names.length === 0) return {};
+	const values = Object.fromEntries(names.map((name) => [name, source[name] ?? ""]));
+	const define = { "import.meta.env": JSON.stringify(values) };
+	for (const [name, value] of Object.entries(values)) {
+		define[`process.env.${name}`] = JSON.stringify(value);
+		define[`import.meta.env.${name}`] = JSON.stringify(value);
+	}
+	return define;
+}
+/**
 * Resolve the first existing entry file from a candidate list (project-relative).
 *
 * @param candidates - Ordered candidate paths to probe.
@@ -2440,12 +2468,13 @@ function normalizeAssetPath(absolutePath, outDir) {
 * @param outDir - The publish root; stored asset paths are made relative to it.
 * @param outdir - The bundler output directory (`<outDir>/assets`).
 * @param minify - Whether to minify.
+* @param define - Global names replaced with constant expressions.
 * @example
 * ```ts
-* await runOne(ctx, runner, "css", ["a.css"], "dist", true);
+* await runOne(ctx, runner, "css", ["a.css"], "dist", true, {});
 * ```
 */
-async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
+async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, define) {
 	if (entrypoints.length === 0) return;
 	const result = await runner({
 		entrypoints,
@@ -2454,7 +2483,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		splitting: true,
 		target: "browser",
 		naming: FINGERPRINT_NAMING,
-		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : []
+		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : [],
+		define
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -2489,10 +2519,11 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 async function bundle(ctx, options = {}) {
 	const runner = options.runner ?? defaultRunner;
 	const { minify, outDir } = ctx.config;
+	const define = envDefines(ctx.config.env ?? []);
 	const assetsDir = node_path$1.default.join(outDir, "assets");
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
 	const jsEntrypoints = options.jsEntrypoints ?? resolveJsEntrypoints(ctx);
-	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify)]);
+	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify, define), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify, define)]);
 }
 //#endregion
 //#region src/plugins/build/phases/asset-tags.ts
@@ -5821,6 +5852,22 @@ function validateFonts(og) {
 	if (isMissingFontDir(og.fontDir)) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
 	if (!(0, node_fs.readdirSync)(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
 }
+/** An environment variable name: letters, digits and `_`, not starting with a digit. */
+const ENV_NAME = /^[A-Z_a-z]\w*$/;
+/**
+* Whether a `build.env` value lists environment variable names.
+*
+* @param value - The configured `build.env`.
+* @returns True for an array of valid names.
+* @example
+* ```ts
+* isEnvNameList(["IS_DEVELOPMENT"]); // true
+* isEnvNameList(["process.env.X"]); // false
+* ```
+*/
+function isEnvNameList(value) {
+	return Array.isArray(value) && value.every((name) => typeof name === "string" && ENV_NAME.test(name));
+}
 /**
 * Validates `build` config synchronously in `onInit` (return value discarded).
 * Throws an actionable `[web] build.<field>` error when `outDir` is empty, or
@@ -5837,6 +5884,7 @@ function validateConfig$2(config) {
 	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$7}.publicDir: must be a string when set.`);
 	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$7}.template: must be a string path when set.`);
 	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$7}.clientEntry: must be a string path when set.`);
+	if (config.env !== void 0 && !isEnvNameList(config.env)) throw new Error(`${ERROR_PREFIX$7}.env: must list environment variable names.\n  Use names like "IS_DEVELOPMENT".`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
 //#endregion

package/dist/index.d.cts

@@ -1715,6 +1715,13 @@ type Config$3 = {
   }; /** Emit per-path i18n bare-path redirect HTML pages. Default `false`. */
   localeRedirects?: boolean; /** Authoritative client bundle entry path (overrides the conventional scan). */
   clientEntry?: string;
+  /**
+   * Environment variable names the client bundle reads, e.g. `["IS_DEVELOPMENT", "IS_LOCAL"]`.
+   * Each becomes a constant under `process.env.<NAME>` and `import.meta.env.<NAME>`: the value
+   * the build process has, or `""` when unset. With `minify`, a branch on an unset flag is dropped
+   * together with the dynamic `import()` chunk it guards. Default: none.
+   */
+  env?: readonly string[];
   /**
    * Path to a custom HTML document shell, giving the app full control over the
    * scaffold (charset, viewport, `<html lang>`, body attributes, wrapper markup).

package/dist/index.d.mts

@@ -1713,6 +1713,13 @@ type Config$3 = {
   }; /** Emit per-path i18n bare-path redirect HTML pages. Default `false`. */
   localeRedirects?: boolean; /** Authoritative client bundle entry path (overrides the conventional scan). */
   clientEntry?: string;
+  /**
+   * Environment variable names the client bundle reads, e.g. `["IS_DEVELOPMENT", "IS_LOCAL"]`.
+   * Each becomes a constant under `process.env.<NAME>` and `import.meta.env.<NAME>`: the value
+   * the build process has, or `""` when unset. With `minify`, a branch on an unset flag is dropped
+   * together with the dynamic `import()` chunk it guards. Default: none.
+   */
+  env?: readonly string[];
   /**
    * Path to a custom HTML document shell, giving the app full control over the
    * scaffold (charset, viewport, `<html lang>`, body attributes, wrapper markup).

package/dist/index.mjs

@@ -2313,10 +2313,11 @@ const CSS_EXTERNAL_FONT_GLOBS = [
 * @param options.naming.chunk - Naming template for lazy split chunks.
 * @param options.naming.asset - Naming template for additional emitted assets.
 * @param options.external - Import/url() globs left unresolved in the output.
+* @param options.define - Global names replaced with constant expressions.
 * @returns The structural build result.
 * @example
 * ```ts
-* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [] });
+* await defaultRunner({ entrypoints: ["a.css"], outdir: "dist", minify: true, splitting: true, target: "browser", naming: FINGERPRINT_NAMING, external: [], define: {} });
 * ```
 */
 async function defaultRunner(options) {
@@ -2328,6 +2329,33 @@ async function defaultRunner(options) {
 	return bun.build(options);
 }
 /**
+* The bundle-time constants for the `build.env` names. Each name becomes `process.env.<NAME>` and
+* `import.meta.env.<NAME>`, and the whole `import.meta.env` object is set too, because
+* `browserEnv()` spreads it. The value is the build process's own variable, or `""` when unset.
+* With `minify`, a branch on an unset flag is removed together with the dynamic `import()` chunk
+* it guards, so developer-only code never ships in a build without the flag.
+*
+* @param names - The `build.env` names.
+* @param source - Where the values come from; the build process's environment by default.
+* @returns The `define` map for `Bun.build`; empty without names.
+* @example
+* ```ts
+* envDefines(["IS_DEVELOPMENT"], { IS_DEVELOPMENT: "true" });
+* // { "process.env.IS_DEVELOPMENT": "\"true\"", "import.meta.env.IS_DEVELOPMENT": "\"true\"",
+* //   "import.meta.env": "{\"IS_DEVELOPMENT\":\"true\"}" }
+* ```
+*/
+function envDefines(names, source = process.env) {
+	if (names.length === 0) return {};
+	const values = Object.fromEntries(names.map((name) => [name, source[name] ?? ""]));
+	const define = { "import.meta.env": JSON.stringify(values) };
+	for (const [name, value] of Object.entries(values)) {
+		define[`process.env.${name}`] = JSON.stringify(value);
+		define[`import.meta.env.${name}`] = JSON.stringify(value);
+	}
+	return define;
+}
+/**
 * Resolve the first existing entry file from a candidate list (project-relative).
 *
 * @param candidates - Ordered candidate paths to probe.
@@ -2396,12 +2424,13 @@ function normalizeAssetPath(absolutePath, outDir) {
 * @param outDir - The publish root; stored asset paths are made relative to it.
 * @param outdir - The bundler output directory (`<outDir>/assets`).
 * @param minify - Whether to minify.
+* @param define - Global names replaced with constant expressions.
 * @example
 * ```ts
-* await runOne(ctx, runner, "css", ["a.css"], "dist", true);
+* await runOne(ctx, runner, "css", ["a.css"], "dist", true, {});
 * ```
 */
-async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
+async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify, define) {
 	if (entrypoints.length === 0) return;
 	const result = await runner({
 		entrypoints,
@@ -2410,7 +2439,8 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 		splitting: true,
 		target: "browser",
 		naming: FINGERPRINT_NAMING,
-		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : []
+		external: kind === "css" ? [...CSS_EXTERNAL_FONT_GLOBS] : [],
+		define
 	});
 	if (!result.success) throw new Error(`[web] build.bundle ${kind} build failed`);
 	const hashed = {};
@@ -2445,10 +2475,11 @@ async function runOne(ctx, runner, kind, entrypoints, outDir, outdir, minify) {
 async function bundle(ctx, options = {}) {
 	const runner = options.runner ?? defaultRunner;
 	const { minify, outDir } = ctx.config;
+	const define = envDefines(ctx.config.env ?? []);
 	const assetsDir = path.join(outDir, "assets");
 	const cssEntrypoints = options.cssEntrypoints ?? resolveEntrypoints(CSS_ENTRY_CANDIDATES);
 	const jsEntrypoints = options.jsEntrypoints ?? resolveJsEntrypoints(ctx);
-	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify)]);
+	await Promise.all([runOne(ctx, runner, "css", cssEntrypoints, outDir, assetsDir, minify, define), runOne(ctx, runner, "js", jsEntrypoints, outDir, assetsDir, minify, define)]);
 }
 //#endregion
 //#region src/plugins/build/phases/asset-tags.ts
@@ -5777,6 +5808,22 @@ function validateFonts(og) {
 	if (isMissingFontDir(og.fontDir)) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" does not exist — provide a directory with at least one font.`);
 	if (!readdirSync(og.fontDir).some((name) => FONT_EXTENSIONS.some((extension) => name.endsWith(extension)))) throw new Error(`${ERROR_PREFIX$7}.ogImage: fontDir "${og.fontDir}" contains no .ttf/.otf/.woff font files.`);
 }
+/** An environment variable name: letters, digits and `_`, not starting with a digit. */
+const ENV_NAME = /^[A-Z_a-z]\w*$/;
+/**
+* Whether a `build.env` value lists environment variable names.
+*
+* @param value - The configured `build.env`.
+* @returns True for an array of valid names.
+* @example
+* ```ts
+* isEnvNameList(["IS_DEVELOPMENT"]); // true
+* isEnvNameList(["process.env.X"]); // false
+* ```
+*/
+function isEnvNameList(value) {
+	return Array.isArray(value) && value.every((name) => typeof name === "string" && ENV_NAME.test(name));
+}
 /**
 * Validates `build` config synchronously in `onInit` (return value discarded).
 * Throws an actionable `[web] build.<field>` error when `outDir` is empty, or
@@ -5793,6 +5840,7 @@ function validateConfig$2(config) {
 	if (config.publicDir !== void 0 && typeof config.publicDir !== "string") throw new Error(`${ERROR_PREFIX$7}.publicDir: must be a string when set.`);
 	if (config.template !== void 0 && typeof config.template !== "string") throw new Error(`${ERROR_PREFIX$7}.template: must be a string path when set.`);
 	if (config.clientEntry !== void 0 && typeof config.clientEntry !== "string") throw new Error(`${ERROR_PREFIX$7}.clientEntry: must be a string path when set.`);
+	if (config.env !== void 0 && !isEnvNameList(config.env)) throw new Error(`${ERROR_PREFIX$7}.env: must list environment variable names.\n  Use names like "IS_DEVELOPMENT".`);
 	if (config.ogImage) validateFonts(config.ogImage);
 }
 //#endregion

package/package.json

@@ -137,5 +137,5 @@
     "release:doctor": "moku-release doctor",
     "release": "moku-release"
   },
-  "version": "2.3.3"
+  "version": "2.4.0"
 }