Configuration Reference

Complete reference for all nuxt-directus-sdk configuration options.

Module Options

Configure the module in your nuxt.config.ts:

typescript

export default defineNuxtConfig({
  modules: ['nuxt-directus-sdk'],

  directus: {
    // Configuration options here
  },
})

Module options are automatically loaded into Nuxt RuntimeConfig().

adminToken is automatically excluded from public runtime config for security.

typescript

// Client-side and server-side
const config = useRuntimeConfig()
console.log(config.public.directus.url)

// Server-side only (includes adminToken)
const config = useRuntimeConfig()
console.log(config.directus.adminToken)

All Configuration Options

typescript

export default defineNuxtConfig({
  modules: ['nuxt-directus-sdk'],

  directus: { 
    // Core configuration — simple string
    url: process.env.DIRECTUS_URL,
    // Or split URLs for Docker/K8s:
    // url: { client: 'https://cms.example.com', server: 'http://directus:8055' },
    adminToken: process.env.DIRECTUS_ADMIN_TOKEN,

    // Development
    devProxy: {
      enabled: true,
      path: '/directus',
      wsPath: '/directus-ws',
    },
    devtools: true,
    visualEditor: true,

    // Image integration
    image: true, // Directus provider is automatically configured

    // Type generation
    types: {
      enabled: true,
      prefix: 'App',
    },

    // Authentication
    auth: {
      enabled: true,
      enableGlobalAuthMiddleware: false,
      autoRefresh: true,
      credentials: 'include',
      realtimeAuthMode: 'handshake',
      readMeFields: ['id', 'email', 'first_name', 'last_name', 'avatar', 'role'],
      redirect: {
        home: '/',
        login: '/auth/login',
        logout: '/',
      },
    },
  },
})

Core Options

`url`

Type: string | { client: string, server: string }
Required: Yes
Default: process.env.DIRECTUS_URL
Environment Variable: DIRECTUS_URL

Your Directus instance URL. Can be a simple string, or an object with separate client and server URLs for environments where SSR needs to reach Directus via an internal hostname (e.g. Docker, Kubernetes).

typescript

export default defineNuxtConfig({
  directus: {
    // Simple string — used everywhere
    url: 'https://your-directus-instance.com',

    // Or split URLs for Docker/K8s
    url: {
      client: 'https://cms.example.com', // Browser requests
      server: 'http://directus:8055', // SSR / server-side requests
    },
  },
})

Or use environment variable (string form only):

dotenv

DIRECTUS_URL=https://your-directus-instance.com

When to use split URLs

Use the object form when your Nuxt server can reach Directus via an internal network address that browsers can't access. Common scenarios:

Docker Compose: server: 'http://directus:8055' (container name)
Kubernetes: server: 'http://directus-service.default.svc.cluster.local:8055'
Private network: server: 'http://10.0.0.5:8055'

The client URL is what browsers use and what SSO redirects point to. The server URL is only used during SSR and is never exposed to the browser.

`adminToken`

Type: string
Required: No (required for type generation and admin operations)
Default: process.env.DIRECTUS_ADMIN_TOKEN
Environment Variable: DIRECTUS_ADMIN_TOKEN

Admin token for privileged operations and type generation.

typescript

export default defineNuxtConfig({
  directus: {
  },
})

Or use environment variable:

dotenv

DIRECTUS_ADMIN_TOKEN=your-admin-token-here

Security Note: Never commit admin tokens to version control. Always use environment variables.

Development Options

`devProxy`

Type: boolean | { enabled?: boolean, path?: string, wsPath?: string }
Default: { enabled: true, path: '/directus', wsPath: '/directus-ws' } in dev mode
Default: false in production

Development proxy configuration. When enabled, creates a proxy that forwards requests to your Directus instance, eliminating CORS issues and supporting dynamic ports.

typescript

