Setting up Nitro for Plugin Development

Nitro is no longer supported. Please see our announcement and DDEV migration guide.

Nitro supports running multiple sites with their own PHP versions, settings and Xdebug making plugin development easy. There are many ways to setup Nitro for plugin development but here are just a few.

# Local Composer Repository

One of the easiest ways to start plugin development with Nitro is to run the add to create a new site.

$ nitro add plugins-dev

Navigate to the plugins-dev folder and create a plugins directory.

$ cd plugins-dev
$ mkdir plugins

Clone your plugin repository in the plugins directory.

$ git clone

Edit your composer.json to add a repositories setting:

"repositories": [
      "type": "path",
      "url": "./plugins/*"

To add your local plugin, you need to require it in your project. In your sites root directory, require your plugin with the composer command:

$ nitro composer require craftcms/commerce

In the output, you will see your plugin referenced using a symlink during the installation.

- Installing craftcms/commerce ( Symlinking from ./plugins/commerce

In the control panel, visit SettingsPlugins, choose Commerce and switch on the Enable setting. You can now develop your plugins locally and keep changes tracked with Git!

# Running Codeception and PHPUnit with PhpStorm

PhpStorm allows you to use a remote interpreter to execute Codeception or PHPUnit tests. To run codeceptions tests with Nitro, perform the following actions:

  1. Configure the remote interpreter in PhpStorm using Docker.
  2. Select the image and version to use (e.g. craftcms/nginx:7.4-dev).
  3. Add the configuration for running tests.

These tests will run inside a container that is not attached to the default nitro-network. This means the databases are not reachable by the usual hostname (e.g. mysql-8.0-3306.database.internal). Instead, you must use host.docker.internal and database port (e.g. 3306) in your .env file to reach the database.