From 327fbf3bbbc574eccd405994cf2e64d1b9540409 Mon Sep 17 00:00:00 2001 From: louis Date: Fri, 15 May 2026 16:28:50 +0200 Subject: [PATCH 1/3] add readmes --- packages/directus-extension/README.md | 86 ++++++++++++++++++- .../src/directus-extension-project.ts | 25 ++++++ packages/directus/README.md | 83 +++++++++++++++++- packages/directus/src/index.ts | 53 ++++++++++++ 4 files changed, 245 insertions(+), 2 deletions(-) diff --git a/packages/directus-extension/README.md b/packages/directus-extension/README.md index b3fa7dd..89e1e27 100644 --- a/packages/directus-extension/README.md +++ b/packages/directus-extension/README.md @@ -1 +1,85 @@ -# replace this \ No newline at end of file +# @wbce/projen-directus-extension + +Projen constructs for authoring [d9](https://github.com/LaWebcapsule/d9) (Directus 9) extensions. Provides: + +- `ExtensionFolder` — a pnpm workspace that holds extension packages +- `DirectusExtensionProject` — a TypeScript project for a single extension or a bundle of related extensions +- `DirectusExtensionType` — enum of supported extension kinds + +This package is typically consumed via [`@wbce/projen-directus`](../directus), which wires up an `ExtensionFolder` automatically and exposes `project.addExtension(...)`. + +## Usage + +In a `DirectusProject`: + +```js +import { DirectusProject } from '@wbce/projen-directus'; +import { DirectusExtensionType } from '@wbce/projen-directus-extension'; + +const project = new DirectusProject({ + name: 'my-d9', + defaultReleaseBranch: 'main', +}); + +// Single-type extension +project.addExtension('my-hook', [DirectusExtensionType.HOOK]); + +// Bundle: multiple types in one package +project.addExtension('my-bundle', [ + DirectusExtensionType.INTERFACE, + DirectusExtensionType.DISPLAY, +]); + +// Shared library (no extension type) — can be depended on by other extensions +project.addExtension('shared', []); + +// Cross-extension dependency +const myHook = project.addExtension('feature', [DirectusExtensionType.HOOK]); +myHook.addDeps('shared@workspace:'); + +project.synth(); +``` + +## Extension types + +`DirectusExtensionType` values: + +| Type | Kind | +| --- | --- | +| `INTERFACE` | UI | +| `DISPLAY` | UI | +| `LAYOUT` | UI | +| `MODULE` | UI | +| `PANEL` | UI | +| `ENDPOINT` | API | +| `HOOK` | API | +| `OPERATION` | API | + +Passing `[]` produces a plain TypeScript library that emits `lib/` with type declarations — useful for sharing code between extensions. + +## What gets generated + +Per extension: + +- A TypeScript project under `//` +- Sample `src/index.ts` from a template matching the chosen type(s) +- `directus:extension` field in `package.json` (single type) or a `bundle` config (multiple types) +- Build step that runs `directus-extension build` and copies `dist/` into the parent project's `extensions/` tree at the right subfolder (`hooks/`, `endpoints/`, …) +- Vue is added as a devDep automatically when a UI type is included + +The `ExtensionFolder` itself is a pnpm workspace; running `pnpm install` + `pnpm run --recursive build` inside it builds every extension. This is what the parent `DirectusProject`'s `build-extensions` task does. + +## Direct usage + +The constructs can be used outside `DirectusProject` if needed: + +```js +import { ExtensionFolder, DirectusExtensionType } from '@wbce/projen-directus-extension'; + +const folder = new ExtensionFolder({ parent: someProject, name: 'plugins' }); +folder.add('my-endpoint', [DirectusExtensionType.ENDPOINT]); +``` + +## License + +GPL-3.0-or-later diff --git a/packages/directus-extension/src/directus-extension-project.ts b/packages/directus-extension/src/directus-extension-project.ts index 98ae774..e7690d0 100644 --- a/packages/directus-extension/src/directus-extension-project.ts +++ b/packages/directus-extension/src/directus-extension-project.ts @@ -96,6 +96,31 @@ export class DirectusExtensionProject extends typescript.TypeScriptProject { projenrcTs: false, projenrcJs: false, projenrcJson: false, + readme: options.readme ?? { + contents: isEmpty + ? [ + `# ${options.name}`, + '', + `Shared library used by sibling [d9](https://github.com/LaWebcapsule/d9) extensions in this workspace.`, + '', + 'Built via `tsc`; consumers depend on it with `@workspace:`.', + ].join('\n') + : [ + `# ${options.name}`, + '', + `[d9](https://github.com/LaWebcapsule/d9) extension (${extensionTypes.join(', ')}).`, + '', + '## Develop', + '', + 'Edit files under `src/`. The build step runs `directus-extension build` and copies the output into the parent project\'s `extensions/` folder so d9 picks it up (with `EXTENSIONS_AUTO_RELOAD=true`, no restart needed).', + '', + '```sh', + 'pnpm build # build this extension only', + '```', + '', + 'Or from the parent project root: `npx projen build-extensions` to build every extension.', + ].join('\n'), + }, devDeps: [ '@wbce/projen-directus-extension', '@wbce-d9/extensions-sdk', diff --git a/packages/directus/README.md b/packages/directus/README.md index b3fa7dd..496489b 100644 --- a/packages/directus/README.md +++ b/packages/directus/README.md @@ -1 +1,82 @@ -# replace this \ No newline at end of file +# @wbce/projen-directus + +Projen template for [d9](https://github.com/LaWebcapsule/d9) projects (fork of Directus v9). Scaffolds a local development setup with Docker Compose (Postgres + Redis), extension management, and GitHub workflows — then produces a Docker image you can deploy to any environment. + +Companion package: [`@wbce/projen-directus-extension`](../directus-extension) for authoring extensions. + +## Bootstrap a new project + +```sh +npx projen new --from @wbce/projen-directus +``` + +This creates a `.projenrc.js` and synthesizes the project. + +## Usage + +`.projenrc.js`: + +```js +import { DirectusProject } from '@wbce/projen-directus'; +import { DirectusExtensionType } from '@wbce/projen-directus-extension'; + +const project = new DirectusProject({ + name: 'my-d9', + defaultReleaseBranch: 'main', + eslintOptions: { + dirs: ['src', 'test'], + prettier: true, + }, +}); + +// A shared package other extensions can depend on +project.addExtension('shared', []); + +// A hook extension that depends on the shared package +const myHook = project.addExtension('my-hook', [DirectusExtensionType.HOOK]); +myHook.addDeps('shared@workspace:'); + +project.synth(); +``` + +Then synth and start it: + +```sh +npx projen +npx projen first-run # boot stack + create admin user +npx projen run # start d9 (port 8055) +``` + +The default admin user is `admin@example.com` / `totototo`. + +### Extension types + +`DirectusExtensionType` values: `INTERFACE`, `DISPLAY`, `LAYOUT`, `MODULE`, `PANEL`, `ENDPOINT`, `HOOK`, `OPERATION`. Pass an empty array for a shared (non-extension) package. + +Extensions live under `./plugins/` (configurable via `extensionsFolderName`) and are built by the `build-extensions` task. + +## Generated tasks + +| Task | Description | +| --- | --- | +| `first-run` | Boot the stack, create admin, start d9 | +| `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 with healthchecks +- `Dockerfile` — Node 22 + pnpm, builds extensions +- `.env.local` — sample for local environment overrides +- GitHub workflows via [`@wbce/projen-shared`](../shared) (set `githubConfig: false` to disable) +- A `*-save` branch workflow that auto-opens a PR back to the base branch + +## Options + +See [API.md](./API.md) for the full `DirectusProjectOptions` reference. Highlights: + +- `extensionsFolderName` — folder for extension packages (default: `plugins`) +- `packageVersions.d9` — version of `@wbce-d9/directus9` (default: `12.0.1`) +- `packageVersions.atlas` — version of `@ariga/atlas` (default: `0.32.0`) +- `githubConfig` — `GitHubConfigOptions` or `false` to disable \ No newline at end of file diff --git a/packages/directus/src/index.ts b/packages/directus/src/index.ts index 55c2c32..90b9a51 100644 --- a/packages/directus/src/index.ts +++ b/packages/directus/src/index.ts @@ -57,6 +57,59 @@ export class DirectusProject extends javascript.NodeProject { }, }, licensed: false, + readme: options.readme ?? { + contents: [ + `# ${options.name}`, + '', + 'A [d9](https://github.com/LaWebcapsule/d9) (Directus 9 fork) project scaffolded with [`@wbce/projen-directus`](https://www.npmjs.com/package/@wbce/projen-directus). Develop locally against Docker Compose, then build a Docker image to deploy anywhere.', + '', + '## Local development', + '', + '```sh', + 'npx projen install # install dependencies', + 'npx projen first-run # boot stack, create admin, start d9', + '```', + '', + 'Open http://localhost:8055 and sign in as `admin@example.com` / `totototo`. Extensions auto-reload (`EXTENSIONS_AUTO_RELOAD=true`).', + '', + '## Deploy', + '', + 'A `Dockerfile` is included. Build and push the image for your target environment:', + '', + '```sh', + 'docker build -t /: .', + 'docker push /:', + '```', + '', + 'Configure the deployed instance with environment variables (database, cache, secrets) — see the d9 docs.', + '', + '## Common tasks', + '', + '| Task | Description |', + '| --- | --- |', + '| `npx projen run` | Start d9 (`docker compose up directus`) |', + '| `npx projen build-extensions` | Install and build all extensions |', + '| `npx projen create-an-admin` | Create the default admin user |', + '', + 'See `.projen/tasks.json` for the full list.', + '', + '## Configuration', + '', + 'Edit `.projenrc.js` and run `npx projen` to regenerate project files. Local environment overrides go in `.env.local`.', + '', + '## Extensions', + '', + 'Extensions live under `./plugins/`. Add new ones in `.projenrc.js`:', + '', + '```js', + "import { DirectusExtensionType } from '@wbce/projen-directus-extension';", + '', + "project.addExtension('my-hook', [DirectusExtensionType.HOOK]);", + '```', + '', + 'Then `npx projen && npx projen build-extensions`.', + ].join('\n'), + }, devDeps: [ '@wbce/projen-directus', '@wbce/projen-directus-extension', From bc57aacfaee1274670742c4c216238a08f929903 Mon Sep 17 00:00:00 2001 From: louis Date: Fri, 15 May 2026 16:30:10 +0200 Subject: [PATCH 2/3] suite --- .changeset/stale-showers-write.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/stale-showers-write.md diff --git a/.changeset/stale-showers-write.md b/.changeset/stale-showers-write.md new file mode 100644 index 0000000..0ef8923 --- /dev/null +++ b/.changeset/stale-showers-write.md @@ -0,0 +1,6 @@ +--- +"@wbce/projen-directus-extension": patch +"@wbce/projen-directus": patch +--- + +add readmes From 40f3d80bcded6e5b26e1ac62e9194077e7328755 Mon Sep 17 00:00:00 2001 From: louis Date: Fri, 15 May 2026 16:36:17 +0200 Subject: [PATCH 3/3] suite --- packages/directus/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/directus/README.md b/packages/directus/README.md index 496489b..6d6a5c7 100644 --- a/packages/directus/README.md +++ b/packages/directus/README.md @@ -70,7 +70,6 @@ Extensions live under `./plugins/` (configurable via `extensionsFolderName`) and - `Dockerfile` — Node 22 + pnpm, builds extensions - `.env.local` — sample for local environment overrides - GitHub workflows via [`@wbce/projen-shared`](../shared) (set `githubConfig: false` to disable) -- A `*-save` branch workflow that auto-opens a PR back to the base branch ## Options