Running Dev Environment ​

This guide explains how to setup and run a Development environment for Directus so that you can work on the platform's source code. To install the Production version, please follow to our Docker Guide.

1. Fork the Directus repository ​

Go to the repository and fork it to your GitHub account. A fork is your copy of the Directus repository which allows you to freely experiment with changes without affecting the original project.

2. Clone from your repository ​

git clone git@github.com:YOUR-USERNAME/directus.git

git clone git@github.com:YOUR-USERNAME/directus.git

3. Make a new branch ​

git checkout -b YOUR-BRANCH-NAME

git checkout -b YOUR-BRANCH-NAME

4. Install dependencies and build the project ​

pnpm install
pnpm build

pnpm install
pnpm build

5. Setup local configuration ​

Create a .env file in /api ​

Create an .env file under the api folder using vars from the online config help.

Upload/Extensions Folder ​

If you are using the local storage driver, your files will upload to /api/uploads. If you are locally developing extensions from the extensions folder, that folder should be located at /api/extensions.

6. Initialize the database ​

For this step, you'll need to already have a SQL database up-and-running, except if you're using the SQLite driver, which will create the database (file) for you.

To start the initialization run the following command:

pnpm --filter api cli bootstrap

pnpm --filter api cli bootstrap

This will set-up the required tables for Directus and make sure all the migrations have run.

7. Start the development server ​

You can run all packages in development with the following command:

pnpm --recursive dev

pnpm --recursive dev

If you wish to choose what packages to work on, you should run the dev script for that package. You can see their names and list of scripts in their related package.json.

Example of running the API only:

pnpm --filter api dev

pnpm --filter api dev

If you want to work on multiple packages at once, you should create a new instance of your terminal for each package. Example of running both the API and App at the same time:

pnpm --filter api dev

pnpm --filter api dev

pnpm --filter app dev

pnpm --filter app dev

8. Make your fixes/changes ​

At this point you are ready to start working on Directus! Before diving in however, it's worth reading through the introduction to Contributing.

Debugging The App ​

There are several ways to debug the app but the easiest way to do it is with the Vue Devtools. It's recommended to use the Vue Devtools with Chrome.

Debugging The API in VS Code ​

To debug the API, we recommend to use Visual Studio Code with it's built in debugger.

1. First you need to setup the config for the debugger. Create the following file ./directus/api/.vscode/launch.json and paste in the following structure.

{
	"version": "0.2.0",
	"configurations": [
		{
			"type": "node",
			"request": "launch",
			"name": "Debug Api",
			"skipFiles": ["<node_internals>/**"],
			"cwd": "${workspaceFolder}/api",
			"runtimeExecutable": "pnpm",
			"runtimeArgs": ["run", "dev"]
		}
	]
}

{
	"version": "0.2.0",
	"configurations": [
		{
			"type": "node",
			"request": "launch",
			"name": "Debug Api",
			"skipFiles": ["<node_internals>/**"],
			"cwd": "${workspaceFolder}/api",
			"runtimeExecutable": "pnpm",
			"runtimeArgs": ["run", "dev"]
		}
	]
}

2. Make sure that you have caching disabled as it otherwise returns the cached response. To disable this, go to your .env file in the API and set CACHE_ENABLED to false.

3. In the tsconfig.json, set sourceMap to true.

4. Now you can start the API by going to the debugger view in VS Code, select to debug the API and press Start Debugging. This runs the API and allows you to set breakpoints.

9. Running tests ​

Tests run automatically through GitHub Actions. However you may wish to run the tests locally especially when you write tests yourself.

Install Docker and ensure that the service is running.

# Ensure that you are testing on the lastest codebase
pnpm build

# Run the unit tests
pnpm test

# Clean up in case you ran the blackbox tests before
docker compose -f tests/blackbox/docker-compose.yml down -v

# Start the necessary containers for the blackbox tests
docker compose -f tests/blackbox/docker-compose.yml up -d --wait

# Run the blackbox tests
pnpm test:blackbox

# Ensure that you are testing on the lastest codebase
pnpm build

# Run the unit tests
pnpm test

# Clean up in case you ran the blackbox tests before
docker compose -f tests/blackbox/docker-compose.yml down -v

# Start the necessary containers for the blackbox tests
docker compose -f tests/blackbox/docker-compose.yml up -d --wait

# Run the blackbox tests
pnpm test:blackbox