Getting Started

Before you get started

It’s important to ensure you have a good local environment set up. We recommend using LocalWP to create a local environment, but you can use any method you are comfortable with (ie. Docker, wp-env, WordPress Studio, etc.).

At this point, it is also important to ensure you have the following required applications installed on your computer.

• PHP 8.0 or higher (PHP 8.3 recommended)
  • This is usually already set up with your local environment.
• npm or Bun
• Composer (installed globally)

Once your environment is up and running, open your editor of choice (VS Code, PHPStorm, etc.) and start a new project at the WordPress root folder or your new environment. Now, navigate to the /wp-content/themes folder in the terminal.

The best way to get started using WP Rig is to clone our Github repo into your themes folder.

git clone https://github.com/wprig/wprig.git

If you are working on an existing theme built on WP Rig, you would clone that theme instead.

Init WP Rig

Once you have the latest version cloned into your themes folder, change directories to the new folder created by the clone (usually /wprig unless you named it something else).

cd wprig

Next, we need to initialize WP Rig by installing all dependencies necessary to run the build tools. WP Rig relies on a curated suite of open-source Node packages, custom scripts and Composer packages to provide the best developer experience possible.

npm run rig-init

or

bun run rig-init:bun

Bun support was recently added in v3.1. Bun is a much faster and more efficient tool than npm. In the future, it is likely this will become the default tool, but for now we pass the bun flag to ensure fastest possible install. For the rest of this guide, we will refer to running all Node commands with npm (ex. npm run dev), but just know if you are using Bun, you can replace npm with bun for any of the following commands (ex. bun run dev).

After all dependencies have been installed, WP Rig will setup a default config file for you and prompt you about next steps.

Start building your theme

From here, you have a few options. WP Rig is designed to be used in several different theme type scenarios, so your next steps will depend on what kind of theme you are building.

Standard theme (hybrid)

The default approach from here is a classic hybrid theme (not block-based, no site editor). If this is the kind of theme you want to build you can skip to the next section, running the build server.

Universal hybrid theme or Block-based theme

While WP Rig is not a block-based theme by default, it can easily be converted to a universal theme (hybrid theme with site editor – best of both worlds) or a block based theme. To run the converter, run the following command:

npm run editor-support

This will run several processes that alter WP Rig to convert it to a universal hybrid theme (keeping the menu manager and other classic hybrid theme features). This will also scaffold a default theme.json file. If you are building a strictly block-based theme, you will want to run an additional command:

npm run block-based

Child theme

As of v3.1, WP Rig can also be used as a child theme with a build process built-in. This is essentially an extremely slimmed down version of WP Rig, removing a lot of functionality, but still keeping the essential build tools to process all JS and CSS files along with PHP/Composer tools if you choose to add theme-specific functionality that does not make sense for a plugin (custom menu walkers, conditional enqueuing, passing custom data to JS files using wp_localize_script, etc.). To convert WP Rig to a child theme for any other theme, run the following conversion script:

npm run childify

This will prompt you for the name of your parent theme and any other details it needs to effectively run the converter and link WP Rig to the parent theme. Additional options for childify can be found in the readme.md file in WP Rig.

Running the build

One of the most important parts of WP Rig is the build processes. After you install all dependencies, the theme still needs to be built before you can activate the WP Rig starter theme in the WordPress admin area and see the starting point on the WordPress frontend. There are basically 3 ways to utilize the build server:

Dev mode

This is the most common way to run the build. While editing files, this will watch for changes to the theme files and automatically rebuild changed files on the fly for a fast and smooth development experience while you write your code changes. This will leave the build server running indefinitely, so only run this one if you are currently actively developing your theme as node does consume your computer’s resources.

npm run dev

One-off Builds

This is a good option if you are just trying to see WP Rig for the first time in WordPress when getting started.

npm run build

WP Rig offers some granular scripts for building only specific parts of the theme. You can find these in the package.json file in the root of WP Rig. We also have a full breakdown of these scrips here.

Bundle (Deployment ready version of theme)

The bundle command will actually generate a whole new theme using the values in the /config/config.json file as a guide.

The naming conventions for the new theme will follow the settings in this file. You can think of this as essentially a white-labeling feature for WP Rig. This means that you will need to activate this other theme before testing it.

Usually, you only want to run this command when you are done developing your theme and ready to ship it. This is also a good option to use in a CI/CD pipeline that is designed to build/deploy your theme after changes have been merged (ex. feature branches merged into the main branch or staging branch of your theme).

npm run bundle

Development workflow

You can now go to Appearance > Themes in the WordPress admin and activate WP Rig. Feel free to then refresh your home page to see the WP Rig starting point.

From here you can start making WP Rig your own. Reminder, WP Rig is a starter theme, so by default it is intended to be a blank canvas of a theme with some decent defaults to start with. A good way to think of it is WP Rig is your source theme (theme with your source files and build tools) and when you have customized WP Rig to the point where you are happy to call it your theme now, you can run the bundle command and have it generate your theme from WP Rig. Until then, you will likely be running the dev build while you edit/add/remove various aspects of your theme (CSS, JS, page templates, images, fonts, etc.).

Happy coding and please feel free to explore these additional resources about other features, commands and workflows in WP Rig.