@shuvi/platform-web 1.0.63 → 2.0.0-dev.6

package/lib/node/features/html-render/index.js

@@ -21,7 +21,7 @@ const version_1 = require("../../version");
 const middlewares_1 = require("../middlewares");
 const generateResource_1 = __importDefault(require("./lib/generateResource"));
 const buildHtml_1 = require("./lib/buildHtml");
-const build_manifest_plugin_1 = __importDefault(require("./lib/webpack/build-manifest-plugin"));
+const build_manifest_plugin_rspack_1 = __importDefault(require("./lib/webpack/build-manifest-plugin.rspack"));
 const server_1 = __importDefault(require("./server"));
 const ENTRY_FLAG = 'shuviEntry';
 function makeEntryRequest(req) {
@@ -46,7 +46,7 @@ Object.defineProperty(exports, "getPageMiddleware", { enumerable: true, get: fun
 /** This plugin uses `platformContext` so that it is set to a plugin getter */
 const getPlugin = (platformContext) => {
     const core = (0, service_1.createPlugin)({
-        configWebpack: (chain, { webpack, name, mode }, ctx) => {
+        configWebpack: (chain, { rspack, name, mode }, ctx) => {
             const isDev = mode === 'development';
             const pkgVersion = (0, version_1.getVersion)();
             const isServer = name === shared_1.BUNDLER_TARGET_SERVER;
@@ -68,7 +68,7 @@ const getPlugin = (platformContext) => {
                         }
                     }
                 ]);
-                chain.plugin('private/build-manifest').use(build_manifest_plugin_1.default, [
+                chain.plugin('private/build-manifest').use(build_manifest_plugin_rspack_1.default, [
                     {
                         filename: shared_1.CLIENT_BUILD_MANIFEST_PATH,
                         modules: true,
@@ -81,7 +81,7 @@ const getPlugin = (platformContext) => {
                     chain.resolve.alias.set('@shuvi/platform-shared/shuvi-app/application$', '@shuvi/platform-shared/shuvi-app/application.bare');
                     chain
                         .plugin('replace/ReactView.server')
-                        .use(webpack.NormalModuleReplacementPlugin, [
+                        .use(rspack.NormalModuleReplacementPlugin, [
                         /\.\/ReactView\.server/,
                         function (resource) {
                             const { context } = resource;
@@ -93,7 +93,7 @@ const getPlugin = (platformContext) => {
                         }
                     ]);
                 }
-                chain.plugin('private/build-manifest').use(build_manifest_plugin_1.default, [
+                chain.plugin('private/build-manifest').use(build_manifest_plugin_rspack_1.default, [
                     {
                         filename: shared_1.SERVER_BUILD_MANIFEST_PATH,
                         modules: false,

package/lib/node/features/html-render/lib/buildHtml.js

@@ -44,6 +44,7 @@ const buildHtml = (_a) => __awaiter(void 0, [_a], void 0, function* ({ context,
         const request = (0, node_mocks_http_1.createRequest)({
             url: pathname
         });
+        // @ts-expect-error type error caused by adding dependency @rspack/cli
         const response = (0, node_mocks_http_1.createResponse)({
             eventEmitter: events_1.EventEmitter
         });

package/lib/node/features/html-render/lib/webpack/build-manifest-plugin.d.ts

@@ -1,27 +1,235 @@
-import { Compiler, Compilation, Plugin } from '@shuvi/toolpack/lib/webpack';
+import { Compiler, Compilation, Plugin } from '@shuvi/toolpack/lib/webpack/index.webpack';
+/**
+ * Configuration options for BuildManifestPlugin
+ */
 interface Options {
+    /** Output filename for the build manifest JSON file */
     filename: string;
+    /** Whether to include module information in the manifest */
     modules: boolean;
+    /** Whether to include chunk request information */
     chunkRequest: boolean;
 }
+/**
+ * Webpack plugin that generates a build manifest JSON file containing mappings
+ * of entry filenames to their actual output filenames (which may be hashed in production).
+ *
+ * This plugin is essential for frameworks that need to know the relationship between
+ * entry points and their corresponding built assets, especially when assets are
+ * hashed for cache busting.
+ *
+ * ## Features
+ * - Maps entry points to their output files
+ * - Tracks bundle files and their relationships
+ * - Collects polyfill files
+ * - Supports loadable modules/chunks
+ * - Handles both development and production builds
+ *
+ * ## Generated Manifest Structure
+ * ```json
+ * {
+ *   "entries": {
+ *     "main": {
+ *       "js": ["/static/js/main.abc123.js"],
+ *       "css": ["/static/css/main.def456.css"]
+ *     }
+ *   },
+ *   "bundles": {
+ *     "main": "/static/js/main.abc123.js"
+ *   },
+ *   "chunkRequest": {
+ *     "/static/js/chunk.xyz789.js": "/pages/about"
+ *   },
+ *   "loadble": {
+ *     "/pages/about": {
+ *       "files": ["/static/js/chunk.xyz789.js"],
+ *       "children": [
+ *         {
+ *           "id": "module-id",
+ *           "name": "AboutPage"
+ *         }
+ *       ]
+ *     }
+ *   },
+ *   "polyfillFiles": ["/static/js/polyfills.ghi012.js"]
+ * }
+ * ```
+ *
+ * ## Usage Example
+ * ```typescript
+ * // In webpack configuration
+ * const BuildManifestPlugin = require('./build-manifest-plugin');
+ *
+ * module.exports = {
+ *   plugins: [
+ *     new BuildManifestPlugin({
+ *       filename: 'build-manifest.json',
+ *       modules: true,
+ *       chunkRequest: true
+ *     })
+ *   ]
+ * };
+ * ```
+ *
+ * ## Use Cases
+ * - **SSR Frameworks**: Map entry points to built assets for server-side rendering
+ * - **Asset Loading**: Determine which files to load for specific routes
+ * - **Cache Management**: Track hashed filenames for cache invalidation
+ * - **Code Splitting**: Understand relationships between chunks and their requests
+ */
 export default class BuildManifestPlugin implements Plugin {
     private _options;
     private _manifest;
+    /**
+     * Creates a new BuildManifestPlugin instance
+     * @param options - Configuration options for the plugin
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with default options
+     * new BuildManifestPlugin()
+     *
+     * // Custom configuration
+     * new BuildManifestPlugin({
+     *   filename: 'assets-manifest.json',
+     *   modules: true,
+     *   chunkRequest: true
+     * })
+     * ```
+     */
     constructor(options?: Partial<Options>);
+    /**
+     * Creates the build manifest by analyzing compilation assets and chunks
+     * @param compiler - Webpack compiler instance
+     * @param compilation - Webpack compilation instance
+     * @returns The generated manifest object
+     *
+     * This method performs the following operations:
+     * 1. Initializes the manifest structure
+     * 2. Collects entry point information
+     * 3. Processes chunk groups and their assets
+     * 4. Identifies polyfill files
+     * 5. Sorts and organizes loadable modules
+     */
     createAssets(compiler: Compiler, compilation: Compilation): {
         entries: {};
         bundles: {};
         chunkRequest: {};
         loadble: {};
     };
+    /**
+     * Applies the plugin to the webpack compiler
+     * @param compiler - Webpack compiler instance
+     *
+     * This method hooks into the webpack compilation process to:
+     * 1. Listen for the 'make' hook to prepare for asset processing
+     * 2. Hook into 'processAssets' to generate the manifest file
+     * 3. Create the JSON file as a compilation asset
+     */
     apply(compiler: Compiler): void;
+    /**
+     * Collects entry point information from chunk groups
+     * @param entrypoint - The entry point chunk group to process
+     *
+     * This method processes entry points and maps them to their output files,
+     * filtering out source maps and hot update files.
+     */
     private _collectEntries;
+    /**
+     * Collects information from chunk groups including chunks and modules
+     * @param chunkGroup - The chunk group to process
+     * @param compiler - Webpack compiler instance
+     * @param compilation - Webpack compilation instance
+     * @param chunkRootModulesMap - Map of chunk root modules for efficient lookup
+     *
+     * This method processes chunk groups to collect:
+     * - Chunk information (files, requests)
+     * - Module information (if enabled)
+     * - Loadable modules and their relationships
+     */
     private _collect;
+    /**
+     * Collects information from individual chunks
+     * @param chunk - The webpack chunk to process
+     * @param request - The request that generated this chunk
+     *
+     * This method processes chunks to:
+     * - Identify bundle files
+     * - Map chunk requests to files
+     * - Filter out source maps and hot update files
+     */
     private _collectChunk;
+    /**
+     * Collects module information from chunks (when modules option is enabled)
+     * @param chunk - The webpack chunk to process
+     * @param request - The request that generated this chunk
+     * @param compiler - Webpack compiler instance
+     * @param compilation - Webpack compilation instance
+     * @param chunkRootModulesMap - Map of chunk root modules
+     *
+     * This method processes chunks to collect:
+     * - Loadable module files (JS and CSS)
+     * - Module metadata (ID, name)
+     * - Root modules for code splitting analysis
+     */
     private _collectChunkModule;
+    /**
+     * Adds entry information to the manifest
+     * @param name - Entry point name
+     * @param ext - File extension
+     * @param value - File path
+     *
+     * @example
+     * ```typescript
+     * this._pushEntries('main', 'js', '/static/js/main.abc123.js')
+     * // Results in: { entries: { main: { js: ['/static/js/main.abc123.js'] } } }
+     * ```
+     */
     private _pushEntries;
+    /**
+     * Adds bundle information to the manifest
+     * @param name - Bundle name
+     * @param file - Bundle file path
+     *
+     * @example
+     * ```typescript
+     * this._pushBundle({ name: 'main', file: '/static/js/main.abc123.js' })
+     * // Results in: { bundles: { main: '/static/js/main.abc123.js' } }
+     * ```
+     */
     private _pushBundle;
+    /**
+     * Adds chunk request information to the manifest (when chunkRequest option is enabled)
+     * @param file - Chunk file path
+     * @param request - Request that generated the chunk
+     *
+     * @example
+     * ```typescript
+     * this._pushChunkRequest({
+     *   file: '/static/js/chunk.xyz789.js',
+     *   request: '/pages/about'
+     * })
+     * // Results in: { chunkRequest: { '/static/js/chunk.xyz789.js': '/pages/about' } }
+     * ```
+     */
     private _pushChunkRequest;
+    /**
+     * Adds loadable module information to the manifest
+     * @param request - The request that generated the loadable module
+     * @param module - Module item with ID and name
+     *
+     * @example
+     * ```typescript
+     * // Adding a file
+     * this._pushLoadableModules('/pages/about', '/static/js/chunk.xyz789.js')
+     *
+     * // Adding a module
+     * this._pushLoadableModules('/pages/about', {
+     *   id: 'module-id',
+     *   name: 'AboutPage'
+     * })
+     * ```
+     */
     private _pushLoadableModules;
 }
 export {};

package/lib/node/features/html-render/lib/webpack/build-manifest-plugin.js

@@ -1,14 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const shared_1 = require("../../../../../shared");
-const webpack_1 = require("@shuvi/toolpack/lib/webpack");
-const Entrypoint = (0, webpack_1.resolveWebpackModule)('webpack/lib/Entrypoint');
-const { RawSource } = webpack_1.sources;
+const index_webpack_1 = require("@shuvi/toolpack/lib/webpack/index.webpack");
+const Entrypoint = (0, index_webpack_1.resolveWebpackModule)('webpack/lib/Entrypoint');
+const { RawSource } = index_webpack_1.sources;
+/**
+ * Default configuration options for BuildManifestPlugin
+ */
 const defaultOptions = {
     filename: 'build-manifest.json',
     modules: false,
     chunkRequest: false
 };
+/**
+ * Extracts file extension from a filepath
+ * @param filepath - The file path to extract extension from
+ * @returns The file extension (without dot) or empty string if no extension
+ *
+ * @example
+ * ```typescript
+ * getFileExt('app.js') // returns 'js'
+ * getFileExt('styles.css') // returns 'css'
+ * getFileExt('README') // returns ''
+ * ```
+ */
 function getFileExt(filepath) {
     const match = filepath.match(/\.(\w+)$/);
     if (!match)
@@ -30,12 +45,107 @@ function getFileExt(filepath) {
 //   }
 //   return entrypoints;
 // }
-// This plugin creates a build-manifest.json for all assets that are being output
-// It has a mapping of "entry" filename to real filename. Because the real filename can be hashed in production
+/**
+ * Webpack plugin that generates a build manifest JSON file containing mappings
+ * of entry filenames to their actual output filenames (which may be hashed in production).
+ *
+ * This plugin is essential for frameworks that need to know the relationship between
+ * entry points and their corresponding built assets, especially when assets are
+ * hashed for cache busting.
+ *
+ * ## Features
+ * - Maps entry points to their output files
+ * - Tracks bundle files and their relationships
+ * - Collects polyfill files
+ * - Supports loadable modules/chunks
+ * - Handles both development and production builds
+ *
+ * ## Generated Manifest Structure
+ * ```json
+ * {
+ *   "entries": {
+ *     "main": {
+ *       "js": ["/static/js/main.abc123.js"],
+ *       "css": ["/static/css/main.def456.css"]
+ *     }
+ *   },
+ *   "bundles": {
+ *     "main": "/static/js/main.abc123.js"
+ *   },
+ *   "chunkRequest": {
+ *     "/static/js/chunk.xyz789.js": "/pages/about"
+ *   },
+ *   "loadble": {
+ *     "/pages/about": {
+ *       "files": ["/static/js/chunk.xyz789.js"],
+ *       "children": [
+ *         {
+ *           "id": "module-id",
+ *           "name": "AboutPage"
+ *         }
+ *       ]
+ *     }
+ *   },
+ *   "polyfillFiles": ["/static/js/polyfills.ghi012.js"]
+ * }
+ * ```
+ *
+ * ## Usage Example
+ * ```typescript
+ * // In webpack configuration
+ * const BuildManifestPlugin = require('./build-manifest-plugin');
+ *
+ * module.exports = {
+ *   plugins: [
+ *     new BuildManifestPlugin({
+ *       filename: 'build-manifest.json',
+ *       modules: true,
+ *       chunkRequest: true
+ *     })
+ *   ]
+ * };
+ * ```
+ *
+ * ## Use Cases
+ * - **SSR Frameworks**: Map entry points to built assets for server-side rendering
+ * - **Asset Loading**: Determine which files to load for specific routes
+ * - **Cache Management**: Track hashed filenames for cache invalidation
+ * - **Code Splitting**: Understand relationships between chunks and their requests
+ */
 class BuildManifestPlugin {
+    /**
+     * Creates a new BuildManifestPlugin instance
+     * @param options - Configuration options for the plugin
+     *
+     * @example
+     * ```typescript
+     * // Basic usage with default options
+     * new BuildManifestPlugin()
+     *
+     * // Custom configuration
+     * new BuildManifestPlugin({
+     *   filename: 'assets-manifest.json',
+     *   modules: true,
+     *   chunkRequest: true
+     * })
+     * ```
+     */
     constructor(options = {}) {
         this._options = Object.assign(Object.assign({}, defaultOptions), options);
     }
+    /**
+     * Creates the build manifest by analyzing compilation assets and chunks
+     * @param compiler - Webpack compiler instance
+     * @param compilation - Webpack compilation instance
+     * @returns The generated manifest object
+     *
+     * This method performs the following operations:
+     * 1. Initializes the manifest structure
+     * 2. Collects entry point information
+     * 3. Processes chunk groups and their assets
+     * 4. Identifies polyfill files
+     * 5. Sorts and organizes loadable modules
+     */
     createAssets(compiler, compilation) {
         const assetMap = (this._manifest = {
             entries: {},
@@ -43,6 +153,7 @@ class BuildManifestPlugin {
             chunkRequest: {},
             loadble: {}
         });
+        // Create a map of chunk root modules for efficient lookup
         const chunkRootModulesMap = new Map();
         compilation.chunks.forEach(chunk => {
             const { chunkGraph } = compilation;
@@ -55,6 +166,7 @@ class BuildManifestPlugin {
                 });
             }
         });
+        // Process all chunk groups
         compilation.chunkGroups.forEach(chunkGroup => {
             if (chunkGroup instanceof Entrypoint) {
                 this._collectEntries(chunkGroup);
@@ -62,6 +174,7 @@ class BuildManifestPlugin {
             this._collect(chunkGroup, compiler, compilation, chunkRootModulesMap);
         });
         const compilationAssets = compilation.getAssets();
+        // Collect polyfill files
         this._manifest.polyfillFiles = compilationAssets
             .filter(p => {
             // Ensure only .js files are passed through
@@ -71,22 +184,39 @@ class BuildManifestPlugin {
             return p.info && shared_1.BUILD_CLIENT_RUNTIME_POLYFILLS_SYMBOL in p.info;
         })
             .map(v => v.name);
+        // Sort loadable modules for consistent output
         this._manifest.loadble = Object.keys(this._manifest.loadble)
             .sort()
             // eslint-disable-next-line no-sequences
             .reduce((a, c) => ((a[c] = this._manifest.loadble[c]), a), {});
         return assetMap;
     }
+    /**
+     * Applies the plugin to the webpack compiler
+     * @param compiler - Webpack compiler instance
+     *
+     * This method hooks into the webpack compilation process to:
+     * 1. Listen for the 'make' hook to prepare for asset processing
+     * 2. Hook into 'processAssets' to generate the manifest file
+     * 3. Create the JSON file as a compilation asset
+     */
     apply(compiler) {
         compiler.hooks.make.tap('BuildManifestPlugin', compilation => {
             compilation.hooks.processAssets.tap({
                 name: 'BuildManifestPlugin',
-                stage: webpack_1.webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONS
+                stage: index_webpack_1.webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONS
             }, assets => {
                 assets[this._options.filename] = new RawSource(JSON.stringify(this.createAssets(compiler, compilation), null, 2), true);
             });
         });
     }
+    /**
+     * Collects entry point information from chunk groups
+     * @param entrypoint - The entry point chunk group to process
+     *
+     * This method processes entry points and maps them to their output files,
+     * filtering out source maps and hot update files.
+     */
     _collectEntries(entrypoint) {
         for (const chunk of entrypoint.chunks) {
             // If there's no name or no files
@@ -102,6 +232,18 @@ class BuildManifestPlugin {
             }
         }
     }
+    /**
+     * Collects information from chunk groups including chunks and modules
+     * @param chunkGroup - The chunk group to process
+     * @param compiler - Webpack compiler instance
+     * @param compilation - Webpack compilation instance
+     * @param chunkRootModulesMap - Map of chunk root modules for efficient lookup
+     *
+     * This method processes chunk groups to collect:
+     * - Chunk information (files, requests)
+     * - Module information (if enabled)
+     * - Loadable modules and their relationships
+     */
     _collect(chunkGroup, compiler, compilation, chunkRootModulesMap) {
         const collectModules = this._options.modules;
         chunkGroup.origins.forEach(chunkGroupOrigin => {
@@ -115,6 +257,16 @@ class BuildManifestPlugin {
             });
         });
     }
+    /**
+     * Collects information from individual chunks
+     * @param chunk - The webpack chunk to process
+     * @param request - The request that generated this chunk
+     *
+     * This method processes chunks to:
+     * - Identify bundle files
+     * - Map chunk requests to files
+     * - Filter out source maps and hot update files
+     */
     _collectChunk(chunk, { request }) {
         if (!chunk.files) {
             return;
@@ -140,6 +292,19 @@ class BuildManifestPlugin {
             }
         }
     }
+    /**
+     * Collects module information from chunks (when modules option is enabled)
+     * @param chunk - The webpack chunk to process
+     * @param request - The request that generated this chunk
+     * @param compiler - Webpack compiler instance
+     * @param compilation - Webpack compilation instance
+     * @param chunkRootModulesMap - Map of chunk root modules
+     *
+     * This method processes chunks to collect:
+     * - Loadable module files (JS and CSS)
+     * - Module metadata (ID, name)
+     * - Root modules for code splitting analysis
+     */
     _collectChunkModule(chunk, { request, compiler, compilation, chunkRootModulesMap }) {
         if (chunk.canBeInitial()) {
             return;
@@ -174,6 +339,18 @@ class BuildManifestPlugin {
             }
         }
     }
+    /**
+     * Adds entry information to the manifest
+     * @param name - Entry point name
+     * @param ext - File extension
+     * @param value - File path
+     *
+     * @example
+     * ```typescript
+     * this._pushEntries('main', 'js', '/static/js/main.abc123.js')
+     * // Results in: { entries: { main: { js: ['/static/js/main.abc123.js'] } } }
+     * ```
+     */
     _pushEntries(name, ext, value) {
         const entries = this._manifest.entries;
         if (!entries[name]) {
@@ -188,11 +365,36 @@ class BuildManifestPlugin {
             entries[name][ext].push(value);
         }
     }
+    /**
+     * Adds bundle information to the manifest
+     * @param name - Bundle name
+     * @param file - Bundle file path
+     *
+     * @example
+     * ```typescript
+     * this._pushBundle({ name: 'main', file: '/static/js/main.abc123.js' })
+     * // Results in: { bundles: { main: '/static/js/main.abc123.js' } }
+     * ```
+     */
     _pushBundle({ name, file }) {
         if (name) {
             this._manifest.bundles[name] = file;
         }
     }
+    /**
+     * Adds chunk request information to the manifest (when chunkRequest option is enabled)
+     * @param file - Chunk file path
+     * @param request - Request that generated the chunk
+     *
+     * @example
+     * ```typescript
+     * this._pushChunkRequest({
+     *   file: '/static/js/chunk.xyz789.js',
+     *   request: '/pages/about'
+     * })
+     * // Results in: { chunkRequest: { '/static/js/chunk.xyz789.js': '/pages/about' } }
+     * ```
+     */
     _pushChunkRequest({ file, request }) {
         if (this._options.chunkRequest && request) {
             this._manifest.chunkRequest[file] = request;