export default defineNuxtConfig({
  directus: {
    // Simple boolean
    devProxy: true,

    // Or detailed configuration
    devProxy: {
      enabled: true,
      path: '/directus', // HTTP proxy mount path
      wsPath: '/directus-ws', // WebSocket proxy path (optional)
    },
  },
})

How it works:

In development: Requests automatically route through the proxy using the current port
Supports Nuxt's dynamic port changes (e.g., port 3000 → 3001)
In production: Direct connection to Directus URL
WebSocket proxy available at wsPath for realtime features

Disable proxy:

typescript

export default defineNuxtConfig({
  directus: {
    devProxy: false, // Use direct connection in dev
  },
})

`devtools`

Type: boolean
Default: true

Add Directus admin panel to Nuxt Devtools.

typescript

export default defineNuxtConfig({
  directus: {
    devtools: true, // Enable Directus tab in devtools
  },
})

When enabled, you can access the Directus admin panel directly from Nuxt Devtools.

`visualEditor`

Type: boolean
Default: true

Enable visual editor capabilities. When enabled, the module:

Automatically detects when your site is loaded inside a Directus admin iframe
Renders data-directus attributes on DirectusVisualEditor components (only inside the iframe)
Applies the @directus/visual-editing SDK to enable inline editing
Calls refreshNuxtData() when content is saved (no full page reload)

typescript

export default defineNuxtConfig({
  directus: {
    visualEditor: true, // Enable visual editor (default)
  },
})

When disabled, DirectusVisualEditor renders as a pass-through wrapper with no attributes.

Add ?debug to any page URL to enable debug logging for the visual editor in the browser console. This is useful for diagnosing CSP issues, URL mismatches, and iframe detection on staging/production deployments.

`image`

Type: boolean | { enabled?: boolean, setDefaultProvider?: boolean }
Default: true

Configure @nuxt/image integration with Directus provider.

typescript

export default defineNuxtConfig({
  directus: {
    // Enable with defaults
    image: true,

    // Disable @nuxt/image integration
    image: false,

    // Set Directus as default provider
    image: {
      setDefaultProvider: true,
    },
  },
})

Options

enabled (boolean, default: true) - Enable/disable @nuxt/image integration
setDefaultProvider (boolean, default: false) - Set Directus as the default provider for <NuxtImg> components (no need to specify provider="directus")

When enabled, the module automatically:

Installs and configures @nuxt/image
Sets up the Directus provider with your instance's assets endpoint

Usage

With setDefaultProvider: false (default):

vue

<NuxtImg
  provider="directus"
  src="your-file-id"
  width="800"
  height="600"
/>

With setDefaultProvider: true:

vue

<!-- No need to specify provider -->
<NuxtImg
  src="your-file-id"
  width="800"
  height="600"
/>

See the File Management Guide for more details.

Type Generation

The module generates TypeScript types from your Directus schema at build time. Enabled by default when DIRECTUS_ADMIN_TOKEN is set.

See the Type Generation guide for what gets generated, the prefix option, and advanced filtering (include / exclude / expandReferences / verbose). The standalone CLI is documented on the generate-types CLI page.

`types`

Type: boolean | { enabled?: boolean, prefix?: string, include?: string[], expandReferences?: boolean, exclude?: string[], verbose?: boolean }
Default: true

Enable/disable automatic type generation from your Directus schema.

typescript

export default defineNuxtConfig({
  directus: {
    types: true, // Generate types from Directus schema
  },
})

Requires adminToken to be set.

When enabled, types are automatically generated and available globally:

typescript

// Access generated types
type Article = DirectusSchema['articles']
type User = DirectusUser
type File = DirectusFile

// Use with Directus SDK - fully typed!
const directus = useDirectus()
const articles = await directus.request(readItems('articles'))
// articles is typed as Article[]

Disable type generation:

typescript

export default defineNuxtConfig({
  directus: {
    types: false,
  },
})

See the Type Generation guide for:

