@lynx-js/rspeedy 0.8.2

package/lib/config/index.d.ts

@@ -0,0 +1,172 @@
+import type { RsbuildConfig, RsbuildPlugins } from '@rsbuild/core';
+import type { Dev } from './dev/index.js';
+import type { Output } from './output/index.js';
+import type { Performance } from './performance/index.js';
+import type { Server } from './server/index.js';
+import type { Source } from './source/index.js';
+import type { Tools } from './tools/index.js';
+/**
+ * The `Config` is the configuration that `rspeedy` uses.
+ *
+ * @public
+ */
+export interface Config {
+    /**
+     * The Rsbuild provider.
+     *
+     * @example
+     * You can switch from Rspack to Webpack by:
+     *
+     * - Use `webpackProvider` from `@rsbuild/webpack`
+     * - Add `pluginSwc` from `@rsbuild/plugin-webpack-swc` for TypeScript transpilation
+     *
+     * ```ts
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * import { webpackProvider } from '@rsbuild/webpack'
+     * import { pluginSwc } from '@rsbuild/plugin-webpack-swc'
+     *
+     * export default defineConfig({
+     *   provider: webpackProvider,
+     *   plugins: [
+     *     pluginSwc(),
+     *   ],
+     * })
+     * ```
+     *
+     * @alpha
+     */
+    provider?: RsbuildConfig['provider'];
+    /**
+     * The {@link Dev} option is used to control the behavior related with development. Including: HMR, DevServer, etc.
+     */
+    dev?: Dev | undefined;
+    /**
+     * The {@link Config.environments} option is used to set the output environment.
+     *
+     * @remarks
+     *
+     * Normally you don't need this if you are not using Lynx for Web.
+     *
+     * @example
+     *
+     * - Using different entries for Lynx and Web.
+     *
+     * ```ts
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *   environments: {
+     *     lynx: {},
+     *     web: {
+     *       source: { entry: { web: './src/index.web.jsx' } },
+     *     },
+     *   },
+     *   source: {
+     *     entry: './src/index.jsx',
+     *   },
+     * })
+     * ```
+     *
+     * @example
+     *
+     * - Building Web-only outputs.
+     *
+     * ```ts
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *   environments: {
+     *     web: {
+     *       source: { entry: { web: './src/index.web.jsx' } },
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    environments?: RsbuildConfig['environments'] | undefined;
+    /**
+     * Specify the build mode for Rsbuild and Rspack, as each mode has different default behavior and optimizations.
+     *
+     * @remarks
+     *
+     * The default value of mode depends on the `process.env.NODE_ENV` environment variable:
+     *
+     * - If `NODE_ENV` is production, the default value is production.
+     *
+     * - If `NODE_ENV` is development, the default value is development.
+     *
+     * - If `NODE_ENV` has any other value, the default value is none.
+     *
+     * - If you set the value of mode, the value of `NODE_ENV` will be ignored.
+     *
+     * When using Rspeedy's CLI:
+     *
+     * - `rspeedy dev` and `rspeedy preview` will set the default values of `NODE_ENV` and `mode` to `'development'`.
+     *
+     * - `rspeedy build` will set the default values of `NODE_ENV` and `mode` to `'production'`.
+     *
+     * @example
+     *
+     * If the value of `mode` is `'development'`:
+     *
+     * - Enable HMR and register the {@link https://rspack.dev/plugins/webpack/hot-module-replacement-plugin | HotModuleReplacementPlugin}.
+     *
+     * - Generate JavaScript source maps, but do not generate CSS source maps. See {@link Output.sourceMap} for details.
+     *
+     * - The `process.env.NODE_ENV` in the source code will be replaced with `'development'`.
+     *
+     * - The `import.meta.env.MODE` in the source code will be replaced with `'development'`.
+     *
+     * - The `import.meta.env.DEV` in the source code will be replaced with `true`.
+     *
+     * - The `import.meta.env.PROD` in the source code will be replaced with `false`.
+     *
+     * @example
+     *
+     * If the value of `mode` is `'production'`:
+     *
+     * - Enable JavaScript code minification and register the {@link https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin | SwcJsMinimizerRspackPlugin}.
+     *
+     * - Generated JavaScript and CSS filenames will have hash suffixes, see {@link Output.filenameHash}.
+     *
+     * - Generated CSS Modules classnames will be shorter, see {@link CssModules.localIdentName}.
+     *
+     * - Do not generate JavaScript and CSS source maps, see {@link Output.sourceMap}.
+     *
+     * - The `process.env.NODE_ENV` in the source code will be replaced with `'production'`.
+     *
+     * - The `import.meta.env.MODE` in the source code will be replaced with `'production'`.
+     *
+     * - The `import.meta.env.DEV` in the source code will be replaced with `false`.
+     *
+     * - The `import.meta.env.PROD` in the source code will be replaced with `true`.
+     */
+    mode?: 'development' | 'production' | 'none' | undefined;
+    /**
+     * The {@link Output} option is used to set how and where should the bundles and assets output.
+     */
+    output?: Output | undefined;
+    /**
+     * The {@link Performance} option is used to
+     */
+    performance?: Performance | undefined;
+    /**
+     * The {@link Server} option changes the behavior of dev-server.
+     */
+    server?: Server | undefined;
+    /**
+     * The {@link Source} option changes the behavior of source files.
+     */
+    source?: Source | undefined;
+    /**
+     * The {@link Tools} options changes the behavior of various building tools.
+     */
+    tools?: Tools | undefined;
+    /**
+     * The `plugins` option is used to customize the build process in a variety of ways.
+     *
+     * @remarks
+     * Rspeedy use the plugin APIs from {@link https://rsbuild.dev/plugins/dev/index | Rsbuild}. See the corresponding document for developing a plugin.
+     */
+    plugins?: RsbuildPlugins | undefined;
+}

