Initialize Directus + Next.js Stack
Bootstrap checklist: versions, environment, dependencies, client, verification. How each tool works is in directus-dev and nextjs-dev; this skill says which of their pieces to use and in what order.
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) |
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; the Directus Flow sends it in a header (see deployment) |
.env.local is not committed. A variable with the NEXT_PUBLIC_ prefix is shipped to the browser: only the address may have it, never a token.
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.
4. Dependencies
npm install @directus/sdk@26 server-only
server-only makes the build fail when a Client Component imports the Directus client. 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.
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. Verify Connections
- Directus is up:
curl "$NEXT_PUBLIC_DIRECTUS_URL/server/ping"answerspong. - MCP: call the Directus MCP
schematool with no parameters. It lists the collections. If it fails, check Settings → AI → Model Context Protocol and the token. - SDK and token: a temporary route that reads a core collection and pings:
// 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.
8. Project CLAUDE.md
Copy templates/CLAUDE.md.template to the project root as CLAUDE.md and replace [PROJECT_NAME] and [DIRECTUS_URL].