Directus SDK

The Directus SDK allows to work with Directus directly in your JavaScript and TypeScript projects. The SDK is split into separate modules, giving granular control over which features to include and which can be pruned at build-time. It is lightweight and dependency-free.

npm install @directus/sdk

Create a Client

The Directus SDK is a "Composable Client" that allows you to customize and build a client with the specific features you need. The client starts as an empty wrapper without any functionality. To add features, import and use the following composables:

import { createDirectus, rest } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(rest());

import { createDirectus, rest } from '@directus/sdk';

interface Post {
  id: number;
  title: string;
  content: string;
}

interface Schema {
  posts: Post[];
}

const directus = createDirectus<Schema>('http://directus.example.com').with(rest());

:: ::

Making Requests

To make a request, you must create the client with the rest() or graphql() composable. If using rest(), you must also import and use one of the query functions.

import { createDirectus, rest, readItems } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(rest());

const allPosts = await directus.request(readItems('posts'));

const somePosts = await directus.request(
  readItems('posts', {
    filter: { status: { _eq: 'published' } },
    sort: ['-date_created'],
    fields: ['id', 'title', 'date_created'],
    limit: 3
  })
);

Custom Endpoints

To call custom endpoints using the SDK, you can manually provide a path and method. If using TypeScript, you can type the output.

import { createDirectus, rest } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(rest());

const result = await directus.request(() => ({
  path: '/custom/endpoint',
  method: 'GET',
}));

import { createDirectus, rest, customEndpoint } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(rest());

const result = await directus.request(customEndpoint<OutputType>({
  path: '/custom/endpoint',
  method: 'GET',
}));

::

GraphQL Usage

Add the graphql() composable to the client, and use the .query() method.

import { createDirectus, graphql } from '@directus/sdk';

interface Post {
  id: number;
  title: string;
  content: string;
}

interface Schema {
  posts: Post[];
}

const directus = createDirectus<Schema>('http://directus.example.com').with(graphql());

const result = await directus.query<Post[]>(`
  query {
    posts {
      id
      title
      content
    }
  }
`);

Authentication

The authentication() composable provides the Directus client with new login(), logout(), and refresh() methods. It also manages token storage and refreshing on your behalf.

import { createDirectus, authentication } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(authentication());

await directus.login({ email, password }, login_options);
await directus.refresh();
await directus.logout();

This approach will handle refreshing of the token automatically. The current token is stored inside the initialized client.

Login Options

The login options object contains three optional parameters to control the behavior of the request.

type LoginOptions = {
  otp?: string;
  mode?: AuthenticationMode;
  provider?: string;
};

• otp contains the user's one-time-password if two-factor authentication is enabled.
• mode defines how the refresh token is returned. One of json, cookie or session. Defaults to cookie.
• provider specifies a non-redirect authentication provider. LDAP providers use identifier (typically a username) rather than email:

await client.login({ identifier: 'username', password: 'd1r3ctu5' }, { provider: 'ldap' });

For SSO providers that use browser redirects (Google, GitHub, Okta, etc.), see SSO Login below.

SSO Login

SSO providers like Google, GitHub, and Okta rely on browser redirects. The .login() method does not apply to these providers. Instead, redirect the user to Directus and call .refresh() after they return.

1. Create a link that sends the user to your Directus /auth/login/<provider> endpoint with a redirect query parameter pointing back to your app. Replace <provider> with the provider name configured in AUTH_PROVIDERS.
2. The user authenticates with the external provider.
3. Directus redirects the user back to the URL in the redirect parameter.
4. On your callback page, call client.refresh() to establish the session.

Use session mode with credentials: 'include' so the session cookie set by Directus during the redirect is sent with subsequent requests.

<a href="https://directus.example.com/auth/login/google?redirect=https://your-app.com/callback">
  Login with Google
</a>

import { createDirectus, authentication, rest, readMe } from '@directus/sdk';

const client = createDirectus('https://directus.example.com')
  .with(authentication('session', { credentials: 'include' }))
  .with(rest({ credentials: 'include' }));

await client.refresh();

const me = await client.request(readMe());

Token Management

Set Token

import { createDirectus, staticToken, rest } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com')
  .with(staticToken('TOKEN'))
  .with(rest());

