Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →wp-scripts is the official WordPress JavaScript build toolkit, distributed as the @wordpress/scripts npm package. Install it as a development dependency, add start and build scripts to package.json, then use npm run start while developing and npm run build to create optimized assets for deployment. It supplies a maintained webpack and Babel configuration, understands WordPress block projects, and can be adapted for plugins, themes, custom entry points, and non-standard source directories.
Antihost offers managed WordPress hosting with free migration, one-click staging and a 14-day free trial.
What wp-scripts does
The @wordpress/scripts package, commonly called wp-scripts, standardizes the JavaScript build process for WordPress projects that need a compilation step. It transforms modern JavaScript and JSX, bundles modules, and produces browser-compatible output without requiring every project to design its own webpack configuration.
As an Amazon Associate I earn from qualifying purchases.
That matters when your source uses JSX, modern syntax, multiple modules, or WordPress packages that should not be bundled into your application. Instead of maintaining a complete Babel and webpack stack yourself, you start with the configuration WordPress maintains and customize it only where your project needs different behavior.
wp-scripts began with block development and has evolved to support broader WordPress work, including theme assets. It is appropriate for a block plugin, a plugin with an admin interface, a theme with compiled JavaScript and styles, or any project in which source files must become deployable browser assets.
Prerequisites and version compatibility
Install Node.js and npm before creating the project. For @wordpress/scripts version 30.20.0, the package metadata lists these minimum engines:
| Component | Minimum listed version | Qualification |
|---|---|---|
| Node.js | 18.12.0 or newer | Requirement stated in the 30.20.0 package metadata available in 2026 |
| npm | 8.19.2 or newer | Requirement stated in the same package metadata |
Engine requirements can change when you upgrade the package. Check the version actually installed in your project rather than assuming that a requirement from another release still applies. You can inspect your runtime with node --version and npm --version. If npm reports an engine mismatch, update Node and npm before debugging your JavaScript.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsInstall wp-scripts in a project
Run the installation from the directory that contains (or will contain) your package.json:
npm install @wordpress/scripts --save-devThe --save-dev flag records wp-scripts as a development dependency. Your server needs the generated files, not the build tool itself, so keeping the package in devDependencies separates authoring tools from runtime code.
Add named npm scripts to package.json:
{"scripts":{"start":"wp-scripts start","build":"wp-scripts build"}}Use those scripts from the project root:
npm run start
npm run buildOn a fresh installation, npm also creates node_modules and package-lock.json. Commit the lockfile so other developers and deployment systems resolve the same dependency tree. Do not commit node_modules unless your hosting process explicitly requires it.
Use the standard project layout
A conventional project has source files in src and generated files in build:
project/
├── src/
├── build/
├── node_modules/
├── package-lock.json
└── package.jsonFor a block project, a block.json file normally sits with the block source. wp-scripts can detect block metadata and use it to discover block entry points. The generated build directory is disposable: remove it and run a new build when you need to regenerate assets.
Keep authored code in the source directory and avoid editing compiled files by hand. A deployment package should contain the generated assets, the PHP that registers or enqueues them, and the metadata files required by that PHP.
Rank #2
Understand start versus build
npm run start: iterative development
wp-scripts start launches the development build and watches source files. When you save a JavaScript, JSX, or related source file, webpack rebuilds the affected output so you can continue working without manually running a command after every edit.
Leave the process running in a terminal while you develop. Stop it with the terminal interrupt command when you finish. This mode is for feedback and iteration; it is not the command to use for the final deployable bundle.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →npm run build: deployable output
wp-scripts build creates an optimized production build. It is the command to run before packaging a plugin or theme, uploading assets, or creating a release artifact. The command also creates build/index.asset.php. That PHP file records the WordPress script dependencies discovered during the build and includes a version value that can be used for cache busting when assets are enqueued.
Do not confuse the JavaScript bundle with its metadata. If your PHP enqueue code needs dependency information or a changing version, load the generated asset file rather than hard-coding a stale list. Regenerate the build whenever source changes, then ship the matching JavaScript and index.asset.php files together.
Choose and configure entry points
Pass entry files on the command line
For a project that does not follow the default block layout, pass entry files directly:
wp-scripts build entry-one.js entry-two.jsThe same form works with start when you need watch mode. Each supplied file is treated as an entry point; webpack resolves its imports and produces the corresponding compiled assets. Use explicit entries for separate front-end and admin bundles, independent theme applications, or a project whose source files are organized outside the conventional block structure.
Free tools Windows power users keep installed
One-click scans. No signup required.
Let block.json provide block entries
Block projects can use automatic block.json detection. The metadata identifies the block’s scripts and allows wp-scripts to discover entries without a long command-line list. This is usually the least fragile option when a plugin contains several blocks because each block keeps its metadata beside its source.
When automatic detection does not match your layout, use explicit entry arguments or a webpack configuration. Avoid mixing several discovery strategies until you know which files each strategy is selecting; duplicate entries can lead to confusing output and redundant bundles.
Rank #3
Extend the default webpack configuration
wp-scripts uses webpack behind the scenes. Most projects should keep its defaults, but a larger application may need aliases, an additional loader, a custom output rule, or a different set of entry points.
Place webpack.config.js or webpack.config.babel.js beside package.json. A common extension pattern imports the package’s default configuration and merges your project-specific settings:
const defaultConfig = require('@wordpress/scripts/config/webpack.config');
module.exports = {
...defaultConfig,
// Add only the entries, aliases, or rules your project requires.
};Keep the inherited configuration unless you have a deliberate reason to replace part of it. Replacing it wholesale can discard WordPress-oriented handling that your blocks or dependencies rely on. After every configuration change, run a production build and inspect the generated files rather than assuming that a successful command produced the intended entries.
Use a custom file when the default command-line options cannot express your layout or when several environments need the same build rules. For a single alternate source directory, the theme flags described below are usually simpler than maintaining a full configuration file.
Use wp-scripts in a theme
Theme projects can point wp-scripts at directories other than src and build. The Theme Handbook documents this pattern:
wp-scripts start --webpack-src-dir=resources --output-path=publicHere, source files live under resources and generated files are written to public. Use the same flags with build when producing the release output:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
wp-scripts build --webpack-src-dir=resources --output-path=publicMake the paths agree with your theme’s PHP. If PHP enqueues files from public while the build writes to build, the browser will receive missing or stale assets even though webpack completed successfully. Decide whether the generated directory belongs in the distributed theme and keep that decision consistent with your deployment process.
Theme support is not a separate package. It is the same wp-scripts workflow with source and output paths adjusted for the theme’s structure. The package originally targeted blocks, but its configuration and command-line options now accommodate theme asset pipelines as well.
Enqueue generated assets safely
WordPress needs PHP code that registers or enqueues the files produced by the build. The important detail is to use the generated asset metadata when it exists. The metadata supplies dependency handles and a version value, so your enqueue logic can track the bundle’s actual requirements and invalidate browser caches after a new build.
Keep the JavaScript file and its companion index.asset.php from the same build together. If you copy only the JavaScript or reuse metadata from an older build, dependency order and cache behavior can diverge from the bundle that users are running.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThe exact PHP path depends on whether the project is a plugin, a classic theme, or a block whose metadata registers scripts automatically. Test the enqueue on a clean WordPress installation and check the browser’s network and console panels for 404 responses, missing dependencies, and JavaScript errors.
Run quality checks supplied by the package
The package reference includes commands for common project checks, including JavaScript linting, style linting, formatting, and tests. These commands are versioned with wp-scripts, so inspect the reference for the package version in your lockfile before adding them to continuous integration.
A practical workflow is:
- Run the JavaScript and style linters while editing or before opening a pull request.
- Apply the formatter only when you intend to rewrite files; review the resulting diff.
- Run the available test command for the project type, then run a production build.
- Fail the build pipeline when a required check fails instead of deploying partially generated output.
Do not assume that a command documented for one major release has identical options in another. When updating wp-scripts, read its changelog and migration notes and adjust scripts deliberately.
Default wp-scripts or custom webpack?
Both approaches can produce WordPress assets, but they optimize for different priorities:
| Decision axis | Default wp-scripts | Custom webpack setup |
|---|---|---|
| Initial setup | Install one package and use the supplied commands. | Choose, install, and configure webpack, Babel, loaders, and plugins yourself. |
| Maintenance effort | WordPress maintains the shared configuration and command surface. | Your team owns configuration updates, compatibility fixes, and documentation. |
| Webpack control | Use defaults, command-line entry arguments, or an extension file for exceptions. | Full control over rules, plugins, aliases, optimization, and output. |
| WordPress dependency handling | Designed around WordPress package conventions and generated dependency metadata. | You must reproduce and maintain the dependency decisions your project needs. |
block.json detection |
Automatic block entry detection is available. | You must implement or configure equivalent discovery. |
| Theme directories | Source and output paths can be changed with flags such as --webpack-src-dir and --output-path. |
Directory behavior is entirely yours to define. |
| Linting and tests | The package reference provides commands for common checks. | Select and wire your own tools. |
| Upgrade burden | Follow wp-scripts changelog and migration guidance; defaults may evolve. | Fewer upstream assumptions, but every tool upgrade is your responsibility. |
Choose the default configuration when your project is a conventional block, plugin, or theme and you value a small maintenance surface. Choose an extensively customized webpack stack only when the project has requirements that wp-scripts cannot express without excessive overrides.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common problems and precise fixes
wp-scripts: command not found
Run the command through an npm script after installing the package locally. npm adds local binaries to the script path, so npm run start and npm run build should find wp-scripts without a global installation. If the error persists, confirm that installation completed and that the command is running in the directory containing package.json.
Node or npm engine errors
Compare the installed runtime with the requirements for your exact @wordpress/scripts version. For version 30.20.0, Node must be at least 18.12.0 and npm at least 8.19.2. Upgrade the runtime, reinstall dependencies, and retry. Do not suppress an engine warning and assume the resulting build is supported.
Changes are not rebuilding
Ensure that the watch process is running with npm run start, that you edited a file inside the configured source directory, and that your editor is not writing to a generated directory that webpack ignores. For a theme using resources, verify that the command includes --webpack-src-dir=resources.
Recommended Free Tools
The browser loads an old bundle
Run npm run build, deploy the newly generated JavaScript and its matching index.asset.php, and confirm that PHP uses the metadata version when enqueueing. A browser cache can preserve an older URL when the version value is hard-coded or the metadata file was not uploaded.
A script or dependency is missing
Inspect the compiled output and the browser network panel. Check that the intended file was selected as an entry, that imports resolve from the project, and that PHP enqueues the generated asset rather than a source file. For block projects, verify that block.json points to the expected script and that automatic detection is not being bypassed by a conflicting custom configuration.
A custom layout produces files in the wrong directory
Use one source/output strategy consistently. Either pass the theme directory flags on both start and build, or define the paths in the custom webpack configuration. Then update PHP paths and deployment packaging to match the actual output.
Upgrade without breaking the project
wp-scripts is a maintained toolchain, so an upgrade can change defaults, supported runtimes, or configuration behavior. Before changing the version:
- Read the package changelog and migration instructions for the target release.
- Check the target package’s Node and npm engine requirements.
- Run the existing lint, test, and production-build commands on the current version.
- Update the dependency and lockfile in a reviewable change.
- Run the same checks again and inspect entry points, generated filenames, dependency metadata, and browser behavior.
Do not make migration promises based solely on a roadmap. WordPress has described @wordpress/build as a next-generation direction intended to replace the webpack/Babel pipeline in newer architecture and to deliver capabilities to wp-scripts build users. That is a direction statement, not a guarantee that every project should migrate immediately. Re-check current WordPress developer guidance before planning a move.
Quick Recap
A repeatable development-to-release workflow
- Create or enter the plugin or theme directory and verify the Node and npm versions required by your selected wp-scripts release.
- Install
@wordpress/scriptswithnpm install @wordpress/scripts --save-dev. - Add
startandbuildscripts topackage.json. - Place authored JavaScript and JSX in
src, or choose an explicit source directory for a theme. - Use
block.jsondetection for conventional blocks, command-line entries for a small custom layout, and a webpack extension file for complex requirements. - Run
npm run startwhile developing and verify that changed source files produce updated output. - Run the package’s available lint, formatting, and test checks for the project.
- Run
npm run buildbefore release. - Deploy the generated assets together with
build/index.asset.php, or the equivalent metadata path when using a custom output directory. - Test the installed plugin or theme in WordPress, checking the browser console, network requests, block editor behavior, front-end behavior, and cache invalidation.
What to remember
- wp-scripts is the
@wordpress/scriptsnpm package for standardized WordPress JavaScript builds. startwatches source files for development;buildcreates optimized output and dependency/version metadata.- Webpack entry arguments, automatic
block.jsondetection, and custom webpack files cover most project layouts. - The theme flags
--webpack-src-dirand--output-pathlet you keep source and generated assets in theme-specific directories. - Check the installed package’s engine requirements and migration notes before upgrading.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
