Installation / Setup

Requirements

Node.js

PHP

Chisel

New project

Recommended: Initialize Git before installing Chisel. This ensures that Git hooks (Husky) are set up correctly during installation, and allows the pre-commit hook to properly detect your initial commit.

Step 1: Create project folder and initialize Git

mkdir my-project
cd my-project
git init

mkdir my-project
cd my-project
git init

Step 2: Run the Chisel generator

git init
npx generator-chisel

git init
npx generator-chisel

Follow the instructions shown in the terminal to complete the project setup. The generator will ask you several questions about your project configuration and create all necessary files.

Step 3: Verify the installation

Wait for the installation to finish and you should be able to open your project in the browser using the project-name.test url.

Alternative: Docker installation

You can also install the project in docker using the command:

npx -y generator-chisel --devcontainer

npx -y generator-chisel --devcontainer

This sets up a complete development environment using Docker containers.

Setting up Git hooks after installation

If you ran git init after Chisel installation, you need to manually set up the Git hooks (in your project folder):

npm run prepare

npm run prepare

This installs Husky and configures the pre-commit hook that:

• Protects core/ files from accidental modification
• Runs lint-staged for code quality checks

Existing Project

When joining a project with an existing Chisel codebase in a repository, follow these steps to set up the project locally:

Step 1: Clone and navigate

git clone <repository-url>
cd <project-folder>

git clone <repository-url>
cd <project-folder>

Navigate to the theme folder (typically wp-content/themes/<theme-name>).

Step 2: Install dependencies

composer install
npm install

composer install
npm install

Step 3: Configure WordPress

Copy wp-config-custom.php and rename it to wp-config.php (wp-config.php is gitignored for security reasons, but you need your local version to start the project).

npm run wp-config

npm run wp-config

This creates a wp-config-local.php file. Ensure it contains the following settings for local development:

define( 'WP_DEBUG', true ); 
define( 'WP_DEBUG_LOG', true ); 
define( 'WP_DEBUG_DISPLAY', false ); 

// Required for the theme fast refresh mode
define( 'SCRIPT_DEBUG', true ); 
define( 'WP_ENVIRONMENT_TYPE', 'development' );

define( 'WP_DEBUG', true ); 
define( 'WP_DEBUG_LOG', true ); 
define( 'WP_DEBUG_DISPLAY', false ); 

// Required for the theme fast refresh mode
define( 'SCRIPT_DEBUG', true ); 
define( 'WP_ENVIRONMENT_TYPE', 'development' );

Step 4: Build assets

npm run build

npm run build

Step 5: Start development

npm run dev

npm run dev

The local URL is project-name.test with “fast refresh” mode enabled for CSS and JavaScript.

Troubleshooting

Browser keeps refreshing after starting dev mode

Solution: Open DevTools (Chrome) → Network tab → Check “Disable cache” → Refresh the browser.

CSS does not refresh after modifying styles

Solution: Same as above—disable cache in DevTools.

Git hooks not working

Solution: Run npm run prepare to install Husky hooks.

Pre-commit hook shows error on initial commit

Solution: The pre-commit hook is designed to allow all files (including core/) on the initial commit. If you’re seeing errors, ensure you ran git init before installing Chisel, or run npm run prepare after cloning.