package/lib/config/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/lib/config/loadConfig.d.ts

@@ -0,0 +1,50 @@
+import type { Config } from './index.js';
+export declare const resolveConfigPath: (root: string, customConfig?: string) => string;
+/**
+ * The options of loadConfig.
+ *
+ * @public
+ */
+export interface LoadConfigOptions {
+    configPath?: string | undefined;
+    cwd?: string | undefined;
+}
+/**
+ * The result of {@link loadConfig}.
+ *
+ * @public
+ */
+export interface LoadConfigResult {
+    /**
+     * The configuration object that exported from the configuration file.
+     *
+     * @remarks
+     *
+     * The returned object has already been validated.
+     */
+    content: Config;
+    /**
+     * The configuration path that has been loaded.
+     */
+    configPath: string;
+}
+/**
+ * Load the build config by the config path.
+ *
+ * @param loadConfigOptions - the options of `loadConfig` method.
+ * @returns Build config.
+ *
+ * @example
+ *
+ * ```ts
+ * import { loadConfig } from '@lynx-js/rspeedy'
+ *
+ * void async function () {
+ *   const config = await loadConfig({ configPath: './lynx.config.js' })
+ *   console.log(config);
+ * }()
+ * ```
+ *
+ * @public
+ */
+export declare function loadConfig(loadConfigOptions: LoadConfigOptions): Promise<LoadConfigResult>;

package/lib/config/loadConfig.js

