Connect to Realtime | Directus Docs

Instead of needing to make a request to see if data has changed, your application can receive updates in realtime over a persistent connection with Directus. All subscriptions and actions over a realtime connection use the permissions of the authenticated user, or public permissions if not authenticated.

This guide will cover getting started with Realtime by connecting to Directus with the Directus SDK on the web, subscribing to changes, and creating new items.

Before You Start

You will need a Directus project.

Everything you need to start building. Provisioned in 90 seconds.

Create a messages collection with a date_created field enabled on collection creation. Add text and user text fields. Follow the data modeling quickstart to learn more.

Add an access policy called Public Posts to your user in the Data Studio. Within it, create a new permission to allow the read and create actions on the messages collection.

In the Data Studio, create a static token for your user, copy it, and save your user profile.

Enable Realtime

Directus Realtime is disabled by default on self-hosted projects. Set the WEBSOCKETS_ENABLED environment variable to true. If you use Directus Cloud to host your project, you do not need to manually enable Realtime.

Connect via Directus Realtime

Create an index.html file, import the Directus SDK from a CDN, create a client with the realtime composable, and connect. Be sure to replace your Directus project URL and access token.

<!doctype html>
<html>
    <body>
        <script>
            import { createDirectus, staticToken, realtime } from 'https://www.unpkg.com/@directus/sdk/dist/index.js';

            const directus = createDirectus('https://example.directus.app')
                .with(staticToken('your_access_token'))
                .with(realtime());

            await directus.connect();
        </script>
    </body>
</html>

After subscribing to collections over your connection, you will receive new messages whenever items in the collection are created, updated, or deleted.

At the bottom of your <script>, create a new subscripion:

const { subscription } = await directus.subscribe('messages', {
    event: 'create',
    query: { fields: ['user', 'text'] },
});

for await (const item of subscription) {
    console.log(item);
}

Your page will log on the console every time an item is created in the messages collection.

Create an Item

You can also perform actions over an open Realtime connection. Create a new function that sends a message over the connection to create an item:

function createItem(text, user) {
    directus.sendMessage({
        type: 'items',
        collection: 'messages',
        action: 'create',
        data: { text, user },
    });
}

Open your browser and create items by using your new function directly in the console:

createItem('Hello World!', 'Ben');
createItem('Hello Universe!', 'Rijk');
createItem('Hello Everyone Everywhere All At Once!', 'Kevin');

Log Messages

Use the directus.onWebSocket() method to listen for events that happen to the WebSocket collection.

directus.onWebSocket('open', function () {
    console.log('Connection is open');
});

directus.onWebSocket('message', function (message) {
    console.log('New message of type ' + message.type);
    console.log(message.data);
});

directus.onWebSocket('close', function () {
    console.log('Connection has closed');
});

directus.onWebSocket('error', function (error) {
    console.log('Connection has had an error');
    console.log(error);
});

Next Steps

Learn more about authenticating realtime connections and how to manage subscriptions.

Create an Automation

Get started using flows, triggers, operations and the data chain in Directus Automate.

Resources & Links

Key links across the Directus ecosystem.

Connect to Realtime Data