Introduction to @wordpress/scripts: Modern WordPress Builds

Previously in this course, we covered Setting up the WordPress Development Environment, where we established our local workspace and plugin scaffolding. Now, we're ready to modernize our development workflow.

Writing raw, uncompiled JavaScript for WordPress is a recipe for maintenance headaches. As we prepare to build a React-based admin dashboard for our Knowledge Base plugin, we need a professional build pipeline. That is where @wordpress/scripts comes in.

Understanding the Build Pipeline

In the modern WordPress ecosystem, we don't ship source code directly to the browser. Instead, we use tools to transpile modern JavaScript (ESNext/JSX) into browser-compatible code.

@wordpress/scripts is a collection of reusable scripts maintained by the WordPress core team. It abstracts away the complexity of configuring Webpack and Babel.

• Webpack handles the "bundling"—taking your modular JavaScript files and combining them into a single, optimized file.
• Babel handles "transpilation"—converting modern syntax (like arrow functions or classes) into older versions of JavaScript that older browsers understand.

By using this package, you avoid the "configuration hell" that often plagues custom Webpack setups.

Setting Up Your Project

First, ensure you have Node.js installed. Open your terminal, navigate to your plugin directory, and initialize your package.json file:

Bash
npm init -y

Next, install the WordPress scripts package as a development dependency:

Bash
npm install @wordpress/scripts --save-dev

This command adds the necessary tools to your node_modules folder and updates your package.json. Now, open that file and update the scripts section to leverage the built-in commands:

JSON
{
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
  }
}

Building Your First Script

To see this in action, create a folder named src in your plugin root and add an index.js file:

JAVASCRIPT
// src/index.js
const greeting = "Hello from the build pipeline!";
console.log(greeting);

Now, run the build command in your terminal:

Bash
npm run build

@wordpress/scripts looks for src/index.js by default and outputs a bundled file into build/index.js. If you inspect build/index.js, you'll see your code wrapped in a Webpack runtime environment. This build/index.js is the file you will eventually enqueue in WordPress using the Enqueuing scripts and styles the correct way in WordPress guidelines.

Hands-on Exercise

1. Add a second file in your src folder called utils.js and export a simple function: export const log = (msg) => console.log('Log: ' + msg);.
2. Import this function into src/index.js and use it.
3. Run npm run build again.
4. Observe how Webpack automatically resolves the module dependency and bundles both files into one.

Common Pitfalls

• Forgetting the build/ directory: Always add build/ to your .gitignore file. You should never commit your built assets to version control; only commit the source code.
• Dependency Confusion: Ensure you are using npm install --save-dev for build tools. If you accidentally install them as production dependencies, your plugin will be unnecessarily bloated when you package it for distribution.
• Enqueuing the wrong file: Beginners often try to enqueue the src/index.js file. Remember: the browser needs the compiled output in build/index.js.

By mastering these tools, you're setting the stage for the more complex React development we'll tackle later in this course. You now have a repeatable, professional environment for compiling your assets.

Up next: Configuring ESLint and Prettier to ensure our code quality remains high as our codebase grows.