Initialize Directus + Next.js + Trigger.dev Stack
Bootstrap checklist: versions, environment, dependencies, client, Trigger.dev project, verification. How each tool works is in directus-dev, nextjs-dev and trigger-dev; this skill says which of their pieces to use and in what order, and where the three meet.
1. Versions
| Piece | Version | Why |
|---|---|---|
| Directus | 12 (MCP needs 11.12 or later) | MCP is switched on in Settings → AI. The health endpoint needs a token in 12, use /server/ping |
@directus/sdk |
26 | Needs Node 22 or later |
| Next.js | ^16.3.8 |
proxy.ts replaces the deprecated middleware file; earlier 16.3 patches miss security fixes |
| Node.js | 22 or later | The SDK's floor (Next.js itself needs 20.9) |
| Trigger.dev server | 4.x, self-hosted | trigger-dev targets 4.4.4 as its baseline and marks newer features with the server version they need (spread window for schedules: 4.6.0) |
@trigger.dev/sdk, @trigger.dev/react-hooks, trigger.dev (CLI) |
the version of the server | One line for all four. A CLI or SDK that differs from the server makes deploy fail or behave unpredictably (trigger-dev → deployment) |
2. Environment File
cp templates/.env.example .env.local
| Variable | How to obtain |
|---|---|
NEXT_PUBLIC_DIRECTUS_URL |
Directus address (http://localhost:8055 for the local Docker stack) |
DIRECTUS_ADMIN_TOKEN |
Create a dedicated user in Directus with a policy that grants only what the server code reads and writes, then generate a static token on the user's page. The name is historical: an administrator token is for local development only |
DIRECTUS_URL, DIRECTUS_TOKEN, NEXT_PUBLIC_CMS_URL |
Already in .env.example as ${...} references to the two rows above. The recipes of directus-dev and nextjs-dev read these names (client, NextAuth, the images block of next.config.ts), so do not delete them |
NEXTAUTH_URL, NEXTAUTH_SECRET |
NextAuth path only: http://localhost:3000, and openssl rand -base64 32 |
REVALIDATION_SECRET |
openssl rand -base64 32; sent in a header by the Directus Flow, and by a task that calls the route itself (see deployment) |
DIRECTUS_WEBHOOK_SECRET |
openssl rand -base64 32; sent by the Directus Flow that starts a task. A different value from REVALIDATION_SECRET: starting tasks costs money, expiring a cache does not (see directus-to-trigger) |
TRIGGER_API_URL |
Address of the self-hosted Trigger.dev. Set it wherever tasks.trigger() runs: without it the SDK falls back to Trigger.dev Cloud and sends your key there |
TRIGGER_SECRET_KEY |
Trigger.dev dashboard → project → API keys → the environment secret key (tr_dev_… for dev). The SDK in the Next.js server triggers tasks with it |
TRIGGER_ACCESS_TOKEN |
Trigger.dev dashboard → Account → Personal Access Tokens (tr_pat_…). The MCP server and trigger deploy use it, the SDK does not |
TRIGGER_PROJECT_REF |
Project page → proj_… |
NEXT_PUBLIC_TRIGGER_API_URL |
Already in .env.example as ${TRIGGER_API_URL}: the address that browser hooks (baseURL) need. An address, never a key |
.env.local is not committed. A variable with the NEXT_PUBLIC_ prefix is shipped to the browser: only addresses may have it, never a token or a key.
3. Local Directus (optional)
Follow directus-dev → skill docker-local-dev (Compose file, .env, /server/ping check). Set LOCAL_FRONTEND_ORIGIN=http://localhost:3000 there so CORS and Live Preview accept the Next.js dev server, then use the local address as NEXT_PUBLIC_DIRECTUS_URL. The self-hosted Trigger.dev server is set up with trigger-dev → deployment → references/self-hosted-infrastructure.md; this stack assumes it is already running.
4. Dependencies
npm install @directus/sdk@26 server-only
npm install @trigger.dev/sdk@<server-version> @trigger.dev/react-hooks@<server-version>
npm install --save-dev trigger.dev@<server-version>
server-only makes the build fail when a Client Component imports the Directus client. trigger.dev is a development dependency, called through npx trigger.dev or an npm script, so the CLI is the version of the SDK instead of whatever @latest is today. Add next-auth@4 or better-auth only when you build login (see authentication).
5. Client and Types
Create lib/directus.ts and types/directus.ts as described in directus-dev → skill sdk-patterns → references/ssr-client.md, reading DIRECTUS_URL and DIRECTUS_TOKEN (they expand to this stack's NEXT_PUBLIC_DIRECTUS_URL and DIRECTUS_ADMIN_TOKEN). Two things from that file decide how the rest works:
rest()has nocacheoption (passingcachetorest()is TS2353). Caching is set per request: see "Cache" indirectus-to-nextjs.- Core collections are read with their own commands (
readCollections();readItemsrefusesdirectus_*collections).
Fill types/directus.ts from the real schema: call the Directus MCP schema tool and mirror each collection. Tasks import the same types/directus.ts but not lib/directus.ts, which carries import 'server-only' and throws outside Next.js (directus-to-trigger has the task-side client).
6. Images
Allow the Directus host in next.config.ts (images.remotePatterns, and dangerouslyAllowLocalIP for a local Directus): see nextjs-dev → skill data-fetching → references/headless-cms.md. How file URLs are built, and why they carry no token, is in "Assets" of directus-to-nextjs.
7. The Trigger.dev Project
Initialize with the CLI at the server's version, pointing at your instance (trigger-dev → setup has the flags, including the non-interactive form). Step 4 already installed the packages at the server's version, and init would install the newest SDK by default, so skip its install:
npx trigger.dev@<server-version> init --project-ref "$TRIGGER_PROJECT_REF" --api-url "$TRIGGER_API_URL" --skip-package-install
Then check three things that belong to this stack, not to Trigger.dev in general:
trigger.config.tstakes the project fromTRIGGER_PROJECT_REF(not a literalproj_…), setsmaxDuration, and lists./triggerindirs. The options are intrigger-dev→config-and-build.- Task files live in
trigger/and import@trigger.dev/sdk(no/v3path). The task-side Directus client is created inside the task, not imported fromlib/directus.ts. - Environment variables for deployed tasks are set in the Trigger.dev project, per environment. They do not come from
.env.localand not from the Next.js host (deploymentlists them).
Log the CLI in against your instance once (npx trigger.dev@<server-version> login --api-url "$TRIGGER_API_URL"), then start the dev server in its own terminal: npx trigger.dev@<server-version> dev.
8. Verify Connections
| Service | How to verify |
|---|---|
| Directus MCP | Call the schema tool with no parameters: it lists the collections. If it fails, check Settings → AI → Model Context Protocol and the token |
| Directus SDK | A temporary route (below) |
| Trigger.dev MCP | Call whoami or list_projects; with --dev-only in .mcp.json only the dev environment answers |
| Trigger.dev tasks | npx trigger.dev dev lists the tasks of trigger/; trigger the example task with the MCP trigger_task tool and read it with get_run_details |
| Next.js to Trigger.dev | A Server Action or route that calls tasks.trigger() returns a run id (see background-tasks) |
// app/api/directus-check/route.ts: temporary, delete it after the check
import directus from '@/lib/directus';
import { readCollections, serverPing } from '@directus/sdk';
export async function GET() {
const [pong, collections] = await Promise.all([
directus.request(serverPing()),
directus.request(readCollections()),
]);
return Response.json({ pong, collections: collections.length });
}
Open /api/directus-check with npm run dev. A 401 or 403 from Directus means the token is wrong or its user may not read the schema.
9. Project CLAUDE.md
Copy templates/CLAUDE.md.template to the project root as CLAUDE.md and replace [PROJECT_NAME], [DIRECTUS_URL] and [TRIGGER_API_URL].