Directus TypeForge

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

This tool works directly with Directus schema snapshots for improved accuracy and compatibility.

View project on NPM | View project on GitHub

Features

• Schema Snapshot Support: Generate types from a schema snapshot file or directly from a Directus server
• Singleton Collection Detection: Automatically identify and properly type singleton collections
• TypeDoc Support: Add JSDoc comments from field notes to your generated types
• System Collections Support: Properly handle Directus system collections with configurable detail levels
• Authentication Options: Support for email/password or bearer token authentication
• Relationship Handling: Generate proper TypeScript types for all relationship types (M2O, O2M, M2M, and M2A)
• Type Name Conventions: Generate appropriate type names by converting collection names to PascalCase and automatically handling pluralization (e.g., Event for an events collection, while preserving singleton collection names like Settings or Globals)
• SDK Compatibility: Generated types work seamlessly with the Directus SDK
• Customizable Output: Control type generation behavior with various options
• Configurable Architecture: All type detection patterns and mappings use a centralized configuration system

Installation

Using npx

1npx directus-typeforge [options]

Local Install

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

Global Install

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

Available Options

Option	Alias	Description	Default
--snapshotFile	-i	Path to schema snapshot 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
--makeRequired	-m	Make all fields required (no optional '?' syntax)	true
--includeSystemFields	-s	Include all system fields in system collections	true
--addTypedocNotes	-d	Add JSDoc comments from field notes	true
--debug		Enable debug logging	false
--logLevel		Set log level (error, warn, info, debug, trace)	info
--logFile		Path to write debug logs

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

SDK Compatibility Options

TypeForge is optimized for compatibility with the Directus SDK by default:

• Fields are required by default (no optional ? modifier) since the SDK handles nullability internally
• System fields are included by default to improve type checking with SDK operations
• TypeDoc comments are added from field notes
• Type references for relations are enabled

Usage Examples

1# From a Schema Snapshot File
2npx directus-typeforge -i schema-snapshot.json > schema.ts
3
4# From a Live Server with email/password
5npx directus-typeforge --host https://example.com --email user@example.com --password pass123 -o schema.ts
6
7# From a Live Server with token
8npx directus-typeforge --host https://example.com --token your-static-token -o schema.ts
9
10
11# Custom Root Type Name
12npx directus-typeforge -i schema-snapshot.json --typeName MySchema > schema.ts
13
14# Make fields optional (add ? syntax)
15npx directus-typeforge -i schema-snapshot.json --makeRequired=false -o ./types/schema.ts
16
17# Exclude system fields from system collections
18npx directus-typeforge -i schema-snapshot.json --includeSystemFields=false -o ./types/schema.ts
19
20# Disable JSDoc comments from field notes
21npx directus-typeforge -i schema-snapshot.json --addTypedocNotes=false -o ./types/schema.ts
22
23# Generate using 'type' instead of 'interface'
24npx directus-typeforge -i schema-snapshot.json -u -o ./types/schema.ts
25
26# Enable debug logging to troubleshoot issues
27npx directus-typeforge -i schema-snapshot.json --debug --logLevel debug --logFile ./typeforge-debug.log -o ./types/schema.ts

Expected Output

1export interface Event {
2  id: string;
3  title: string; // No optional ? with --makeRequired
4  start_date: string;
5  event_registrations: string[] | EventRegistration[];
6}
7
8export interface EventRegistration {
9  id: string;
10  event: string | Event;
11  user: string | DirectusUser;
12}
13
14export interface Ticket {
15  id: string;
16  date_created: string;
17  date_updated: string;
18  title: string;
19  event: string | Event;
20}
21
22// Junction table for many-to-many relationship
23export interface ArticlesCategory {
24  id: number;
25  articles_id: number[] | Article[];
26  categories_id: string[] | Category[];
27}
28
29// Junction table for many-to-any relationship
30export interface ProductsRelatedItem {
31  id: number;
32  products_id: number[] | Product[];
33  item: string; // ID of the related item
34  collection: string; // Collection of the related item
35}
36
37// Full system collection with --includeSystemFields
38export interface DirectusUser {
39  id: string;
40  first_name: string;
41  last_name: string;
42  email: string;
43  password: string;
44  location: string;
45  title: string;
46  description: string;
47  avatar: string;
48  language: string;
49  // ...all system fields included
50  // Custom fields
51  stripe_customer_id: string;
52  verification_token: string;
53  verification_url: string;
54}
55
56// Minimal system collection with --includeSystemFields=false
57export interface DirectusUser {
58  id: string;
59}
60
61export interface ApiCollections {
62  events: Event[];
63  tickets: Ticket[];
64  settings: Setting; // Singleton collection (not an array)
65
66  // System collections included with --includeSystemFields
67  directus_users: DirectusUser[];
68  directus_files: DirectusFile[];
69}

Integration with Directus SDK

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

1import type { ApiCollections } from "$lib/types/directus/api-collection";
2import { DIRECTUS_URL } from "$env/static/private";
3import { createDirectus, rest } from "@directus/sdk";
4
5export const initDirectus = () => {
6  return createDirectus<ApiCollections>(DIRECTUS_URL).with(rest());
7};

Type Compatibility with Directus SDK

The types generated by TypeForge follow the patterns outlined in the Advanced Types with the Directus SDK documentation.

Recommended Pattern

We recommend using the following pattern to create type-safe functions when working with the SDK:

1async function getArticles() {
2  return await client.request(
3    readItems("articles", {
4      fields: ["id", "title", "content"],
5      filter: { status: { _eq: "published" } },
6    }),
7  );
8}
9
10// This type will automatically be inferred as:
11// { id: string; title: string; content: string; }
12export type Article = Awaited<ReturnType<typeof getArticles>>;

Debugging

If you encounter issues with type generation, TypeForge provides comprehensive debugging options:

Enable Debug Logging

Use the --debug flag to enable detailed logging:

1npx directus-typeforge -i schema-snapshot.json --debug -o ./types/schema.ts

Set Log Level

Control the verbosity with the --logLevel option:

1# Available levels: error, warn, info, debug, trace (from least to most verbose)
2npx directus-typeforge -i schema-snapshot.json --debug --logLevel trace -o ./types/schema.ts

Write Logs to File

Save logs to a file for easier troubleshooting:

1npx directus-typeforge -i schema-snapshot.json --debug --logFile ./debug.log -o ./types/schema.ts

Debug Mode for Issue Reporting

When reporting issues, include the debug logs:

1npx directus-typeforge -i schema-snapshot.json --debug --logLevel debug --logFile ./typeforge-debug.log -o ./types/schema.ts

The logs contain detailed information about:

• Relationship detection and resolution
• Field type mapping decisions
• Junction table identification
• System field handling
• Overall process flow

Caveats

• JSON Repeaters: JSON fields with complex structures are typed as Record<string, unknown> for better type safety, but you may need to define more specific types for your application.
• Complex Field Types: Specialized Directus field types are mapped to appropriate TypeScript types (string, number, boolean, etc.) rather than using string literals.
• Special Types: Certain system types like permissions and settings use standard TypeScript types for better type checking.
• Type Safety: For more specific typing of JSON fields, you might need to manually extend the generated types with your application-specific interfaces.

License

MIT