Type prefix to avoid naming conflicts
Filtering collectionsadvanced with include / exclude / expandReferences / verbose
Manually Generating Typesadvanced that work with the module
Using the CLI for on-demand generation

SDK Auto-Imports

`autoImportSdk`

Type: boolean | { exclude?: string[] }
Default: true

Controls whether the module auto-imports functions from @directus/sdk. By default every SDK function is auto-imported (minus a small list the module wraps or explicitly doesn't support — see Composables > Auto-Imported Directus SDK Functions).

Disable entirely — you'll need to import { ... } from '@directus/sdk' wherever you use them:

typescript

export default defineNuxtConfig({
  directus: {
    autoImportSdk: false,
  },
})

Exclude specific functions — useful if an SDK function name collides with something else in your app:

typescript

export default defineNuxtConfig({
  directus: {
    autoImportSdk: {
      exclude: ['aggregate', 'customEndpoint'],
    },
  },
})

Your exclude list is added to the module's built-in exclusions; you don't need to repeat createDirectus, rest, etc.

Tree-shaking means disabling auto-imports has no bundle-size benefit for end users — unused SDK functions don't ship regardless. The option exists for collisions and for teams that prefer explicit imports.

Authentication Options

`auth`

Authentication configuration.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      // Auth options here
    },
  },
})

`auth.enabled`

Type: boolean
Default: true

Enable/disable authentication features.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      enabled: true,
    },
  },
})

`auth.enableGlobalAuthMiddleware`

Type: boolean
Default: false

Enable global authentication middleware on all routes.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      enableGlobalAuthMiddleware: true, // All routes require auth by default
    },
  },
})

When enabled, all routes are protected. Allow public routes with:

vue

<script setup>
definePageMeta({
  middleware: [] // Override global middleware
})
</script>

`auth.autoRefresh`

Type: boolean
Default: true

Automatically refresh authentication tokens before expiry.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      autoRefresh: true, // Auto-refresh session tokens
    },
  },
})

`auth.credentials`

Type: 'include' | 'omit' | 'same-origin'
Default: 'include'

Credentials mode for cross-domain requests.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      credentials: 'include', // Required for cross-domain cookies
    },
  },
})

Options:

'include' - Always send cookies (required for cross-domain)
'same-origin' - Only send cookies for same-origin requests
'omit' - Never send cookies

`auth.realtimeAuthMode`

Type: 'public' | 'handshake' | 'strict'
Default: 'public'

WebSocket authentication mode for realtime features.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      realtimeAuthMode: 'handshake',
    },
  },
})

Modes:

'public' - No authentication required
'handshake' - Authenticate during connection
'strict' - Full authentication required

`auth.readMeFields`

Type: Array<string>
Default: [] (fetches all fields)

Fields to fetch for the current user.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      readMeFields: ['id', 'email', 'first_name', 'last_name', 'avatar'],
    },
  },
})

Reduces payload size by only fetching needed fields.

`auth.redirect`

Redirect configuration for authentication.

typescript

export default defineNuxtConfig({
  directus: {
    auth: {
      redirect: {
        home: '/', // After login
        login: '/auth/login', // When not authenticated
        logout: '/', // After logout
      },
    },
  },
})

`auth.redirect.home`

Type: string
Default: '/'

Where to redirect after successful login.

`auth.redirect.login`

Type: string
Default: '/auth/login'

Where to redirect when authentication is required.

`auth.redirect.logout`

Type: string
Default: '/'

Where to redirect after logout.

Environment Variables

.env for Development

dotenv

# Required
DIRECTUS_URL=http://localhost:8055

# Optional (for type generation and admin operations)
DIRECTUS_ADMIN_TOKEN=your-admin-token-here

.env for Production

For production, set environment variables in your hosting platform:

Vercel:

bash

vercel env add DIRECTUS_URL production
vercel env add DIRECTUS_ADMIN_TOKEN production

Netlify:

bash

