Directus Extension CLI Utility

The create-directus-extension CLI utility is used to scaffold a Directus extension.

Creating Extensions

To create an extension, run the create-directus-extension command:

npx create-directus-extension@latest

After specifying the name of the extension, the type of the extension and the programming language you want to use, the utility will create a folder with the recommended file structure to create an extension.

If you want to combine and share dependencies between one or more extensions, use the bundle extension type.

Building Your Extension

Before your extension can be used by Directus, it has to be built. If you used the create-directus-extension utility to scaffold your extension, building your extension is done by running:

npm run build

The generated package.json contains a script that calls the directus-extension CLI which is part of @directus/extensions-sdk:

{
	"scripts": {
		"build": "directus-extension build"
	}
}

If you prefer to scaffold your extension manually, you can use the directus-extension CLI binary directly. The --help flag provides useful information regarding the available options and flags.

Internally, the CLI uses Rollup to bundle your extension to a single entrypoint.

::callout{icon="material-symbols:info-outline"}

Watch

The CLI supports rebuilding extensions whenever a file has changed by using the --watch flag.

::

::callout{icon="material-symbols:info-outline"}

Automatically Reload Extensions

To automatically reload extensions every time you make a change, without having to restart Directus, in your docker-compose.yml file, set EXTENSIONS_AUTO_RELOAD=true.

::

Validate Extensions

Extensions can be validated using the following command:

npx create-directus-extension@latest validate

The following validations are run:

::callout{icon="material-symbols:info-outline"}

Checking Specific Validations

To make sure your extension is passing a specific validation, you can do so using the -c or --check flag:

npx create-directus-extension@latest -c <VALIDATION_NAME>

::

::callout{icon="material-symbols:info-outline"}

Verbose Report

By default, validation will report any issues. However, a full report for every check can be generated using the -v or --verbose flag:

npx create-directus-extension@latest -v

::

Linking Extensions

In order to create or check that a valid symbolic link of your extension exists, run the following in your Directus extension project:

npx create-directus-extension@latest link

Configuring the CLI

Most of the time, it should be sufficient to use the CLI as is. But, in some cases it might be necessary to customize it to your specific needs. This can be done by creating a extension.config.js file at the root of your extension package. An example with the currently available options will look something like:

export default {
	plugins: [],
	watch: {
		clearScreen: false
	}
};