From bbd227f8d16f973803d4f257f4cfdc8dea54ce33 Mon Sep 17 00:00:00 2001 From: Arno V Date: Wed, 26 Nov 2025 17:30:58 -0500 Subject: [PATCH] feat(bundlesize): add JSON schema for bundlesize config and update docs Introduces a JSON schema for bundlesize configuration to enable IDE autocompletion and validation. Updates example configs and documentation to reference the new $schema property, and includes the schema in the package files. --- examples/bundlesize/bundlesize.config.js | 2 + packages/bundlesize/README.md | 33 ++++ packages/bundlesize/bundlesize.config.js | 2 + packages/bundlesize/package.json | 1 + .../schemas/bundlesize.config.schema.json | 151 ++++++++++++++++++ 5 files changed, 189 insertions(+) create mode 100644 packages/bundlesize/schemas/bundlesize.config.schema.json diff --git a/examples/bundlesize/bundlesize.config.js b/examples/bundlesize/bundlesize.config.js index f538a4b0..dd6b097f 100644 --- a/examples/bundlesize/bundlesize.config.js +++ b/examples/bundlesize/bundlesize.config.js @@ -1,4 +1,6 @@ export default { + $schema: + "https://cdn.jsdelivr.net/npm/@node-cli/bundlesize/schemas/bundlesize.config.schema.json", report: { // header: "## My custom header", // footer: (limitReached, diff) => diff --git a/packages/bundlesize/README.md b/packages/bundlesize/README.md index 1c6d8bd1..ee42a44e 100644 --- a/packages/bundlesize/README.md +++ b/packages/bundlesize/README.md @@ -14,6 +14,39 @@ A configuration file must be provided via the `-c` parameter. +### JSON Schema Support + +For IDE autocompletion and validation, you can add a `$schema` property to your configuration file: + +```js +export default { + $schema: + "https://cdn.jsdelivr.net/npm/@node-cli/bundlesize/schemas/bundlesize.config.schema.json", + sizes: [ + { + path: "dist/bundle.js", + limit: "10 kB" + } + ] +}; +``` + +This provides: + +- Autocompletion for configuration options +- Inline documentation for each property +- Validation of configuration values + +**Note**: For a specific version of the schema, use: + +``` +https://cdn.jsdelivr.net/npm/@node-cli/bundlesize@VERSION/schemas/bundlesize.config.schema.json +``` + +### Configuration Options + +### Configuration Options + For the size option, it must export an object named "size" which is an array of objects with the following properties: - `path`: the path to the file to check diff --git a/packages/bundlesize/bundlesize.config.js b/packages/bundlesize/bundlesize.config.js index 9b10bcfb..98cde0c0 100644 --- a/packages/bundlesize/bundlesize.config.js +++ b/packages/bundlesize/bundlesize.config.js @@ -1,4 +1,6 @@ export default { + $schema: + "https://cdn.jsdelivr.net/npm/@node-cli/bundlesize/schemas/bundlesize.config.schema.json", sizes: [ { path: "dist/bundlesize.js", diff --git a/packages/bundlesize/package.json b/packages/bundlesize/package.json index 42abcda8..7ec32093 100644 --- a/packages/bundlesize/package.json +++ b/packages/bundlesize/package.json @@ -10,6 +10,7 @@ "bin": "dist/bundlesize.js", "files": [ "dist", + "schemas", "README.md" ], "node": ">=18", diff --git a/packages/bundlesize/schemas/bundlesize.config.schema.json b/packages/bundlesize/schemas/bundlesize.config.schema.json new file mode 100644 index 00000000..c17e9605 --- /dev/null +++ b/packages/bundlesize/schemas/bundlesize.config.schema.json @@ -0,0 +1,151 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cdn.jsdelivr.net/npm/@node-cli/bundlesize/schemas/bundlesize.config.schema.json", + "title": "Bundlesize Configuration", + "description": "Configuration schema for @node-cli/bundlesize - a CLI tool that checks file(s) size and reports if limits have been reached", + "type": "object", + "properties": { + "$schema": { + "type": "string", + "description": "Path to the JSON Schema for this configuration file" + }, + "sizes": { + "type": "array", + "description": "Array of file size entries to check", + "items": { + "oneOf": [ + { + "$ref": "#/$defs/SizeEntry" + }, + { + "$ref": "#/$defs/HeaderEntry" + } + ] + } + }, + "report": { + "$ref": "#/$defs/ReportConfiguration" + } + }, + "additionalProperties": false, + "$defs": { + "SizeEntry": { + "type": "object", + "description": "A file size entry to check", + "properties": { + "path": { + "type": "string", + "description": "Path to the file to check. Supports glob patterns and special placeholders: for content hashes, for semantic versions" + }, + "limit": { + "type": "string", + "description": "Maximum allowed size for the file (gzipped). Examples: '1.5 kB', '500 B', '2 MB'", + "pattern": "^[0-9]+(\\.[0-9]+)?\\s*(B|kB|KB|MB|GB|TB|PB)$" + }, + "alias": { + "type": "string", + "description": "Optional alias for the file in reports. Useful when using dynamic path patterns" + } + }, + "required": ["path", "limit"], + "additionalProperties": false + }, + "HeaderEntry": { + "type": "object", + "description": "A header entry for grouping files in reports", + "properties": { + "header": { + "type": "string", + "description": "Header text for a group of files in the report (e.g., '### Main Bundle')" + } + }, + "required": ["header"], + "additionalProperties": false + }, + "ColumnDefinition": { + "type": "object", + "description": "A column definition for the report table", + "minProperties": 1, + "maxProperties": 1, + "additionalProperties": { + "type": "string", + "description": "Column header text" + } + }, + "ReportConfiguration": { + "type": "object", + "description": "Configuration for generating size comparison reports", + "properties": { + "current": { + "type": "string", + "description": "Path to the current stats JSON file (relative to config file)" + }, + "previous": { + "type": "string", + "description": "Path to the previous stats JSON file for comparison (relative to config file)" + }, + "header": { + "type": "string", + "description": "Custom header for the report. Defaults to '## Bundle Size'" + }, + "threshold": { + "type": "number", + "description": "Minimum byte difference to report as a change. Differences below this threshold are treated as no change. Defaults to 0", + "minimum": 0 + }, + "columns": { + "type": "array", + "description": "Custom column definitions for the report table. Default columns: status, file, size, limits", + "items": { + "$ref": "#/$defs/ColumnDefinition" + }, + "examples": [ + [ + { "status": "Status" }, + { "file": "File" }, + { "size": "Size (Gzip)" }, + { "limits": "Limits" } + ] + ] + } + }, + "required": ["current", "previous"], + "additionalProperties": true + } + }, + "examples": [ + { + "sizes": [ + { + "path": "dist/index.js", + "limit": "10 kB" + }, + { + "path": "dist/vendor..js", + "limit": "50 kB", + "alias": "vendor" + } + ] + }, + { + "sizes": [ + { "header": "### Core" }, + { + "path": "dist/core.js", + "limit": "5 kB" + }, + { "header": "### Plugins" }, + { + "path": "dist/plugins/*.js", + "limit": "2 kB" + } + ], + "report": { + "current": "stats/current.json", + "previous": "stats/previous.json", + "header": "## Bundle Size Report", + "threshold": 100 + } + } + ] +}