# In Netlify UI: Site settings → Environment variables
DIRECTUS_URL=https://your-directus.com
DIRECTUS_ADMIN_TOKEN=your-token

Docker:

dockerfile

ENV DIRECTUS_URL=https://your-directus.com
ENV DIRECTUS_ADMIN_TOKEN=your-token

Docker with split URLs

When using Docker Compose, you can use the object URL form in nuxt.config.ts to route SSR requests through the internal Docker network:

typescript

export default defineNuxtConfig({
  directus: {
    url: {
      client: 'https://cms.example.com',
      server: 'http://directus:8055', // Docker service name
    },
  }
})

Directus Server Configuration

Required Directus Settings

For the module to work correctly, configure your Directus instance:

dotenv

# Directus .env

# Authentication
AUTH_LOCAL_MODE=session

# Session cookies
SESSION_COOKIE_SECURE=true  # false in development
SESSION_COOKIE_SAME_SITE=Lax  # None for cross-domain
SESSION_COOKIE_DOMAIN=.yourdomain.com  # For cross-domain

# CORS (required)
CORS_ENABLED=true
CORS_ORIGIN=https://your-nuxt-app.com
CORS_CREDENTIALS=true

# Realtime/WebSocket (optional)
WEBSOCKETS_ENABLED=true
WEBSOCKETS_REST_AUTH=strict

Same Domain Setup

If Nuxt and Directus are on the same domain:

dotenv

# Directus .env
SESSION_COOKIE_SECURE=false  # true in production
SESSION_COOKIE_SAME_SITE=Lax
CORS_ORIGIN=http://localhost:3000

Cross-Domain Setup

If on different domains (e.g., app.example.com and api.example.com):

dotenv

# Directus .env
SESSION_COOKIE_DOMAIN=.example.com  # Shared parent domain
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_SAME_SITE=None  # Required for cross-domain
CORS_ORIGIN=https://app.example.com

TypeScript Configuration

The module automatically adds type declarations. Ensure your tsconfig.json extends Nuxt's config:

json

{
  "extends": "./.nuxt/tsconfig.json"
}

Generated types are available globally:

typescript

// Access generated types
type Article = DirectusSchema['articles']
type User = DirectusUser
type File = DirectusFile

// Use with Directus SDK
const directus = useDirectus()
const articles = await directus.request(readItems('articles'))
// articles is typed as Article[]

Configuration Reference ​

Module Options ​

Core Options ​

url ​

adminToken ​

Development Options ​

devProxy ​

devtools ​

visualEditor ​

image ​

Options ​

Usage ​

Type Generation ​

types ​

SDK Auto-Imports ​

autoImportSdk ​

Authentication Options ​

auth ​

auth.enabled ​

auth.enableGlobalAuthMiddleware ​

auth.autoRefresh ​

auth.credentials ​

auth.realtimeAuthMode ​

auth.readMeFields ​

auth.redirect ​

auth.redirect.home ​

auth.redirect.login ​

auth.redirect.logout ​

Environment Variables ​

.env for Development ​

.env for Production ​

Directus Server Configuration ​

Required Directus Settings ​

Same Domain Setup ​

Cross-Domain Setup ​

TypeScript Configuration ​

See Also ​

Configuration Reference

Module Options

Core Options

`url`

`adminToken`

Development Options

`devProxy`

`devtools`

`visualEditor`

`image`

Options

Usage

Type Generation

`types`

SDK Auto-Imports

`autoImportSdk`

Authentication Options

`auth`

`auth.enabled`

`auth.enableGlobalAuthMiddleware`

`auth.autoRefresh`

`auth.credentials`

`auth.realtimeAuthMode`

`auth.readMeFields`

`auth.redirect`

`auth.redirect.home`

`auth.redirect.login`

`auth.redirect.logout`

Environment Variables

.env for Development

.env for Production

Directus Server Configuration

Required Directus Settings

Same Domain Setup

Cross-Domain Setup

TypeScript Configuration

See Also