@@ -0,0 +1,98 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import fs from 'node:fs';
+import { extname, isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import color from 'picocolors';
+import { validate } from './validate.js';
+import { register } from '../../register/index.js';
+import { debug } from '../debug.js';
+export const resolveConfigPath = (root, customConfig) => {
+    if (customConfig) {
+        debug(`load custom config file ${customConfig} from ${root}`);
+        const customConfigPath = isAbsolute(customConfig)
+            ? customConfig
+            : join(root, customConfig);
+        if (fs.existsSync(customConfigPath)) {
+            return customConfigPath;
+        }
+        throw new Error(`Cannot find config file: ${color.dim(customConfigPath)}`);
+    }
+    const CONFIG_FILES = [
+        'lynx.config.ts',
+        'lynx.config.js',
+        'lynx.config.mts',
+        'lynx.config.mjs',
+    ];
+    for (const file of CONFIG_FILES) {
+        debug(`load default config file ${file} from ${root}`);
+        const configFile = join(root, file);
+        if (fs.existsSync(configFile)) {
+            debug(`default config ${configFile} found`);
+            return configFile;
+        }
+    }
+    throw new Error([
+        `Cannot find the default config file: ${color.dim(join(root, CONFIG_FILES[0]))}.`,
+        `Use custom config with ${color.green('`--config <config>`')} options.`,
+    ].join(' '));
+};
+/**
+ * Load the build config by the config path.
+ *
+ * @param loadConfigOptions - the options of `loadConfig` method.
+ * @returns Build config.
+ *
+ * @example
+ *
+ * ```ts
+ * import { loadConfig } from '@lynx-js/rspeedy'
+ *
+ * void async function () {
+ *   const config = await loadConfig({ configPath: './lynx.config.js' })
+ *   console.log(config);
+ * }()
+ * ```
+ *
+ * @public
+ */
+export async function loadConfig(loadConfigOptions) {
+    let { configPath } = loadConfigOptions;
+    if (!configPath || !isAbsolute(configPath)) {
+        configPath = resolveConfigPath(loadConfigOptions.cwd ?? process.cwd(), configPath);
+    }
+    // Note that we are using `pathToFileURL` since absolute paths must be valid file:// URLs on Windows.
+    const specifier = pathToFileURL(configPath).toString();
+    const unregister = shouldUseNativeImport(configPath)
+        ? /** noop */ () => void 0
+        : register();
+    try {
+        const exports = await import(
+        /* webpackIgnore: true */ `${specifier}?t=${Date.now()}`);
+        const content = validate('default' in exports ? exports.default : exports, configPath);
+        return {
+            configPath,
+            content,
+        };
+    }
+    finally {
+        unregister();
+    }
+}
+function shouldUseNativeImport(configPath) {
+    return isJavaScriptPath(configPath) || hasNativeTSSupport();
+}
+function hasNativeTSSupport() {
+    const { NODE_OPTIONS } = process.env;
+    if (!NODE_OPTIONS) {
+        return false;
+    }
+    return NODE_OPTIONS.includes('--experimental-transform-types')
+        || NODE_OPTIONS.includes('--experimental-strip-types');
+}
+function isJavaScriptPath(configPath) {
+    const ext = extname(configPath);
+    return ['.js', '.mjs', '.cjs'].includes(ext);
+}
+//# sourceMappingURL=loadConfig.js.map

package/lib/config/output/css-modules.d.ts

@@ -0,0 +1,84 @@
+/**
+ * {@inheritdoc Output.cssModules}
+ *
+ * @public
+ */
+export interface CssModules {
+    /**
+     * The `auto` option allows CSS modules to be automatically enabled based on their filenames.
+     *
+     * @remarks
+     *
+     * Given the various `auto` values, the behavior is described as follows:
+     *
+     * - `true`: enable CSS modules for all files matching `/\.module\.\w+$/i.test(filename)` RegExp.
+     *
+     * - `false`: disable CSS modules.
+     *
+     * - `RegExp`: enable CSS modules for all files matching the `auto.test(filename)` RegExp.
+     *
+     * - `function`: enable CSS modules based on the filter function.
+     *
+     * See {@link https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#auto | css-loader#auto} for details.
+     *
+     * @example
+     *
+     * Enable CSS module for `*.module.css` and `shared/*.css`:
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     * export default defineConfig({
+     *   output: {
+     *     cssModules: {
+     *       auto: (filename) => {
+     *         return filename.includes('.module.') || filename.includes('shared/')
+     *       },
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    auto?: boolean | RegExp | ((filename: string) => boolean) | undefined;
+    /**
+     * Allows exporting names from global class names, so you can use them via import.
+     *
+     * @remarks
+     *
+     * See {@link https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportglobals | css-loader#exportGlobals} for details.
+     */
+    exportGlobals?: boolean | undefined;
+    /**
+     * The style of exported class names.
+     *
+     * @remarks
+     *
+     * Given the various `exportLocalsConvention` values, the behavior is described as follows:
+     *
+     * - `'asIs'`:	Class names will be exported as is.
+     *
+     * - `'camelCase'`: Class names will be camelized, the original class name will not to be removed from the locals
+     *
+     * - `'camelCaseOnly'`: Class names will be camelized, the original class name will be removed from the locals
+     *
+     * - `'dashes'`: Only dashes in class names will be camelized
+     *
+     * - `'dashesOnly'`: Dashes in class names will be camelized, the original class name will be removed from the locals
+     *
+     * See {@link https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#exportlocalsconvention | css-loader#exportLocalsConvention} for details.
+     */
+    exportLocalsConvention?: CssModuleLocalsConvention | undefined;
+    /**
+     * Sets the format of the className generated by CSS Modules after compilation.
+     *
+     * @remarks
+     *
+     * See {@link https://github.com/webpack-contrib/css-loader?tab=readme-ov-file#localIdentName | css-loader#localIdentName} for details.
+     */
+    localIdentName?: string | undefined;
+}
+/**
+ * {@inheritdoc CssModules.exportLocalsConvention}
+ *
+ * @public
+ */
+export type CssModuleLocalsConvention = 'asIs' | 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly';

package/lib/config/output/css-modules.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=css-modules.js.map

package/lib/config/output/dist-path.d.ts

@@ -0,0 +1,68 @@
+/**
+ * {@inheritdoc Output.distPath}
+ *
+ * @public
+ */
+export interface DistPath {
+    /**
+     * The root directory of all output files.
+     *
+     * @remarks
+     *
+     * Default value:
+     *
+     * - `'dist'`
+     */
+    root?: string | undefined;
+    /**
+     * The output directory of CSS style files.
+     *
+     * @remarks
+     *
+     * Default value:
+     *
+     * - The same as {@link DistPath.intermediate}
+     */
+    css?: string | undefined;
+    /**
+     * The output directory of async JavaScript files.
+     *
+     * @remarks
+     *
+     * Default value:
+     *
+     * - The `async` subdirectory of {@link DistPath.css}.
+     */
+    cssAsync?: string | undefined;
+    /**
+     * The output directory of the intermediate files.
+     *
+     * @remarks
+     *
+     * Default value:
+     *
+     * - `'.rspeedy'`
+     */
+    intermediate?: string | undefined;
+    /**
+     * The output directory of JavaScript files.
+     *
+     * @remarks
+     *
+     * Default value:
+     *
+     * - `'static/js'`
+     */
+    js?: string | undefined;
+    /**
+     * The output directory of async JavaScript files.
+     *
+     * @remarks
+     *
+     * Default value:
+     *
+     * - The `async` subdirectory of {@link DistPath.js}.
+     */
+    jsAsync?: string | undefined;
+}
+export declare const DEFAULT_DIST_PATH_INTERMEDIATE = ".rspeedy";

package/lib/config/output/dist-path.js

@@ -0,0 +1,2 @@
+export const DEFAULT_DIST_PATH_INTERMEDIATE = '.rspeedy';
+//# sourceMappingURL=dist-path.js.map

package/lib/config/output/filename.d.ts

@@ -0,0 +1,167 @@
+/**
+ * {@inheritdoc Output.filename}
+ *
+ * @public
+ */
+export interface Filename {
+    /**
+     * The name of the bundle files.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - `'[name].[platform].bundle'`
+     *
+     * The following placeholder is supported:
+     *
+     * - `[name]`: the name of the entry.
+     * - `[contenthash]`: the contenthash of the bundle.
+     * - `[platform]`: the environment name of the bundle.
+     *
+     * @example
+     *
+     * - Using content hash in bundle filename:
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *   output: {
+     *     filename: {
+     *       bundle: '[name].[contenthash].bundle',
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * @example
+     *
+     * - Using content hash with length in bundle filename:
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *   output: {
+     *     filename: {
+     *       bundle: '[name].[contenthash:8].bundle',
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    bundle?: string | undefined;
+    /**
+     * The name of the template files.
+     *
+     * @deprecated
+     *
+     * Use {@link Filename.bundle} instead.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - `'[name].lynx.bundle'`
+     *
+     * The following placeholder is supported:
+     *
+     * - `[name]`: the name of the entry.
+     * - `[contenthash]`: the contenthash of the template.
+     *
+     * @example
+     *
+     * - Using content hash in bundle filename:
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *   output: {
+     *     filename: {
+     *       template: '[name].[contenthash].bundle',
+     *     },
+     *   },
+     * })
+     * ```
+     *
+     * @example
+     *
+     * - Using content hash with length in bundle filename:
+     *
+     * ```js
+     * import { defineConfig } from '@lynx-js/rspeedy'
+     *
+     * export default defineConfig({
+     *   output: {
+     *     filename: {
+     *       template: '[name].[contenthash:8].bundle',
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    template?: string | undefined;
+    /**
+     * The name of the JavaScript files.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - Development: `'[name].js'`
+     * - Production: `'[name].[contenthash:8].js'`
+     */
+    js?: string | undefined;
+    /**
+     * The name of the CSS files.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - `'[name].css'`
+     */
+    css?: string | undefined;
+    /**
+     * The name of the SVG images.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - `'[name].[contenthash:8].svg'`
+     */
+    svg?: string | undefined;
+    /**
+     * The name of the font files.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - `'[name].[contenthash:8][ext]'`
+     */
+    font?: string | undefined;
+    /**
+     * The name of non-SVG images.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - `'[name].[contenthash:8][ext]'`
+     */
+    image?: string | undefined;
+    /**
+     * The name of media assets, such as video.
+     *
+     * @remarks
+     *
+     * Default values:
+     *
+     * - `'[name].[contenthash:8][ext]'`
+     */
+    media?: string | undefined;
+}

package/lib/config/output/filename.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=filename.js.map