diff --git a/website/docs/en/api/_meta.json b/website/docs/en/api/_meta.json index c222d4a1a71b..184d8f00a037 100644 --- a/website/docs/en/api/_meta.json +++ b/website/docs/en/api/_meta.json @@ -17,5 +17,6 @@ "type": "dir", "name": "plugin-api", "label": "Plugin API" - } + }, + "stats" ] diff --git a/website/docs/en/api/stats.mdx b/website/docs/en/api/stats.mdx new file mode 100644 index 000000000000..9439046667e9 --- /dev/null +++ b/website/docs/en/api/stats.mdx @@ -0,0 +1,285 @@ +import WebpackLicense from '@components/webpack-license'; + + + +# Stats Data + +While using Rspack, you can use the following command to generate a JSON file of the statistics module information to analyze the module dependency relationship: + +```bash +# Generate a statistical information JSON file named `compilation-stats.json` +$ rspack --json=compilation-stats.json +``` + +## Structure + +The top-level structure of the output object is as follows: + +```json +{ + // Fixed simulated webpack version number for compatibility with plugins + "version": "5.75.0", + // Current version number of rspack + "rspackVersion": "0.7.4", + // Compilation specific hash + "hash": "", + // Compilation time in milliseconds + "time": 2469, + // The `output.publicPath` in the configuration + "publicPath": "auto", + // Path to rspack output directory + "outputPath": "/", + // Chunk name to emitted asset(s) mapping + "assetsByChunkName": { + "main": ["main.js", "main.js.map"], + "named-chunk": ["named-chunk.js", "named-chunk.js.map"] + }, + // List of asset objects, refer to the "Asset Object" + "assets": [], + // List of chunk objects, refer to the "Chunk Object" + "chunks": [], + // List of module objects, refer to the "Module Object" + "modules": [], + // Map of entry objects, refer to the "Entry Object" + "entrypoints": {}, + // List of error objects, refer to the "Error/Warning Object" + "errors": [], + // Number of errors + "errorsCount": 0, + // List of warning objects, refer to the "Error/Warning Object" + "warnings": [], + // Number of warnings + "warningsCount": 0 +} +``` + +## Asset Object + +Each asset object represents an output file emitted from the compilation, and its structure is as follows: + +```json +{ + "type": "asset", + // The `output` filename + "name": "main.js", + // The size of the file in bytes + "size": 2467, + // Indicates whether or not the asset made it to the `output` directory + "emitted": true, + // The chunks this asset contains + "chunkNames": ["main"], + // The chunk IDs this asset contains + "chunks": ["909"], + "info": { + // A flag telling whether the asset is only used for development and doesn't count towards user-facing assets + "development": false, + // A flag telling whether the asset ships data for updating an existing application (HMR) + "hotModuleReplacement": false, + // sourceFilename when asset was created from a source file (potentially transformed) + "sourceFilename": "originalfile.js" + } +} +``` + +## Chunk Object + +Each chunk object represents a group of modules known as a chunk, and its structure is as follows: + +```json +{ + "type": "chunk", + // Whether the chunk went through Code Generation + "rendered": true, + // Whether the chunk is loaded on initial page load or on demand + "initial": false, + // Whether the chunk contains the rspack runtime + "entry": false, + // Size of the chunk (in bytes) + "size": 5382, + // Total size of chunk modules group by the output type (in bytes) + "sizes": { + "asset": 5303, + "javascript": 79 + }, + // List of chunk names contained within this chunk + "names": ["named-chunk"], + // The runtime used by the chunk + "runtime": ["main"], + // The list of product files contained in the chunk + "files": ["named-chunk.js"], + // The list of attached product files contained in the chunk + "auxiliaryFiles": ["named-chunk.js.map"], + // Chunk hash + "hash": "", + // Chunk ID + "id": "906", + // List of idHints of the cache groups hit when splitting chunks (need to enable `optimization.splitChunks`). + "idHints": [], + // Sibling chunk IDs + "siblings": [], + // Parent chunk IDs + "parents": ["909"], + // Children chunk IDs + "children": [], + // List of origins describing how the given chunk originated + "origins": [ + { + // Path to the module + "module": "project_root/index.js", + // The identifier of the module + "moduleIdentifier": "project_root/index.js", + // Relative path to the module + "moduleName": "./index.js", + // Lines of code that generated this chunk + "loc": "2:0-50", + // The dependency request in the module + "request": "./dependent" + } + ], + // List of modules contained in the chunk, for details, refer to the "Module Object" + "modules": [] +} +``` + +## Module Object + +Each module object represents a module in the dependency graph, and its structure is as follows: + +```json +{ + "type": "module", + // Module ID + "id": 670, + // Module source type + "moduleType": "javascript/auto", + // A unique identifier used internally + "identifier": "project_root/a.js", + // Path to the actual file + "name": "./a.js", + // Estimated size of the module in bytes + "size": 19, + // Total size of module group by the output type (in bytes) + "sizes": { + "javascript": 19 + }, + // Whether the module went through loaders and parsing + "built": true, + // Whether the module went through code generation + "codeGenerated": true, + // Whether the module is run during the compilation (you can see it while using css-extract) + "buildTimeExecuted": false, + // Whether the module is cached + "cached": false, + // Whether the module can be cached + "cacheable": true, + // Whether the module is optional, and if it is optional, only a warning will be issued when the module is not found + "optional": false, + + // List of reasons why the module is introduced, similar to the structure of chunk.origins + "reasons": [], + // Unique identifier of the parent module + "issuer": "project_root/index.js", + // Parent module ID + "issuerId": 237, + // Path to the actual file of parent module + "issuerName": "./index.js", + // Reference path from the entry to the current module + "issuerPath": [ + { + "identifier": "project_root/index.js", + "name": "./index.js", + "id": 237 + } + ], + // Absolute path used by the module for conditional matching (usually the resource path) + "nameForCondition": "project_root/a.js", + // The top-down index of the module in the ChunkGroup + "preOrderIndex": 1, + // The bottom-up index of the module in the ChunkGroup + "postOrderIndex": 1, + // The level in module graph + "depth": 1, + + // Whether the module is not included by any chunk + "orphan": false, + // List of IDs of chunks that contain the module + "chunks": [522], + // List of assets generated by the module + "assets": [], + + // Whether the module compiles failed + "failed": false, + // Number of errors + "errors": 0, + // Number of warnings + "warnings": 0, + + // Used module exports, true indicates that all are used, string[] indicates that some fields are used (need to enable `optimization.usedExports`) + "usedExports": true, + // List of fields exported by the module (need to enable `optimization.providedExports`) + "providedExports": ["a"], + // Optimization bailout reasons (need to enable `optimization.concatenateModules`) + "optimizationBailout": [], + // If current module is generated by scope hoisting, this is the list of the original modules (need to enable `optimization.concatenateModules`) + "modules": [], + + // Source code + "source": "export const a = 1;", + + // The compilation time statistics for each phase (in milliseconds, need to enable `profile`) + "profile": { + // Resolving the module + "resolving": 13, + // Compiling the module + "building": 31 + } +} +``` + +## Entry Object + +Each entry object represents an entry chunk group, and its structure is as follows: + +```json +"main": { + // Name of the entry + "name": "main", + // Assets generated by the entry + "assets": [ + { + // File name + "name": "main.js", + // File size + "size": 2467 + } + ], + // Total size of the assets generated by the entry + "assetsSize": 2467, + // List of IDs of the chunks included + "chunks": ["909"], +} +``` + +## Error/Warning Object + +Each error/warning object represents an error/warning threw during the build process, and its structure is as follows: + +```json +{ + // Visual message of the error/warning + "message": " + × Resolve error: Can't resolve './not-exists' in './index.js' + ╭─[1:1] + 1 │ + 3 │ import('./not-exists'); + · ───────────────────── + ╰──── + ", + // Unique identifier of the module where the error/warning occurs + "moduleIdentifier": "project_root/index.js", + // Relative path of the module where the error/warning occurs + "moduleName": "./index.js", + // ID of the module where the error/warning occurs + "moduleId": "10" +} +``` diff --git a/website/docs/zh/api/_meta.json b/website/docs/zh/api/_meta.json index 678f662e4dca..bb2fe9b1bc6b 100644 --- a/website/docs/zh/api/_meta.json +++ b/website/docs/zh/api/_meta.json @@ -17,5 +17,6 @@ "type": "dir", "name": "plugin-api", "label": "插件 API" - } + }, + "stats" ] diff --git a/website/docs/zh/api/stats.mdx b/website/docs/zh/api/stats.mdx new file mode 100644 index 000000000000..f04385ebea30 --- /dev/null +++ b/website/docs/zh/api/stats.mdx @@ -0,0 +1,286 @@ +import WebpackLicense from '@components/webpack-license'; + + + +# Stats Data + +使用 Rspack 编译时,可通过如下命令生成统计模块信息的 JSON 文件,以分析应用的模块依赖关系: + +```bash +# 生成名为 `compilation-stats.json` 的统计信息 JSON 文件 +$ rspack --json=compilation-stats.json +``` + +## 整体结构 + +输出的对象的顶层结构如下: + +```json +{ + // 固定的模拟 webpack 版本号,用于兼容社区 webpack 插件 + "version": "5.75.0", + // 当前 rspack 版本号 + "rspackVersion": "0.7.4", + // 编译的哈希值 + "hash": "", + // 编译耗时(毫秒) + "time": 2469, + // 配置中的 `output.publicPath` + "publicPath": "auto", + // 输出目录路径 + "outputPath": "/", + // chunk 对应的输出文件列表 + "assetsByChunkName": { + "main": ["main.js", "main.js.map"], + "named-chunk": ["named-chunk.js", "named-chunk.js.map"] + }, + // asset 对象列表,详细结构参考《Asset 对象结构》章节 + "assets": [], + // chunk 对象列表,详细结构参考《Chunk 对象结构》章节 + "chunks": [], + // module 对象列表,详细结构参考《Module 对象结构》章节 + "modules": [], + // entry 对象,详细结构参考《Entry 对象结构》章节 + "entrypoints": {}, + // error 对象列表,详细结构参考《Error/Warning 对象结构》章节 + "errors": [], + // 错误个数 + "errorsCount": 0, + // warning 对象列表,详细结构参考《Error/Warning 对象结构》章节 + "warnings": [], + // 告警个数 + "warningsCount": 0 +} +``` + +## Asset 对象结构 + +每个 asset 对象对应一个编译过程中生成的产物文件,它的结构如下: + +```json +{ + "type": "asset", + // 产物的文件名 + "name": "main.js", + // 产物的文件大小(单位为字节) + "size": 2467, + // 产物文件是否生成到 `output` 目录中 + "emitted": true, + // 产物文件包含的 chunk 的名称列表 + "chunkNames": ["main"], + // 产物文件包含的 chunk 的 ID 列表 + "chunks": ["909"], + "info": { + // 该产物是否仅用于 development 环境 + "development": false, + // 该产物是否仅用于 HMR 更新场景 + "hotModuleReplacement": false, + // 从源文件创建产物时(可能转换)sourceFilename + // 常见于处理 assets 类型的资源和使用 CopyRspackPlugin 等场景 + "sourceFilename": "originalfile.js" + } +} +``` + +## Chunk 对象结构 + +每个 chunk 对象对应一个编译过程中产生的 chunk,它的结构如下: + +```json +{ + "type": "chunk", + // chunk 是否生成产物 + "rendered": true, + // chunk 是否应被页面初始加载 + "initial": false, + // chunk 是否包含 runtime + "entry": false, + // chunk 的大小(单位为字节) + "size": 5382, + // chunk 根据模块类型细分的大小(单位为字节) + "sizes": { + "asset": 5303, + "javascript": 79 + }, + // chunk 包含的 chunk 的名称列表 + "names": ["named-chunk"], + // chunk 所使用的 runtime + "runtime": ["main"], + // chunk 包含的产物文件列表 + "files": ["named-chunk.js"], + // chunk 包含的附属产物文件列表 + "auxiliaryFiles": ["named-chunk.js.map"], + // chunk 的哈希值 + "hash": "", + // chunk 的 ID + "id": "906", + // split chunks 时命中的 cache group 的 idHint 列表(需开启 optimization.splitChunks) + "idHints": [], + // 同级 chunk 的 ID 列表 + "siblings": [], + // 父级 chunk 的 ID 列表 + "parents": ["909"], + // 子 chunk 的 ID 列表 + "children": [], + // chunk 内包含的 module 列表,详细结构参考《Module 对象结构》章节 + "modules": [], + // chunk 的引入来源列表 + "origins": [ + { + // 来源 module 的路径 + "module": "project_root/index.js", + // 来源 module 的唯一标识 + "moduleIdentifier": "project_root/index.js", + // 来源 module 的相对路径 + "moduleName": "./index.js", + // 在来源 module 中的代码位置 + "loc": "2:0-50", + // 在来源 module 中的依赖标识 + "request": "./dependent" + } + ] +} +``` + +## Module 对象结构 + +每个 module 对象对应一个编译过程中产生的模块,它的结构如下: + +```json +{ + "type": "module", + // 模块的 ID + "id": 670, + // 模块的类型 + "moduleType": "javascript/auto", + // 模块的唯一标识 + "identifier": "project_root/a.js", + // 模块的相对路径 + "name": "./a.js", + // 模块的大小(单位为字节) + "size": 19, + // 根据模块类型细分的大小(单位为字节) + "sizes": { + "javascript": 19 + }, + // 模块是否经过编译阶段 + "built": true, + // 模块是否经过了代码生成阶段 + "codeGenerated": true, + // 模块是否在编译时运行(常见于 css-extract 等场景) + "buildTimeExecuted": false, + // 模块是否被缓存 + "cached": false, + // 模块是否可被缓存 + "cacheable": true, + // 模块是否可选,若可选当模块未找到时仅会出现警告 + "optional": false, + + // 模块被引入的原因列表,与 chunk.origins 结构类似 + "reasons": [], + // 父模块的唯一标识 + "issuer": "project_root/index.js", + // 父模块的 ID + "issuerId": 237, + // 父模块的相对路径 + "issuerName": "./index.js", + // 从 entry 到当前模块的引用路径 + "issuerPath": [ + { + "identifier": "project_root/index.js", + "name": "./index.js", + "id": 237 + } + ], + // 模块用于条件匹配的绝对路径(通常是资源路径) + "nameForCondition": "project_root/a.js", + // 模块在 Chunk Group 中自顶向下的序号 + "preOrderIndex": 1, + // 模块在 Chunk Group 中自底向上的序号 + "postOrderIndex": 1, + // 模块距离 entry 的层级距离 + "depth": 1, + + // 模块是否未被任何 chunk 包含 + "orphan": false, + // 包含模块的 chunk 的 ID 列表 + "chunks": [522], + // 模块相关的产物列表 + "assets": [], + + // 模块是否编译失败 + "failed": false, + // 模块包含的错误数量 + "errors": 0, + // 模块包含的警告数量 + "warnings": 0, + + // 被使用的模块导出,true 表示全部被使用,string[] 表示部分字段被使用(需开启 optimization.usedExports 配置) + "usedExports": true, + // 模块导出的字段列表(需开启 optimization.providedExports 配置) + "providedExports": ["a"], + // 模块优化降级信息(需开启 optimization.concatenateModules 配置) + "optimizationBailout": [], + // 若当前模块为作用域提升后生成的新模块,此字段为原始的模块列表(需开启 optimization.concatenateModules 配置) + "modules": [], + + // 模块的源代码 + "source": "export const a = 1;", + + // 模块各阶段编译耗时统计(单位为毫秒,需开启 profile 配置) + "profile": { + // 查找模块 + "resolving": 13, + // 编译模块 + "building": 31 + } +} +``` + +## Entry 对象结构 + +每个 entry 对象对应一个编译入口,它的结构如下: + +```json +"main": { + // entry 的名称 + "name": "main", + // entry 对应的产物文件 + "assets": [ + { + // 产物文件名 + "name": "main.js", + // 产物文件大小 + "size": 2467 + } + ], + // entry 对应总产物大小 + "assetsSize": 2467, + // 包含的 chunk 的 ID 列表 + "chunks": ["909"], +} +``` + +## Error/Warning 对象结构 + +每个 error/warning 对象对应一个构建过程中产生的错误/警告,它的结构如下: + +```json +{ + // 错误/警告的提示信息,其中包含了错误的位置提示信息 + "message": " + × Resolve error: Can't resolve './not-exists' in './index.js' + ╭─[1:1] + 1 │ + 3 │ import('./not-exists'); + · ───────────────────── + ╰──── + ", + // 发生错误/警告的模块唯一标识 + "moduleIdentifier": "project_root/index.js", + // 发生错误/警告的模块相对路径 + "moduleName": "./index.js", + // 发生错误/警告的模块 ID + "moduleId": "10" +} +```