import { createDirectus, rest, withToken, readItems } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(rest());

const request = await directus.request(
  withToken('TOKEN', readItems('posts'))
);

import { createDirectus, authentication } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(authentication());

await directus.setToken('TOKEN');

Get a Token

Import authentication or staticToken and use it when creating a client. You now have access to the getToken method.

import { createDirectus, authentication } from '@directus/sdk';
const directus = createDirectus('http://directus.example.com').with(authentication());

const token = await directus.getToken();

Configure Custom Storage

Internally, getToken() and setToken() make use of the configurable storage, which can be customized for your environment's needs. There must be a get() and set() method exposed, and the AuthData type returned.

import { createDirectus, authentication } from '@directus/sdk';

class LocalStorage {
  get() {
    return JSON.parse(localStorage.getItem("directus-data"));
  }
  set(data) {
    localStorage.setItem("directus-data", JSON.stringify(data));
  }
}

const storage = new LocalStorage();
const directus = createDirectus('http://directus.example.com')
    .with(authentication('json', { storage }));

// Set a long term or static token without expiry information.
directus.setToken('TOKEN');

// Set custom credentials to the storage.
storage.set({
  access_token: 'token',
  refresh_token: 'token',
  expires_at: 123456789
});

Cross-Domain Cookies

A common situation is for the Directus backend and frontend to be hosted on different domains, requiring extra configuration to make sure cookies are passed correctly. Usually this is only required for authentication with cookies but this can be set globally for each composable that does requests. This will then apply to all requests made using that composable:

const directus = createDirectus('http://directus.example.com')
  .with(authentication('cookie', { credentials: 'include' }))
  .with(graphql({ credentials: 'include' }))
  .with(rest({ credentials: 'include' }));

Or you can enable this only for specific REST requests using the withOptions:

const result = await directus.request(
  withOptions(refresh(), { credentials: 'include' })
);

Realtime

The Directus SDK makes it easier to work with Realtime by adding .connect(), .subscribe(), .sendMessage(), and .onWebSocket() methods. It also handles reconnect logic.

Global APIs

To keep the SDK dependency-free, it does rely on the APIs mentioned below, which originally came from the browser ecosystem and may not be available in all environments.

The fetch API

This API is shipped with almost every modern runtime. Nevertheless, there might be reasons to overwrite or set the implementation, for example, if an alternative implementation is preferred or if you actually work with a special runtime where fetch is not available.

• node-fetch
• ofetch
• whatwg-fetch

The URL API

This API is shipped with almost every modern runtime. However, there are exceptions, like react-native, that require a polyfill for the SDK to work.

• url-polyfill
• react-native-url-polyfill

The WebSocket API

This API is optional if you're not making use of the realtime() features in the SDK. Backend JavaScript environments often do not ship with an implementation of WebSockets.

• ws
• isomorphic-ws

The logger API

This API is optional and currently only used for debugging realtime() features. This will default to the Console however in environments where this isn't shipped you can overwrite this with any logger.

Polyfilling

There are two polyfilling approaches, with the first taking precedence.

Options Parameter of createDirectus

import { createDirectus } from '@directus/sdk';
import { ofetch } from 'ofetch';
import WebSocket from 'ws';

const directus = createDirectus('http://directus.example.com', {
  globals: {
    WebSocket: WebSocket,
    fetch: ofetch,
  }
});

globalThis object

import { createDirectus } from '@directus/sdk';
import { ofetch } from 'ofetch';
import WebSocket from 'ws';

globalThis.WebSocket = WebSocket;
globalThis.fetch = ofetch;

import 'react-native-url-polyfill/auto';

const directus = createDirectus('http://directus.example.com');

Polyfill libraries will often register itself to the globalThis object. For example, the react-native-url-polyfill package.

Error Handling

isDirectusError type guard

The SDK exports an isDirectusError type guard utility function to determine if the error thrown was from the API

import { createDirectus, rest, isDirectusError, readItems } from '@directus/sdk';

const directus = createDirectus('http://directus.example.com').with(rest());

try {
  const request = await directus.request(readItems('posts')));
} catch(error){
  if(isDirectusError(error)){
    // some error has been returned from the API
  } else {
    // some unknown non API error has been thrown (e.g. unable to parse the JSON response)
  }
}