WP Dev Tools

Development tools for wordpress.

Installation and Usage

Use without installation via npx

npx @stevekanger/wp-dev-tools [command] [...options]

Or install in your project.

npm install -D @stevekanger/wp-dev-tools

and use in package.json

{
  "scripts": {
    "create:block": "wp-dev-tools createBlock"
    "archive": "wp-dev-tools archive"
    "copy": "wp-dev-tools copy"
    "docker:extract": "wp-dev-tools dockerExtract"
  }
}

Creating a Plugin Or Theme

You can easily scaffold a project with the createProject command. Run via npx since your project would be empty at this point.

npx @stevekanger/wp-dev-tools createProject

This runs the interactive setup. When finished cd into your project and run the following commands to setup the project.

npm install
composer install
composer dump-autoload

Docker

Docker ports and webpack proxies are set in .env. You can change those to your liking. Default is set to run on port 8000.

It's recommended but not required to set up a hostname in /etc/hosts on your local machine mapped to the docker port. This allows wordpress loopbacks to work (wp_cron etc.). Set this hostname to DOCKER_EXTRA_HOST and BROWSER_SYNC_PROXY in .env.

You can now start your docker container.

docker compose up -d

If you setup a hostname navigate there in your browser. If not, and didn't change anything in .env go to http://localhost:8000. You can then run through the wordpress installation.

Development

After wordpress is set up you can now run the development command for hot reloads.

Important: Complete the wordpress install before running dev.

npm run dev

Project Structure

All php files reside in inc. All psr-4 classes will be autoloaded via composer from the inc/app folder. Controllers are your connection to wordpress by registering hooks, etc. Services are your business logic and can be bound and retrieved from the service container. Both Controllers and Services have access to the service container via the create() method. You can register Controllers and add Services in the Bootstrap.php file.

All raw js, css, and blocks reside in src. These are files that need to be built during the build process.

Several development tools will be set up. Docker for a controlled development environment, Webpack with typescript and scss by default, Composer for autoloading, and @stevekanger/wp-dev-tools will be added for additional tools.

Project Requirements

Its recommended to use PHP >= 8.3 and Nodejs >= 22.22.2 for all projects.

Commands

All commands are run with command first then options. You can supply options or if necessary options are required you will be prompted via an interactive command line interface.

wp-dev-tools [command] [...options]

createProject

Creates either a theme or plugin project

Option	Type	Allowed	Description
--dest	string	string	The destination installation directory. (Directory must be empty).
--type	string	'theme', 'plugin'	The type of project to create.
--title	string	string	The proper title of the project.
--author	string	string	The proper author name.
--authorHandle	string	string	This is the author name with no spaces. (Either no spaces, kebab or snake case).
--description	string	string	A brief description of the project.
--slug	string	string	The kebab case separated project slug (Used for things like textdomain, namespaces, and docker containers).
--prefix	string	string	The snake case separated project prefix (Used for things like php prefixing).
--version	string	string	The initial project version.
--phpNamespace	string	string	The projects php namespace for all php code.
--wordpressVersion	string	string	The min Wordpress version.
--phpVersion	string	string	The min Php version.
--installTests	boolean	NA	Whether or not to install tests.
--help -h	boolean	NA	Shows the help message.

createBlock

Creates wordpress block files. It does not install a full block plugin only the block files project similar to running npx @wordpress/create-block --no-plugin. The templates have been modified slightly to use typescript.

Option	Type	Allowed	Description
--dest	string	string	The destination installation directory. (Directory must be empty).
--type	string	'static', 'dynamic'	The type of block to create.
--title	string	string	The proper title of the project.
--description	string	string	A brief description of the block.
--slug	string	string	The kebab case separated block slug (Used when registering blocks).
--textdomain	string	string	The project textdomain.
--namespace	string	string	The project namespace (can match textdomain).
--version	string	string	The initial project version.
--help -h	boolean	NA	Shows the help message.

archive

Archives the project files to single a .zip file.

Option	Type	Allowed	Description
--type	string	'dist', 'dev'	The files that you want to include. dist only distribution files. dev all developement files.
--src	string	string	The source directory.
--dest	string	string	The destination directory.
--help -h	boolean	NA	Shows the help message.

copy

Copies the project files to a destination folder.

Option	Type	Allowed	Description
--type	string	'dist', 'dev'	The files that you want to include. dist only distribution files. dev all developement files.
--src	string	string	The source directory.
--dest	string	string	The destination directory.
--help -h	boolean	NA	Shows the help message.

dockerExtract

Copies a resource from the docker container to a local location.

Option	Type	Allowed	Description
--type	string	'dist', 'dev'	The files that you want to include. dist only distribution files. dev all developement files.
--src	string	string	The source files relative to wp-content in the docker container. Example "themes/my-awesome-theme".
--dest	string	string	The destination directory.
--help -h	boolean	NA	Shows the help message.

License

This software is licensed under the GNU General Public License v2.0 or later. See LICENSE for more information.