Setting Up Your Development Environment

This page will guide you through the process of setting up Sensei LMS development environment on your local machine. It should work on Linux, macOS, or Windows Subsystem for Linux on Windows 10.

Table of Contents

• Pre-requisites
• Quick Start
• Development Workflow
• IDE Configuration
• Troubleshooting
• Additional resources

Pre-requisites

Before starting, make sure you have the following software installed and working on your machine:

1. Git to clone the Sensei LMS repository (or your fork of the Sensei LMS repository).
2. Node.js (version >= 22) and NPM to install Node packages used to build assets and other tasks.

• If using nvm: nvm install 22 && nvm use 22

1. Composer to install PHP packages required by Sensei LMS such as the sensei-rest-api and the jetpack-autoloader. It's also necessary to use the PHP CodeSniffer that ensures your code follows code standards.
2. WP-CLI for updating i18n pot files.

Quick Start

Clone the Repository

Clone Sensei into a local directory:

git clone https://github.com/Automattic/sensei.git
cd sensei

Or clone your fork:

git clone https://github.com/YOUR-USERNAME/sensei.git
cd sensei

Install Dependencies

make install

This installs all NPM dependencies required for development.

Start the WordPress Environment

make up

This starts a Docker-based WordPress instance with Sensei installed. The site will be available at:

• URL: http://localhost:8888
• Admin username: admin
• Admin password: password

Install PHP Dependencies

make install-php

This runs composer install inside the WordPress container to install PHP dependencies.

Build Assets

For development with live rebuilding:

npm run start

This watches source files and rebuilds JavaScript/CSS automatically when you make changes.

For a one-time production build:

npm run build:assets

Available Make Commands

Run make help to see all available commands:

Command	Description
make install	Install NPM dependencies (requires Node 22+)
make install-php	Install PHP dependencies via composer
make up	Start the WordPress development environment
make down	Stop the WordPress environment
make destroy	Remove all containers and data
make shell	Open a bash shell in the WordPress container
make wp CMD="..."	Run WP-CLI commands (e.g., make wp CMD="plugin list")
make test-php	Run PHPUnit tests
make lint	Run PHP CodeSniffer
make build	Build a plugin zip file
make logs	View WordPress environment logs

Testing with Different WordPress or PHP Versions

You can test Sensei with specific WordPress or PHP versions:

Test with WordPress 6.8

make up WP=6.8

Test with PHP 8.3

make up PHP=8.3

Test with both

make up WP=6.8 PHP=8.3

Test with nightly WordPress build

make up WP=nightly

Test with beta/RC versions

make up WP=7.0-beta1
make up WP=6.9-RC1

Development Workflow

Making Changes

1. Create a new branch: git checkout -b your-feature-branch
2. Make your changes to the code
3. If you modified JavaScript or SCSS files, ensure npm run start is running
4. Test your changes at http://localhost:8888
5. Run npm run changelog to create a changelog entry for user-facing changes

Running Tests

Run PHP unit tests

make test-php

Run PHP linting

make lint

Run JavaScript linting

npm run lint:js

Plugin Check

Consider installing the Plugin Check plugin. It helps ensure Sensei meets WordPress.org plugin repository requirements. It runs automated checks for common issues including security, performance, and coding standards violations.

Installation:

make wp CMD="plugin install plugin-check --activate"

Running checks:

From the WordPress admin at http://localhost:8888/wp-admin, navigate to Tools → Plugin Check, select "Sensei LMS" from the dropdown, and click "Check it!".

Running these checks before submitting a pull request can catch issues early, especially if you've added new features or modified plugin metadata.

Accessing the Database

To access the WordPress container's MySQL database:

make shell
wp db cli

Or use a database client with these credentials:

• Host: localhost
• Port: 3306 (mapped from container)
• Database: wordpress
• Username: root
• Password: password

IDE Configuration

Pre-commit Hooks

Sensei uses pre-commit hooks to enforce code standards. These are installed automatically when you run npm install.

Recommended Editor Extensions

• PHP_CodeSniffer - For PHP code style checking
• ESLint - For JavaScript linting
• EditorConfig - For consistent formatting across editors

Troubleshooting

Environment won't start

If make up fails:

1. Ensure Docker is running
2. Check if ports 8888 or 3306 are already in use
3. Try make destroy then make up again

Assets not building

If asset compilation fails:

1. Verify Node.js version: node --version (should be 22+)
2. Remove node_modules and reinstall: rm -rf node_modules && make install
3. Check for errors in npm run start output

PHP dependencies missing

If you see PHP autoloader errors:

make install-php

Additional resources

Running unit tests