Setting up your development environment
[better title needed]
[insert table of contents]
Node.js and npm
If you're not sure whether you have Node.js or the right version, run this on your command line:
node --version npm --version
If you get a "command not found" error or an outdated version for Node:
- Windows or Mac users can download and run this Node.js installer.
- Mac users often prefer to install Node using Homebrew. After installing Homebrew, run
brew install nodeto install Node.js. Alternatively, installer packages are available directly from Node.js.
- Linux users can use this guide for Node.js installation on Linux.
If you get an outdated version of npm, run
npm install -g npm.
WordPress ships with a list of dependencies, some of those are managed and updated with npm, some are managed manually.
All npm dependencies are listed in the
package.json file in the root of the project. Some dependencies are only used for development (like Grunt and code linters). Those are listed under
devDependencies. Packages that are used in the WordPress code itself are listed under
Installing npm packages
You can install npm dependencies by running:
Updating npm packages & version locking
The versions of the packages are locked in a package-lock.json to guarantee the same packages are installed every time you run
npm install. To update a dependency, simply run:
npm update <package_name> --save
This will update also update the package-lock.json so that others will also have the new version when they now run
Adding new npm packages
You can add a package by running:
npm install <package_name> --save
If you want to add a development package, run:
npm install <package_name> --save-dev
Both commands will also update the
package-lock.json to include the new package at a specific version.
Building npm packages
npm installs all packages to the
node_modules directory. Sometimes we copy a dependency to WordPress and include it directly. This is configured in
copy.npm-packages. If you want to add a new package and include it in WordPress directly, you need to add it here.
Another way code from npm is included into WordPress is by importing distinct modules directly into our own code and have Webpack bundle it. In that case you don't need to worry about updating the build config.
Some dependencies in WordPress aren't available on npm. They are managed and updated manually. Some of them aren't updated at all anymore and / or might only still be present for backwards compatibility reasons. They are located in the
src/js/_enqueues/vendor directory, which also includes a README.md listing the sources for those dependencies.
Building manual dependencies
The manual dependencies are built just like the rest of the source. This is configured in
[insert a section about developing with VVV (VVV should automatically watch changes, take away the burden entirely)]
Building WordPress yourself
grunt to build its source. In order to start developing, you'll need to run an initial build. To do that, run the following command:
npm install && grunt build
When developing, you don't want to run
grunt build every time you change something. Instead you can run a file watcher which will automatically rebuild when a file is changed. This can be done by running the following command:
Code organization and development practices
src/js. In order to maintain backwards compatibility, the structure of the build remained unchanged.
_enqueues directory. That's where all the scripts are that eventually get copied or built to
src/js in a logical structure. An early example of this is the
media folder, which contains all the separate modules for the media library. This allows us to flexibly and safely change and move around code while maintaining backwards compatibility.
<script> tag in the HTML. WordPress uses Webpack for this.
For anyone wanting to learn about JS modules, Preethi Kasireddy wrote an excellent two part introduction. You can find it here:
- Part 1: about what modules are and why you should use them.
- Part 2: about module bundling and the different ways in which that can be done.
A few guidelines with regard to modular programming
Here are a few useful and easy to understand guidelines to write modular code:
Single responsibility principle
[Explain in layman's terms + link]
Don't repeat yourself (DRY)
[Explain in layman's terms + link]
Loose coupling, high cohesion
[Might be too complex, but if we could make this easy to grasp, we're good.]
WordPress is an open source project. If we can organize our code in a way that makes it more reusable for the greater community of developers, we should try to do so.
[Documentation on WordPress packages]
Introducing new scripts
Once a script is registered in core, it cannot be removed without breaking backwards compatibility. This is because plugin and theme authors unregister / replace scripts or enqueue scripts that aren't enqueued by core on certain screens. Because of modules, anything that is in a registered script can of course be extracted away into a separate module. Anything that needs to be on the global
wp object can still be assigned to it. However, using modules should eventually lead to better composition. Modules that don't need to know about global API's shouldn't depend on them or assign themselves to global objects.
Transitioning from a PHP rendered admin to a JS rendered admin
Handling legacy / old code