nuxt-directus-sdk 6.0.0-beta.0 → 6.0.0-beta.2

package/README.md

@@ -2,22 +2,30 @@
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![CI][ci-src]][ci-href]
+[![Install size][install-size-src]][install-size-href]
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-> A Nuxt 4 Directus module that uses the Directus SDK to enhance your Nuxt application
+> A Nuxt module for Directus with built-in authentication, realtime, file management, type generation, and visual editor support.
 
-- [✨  Release Notes](/CHANGELOG.md)
+- [✨  Release Notes](https://github.com/rolleyio/nuxt-directus-sdk/releases)
 - [📚  Documentation](https://nuxt-directus-sdk.rolley.io)
 
 ## Features
 
 - 🔒  **Session-based authentication** with cross-domain support
-- ⛰  Authentication out of the box
-- 🚠  Type generation based on Directus collections
-- 🔥  Typesafe Client Websockets enabled
-- 🌉  Automatically configures Nuxt Image for directus
-- 🗂️  Directus Admin panel added to Devtools
+- ⚡  **Realtime** via typed WebSocket subscriptions
+- 📁  **File management** with `@nuxt/image` integration
+- ✏️  **Visual editor** support for `@directus/visual-editing`
+- 🧩  **Auto-generated types** from your Directus schema, plus a standalone CLI
+- 📐  **Rules DSL** for defining and syncing permissions in code
+- 🗂️  Directus admin panel embedded in Nuxt Devtools
+
+## Requirements
+
+- **Nuxt 4.0+**
+- **Directus v11.16.0+** (required by the bundled `@directus/visual-editing` v2 and `@directus/sdk` v21)
 
 ## Quick Setup
 
@@ -39,19 +47,12 @@ bun install --save-dev nuxt-directus-sdk
 
 2. Add `nuxt-directus-sdk` to the `modules` section of `nuxt.config.ts`
 
-```js
+```ts
 export default defineNuxtConfig({
-  modules: [
-    'nuxt-directus-sdk'
-  ],
+  modules: ['nuxt-directus-sdk'],
   directus: {
-    // Optional: customize authentication (defaults shown)
-    auth: {
-      autoRefresh: true,
-      credentials: 'include', // Required for cross-domain
-      realtimeAuthMode: 'public',
-    }
-  }
+    url: process.env.DIRECTUS_URL,
+  },
 })
 ```
 
@@ -59,47 +60,68 @@ export default defineNuxtConfig({
 
 ```dotenv
 DIRECTUS_URL=https://your-directus-url.com
-DIRECTUS_ADMIN_TOKEN=your_admin_token # Optional: for type generation
+DIRECTUS_ADMIN_TOKEN=your_admin_token # Optional: required for type generation
 ```
 
-4. **Configure your Directus backend** for cross-domain authentication (see [Authentication Guide](https://nuxt-directus-sdk.rolley.io/guide/authentication.html))
+4. **Configure your Directus backend** for cross-domain authentication (see the [Authentication Guide](https://nuxt-directus-sdk.rolley.io/guide/authentication.html))
 
 That's it! You can now use Directus within your Nuxt app ✨
 
-For cross-domain setups (e.g., `app.example.com` ↔ `api.example.com`), see the [Authentication Guide](https://nuxt-directus-sdk.rolley.io/guide/authentication.html).
+For cross-domain setups (e.g. `app.example.com` and `api.example.com`), see the [Authentication Guide](https://nuxt-directus-sdk.rolley.io/guide/authentication.html).
+
+## CLI
+
+The module ships with a CLI for type generation and permissions/rules sync that doesn't require a running Nuxt instance. Useful in CI, pre-commit hooks, or quick regeneration during development.
+
+```bash
+# Generate TypeScript types from a Directus schema
+npx nuxt-directus-sdk generate-types --prefix App -o types/directus.d.ts
+
+# Pull permissions/rules to a JSON file
+npx nuxt-directus-sdk rules:pull -o rules.json
+
+# See all commands
+npx nuxt-directus-sdk --help
+```
+
+See the [CLI documentation](https://nuxt-directus-sdk.rolley.io/api/configuration/module#types) for flags and examples.
 
 ## Development
 
-> [!IMPORTANT] The playground uses [directus-template-cli](https://github.com/directus-labs/directus-template-cli?tab=readme-ov-file#applying-a-template) `cms` template.
+> [!IMPORTANT] The playground uses the [directus-template-cli](https://github.com/directus-labs/directus-template-cli?tab=readme-ov-file#applying-a-template) `cms` template.
 > Apply the template with `npx directus-template-cli@latest apply` and follow the interactive prompts.
 
 ```bash
 # Install dependencies
-bun install
+pnpm install
 
 # Add DIRECTUS_ADMIN_TOKEN to playground .env (don't forget to update your token)
 cp ./playground/.env.example ./playground/.env
 
 # Generate type stubs
-bun run dev:prepare
+pnpm run dev:prepare
 
 # Develop with the playground
-bun run dev
+pnpm run dev
 
 # Build the playground
-bun run dev:build
+pnpm run dev:build
 
 # Run ESLint
-bun run lint
+pnpm run lint
 
 # Run Vitest
-bun run test
-bun run test:watch
+pnpm run test
+pnpm run test:watch
 
-# Release new version
-bun run release
+# Release new version (see RELEASING.md)
+pnpm run release
 ```
 
+## Contributing
+
+Contributions are welcome. Please target the `next` branch for new features and fixes; `main` is reserved for stable releases and hotfixes. See [RELEASING.md](./RELEASING.md) for the release process.
+
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/nuxt-directus-sdk/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
 [npm-version-href]: https://npmjs.com/package/nuxt-directus-sdk
@@ -107,6 +129,12 @@ bun run release
 [npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-directus-sdk.svg?style=flat&colorA=18181B&colorB=28CF8D
 [npm-downloads-href]: https://npmjs.com/package/nuxt-directus-sdk
 
+[ci-src]: https://github.com/rolleyio/nuxt-directus-sdk/actions/workflows/ci.yml/badge.svg?branch=main
+[ci-href]: https://github.com/rolleyio/nuxt-directus-sdk/actions/workflows/ci.yml
+
+[install-size-src]: https://packagephobia.com/badge?p=nuxt-directus-sdk
+[install-size-href]: https://packagephobia.com/result?p=nuxt-directus-sdk
+
 [license-src]: https://img.shields.io/npm/l/nuxt-directus-sdk.svg?style=flat&colorA=18181B&colorB=28CF8D
 [license-href]: https://npmjs.com/package/nuxt-directus-sdk
 

package/dist/cli/index.mjs

@@ -1,9 +1,23 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
 import { parseArgs } from 'node:util';
 import { createDirectus, staticToken, rest } from '@directus/sdk';
-import { d as diffRemoteRules, e as formatDiff, c as compareRulesPayloads, f as fetchRemoteRules, k as loadRulesFromPayload, o as pushRules, g as formatPushResult, b as fetchRemoteRulesAsJson } from '../shared/nuxt-directus-sdk.1qEbZAZ_.mjs';
+import { d as diffRemoteRules, e as formatDiff, c as compareRulesPayloads, f as fetchRemoteRules, k as loadRulesFromPayload, o as pushRules, g as formatPushResult, b as fetchRemoteRulesAsJson } from '../shared/nuxt-directus-sdk.BzXguU5u.mjs';
+import { generateTypesFromDirectus } from '../../dist/runtime/types/generate.js';
+
+function parseCsv(raw) {
+  if (!raw)
+    return [];
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function resolveNegatableBoolean(positive, negative, fallback) {
+  if (negative)
+    return false;
+  if (positive !== void 0)
+    return positive;
+  return fallback;
+}
 
 function loadEnv() {
   const envPath = resolve(process.cwd(), ".env");
@@ -28,12 +42,14 @@ function getConnectionConfig(urlFlag, tokenFlag, label) {
   const token = tokenFlag ?? process.env.DIRECTUS_ADMIN_TOKEN;
   if (!url) {
     console.error(`Error: ${label} URL is required`);
-    console.error(`Provide --${label.toLowerCase()}-url or set DIRECTUS_URL in your .env file`);
+    const flagHint = label === "Source" ? "--url (or --source-url)" : `--${label.toLowerCase()}-url`;
+    console.error(`Provide ${flagHint} or set DIRECTUS_URL in your .env file`);
     process.exit(1);
   }
   if (!token) {
     console.error(`Error: ${label} token is required`);
-    console.error(`Provide --${label.toLowerCase()}-token or set DIRECTUS_ADMIN_TOKEN in your .env file`);
+    const flagHint = label === "Source" ? "--token (or --source-token)" : `--${label.toLowerCase()}-token`;
+    console.error(`Provide ${flagHint} or set DIRECTUS_ADMIN_TOKEN in your .env file`);
     process.exit(1);
   }
   return { url, token };
@@ -43,7 +59,7 @@ function createClient(url, token) {
 }
 function printHelp() {
   console.log(`
-Directus Rules CLI
+nuxt-directus-sdk CLI
 
 Usage:
   npx nuxt-directus-sdk <command> [options]
@@ -54,24 +70,40 @@ Commands:
   rules:diff <file>         Compare local JSON file with remote Directus
   rules:diff-files <a> <b>  Compare two local JSON files
   rules:diff-remote         Compare two remote Directus instances
+  generate-types            Generate TypeScript types from a Directus schema
 
 Options:
   -h, --help                Show this help message
-  -o, --output <file>       Output file path (default: rules.json)
+  -o, --output <file>       Output file path (default: stdout for generate-types, rules.json for rules:pull)
   --compact                 Output compact JSON (no pretty-print)
   --dry-run                 Show what would be changed without making changes (rules:push)
   --add-only                Only add new items, don't modify or delete existing (rules:push)
   --skip-deletes            Skip deleting items that exist remotely but not locally (rules:push)
+  --prefix <prefix>         Prefix for custom collection type names (generate-types)
+  --include <names>         Comma-separated collection names to include (generate-types).
+                            When set, only these collections (plus any they reference
+                            via --expand-references, default on) are emitted.
+                            Takes precedence over --exclude if both are set.
+  --no-expand-references    When --include is set, do NOT follow references to other
+                            collections. Strict include mode \u2014 references to collections
+                            not in the list collapse to \`string\`. (generate-types)
+  --exclude <names>         Comma-separated collection names to exclude (generate-types).
+                            References to excluded types are rewritten to \`string\`.
+  --verbose                 Show per-target warnings listing every field whose reference
+                            was collapsed to \`string\` (generate-types).
+  --no-declare-global       Emit types without the \`declare global\` wrapper (generate-types)
 
   Connection options (override DIRECTUS_URL / DIRECTUS_ADMIN_TOKEN):
+  --url <url>               Directus URL (alias of --source-url)
+  --token <token>           Admin token (alias of --source-token)
   --source-url <url>        Source Directus URL
   --source-token <token>    Source admin token
   --target-url <url>        Target Directus URL (for rules:diff-remote)
   --target-token <token>    Target admin token (for rules:diff-remote)
 
 Environment Variables:
-  DIRECTUS_URL              Default Directus URL (used if --source-url not provided)
-  DIRECTUS_ADMIN_TOKEN      Default admin token (used if --source-token not provided)
+  DIRECTUS_URL              Default Directus URL (used if --url / --source-url not provided)
+  DIRECTUS_ADMIN_TOKEN      Default admin token (used if --token / --source-token not provided)
 
 Examples:
   # Pull rules from Directus (uses env vars)
@@ -99,6 +131,27 @@ Examples:
   npx nuxt-directus-sdk rules:diff-remote \\
     --source-url https://staging.example.com --source-token staging-token \\
     --target-url https://production.example.com --target-token production-token
+
+  # Generate TypeScript types, pipe to a file
+  npx nuxt-directus-sdk generate-types > types/directus.d.ts
+
+  # Generate types with a prefix, write directly to a file
+  npx nuxt-directus-sdk generate-types --prefix App -o types/directus.d.ts
+
+  # Generate types from a specific instance
+  npx nuxt-directus-sdk generate-types --url https://my-directus.com --token my-token
+
+  # Exclude specific collections \u2014 references to them become \`string\`
+  npx nuxt-directus-sdk generate-types --exclude directus_activity,directus_revisions
+
+  # Include only specific collections (referenced collections auto-included)
+  npx nuxt-directus-sdk generate-types --include posts
+
+  # Strict include \u2014 only the listed collections, references collapse to \`string\`
+  npx nuxt-directus-sdk generate-types --include posts --no-expand-references
+
+  # Verbose \u2014 show every field whose reference was collapsed, grouped by target
+  npx nuxt-directus-sdk generate-types --exclude directus_users --verbose
 `);
 }
 function loadJsonFile(filePath) {
@@ -191,17 +244,67 @@ async function commandPush(localFile, connection, options) {
     process.exit(1);
   }
 }
