Directus-typeforge NPM

Directus TypeForge

Directus TypeForge generates TypeScript definitions for Directus collections from an OpenAPI schema or a live Directus server. It supports both custom and system collections, providing accurate types for use with the Directus TypeScript SDK.

This tool is a fork and rewrite of elierotenberg/directus-typescript-gen.

View project on NPM | View project on GitHub

Features

Dynamic Generation: Get types from a static schema file or an active Directus instance
System Collections: Automatically handle Directus system collections with proper type definitions
Authentication Options: Support for email/password or bearer token authentication
Relationships: Represent collection relationships with proper TypeScript interfaces
Type Consistency: Generate singular type names (e.g., Event for events collection)
Special Field Types: Support for Directus-specific field types like datetime, JSON, and CSV
Customizable Output: Control the type name generation and references

Installation

Using `npx`

npx directus-typeforge [options]

Local Install

pnpm add -D directus-typeforge
npx directus-typeforge [options]

Global Install

pnpm add -g directus-typeforge
directus-typeforge [options]

Available Options

Option	Alias	Description	Default
`--specFile`	`-i`	Path to OpenAPI spec file	-
`--host`	`-h`	Directus host URL	-
`--email`	`-e`	Email for authentication	-
`--password`	`-p`	Password for authentication	-
`--token`	`-t`	Admin bearer token for authentication	-
`--outFile`	`-o`	Output file for TypeScript types	-
`--typeName`	`-n`	Root type name	`ApiCollections`
`--useTypeReferences`	`-r`	Use interface references for relation types	`true`
`--useTypes`	`-u`	Use 'type' instead of 'interface'	`false`

only disable --useTypeReferences for very specific debugging reasons, it will make all of your relational types break.

Usage Examples

# From a Spec File
npx directus-typeforge -i directus.oas.json > schema.d.ts

# From a Live Server with Email/Password
npx directus-typeforge --host https://example.com --email user@example.com --password pass123 --outFile schema.d.ts

# From a Live Server with Admin Token
npx directus-typeforge --host https://example.com --token your-static-token --outFile schema.d.ts

# Custom Root Type Name
npx directus-typeforge -i directus.oas.json --typeName MySchema > schema.d.ts

# Generate using 'type' instead of 'interface'
npx directus-typeforge -i ./directus.oas.json -u -o ./types/schema.d.ts

Expected Output

export interface Event {
  id: string;
  title?: string;
  start_date?: string;
  event_registrations?: string[] | EventRegistration[];
}

export interface EventRegistration {
  id: string;
  event?: string | Event;
  user?: string | CustomDirectusUser;
}

export interface Ticket {
  id: string;
  date_created?: string;
  date_updated?: string;
  title?: string;
  event?: string | Event;
}

// system collections with custom fields
export interface DirectusUser {
  id: string;
  stripe_customer_id?: string;
  verification_token?: string;
  verification_url?: string;
}

export interface ApiCollections {
  events: Event[];
  tickets: Ticket[];
  directus_users: DirectusUser[];
}

Integration with Directus SDK

Use the generated types directly with the Directus SDK for stronger type-checking and autocompletion:

import type { ApiCollections } from "$lib/types/directus/api-collection";
import { DIRECTUS_URL } from "$env/static/private";
import { createDirectus, rest } from "@directus/sdk";

export const initDirectus = () => {
  return createDirectus<ApiCollections>(DIRECTUS_URL).with(rest());
};

How It Works

TypeForge analyzes your Directus schema through the OpenAPI specification, extracting collection information, field definitions, and relationship mappings:

Schema Reading: Fetches the schema from a file or live Directus instance
Type Name Generation: Creates appropriate interface names for collections
Relationship Analysis: Identifies and properly types all relations
Property Generation: Maps API fields to TypeScript types with proper nullability
System Collection Handling: Identifies and processes Directus system collections
Root Type Creation: Generates a root type that includes all collections

Caveats

System Collections: System collections are generated with standard names like DirectusUser and include ID fields plus any custom, user-created fields. Only system collections with custom fields are included in the output.
JSON Repeaters: JSON repeaters are typed as unknown since there's no standardized structure information in the OpenAPI schema.
Complex Field Types: Some specialized Directus field types are typed with string literals (e.g., 'datetime', 'json', 'csv') to match the Directus SDK's expected types.
Special Types: Certain system types like permissions and settings use unknown for complex nested objects where the structure is variable.