Project-as-code for a Directus v9 backend

#directus #projen #opensource #cms

In practice, turning Directus into the backbone of a production backend takes a fair amount of setup before a project becomes productive. Projen, a project scaffolding and automation framework, can automate that plumbing, so the time the tech teams 'd otherwise need to spend wiring Dockerfiles and build pipelines together goes into writing product and business logic instead.

@wbce/projen-d9 is the projen template we built to automate that plumbing around directus. By default it targets d9 (directus version 9), but you can adapt it to whichever Directus version you actually run. You can also customize it further to fit whatever your team needs. This post walks through what it generates and why.

d9 is a GPL fork of Directus v9 we maintain on GitHub. It does what Directus 9 did: an open-source (GPL-3 license) CMS that, with the right discipline, can stand in for a full custom backend (API, admin UI, permissions, schema), with business logic added as extensions (hooks, endpoints, operations, custom UI panels).

Bootstrap a new project

npx projen new --from @wbce/projen-d9

This creates a .projenrc.js and synthesizes the project.

What you get

The user-facing surface of the template is .projenrc.js:

import { D9Project } from '@wbce/projen-d9';
import { D9ExtensionType } from '@wbce/projen-d9-extension';

const project = new D9Project({
  name: 'my-backend',
  defaultReleaseBranch: 'main',
});

project.addExtension('audit-log', [D9ExtensionType.HOOK]);

project.synth();

npx projen synthesizes everything else (Dockerfile, docker-compose, extension folder, build pipeline, GitHub workflows). projen calls this "project-as-code": project files are outputs synthesized from a config you commit, you re-synth whenever the config changes, and the generated files keep tracking the config over time.

Generated tasks

Task	Description
`first-run`	Bootstrap a complete local dev environment in one cli command
`run`	Start d9 (`docker compose up directus`)
`build-extensions`	Install and build all extensions
`create-an-admin`	Create the default admin user

What gets generated

docker-compose.yml: d9, Postgres (PostGIS), Redis
Dockerfile: Node 22 + pnpm, builds extensions
.env.local: sample for local environment overrides
extensions as a pnpm workspace
GitHub PR and issue templates via @wbce/projen-shared (set githubConfig: false to disable)

A standardized compose stack

With a single CLI command, you can spin up a fully working local Directus environment (database, cache, and API) ready for development. It mirrors a production setup, including caching and geospatial capabilities.

The compose file is built with projen's DockerCompose construct:

database: postgis/postgis:13-master in order to enable geospatial functionality
cache: redis:6
directus: built from the local Dockerfile. EXTENSIONS_AUTO_RELOAD=true is set, so re-running npx projen build-extensions is enough to pick up edits with no container restart.

Bind mounts:

./uploads -> /app/uploads
./extensions -> /app/extensions (the extension tree that build-extensions writes into)
./.env.local -> /app/.env.local (so secrets stay out of the image and git versioning)

Extensions as a pnpm workspace

addExtension(name, types, options?)adds an ExtensionFolder to the parent project. Each addExtension creates a D9ExtensionProject with three quirks:

Its package.json gets the directus:extension field correctly configured.
Its build task is rewritten to compile and then deposit the output in the right subfolder of extensions/
If any of the types are UI extensions (INTERFACE, DISPLAY, LAYOUT, MODULE, PANEL), vue is added as a devDep automatically.

Because every extension is its own package in a real pnpm workspace, we can share packages between extensions :

// A shared library, no extension types
project.addExtension('shared', []);

// Other extensions depend on it via workspace:
const myHook = project.addExtension('audit-log', [D9ExtensionType.HOOK]);
myHook.addDeps('shared@workspace:');

And pnpm catalogs in pnpm-workspace.yaml let you pin shared dependency versions in one place and consume them as catalog: from each extension's package.json.

Deploying

The generated Dockerfile is meant for deployment. Build and push it to your
registry, then run it against your target database and cache.
Simple and efficient, the Docker setup ensures extensions are built inside the image during the build step.

FROM node:22-bookworm-slim
RUN npm install -g npm@11.8.0
RUN npm install -g pnpm@10.33.0
COPY package*.json /app/
WORKDIR /app
RUN NODE_ENV=production npm install
COPY . .
RUN npx projen build-extensions
CMD ["npx", "directus", "start"]