{"_id":"@bostonuniversity/bu-build-toolkit","_rev":"5-ab442d9e8d20c77497c979c69b1dd8d3","name":"@bostonuniversity/bu-build-toolkit","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.0":{"name":"@bostonuniversity/bu-build-toolkit","version":"0.1.0","keywords":["wordpress","webpack","build","toolkit"],"author":{"name":"Boston University"},"_id":"@bostonuniversity/bu-build-toolkit@0.1.0","maintainers":[{"name":"buweb","email":"webteam@bu.edu"},{"name":"jdub233","email":"tamlin@mac.com"},{"name":"dannycrews","email":"dancrews@me.com"},{"name":"rfera213","email":"rfera213@bu.edu"},{"name":"keribu","email":"Keri@bu.edu"},{"name":"timkingbuedu","email":"timking@bu.edu"},{"name":"hirozed","email":"npmjs@ziro88.com"},{"name":"acketon","email":"acketon@gmail.com"}],"contributors":[{"name":"Dakota Chichester","email":"acketon@bu.edu"}],"homepage":"https://github.com/bu-ist/bu-build-toolkit#readme","bugs":{"url":"https://github.com/bu-ist/bu-build-toolkit/issues"},"bin":{"bu-build":"bin/bu-build.js"},"dist":{"shasum":"6e4732aba2eb22b74c2a00b04ad04880d8c9a164","tarball":"https://registry.npmjs.org/@bostonuniversity/bu-build-toolkit/-/bu-build-toolkit-0.1.0.tgz","fileCount":23,"integrity":"sha512-PKK8yCU/GJ9PUIwvhJSgRLjRkVVEGz0whpcNkpTUSx8iodRgQpxyP+A/MNWq4EXErIP6/iVLAQFI+jd/zALhqA==","signatures":[{"sig":"MEUCIQC+Pch/5508X2Nuo7iQxOzoP3I5so+PlfyozKyNPP+gbgIgEkj1ddn7tBGjWzhbpf90sJDVM9jXGoPfarhgfJAhYsM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":98397},"main":"index.js","type":"module","gitHead":"6f2974b9034141ea3dbed7b934c8207bd93b1076","scripts":{},"_npmUser":{"name":"acketon","email":"acketon@gmail.com"},"repository":{"url":"git+https://github.com/bu-ist/bu-build-toolkit.git","type":"git"},"_npmVersion":"10.2.4","description":"A centralized set of build tools for compiling WordPress themes and plugins built on top of @wordpress/scripts and webpack","directories":{},"_nodeVersion":"20.11.0","dependencies":{"chalk":"^5.6.2","rimraf":"~5.0.5","nodemon":"~3.0.2","npm-run-all":"~4.1.5","node-wp-i18n":"~1.2.7","webpack-merge":"~5.10.0","@wordpress/scripts":"~31.2.0","copy-webpack-plugin":"~13.0.1","@wordpress/stylelint-config":"~21.33.0","webpack-remove-empty-scripts":"~1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@wordpress/eslint-plugin":"~23.0.0"},"optionalDependencies":{"sass-embedded":"~1.97.2"},"_npmOperationalInternal":{"tmp":"tmp/bu-build-toolkit_0.1.0_1769099759444_0.13617332043340635","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bostonuniversity/bu-build-toolkit","version":"0.1.1","keywords":["wordpress","webpack","build","toolkit"],"author":{"name":"Boston University"},"_id":"@bostonuniversity/bu-build-toolkit@0.1.1","maintainers":[{"name":"buweb","email":"webteam@bu.edu"},{"name":"jdub233","email":"tamlin@mac.com"},{"name":"dannycrews","email":"dancrews@me.com"},{"name":"rfera213","email":"rfera213@bu.edu"},{"name":"keribu","email":"Keri@bu.edu"},{"name":"timkingbuedu","email":"timking@bu.edu"},{"name":"hirozed","email":"npmjs@ziro88.com"},{"name":"acketon","email":"acketon@gmail.com"}],"contributors":[{"name":"Dakota Chichester","email":"acketon@bu.edu"}],"homepage":"https://github.com/bu-ist/bu-build-toolkit#readme","bugs":{"url":"https://github.com/bu-ist/bu-build-toolkit/issues"},"bin":{"bu-build":"bin/bu-build.js"},"dist":{"shasum":"afde7419e187a68e5482fbf4b00b84321c17d5b3","tarball":"https://registry.npmjs.org/@bostonuniversity/bu-build-toolkit/-/bu-build-toolkit-0.1.1.tgz","fileCount":23,"integrity":"sha512-nnTY5j+rpPf3OhwombMSVdofbEoccPFZqQUfEocblzNSvG1EsHr6pL1S7CzQ5kBuy5KimRTZjKTC/gkJaEJ2nA==","signatures":[{"sig":"MEQCIEntjNlwsCmnmwkW8voFzjrWbsqMIfUhHrot9ffO2TktAiASNdQS/qdXJw377KmSkm/7MHkYcf3rMTJQJ0P20doKrg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":98426},"main":"index.js","type":"module","gitHead":"b972b4c1b0ee449733f4016b2d7b2785c15c9e8b","scripts":{},"_npmUser":{"name":"acketon","email":"acketon@gmail.com"},"repository":{"url":"git+https://github.com/bu-ist/bu-build-toolkit.git","type":"git"},"_npmVersion":"10.2.4","description":"A centralized set of build tools for compiling WordPress themes and plugins built on top of @wordpress/scripts and webpack","directories":{},"_nodeVersion":"20.11.0","dependencies":{"chalk":"~5.6.2","rimraf":"~5.0.5","nodemon":"~3.0.2","npm-run-all":"~4.1.5","webpack-cli":"~6.0.1","node-wp-i18n":"~1.2.7","webpack-merge":"~5.10.0","@wordpress/scripts":"~31.2.0","copy-webpack-plugin":"~13.0.1","@wordpress/stylelint-config":"~23.30.0","webpack-remove-empty-scripts":"~1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@wordpress/eslint-plugin":"~23.0.0"},"optionalDependencies":{"sass-embedded":"~1.97.2"},"_npmOperationalInternal":{"tmp":"tmp/bu-build-toolkit_0.1.1_1769101555672_0.4720731133072713","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@bostonuniversity/bu-build-toolkit","version":"0.1.2","keywords":["wordpress","webpack","build","toolkit"],"author":{"name":"Boston University"},"_id":"@bostonuniversity/bu-build-toolkit@0.1.2","maintainers":[{"name":"buweb","email":"webteam@bu.edu"},{"name":"jdub233","email":"tamlin@mac.com"},{"name":"dannycrews","email":"dancrews@me.com"},{"name":"rfera213","email":"rfera213@bu.edu"},{"name":"keribu","email":"Keri@bu.edu"},{"name":"timkingbuedu","email":"timking@bu.edu"},{"name":"hirozed","email":"npmjs@ziro88.com"},{"name":"acketon","email":"acketon@gmail.com"}],"contributors":[{"name":"Dakota Chichester","email":"acketon@bu.edu"}],"homepage":"https://github.com/bu-ist/bu-build-toolkit#readme","bugs":{"url":"https://github.com/bu-ist/bu-build-toolkit/issues"},"bin":{"bu-build":"bin/bu-build.js"},"dist":{"shasum":"5a67053deaa42de983cb27c1f1f428ebd7f07a75","tarball":"https://registry.npmjs.org/@bostonuniversity/bu-build-toolkit/-/bu-build-toolkit-0.1.2.tgz","fileCount":23,"integrity":"sha512-gilTnGwUzhdlU9EQjkRmvjudb/fKxnyKspyA3lex+0icFK/rFJun9Yy3fdyVVcGScMmZbYEO46JENxQ8tCF+Fw==","signatures":[{"sig":"MEUCIQCVLUY5une/2mgzygjDFLbrGieUOCcf6/5QiwO7Tb7G/AIgZXGuyDwYKMwNOnAs7nKg85LiIttBg4DQkhohy+7UJg4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":98552},"main":"index.js","type":"module","gitHead":"b972b4c1b0ee449733f4016b2d7b2785c15c9e8b","scripts":{},"_npmUser":{"name":"acketon","email":"acketon@gmail.com"},"repository":{"url":"git+https://github.com/bu-ist/bu-build-toolkit.git","type":"git"},"_npmVersion":"10.2.4","description":"A centralized set of build tools for compiling WordPress themes and plugins built on top of @wordpress/scripts and webpack","directories":{},"_nodeVersion":"20.11.0","dependencies":{"chalk":"~5.6.2","rimraf":"~5.0.5","nodemon":"~3.0.2","npm-run-all":"~4.1.5","webpack-cli":"~6.0.1","node-wp-i18n":"~1.2.7","webpack-merge":"~5.10.0","@wordpress/scripts":"~31.2.0","copy-webpack-plugin":"~13.0.1","@wordpress/stylelint-config":"~23.30.0","webpack-remove-empty-scripts":"~1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@wordpress/eslint-plugin":"~23.0.0"},"optionalDependencies":{"sass-embedded":"~1.97.2"},"_npmOperationalInternal":{"tmp":"tmp/bu-build-toolkit_0.1.2_1769103206530_0.45755303194062735","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@bostonuniversity/bu-build-toolkit","version":"0.1.3","keywords":["wordpress","webpack","build","toolkit"],"author":{"name":"Boston University"},"_id":"@bostonuniversity/bu-build-toolkit@0.1.3","maintainers":[{"name":"buweb","email":"webteam@bu.edu"},{"name":"jdub233","email":"tamlin@mac.com"},{"name":"dannycrews","email":"dancrews@me.com"},{"name":"rfera213","email":"rfera213@bu.edu"},{"name":"keribu","email":"Keri@bu.edu"},{"name":"timkingbuedu","email":"timking@bu.edu"},{"name":"hirozed","email":"npmjs@ziro88.com"},{"name":"acketon","email":"acketon@gmail.com"}],"contributors":[{"name":"Dakota Chichester","email":"acketon@bu.edu"}],"homepage":"https://github.com/bu-ist/bu-build-toolkit#readme","bugs":{"url":"https://github.com/bu-ist/bu-build-toolkit/issues"},"bin":{"bu-build":"bin/bu-build.js"},"dist":{"shasum":"30499a529ce89fa65c039f966bd989326cc1f988","tarball":"https://registry.npmjs.org/@bostonuniversity/bu-build-toolkit/-/bu-build-toolkit-0.1.3.tgz","fileCount":23,"integrity":"sha512-Wm/rR722ht3vW1TrHfx+nPPZd9FAPUrsvU6I3k228B7tnw0gszF+NVX3YQiMRbxnvC+c2MNRQTbSGI6vGrYl4A==","signatures":[{"sig":"MEUCIBJl0qKIt+PVTgYpLlkBrSGo8g5OfXyNJMf4W8rYeAkZAiEAgO2FfRxpWXiwdEZpAIIjV49y8a2geVdWasf/DEcP+lI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":100227},"main":"index.js","type":"module","gitHead":"9172eb9c7b1e23ea40cd6bf1b0241525b1fe7958","scripts":{},"_npmUser":{"name":"acketon","email":"acketon@gmail.com"},"repository":{"url":"git+https://github.com/bu-ist/bu-build-toolkit.git","type":"git"},"_npmVersion":"10.2.4","description":"A centralized set of build tools for compiling WordPress themes and plugins built on top of @wordpress/scripts and webpack","directories":{},"_nodeVersion":"20.11.0","dependencies":{"chalk":"~5.6.2","rimraf":"~5.0.5","nodemon":"~3.0.2","npm-run-all":"~4.1.5","webpack-cli":"~6.0.1","node-wp-i18n":"~1.2.7","webpack-merge":"~5.10.0","@wordpress/scripts":"~31.2.0","copy-webpack-plugin":"~13.0.1","@wordpress/stylelint-config":"~23.30.0","webpack-remove-empty-scripts":"~1.0.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@wordpress/eslint-plugin":"~23.0.0"},"optionalDependencies":{"sass-embedded":"~1.97.2"},"_npmOperationalInternal":{"tmp":"tmp/bu-build-toolkit_0.1.3_1769811145049_0.6496674570355412","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@bostonuniversity/bu-build-toolkit","version":"0.1.4","description":"A centralized set of build tools for compiling WordPress themes and plugins built on top of @wordpress/scripts and webpack","type":"module","main":"index.js","bin":{"bu-build":"bin/bu-build.js"},"scripts":{},"keywords":["wordpress","webpack","build","toolkit"],"author":{"name":"Boston University"},"contributors":[{"name":"Dakota Chichester","email":"acketon@bu.edu"}],"repository":{"type":"git","url":"git+https://github.com/bu-ist/bu-build-toolkit.git"},"dependencies":{"@wordpress/scripts":"~31.2.0","@wordpress/stylelint-config":"~23.30.0","chalk":"~5.6.2","copy-webpack-plugin":"~13.0.1","node-wp-i18n":"~1.2.7","nodemon":"~3.0.2","npm-run-all":"~4.1.5","rimraf":"~5.0.5","webpack-cli":"~6.0.1","webpack-merge":"~5.10.0","webpack-remove-empty-scripts":"~1.0.4"},"optionalDependencies":{"sass-embedded":"~1.97.2"},"devDependencies":{"@wordpress/eslint-plugin":"~23.0.0"},"publishConfig":{"access":"public"},"_id":"@bostonuniversity/bu-build-toolkit@0.1.4","gitHead":"e8dae58bd92dd4fe4bb5b8e197ada02f33e5d4f2","bugs":{"url":"https://github.com/bu-ist/bu-build-toolkit/issues"},"homepage":"https://github.com/bu-ist/bu-build-toolkit#readme","_nodeVersion":"20.11.0","_npmVersion":"10.2.4","dist":{"integrity":"sha512-BSJBhRSodHwws5OpBfknvrAeTjuCcEUMo/eDff4riXDFnT8cHpp0ZGRPskVzXMmlAm/kVhpezVjXJEeRo0Z2bw==","shasum":"67ee02b78ea599b35781c1ad294994dd3792709c","tarball":"https://registry.npmjs.org/@bostonuniversity/bu-build-toolkit/-/bu-build-toolkit-0.1.4.tgz","fileCount":23,"unpackedSize":100438,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAJj/yTtwsOOIYVk3P1KaN+QmpKx+JOFXLoXfI6l011bAiEAuwdqd6KsTuvNnVoOEOk3JZqV9SwH4QXVh8nLllgom4Q="}]},"_npmUser":{"name":"acketon","email":"acketon@gmail.com"},"directories":{},"maintainers":[{"name":"buweb","email":"webteam@bu.edu"},{"name":"jdub233","email":"tamlin@mac.com"},{"name":"dannycrews","email":"dancrews@me.com"},{"name":"rfera213","email":"rfera213@bu.edu"},{"name":"keribu","email":"Keri@bu.edu"},{"name":"timkingbuedu","email":"timking@bu.edu"},{"name":"hirozed","email":"npmjs@ziro88.com"},{"name":"acketon","email":"acketon@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/bu-build-toolkit_0.1.4_1770232271556_0.06815780627360457"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-22T16:35:59.365Z","modified":"2026-02-04T19:11:12.028Z","0.1.0":"2026-01-22T16:35:59.616Z","0.1.1":"2026-01-22T17:05:55.830Z","0.1.2":"2026-01-22T17:33:26.666Z","0.1.3":"2026-01-30T22:12:25.217Z","0.1.4":"2026-02-04T19:11:11.760Z"},"bugs":{"url":"https://github.com/bu-ist/bu-build-toolkit/issues"},"author":{"name":"Boston University"},"homepage":"https://github.com/bu-ist/bu-build-toolkit#readme","keywords":["wordpress","webpack","build","toolkit"],"repository":{"type":"git","url":"git+https://github.com/bu-ist/bu-build-toolkit.git"},"description":"A centralized set of build tools for compiling WordPress themes and plugins built on top of @wordpress/scripts and webpack","contributors":[{"name":"Dakota Chichester","email":"acketon@bu.edu"}],"maintainers":[{"name":"buweb","email":"webteam@bu.edu"},{"name":"jdub233","email":"tamlin@mac.com"},{"name":"dannycrews","email":"dancrews@me.com"},{"name":"rfera213","email":"rfera213@bu.edu"},{"name":"keribu","email":"Keri@bu.edu"},{"name":"timkingbuedu","email":"timking@bu.edu"},{"name":"hirozed","email":"npmjs@ziro88.com"},{"name":"acketon","email":"acketon@gmail.com"}],"readme":"# BU Build Toolkit\n\nA centralized set of build tools for compiling WordPress themes and plugins, built on top of `@wordpress/scripts` and Webpack. This toolkit maintains all build dependencies and configuration in one place, eliminating the need to manage these in each individual theme or plugin repository.\n\nEach major version of this Toolkit should be well documented with what setup is needed in each theme or plugin repo as well as instructions on how to update a repo to the next major version of this toolkit. \n\nThe toolkit should NOT make changes that would break or alter the generated output of a theme or plugin except in major versions.\n\n## Features\n\n- **Centralized Dependencies**: All build-related dependencies (`@wordpress/scripts`, webpack, loaders, plugins) are managed in this single package\n- **Tested Configuration**: Webpack, Babel, ESLint, and Stylelint.\n- **Easy Integration**: Themes/plugins only need minimal configuration (entry points and theme-specific settings)\n- **Consistent Builds**: Ensures all BU themes and plugins use the same build process and tooling versions\n\n\n## Installation\n\nIn your theme or plugin:\n\n```bash\nnpm install --save-dev @bostonuniversity/bu-build-toolkit\n```\n\n## Requirements\n\nThis toolkit uses **ESM (ECMAScript Modules)** internally, but your theme's `webpack.config.js` can use **CommonJS** with async dynamic imports (see example below). This avoids needing `\"type\": \"module\"` in your theme's package.json.\n\nCreate this file in your theme or plugin root:\n- `webpack.config.js`\n\n## Usage\n\n### 1. Create a webpack configuration file\n\nCreate a `webpack.config.js` in your theme/plugin root:\n\n```javascript\n// Define your theme's entry points\nconst themeEntryPoints = {\n\t// Styles\n\t'css/normalize': './src/scss/normalize.scss',\n\t'css/theme': './src/scss/theme.scss',\n\t'css/admin': './src/scss/admin.scss',\n\t'css/editor-styles': './src/scss/editor-styles.scss',\n\t'css/block-editor': './src/scss/block-editor.scss',\n\t'css/classic-editor': './src/scss/classic-editor.scss',\n\t\n\t// Blocks\n\t'css/blocks/blocks-bundled': './src/blocks/blocks-bundled.scss',\n\t'css/blocks/blocks-common': './src/blocks/blocks-common.scss',\n\t\n\t// Scripts\n\t'js/theme': './src/js/theme.js',\n\t'js/admin': './src/js/admin.js',\n\t'js/block-editor': './src/js/block-editor.js',\n\t'js/classic-editor': './src/js/classic-editor.js',\n};\n\n// Export async config to dynamically import the ESM toolkit\n// Webpack supports async configs that return promises\nmodule.exports = ( async () => {\n\tconst { createConfig } = await import( '@bostonuniversity/bu-build-toolkit' );\n\t\n\treturn createConfig( {\n\t\tthemeEntryPoints, // Passes the entrypoints unique to this repo to the webpack config.\n\t} );\n} )();\n```\n\n**Note:** This uses CommonJS with dynamic `import()` to load the ESM toolkit, avoiding the need for `\"type\": \"module\"` in your package.json or `.mjs` file extensions.\n\n### 2. Configure your package.json\n\nThe toolkit provides a `bu-build` CLI that handles all common build tasks. Add these scripts to your theme's package.json:\n\n```json\n{\n  \"scripts\": {\n    \"postinstall\": \"cd node_modules/@bostonuniversity/bu-build-toolkit && composer install\",\n    \"check-engines\": \"bu-build check-engines\",\n    \"check-licenses\": \"bu-build check-licenses\",\n    \"start\": \"bu-build start\",\n    \"watch:scripts\": \"bu-build watch:scripts\",\n    \"watch:theme-json\": \"bu-build watch:theme-json\",\n    \"format\": \"bu-build format\",\n    \"lint\": \"bu-build lint\",\n    \"lint:css\": \"bu-build lint:css\",\n    \"lint:js\": \"bu-build lint:js\",\n    \"lint:js:fix\": \"bu-build lint:js:fix\",\n    \"lint:md\": \"bu-build lint:md\",\n    \"lint:pkg\": \"bu-build lint:pkg\",\n    \"lint:php\": \"bu-build lint:php\",\n    \"lint:php:all\": \"bu-build lint:php:all\",\n    \"test:e2e\": \"bu-build test:e2e\",\n    \"test:unit\": \"bu-build test:unit\",\n    \"build\": \"bu-build build\",\n    \"build:scripts\": \"bu-build build:scripts\",\n    \"build:theme-json\": \"bu-build build:theme-json\",\n    \"build:i18n\": \"bu-build build:i18n\",\n    \"build:clean\": \"bu-build build:clean\",\n    \"build:wpi18n\": \"bu-build build:wpi18n\",\n    \"build:wpmakepot\": \"bu-build build:wpmakepot\",\n    \"build:version\": \"bu-build build:version\"\n  },\n  \"devDependencies\": {\n    \"@bostonuniversity/bu-build-toolkit\": \"^0.1.0\"\n  }\n}\n```\n\n**Note:** The `postinstall` script ensures PHP dependencies (like PHP_CodeSniffer for linting) are installed automatically.\n\nThis will install composer.json from the bu-build-toolkit repo installed in your project's node_modules folder and should\ninstall PHPCS to get linting working for PHP files. \n\n\n**Theme.json Compilation** (automatic, no script needed):\n\nIf your theme has a `src/theme-json/` directory with modular files, the toolkit automatically compiles them:\n\n```\nsrc/theme-json/\n  ├── config.mjs       (or .js) - Version, customTemplates, templateParts\n  ├── settings.mjs     (or .js) - Colors, typography, spacing, etc.\n  └── styles.mjs       (or .js) - Element styles\n```\n\nThe toolkit will automatically detect this directory and:\n- Compile to `theme.json` during build\n- Watch for changes during development\n- Merge config → settings → styles in that order\n\nThe `bu-build` CLI automatically provides:\n- Theme.json compilation and watch (if `src/theme-json/` exists)\n- Version management (`build:version`) - updates style.css and theme.css\n- PHP linting (`lint:php`, `lint:php:all`) - uses toolkit's phpcs dependencies\n\n### 3. Copy config files (optional)\n\nThe toolkit includes config files that you can reference or copy:\n\n**Babel**: Copy `node_modules/@bostonuniversity/bu-build-toolkit/config/babel.config.js` to your theme root if you need to customize\n\n**ESLint**: Copy or extend from `node_modules/@bostonuniversity/bu-build-toolkit/config/.eslintrc.json`\n\n**Stylelint**: Copy or extend from `node_modules/@bostonuniversity/bu-build-toolkit/config/.stylelintrc`\n\n**SVGO**: Reference from `node_modules/@bostonuniversity/bu-build-toolkit/config/svgo.config.js`\n\n**PHPCS**: Extend from `node_modules/@bostonuniversity/bu-build-toolkit/config/.phpcs.xml.dist` (see PHP Linting Setup below)\n\nOr reference the defaults provided by this toolkit directly in your package.json:\n\n```json\n{\n  \"eslintConfig\": {\n    \"extends\": \"./node_modules/@bostonuniversity/bu-build-toolkit/config/.eslintrc.json\"\n  },\n  \"stylelint\": {\n    \"extends\": \"./node_modules/@bostonuniversity/bu-build-toolkit/config/.stylelintrc\"\n  },\n  \"svgo\": \"./node_modules/@bostonuniversity/bu-build-toolkit/config/svgo.config.js\"\n}\n```\n\n## Advanced Configuration\n\n### Custom SASS Include Paths\n\nSASS is compiled by @wordpress/scripts which includes `sass-loader`. If your project\nloads imports SASS partials from locations such as node_modules you may need to include\nthose paths so SASS knows to look for partials there. We do this in Responsive Foundation\npartials loaded into child themes. We also use it for common packages like FontAwesome. \n\nAdd additional SASS include paths:\n\n```javascript\nimport { createConfig } from '@bostonuniversity/bu-build-toolkit';\n\nexport default createConfig( {\n\tthemeEntryPoints: { /* your entries */ },\n\tloadPaths: [\n\t\t'./custom/sass/path',\n\t],\n} );\n```\n\n### Custom SASS Options\n\nOverride SASS compiler options:\n\n```javascript\nimport { createConfig } from '@bostonuniversity/bu-build-toolkit';\n\nexport default createConfig( {\n\tthemeEntryPoints: { /* your entries */ },\n\tsassOptions: {\n\t\toutputStyle: 'compressed',\n\t},\n} );\n```\n\n### Different SASS Compiler\nBy default `sass-loader` (within Webpack) will automatically choose which SASS \ncompiler to use. If `sass-embedded` is set as an `optionalDependency` package and\nworks on your system it will be used. `sass-embedded` is usually faster as it runs\nas native code on your system instead of a Javascript implementation. However it\ndoes not work on all operating systems and CPU's. \n\nThere are times where a theme developer may need to force a specific SASS\ncompiler: `sass` (dart-sass in JS), `sass-embedded` (dart-sass but native code), or\n`node-sass`. If so you can specify the `sassCompiler` to use and the toolkit will\npass this to `sass-loader`. \n\nSwitch between `sass-embedded` (default, faster) and `sass`, or `node-sass`:\n\n```javascript\nimport { createConfig } from '@bostonuniversity/bu-build-toolkit';\n\nexport default createConfig( {\n\tthemeEntryPoints: { /* your entries */ },\n\tsassCompiler: 'sass', // or 'sass-embedded'\n} );\n```\n\n### Custom Webpack Stats\nStats is for controling the output logged to the terminal. This can be modified in \nyour project if needed. \n\nModify webpack output statistics:\n\n```javascript\nimport { createConfig } from '@bostonuniversity/bu-build-toolkit';\n\nexport default createConfig( {\n\tthemeEntryPoints: { /* your entries */ },\n\tstatsConfig: {\n\t\tpreset: 'verbose',\n\t\tcolors: true,\n\t},\n} );\n```\n\n## What's Included\n\n### Dependencies\n- `@wordpress/scripts` - WordPress build scripts (includes webpack, css-loader, sass-loader, etc.)\n- `@wordpress/stylelint-config` - WordPress Stylelint configuration\n- `webpack-merge` - Merge webpack configurations\n- `sass-embedded` - Fast SASS compiler\n- `webpack-remove-empty-scripts` - Removes empty JS files from CSS-only entries\n- `npm-run-all` - Run multiple npm scripts in parallel or sequentially\n- `nodemon` - Watch files for changes and re-run commands\n- `rimraf` - Cross-platform file/directory removal\n- `node-wp-i18n` - WordPress internationalization tools (makepot, addtextdomain)\n\n### PHP Dependencies (Composer)\n- `wp-coding-standards/wpcs` - WordPress Coding Standards for PHP_CodeSniffer\n- `phpcompatibility/phpcompatibility-wp` - PHP version compatibility checker\n- `phpcsstandards/phpcsutils` - Utilities for PHP_CodeSniffer\n- `dealerdirect/phpcodesniffer-composer-installer` - Automatic installation of coding standards\n\n### Default Configurations\n- **Babel**: React and modern JavaScript support\n- **ESLint**: WordPress coding standards\n- **Stylelint**: SCSS linting with WordPress standards\n- **Webpack**: Optimized for WordPress block development and theme builds\n\n### Default SASS Include Paths\n- `.` - Allow imports like: `@import 'node_modules/@fortawesome/...'`\n- `./node_modules` - Allow imports like: `@import '@fortawesome/...'`\n- `./node_modules/normalize-scss/sass`\n- `./node_modules/mathsass/dist/`\n- `./node_modules/@bostonuniversity`\n\n## CLI Commands\n\nThe `bu-build` CLI provides all common build commands:\n\n### Development\n- `bu-build start` - Start development mode with watch (auto-detects and compiles theme.json if `src/theme-json/` exists)\n- `bu-build watch:scripts` - Watch and build scripts only (with filtered output)\n- `bu-build watch:theme-json` - Watch and compile theme.json only\n- `bu-build watch:verbose` - Watch with full webpack output\n\n### Building\n- `bu-build build` - Production build (auto-detects theme.json, runs i18n, version update)\n- `bu-build build:scripts` - Build scripts only (with filtered output)\n- `bu-build build:theme-json` - Compile theme.json only\n- `bu-build build:verbose` - Build with full webpack output\n- `bu-build build:version` - Update version in style.css and theme.css\n- `bu-build build:i18n` - Build internationalization files (clean, addtextdomain, makepot)\n- `bu-build build:clean` - Clean language files\n- `bu-build build:wpi18n` - Add text domain to PHP files\n- `bu-build build:wpmakepot` - Generate POT file\n\n### Linting\n- `bu-build lint` - Run all linters (CSS, JS, Markdown, package.json, PHP)\n- `bu-build lint:css` - Lint CSS/SCSS\n- `bu-build lint:js` - Lint JavaScript\n- `bu-build lint:js:fix` - Fix JavaScript linting issues (ignores `/dev/` folder)\n- `bu-build lint:md` - Lint Markdown\n- `bu-build lint:pkg` - Lint package.json\n- `bu-build lint:php` - Lint modified PHP files (uses phpcbf + phpcs)\n- `bu-build lint:php:all` - Lint all PHP files (not just modified)\n\n### Testing\n- `bu-build test:e2e` - Run end-to-end tests\n- `bu-build test:unit` - Run unit tests\n\n### Other\n- `bu-build format` - Format code with Prettier\n- `bu-build check-engines` - Check Node/npm versions match requirements\n- `bu-build check-licenses` - Check dependency licenses\n\n### Benefits of the CLI\n\n1. **Filtered Output**: Build and watch commands automatically filter out verbose webpack stack traces\n2. **Theme.json Compilation**: Automatically compiles modular theme.json files from `src/theme-json/`\n3. **PHP Linting**: Built-in phpcs integration with WordPress coding standards\n4. **Parallel Execution**: Runs multiple tasks in parallel when appropriate (e.g., `watch:scripts` + `watch:theme-json`)\n5. **Sequential Builds**: Runs build steps in the correct order\n6. **Consistent Behavior**: Same commands work across all themes\n\n## Local Development\n\nFor local toolkit development, use the `file:` protocol in your test theme's package.json:\n\n```json\n{\n  \"devDependencies\": {\n    \"@bostonuniversity/bu-build-toolkit\": \"file:../bu-build-toolkit\"\n  }\n}\n```\n\nAfter making changes to the toolkit, run `npm install` in your theme to pick up the updates.\n\n**How it works:** The toolkit uses `resolveLoader` in its webpack configuration to ensure loaders are found in both scenarios:\n- **Production** (npm install): Loaders are hoisted to `theme/node_modules/` by npm\n- **Development** (file: install): Loaders remain in `toolkit/node_modules/` and are resolved via `resolveLoader.modules`\n\nThis approach allows the toolkit to use WordPress's default webpack configuration without overriding rules, minimizing maintenance burden when @wordpress/scripts updates.\n\n### Debugging Build Errors\n\nWhen webpack errors overflow your terminal buffer, save output to a file while viewing it in real-time:\n\n**Mac/Linux (using tee):**\n```bash\nbu-build build 2>&1 | tee build.log\nbu-build start 2>&1 | tee dev.log\n```\n\n**Windows (redirect only):**\n```bash\nbu-build build > build.log 2>&1\nbu-build start > dev.log 2>&1\n```\n\n**Using npm scripts:**\n```bash\n# Add to your package.json:\n\"build:log\": \"bu-build build 2>&1 | tee build.log\"  # Mac/Linux\n\"build:log\": \"bu-build build > build.log 2>&1\"     # Windows\n\n# Then run:\nnpm run build:log\n```\n\nThe log file will contain complete output including:\n- Full webpack stats and configuration\n- Complete error stack traces\n- All module resolution details\n\n**Reading log files in the terminal:**\n\nThe log file contains ANSI color codes that may not display correctly in VS Code. Use terminal commands to view the colorized output:\n\n```bash\n# View the entire log file with colors\ncat build.log\n\n# Page through the log with colors preserved\nless -R build.log\n\n# View the last 50 lines\ntail -n 50 build.log\n\n# Search for specific errors\ngrep -i \"error\" build.log\ngrep -i \"failed\" build.log\n```\n\n## PHP Linting Setup\n\nThe toolkit includes PHP_CodeSniffer with WordPress Coding Standards. To use it:\n\n### 1. Install Composer Dependencies\n\nThe toolkit's `composer.json` includes all necessary PHP linting dependencies. Install them:\n\n```bash\ncd node_modules/@bostonuniversity/bu-build-toolkit && composer install\n```\n\nOr add to your theme's `postinstall` script:\n\n```json\n{\n  \"scripts\": {\n    \"postinstall\": \"cd node_modules/@bostonuniversity/bu-build-toolkit && composer install\"\n  }\n}\n```\n\n### 2. Create `.phpcs.xml.dist`\n\nCreate a minimal config file in your theme root that extends the toolkit's base standards:\n\n```xml\n<?xml version=\"1.0\"?>\n<ruleset name=\"My Theme PHP Standards\">\n\t<!-- Extend BU base standards from the toolkit -->\n\t<rule ref=\"./node_modules/@bostonuniversity/bu-build-toolkit/config/.phpcs.xml.dist\"/>\n\n\t<!-- Theme-specific prefix configuration -->\n\t<rule ref=\"WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedNamespaceFound\">\n\t\t<properties>\n\t\t\t<property name=\"prefixes\" type=\"array\">\n\t\t\t\t<element value=\"BU\\MyTheme\"/>\n\t\t\t</property>\n\t\t</properties>\n\t</rule>\n\n\t<rule ref=\"WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedVariableFound\">\n\t\t<properties>\n\t\t\t<property name=\"prefixes\" type=\"array\">\n\t\t\t\t<element value=\"MY_THEME\"/>\n\t\t\t</property>\n\t\t</properties>\n\t</rule>\n\n\t<rule ref=\"WordPress.WP.I18n\">\n\t\t<properties>\n\t\t\t<property name=\"text_domain\" type=\"array\" value=\"my-theme\"/>\n\t\t</properties>\n\t</rule>\n</ruleset>\n```\n\n### 3. Use the Commands\n\n```bash\nnpm run lint:php        # Lint modified PHP files\nnpm run lint:php:all    # Lint all PHP files\nnpm run lint            # Lint everything (JS, CSS, PHP, etc.)\n```\n\nThe PHP linter:\n- Auto-fixes issues with `phpcbf` where possible\n- Reports remaining issues with `phpcs`\n- Checks WordPress coding standards\n- Verifies PHP 7.4+ compatibility\n- Validates text domain usage\n\n### VSCode Integration\n\nThe toolkit installs PHPCS in `node_modules/@bostonuniversity/bu-build-toolkit/` rather than the project root. This approach works with certain VSCode extensions that support configuring the path to composer.json and PHPCS binaries.\n\n#### Compatible Extensions\n\n**PHP Sniffer & Beautifier (phpsab)** - This extension supports configuring the composer.json path to point to the toolkit's location.\n\nTo configure phpsab for use with the bu-build-toolkit:\n\n1. Install the [PHP Sniffer & Beautifier](https://marketplace.visualstudio.com/items?itemName=brapifra.phpsab) extension. (https://marketplace.visualstudio.com/items?itemName=obliviousharmony.vscode-php-codesniffer also works but has not been updated as recently)\n2. Add the following to your `.vscode/settings.json`:\n\n```json\n{\n  \"phpsab.snifferEnable\": true,\n  \"phpsab.composerJsonPath\": \"./node_modules/@bostonuniversity/bu-build-toolkit/composer.json\",\n  \"phpsab.fixerEnable\": true,\n}\n```\n\n**Note:** Other PHPCS extensions may not support this configuration and require PHPCS to be installed in the project root. The bu-build-toolkit's approach centralizes PHPCS management but may not be compatible with all VSCode extensions. \n\nThe [PHPCS extension by shevaua](https://marketplace.visualstudio.com/items?itemName=shevaua.phpcs) does NOT support this setup. That extension hasn't been updated in 6 years and should not be used: \n\n## Migration from Theme-Based Configuration\n\nIf you're migrating from a theme that has its own build configuration:\n\n1. **Install the toolkit**: `npm install --save-dev @bostonuniversity/bu-build-toolkit`\n\n2. **Create webpack.config.js**: Copy your `themeEntryPoints` from `webpack.customizations.js` into the new format shown above\n\n3. **Remove old dependencies**: You can remove these from your theme's package.json (they're now provided by the toolkit):\n   - `@wordpress/scripts`\n   - `@wordpress/stylelint-config`\n   - `webpack-merge`\n   - `webpack-remove-empty-scripts`\n   - `sass-embedded` or `sass`\n   - `npm-run-all`\n   - `nodemon`\n   - `rimraf`\n   - `node-wp-i18n`\n   \n4. **Simplify PHP linting**: Remove your theme's `composer.json` and replace with toolkit's version:\n   - Use `postinstall` to install toolkit's composer dependencies\n   - Create minimal `.phpcs.xml.dist` extending toolkit's base (see PHP Linting Setup above)\n   - Remove `dev/phpcs/lint-*.sh` scripts (now in toolkit as `bu-build lint:php`)\n\n5. **Update scripts**: Replace theme-specific scripts with `bu-build` commands in package.json\n\n6. **Test**: Run `npm run build` and `npm run start` to verify everything works\n\n## Troubleshooting\n\n### Error Messages in the Terminal\n\nWebpack can produce very long error messages and logging at times. This toolkit attempts to reduce the\namount that is output but occassionally large amounts of source code will be output to the terminal when\na build error occurs. The default Terminal scroll buffer or scrollback setting might not be large enough\nand you may see the terminal output be overridden. \n\nThis can mean you don't see the entire error message as it has been replaced with source code of limited \nutility. \n\nYou can make this better by editing the settings for the terminal scrollback or buffer in your IDE or \nTerminal app so you can scroll back and see the entire output from Webpack. \n\nSee: [VSCode Terminal Buffer Setting](https://code.visualstudio.com/docs/terminal/basics#_navigating-the-buffer)\n\n### SASS Include Paths Not Working\n\nEnsure you're passing `loadPaths` correctly in your config, or use the theme's `node_modules` path.\n\n**Note:** sass-loader v16+ uses `loadPaths` (modern API) instead of `includePaths` (legacy API).\n\n### Blocks Not Building\n\nThe toolkit automatically detects blocks via `block.json` files. Ensure your blocks follow the standard WordPress block structure.\n\n### Build Performance\n\nThe toolkit uses `sass-embedded` by default for faster builds on macOS. If you experience issues, switch to `sass` via the `sassCompiler` option.\n","readmeFilename":"README.md"}