+async function commandGenerateTypes(connection, options) {
+  console.error(`Generating types from ${connection.url}...`);
+  if (options.include.length > 0) {
+    console.error(`Including collections: ${options.include.join(", ")}`);
+  }
+  if (options.exclude.length > 0) {
+    console.error(`Excluding collections: ${options.exclude.join(", ")}`);
+  }
+  const { typeString, logs } = await generateTypesFromDirectus(
+    connection.url,
+    connection.token,
+    options.prefix,
+    {
+      include: options.include,
+      exclude: options.exclude,
+      expandReferences: options.expandReferences,
+      verbose: options.verbose
+    }
+  );
+  for (const line of logs) {
+    console.error(line);
+  }
+  if (!typeString) {
+    console.error("Error: Type generation returned empty output.");
+    process.exit(1);
+  }
+  const output = options.declareGlobal ? typeString : typeString.replace(/^declare global \{\n\n/, "").replace(/\n\}\n\nexport \{\};?\n?$/, "\n");
+  if (options.output) {
+    const outputPath = resolve(process.cwd(), options.output);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, output, "utf-8");
+    console.error(`Types written to ${outputPath}`);
+  } else {
+    process.stdout.write(output);
+  }
+}
 async function main() {
   loadEnv();
   const { values, positionals } = parseArgs({
     allowPositionals: true,
     options: {
       "help": { type: "boolean", short: "h" },
-      "output": { type: "string", short: "o", default: "rules.json" },
+      // `output` has no default here — each command applies its own fallback
+      // (rules:pull defaults to rules.json, generate-types defaults to stdout).
+      "output": { type: "string", short: "o" },
       "compact": { type: "boolean", default: false },
       "dry-run": { type: "boolean", default: false },
       "add-only": { type: "boolean", default: false },
       "skip-deletes": { type: "boolean", default: false },
+      "prefix": { type: "string", default: "" },
+      "include": { type: "string" },
+      "exclude": { type: "string" },
+      // Node's parseArgs doesn't support `--no-X` syntax natively, so we
+      // register both forms. Negation wins if both are passed.
+      "expand-references": { type: "boolean", default: true },
+      "no-expand-references": { type: "boolean" },
+      "verbose": { type: "boolean", default: false },
+      "declare-global": { type: "boolean", default: true },
+      "no-declare-global": { type: "boolean" },
+      "url": { type: "string" },
+      "token": { type: "string" },
       "source-url": { type: "string" },
       "source-token": { type: "string" },
       "target-url": { type: "string" },
@@ -217,12 +320,12 @@ async function main() {
     switch (command) {
       case "rules:pull": {
         const connection = getConnectionConfig(
-          values["source-url"],
-          values["source-token"],
+          values["source-url"] ?? values.url,
+          values["source-token"] ?? values.token,
           "Source"
         );
         await commandPull({
-          output: values.output,
+          output: values.output ?? "rules.json",
           compact: values.compact
         }, connection);
         break;
@@ -234,8 +337,8 @@ async function main() {
           process.exit(1);
         }
         const connection = getConnectionConfig(
-          values["source-url"],
-          values["source-token"],
+          values["source-url"] ?? values.url,
+          values["source-token"] ?? values.token,
           "Source"
         );
         await commandPush(positionals[1], connection, {
@@ -252,8 +355,8 @@ async function main() {
           process.exit(1);
         }
         const connection = getConnectionConfig(
-          values["source-url"],
-          values["source-token"],
+          values["source-url"] ?? values.url,
+          values["source-token"] ?? values.token,
           "Source"
         );
         await commandDiff(positionals[1], connection);
@@ -269,8 +372,8 @@ async function main() {
         break;
       case "rules:diff-remote": {
         const source = getConnectionConfig(
-          values["source-url"],
-          values["source-token"],
+          values["source-url"] ?? values.url,
+          values["source-token"] ?? values.token,
           "Source"
         );
         const target = getConnectionConfig(
@@ -281,6 +384,23 @@ async function main() {
         await commandDiffRemote(source, target);
         break;
       }
+      case "generate-types": {
+        const connection = getConnectionConfig(
+          values.url ?? values["source-url"],
+          values.token ?? values["source-token"],
+          "Source"
+        );
+        await commandGenerateTypes(connection, {
+          prefix: values.prefix ?? "",
+          output: values.output,
+          declareGlobal: resolveNegatableBoolean(values["declare-global"], values["no-declare-global"], true),
+          include: parseCsv(values.include),
+          exclude: parseCsv(values.exclude),
+          expandReferences: resolveNegatableBoolean(values["expand-references"], values["no-expand-references"], true),
+          verbose: values.verbose
+        });
+        break;
+      }
       default:
         console.error(`Unknown command: ${command}`);
         printHelp();

package/dist/module.d.mts

@@ -1,12 +1,12 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { Query } from '@directus/sdk';
+import { Query, DirectusUser } from '@directus/sdk';
 import { ImageProviders, ImageModifiers } from '@nuxt/image';
 
 type DirectusUrl = string | {
     client: string;
     server: string;
 };
-type ReadMeFields = Query<DirectusSchema, DirectusSchema['directus_users']>['fields'];
+type ReadMeFields = Query<DirectusSchema, DirectusUser<DirectusSchema>>['fields'];
 interface ModuleOptions {
     /**
      * Directus API URL
@@ -153,6 +153,61 @@ interface ModuleOptions {
          * @default ''
          */
         prefix?: string;
+        /**
+         * Collection names to include in the generated types. When non-empty,
+         * only these collections (plus any they reference — see
+         * `expandReferences`) are emitted. References to collections not in
+         * the resolved set collapse to `string` (M2O) or `string[]` (O2M).
+         *
+         * Takes precedence over `exclude` if both are set.
+         * @type string[]
+         * @default []
+         */
+        include?: string[];
+        /**
+         * When `include` is set, also pull in any collections referenced by
+         * the included collections (transitively). Follows M2O, O2M, and M2A.
+         * No-op when `include` is empty.
+         * @type boolean
+         * @default true
+         */
+        expandReferences?: boolean;
+        /**
+         * Collection names to exclude from generated types.
+         * References to excluded collections are rewritten to `string` (M2O) or
+         * `string[]` (O2M) so the generated types stay resolvable.
+         * @type string[]
+         * @default []
+         */
+        exclude?: string[];
+        /**
+         * When true, emit per-target warnings listing every field whose
+         * reference was collapsed to `string`/`string[]`. Field lists are
+         * capped at 5 per collection.
+         * @type boolean
+         * @default false
+         */
+        verbose?: boolean;
+    };
+    /**
+     * Auto-import functions from `@directus/sdk`.
+     *
+     * - `true` (default) — auto-imports every SDK function except those wrapped by
+     *   this module (e.g. `createDirectus`, `rest`, `authentication`) or explicitly
+     *   unsupported (e.g. `graphql`, `readGraphqlSdl`).
+     * - `false` — disables auto-imports entirely. You import from `@directus/sdk`
+     *   manually wherever you use SDK functions.
+     * - `{ exclude: [...] }` — auto-imports with additional functions excluded.
+     *   Useful if an SDK function name collides with something else in your app.
+     *
+     * @default true
+     */
+    autoImportSdk?: boolean | {
+        /**
+         * Additional SDK function names to exclude from auto-import.
+         * Added on top of the module's built-in exclusions.
+         */
+        exclude?: string[];
     };
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;

package/dist/module.d.ts

@@ -1,12 +1,12 @@
 import * as _nuxt_schema from '@nuxt/schema';
-import { Query } from '@directus/sdk';
+import { Query, DirectusUser } from '@directus/sdk';
 import { ImageProviders, ImageModifiers } from '@nuxt/image';
 
 type DirectusUrl = string | {
     client: string;
     server: string;
 };
-type ReadMeFields = Query<DirectusSchema, DirectusSchema['directus_users']>['fields'];
+type ReadMeFields = Query<DirectusSchema, DirectusUser<DirectusSchema>>['fields'];
 interface ModuleOptions {
     /**
      * Directus API URL
@@ -153,6 +153,61 @@ interface ModuleOptions {
          * @default ''
          */
         prefix?: string;
+        /**
+         * Collection names to include in the generated types. When non-empty,
+         * only these collections (plus any they reference — see
+         * `expandReferences`) are emitted. References to collections not in
+         * the resolved set collapse to `string` (M2O) or `string[]` (O2M).
+         *
+         * Takes precedence over `exclude` if both are set.
+         * @type string[]
+         * @default []
+         */
+        include?: string[];
+        /**
+         * When `include` is set, also pull in any collections referenced by
+         * the included collections (transitively). Follows M2O, O2M, and M2A.
+         * No-op when `include` is empty.
+         * @type boolean
+         * @default true
+         */
+        expandReferences?: boolean;
+        /**
+         * Collection names to exclude from generated types.
+         * References to excluded collections are rewritten to `string` (M2O) or
+         * `string[]` (O2M) so the generated types stay resolvable.
+         * @type string[]
+         * @default []
+         */
+        exclude?: string[];
+        /**
+         * When true, emit per-target warnings listing every field whose
+         * reference was collapsed to `string`/`string[]`. Field lists are
+         * capped at 5 per collection.
+         * @type boolean
+         * @default false
+         */
+        verbose?: boolean;
+    };
+    /**
+     * Auto-import functions from `@directus/sdk`.
+     *
+     * - `true` (default) — auto-imports every SDK function except those wrapped by
+     *   this module (e.g. `createDirectus`, `rest`, `authentication`) or explicitly
+     *   unsupported (e.g. `graphql`, `readGraphqlSdl`).
+     * - `false` — disables auto-imports entirely. You import from `@directus/sdk`
+     *   manually wherever you use SDK functions.
+     * - `{ exclude: [...] }` — auto-imports with additional functions excluded.
+     *   Useful if an SDK function name collides with something else in your app.
+     *
+     * @default true
+     */
+    autoImportSdk?: boolean | {
+        /**
+         * Additional SDK function names to exclude from auto-import.
+         * Added on top of the module's built-in exclusions.
+         */
+        exclude?: string[];
     };
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-directus-sdk",
-  "version": "6.0.0-beta.0",
+  "version": "6.0.0-beta.2",
   "configKey": "directus",
   "compatibility": {
     "nuxt": "^4.0.0"