WP Scripts for WordPress Development: A How-To

WP Scripts is the official command-line toolkit bundled with WordPress that automates common development tasks like building blocks, enqueuing assets, and running a local dev server. This guide shows you how to install it, scaffold a new block or plugin, and use its most useful commands—so you can skip manual setup and focus on writing code.

What You’ll Need

• A computer running macOS, Linux, or Windows 10+ (with WSL recommended for Windows).
• Node.js (version 16 or later) and npm installed. Check with node -v and npm -v.
• A WordPress development environment (local like Local, or a remote server with SSH access).
• Basic familiarity with the command line (Terminal on macOS/Linux, Command Prompt or PowerShell on Windows).

Step-by-Step

1. Install WP Scripts globally (optional but recommended). Open your terminal and run npm install -g @wordpress/scripts. This makes the wp-scripts command available everywhere. If you prefer not to install globally, you can use npx @wordpress/scripts instead.
2. Navigate to your project folder. For a plugin, go to wp-content/plugins/ in your WordPress installation. For a theme, go to wp-content/themes/your-theme/.
3. Create a new block or plugin (if starting fresh). Run npx @wordpress/create-block my-block (replace my-block with your desired slug). This scaffolds a complete block plugin with all necessary files. For a plain plugin, just create a folder with a PHP file manually.
4. Initialize npm in your project (if not already done). Run npm init -y to create a package.json file. The create-block command does this automatically.
5. Add WP Scripts as a dev dependency. Run npm install --save-dev @wordpress/scripts. This adds the necessary scripts to your package.json.
6. Add useful npm scripts to your package.json. Edit the scripts section to include:

   "scripts": {
     "start": "wp-scripts start",
     "build": "wp-scripts build",
     "lint:js": "wp-scripts lint-js",
     "lint:css": "wp-scripts lint-style",
     "format": "wp-scripts format"
   }

   Save the file.

7. Run the development server. Execute npm start in your terminal. This compiles your JavaScript and CSS in watch mode, automatically rebuilding when you save changes. It also serves your assets from a local URL (usually http://localhost:8888).
8. Edit your source files. For a block, edit the src/ directory—index.js, style.scss, and editor.scss. For a plugin, you can put your JS in src/index.js and CSS in src/style.css.
9. Build for production. When you’re ready to deploy, run npm run build. This creates minified, optimized files in the build/ folder. The PHP files will enqueue these built assets automatically if you use the standard block structure.
10. Lint and format your code. Run npm run lint:js and npm run lint:css to check for coding standards. Use npm run format to automatically fix formatting issues.

Common Mistakes

• Forgetting to run npm install after cloning a project. Always run npm install to install dependencies listed in package.json.
• Using npm start in production. The start command is for development only; it creates unminified files and watches for changes. Use npm run build for production.
• Not enqueuing the built assets correctly. If you’re not using the standard block structure, you need to manually enqueue the build/index.js and build/index.css files using wp_enqueue_script and wp_enqueue_style in your PHP.
• Editing files in the build/ folder. That folder is generated; always edit source files in src/ and rebuild.
• Ignoring Node version requirements. WP Scripts requires Node 16+. Using an older version leads to cryptic errors.

Tips

• Use wp-scripts plugin-zip to create a zip file of your plugin for distribution. Add a script: "plugin-zip": "wp-scripts plugin-zip".
• Take advantage of wp-scripts start --hot to enable hot reloading for faster development.
• Use the --webpack-src-dir flag if you want to keep your source files in a different directory than src/.
• Combine WP Scripts with @wordpress/env for a complete local WordPress environment: npx @wordpress/env start.
• Check the official WordPress Scripts documentation for a full list of commands and options.

Troubleshooting

If something goes wrong, here’s what to try:

• Command not found: wp-scripts – Make sure you installed it globally or as a dev dependency. Try npx wp-scripts --version to verify.
• Node version errors – Run node -v. If it’s below 16, update Node.js from the official website or use a version manager like nvm.
• Build fails with syntax errors – Check the error message for the specific file and line. Often it’s a missing import or a typo. Run npm run lint:js to catch issues early.
• Changes not showing in the browser – Ensure npm start is running and you’re viewing the site via the correct URL (usually http://localhost:8888). Clear your browser cache or hard refresh (Ctrl+Shift+R).
• Assets not loading in WordPress – Verify that the enqueue functions in your PHP reference the correct file paths. For blocks, the block.json file should have the correct editorScript and style fields.
• Port already in use – If the dev server can’t start because port 8888 is taken, use npm start -- --port 3000 to specify a different port.

Frequently Asked Questions

1. Do I need WP Scripts for every WordPress project? No, it’s optional. It’s most useful for block development and modern JavaScript-heavy plugins. Simple themes can use traditional PHP and CSS without it.
2. Can I use WP Scripts with a classic theme? Yes, you can use it to compile JS/CSS for any theme. Just set up your src/ folder and enqueue the built files in your functions.php.
3. What’s the difference between npm start and npm run build? npm start runs in development mode with watch and source maps; npm run build creates minified production files.
4. Can I use TypeScript with WP Scripts? Yes, WP Scripts supports TypeScript out of the box. Just create .ts or .tsx files in your src/ folder.
5. How do I update WP Scripts? Run npm update @wordpress/scripts in your project, or npm install -g @wordpress/scripts@latest for the global version.
6. Does WP Scripts work with Gutenberg blocks? Absolutely—it’s the recommended tool for block development. The create-block command scaffolds a block that uses WP Scripts by default.

Related

• Export AI Data & Prompts Before Switching Platforms
• Phone Specs That Matter for Everyday Use
• Bypass Factory Reset Protection Samsung