directus-extension-typesense

Integrates Typesense with Directus

• 🔒 Keeps your data secure as it adds content to the search index based on a policy (public policy by default).
• 🌐 Supports multilingual content by adding translated fields to index collection.
• 🪄 Adds hooks to keep your search index up-to-date (while handling bulk data imports/updates).
• ⏯️ Adds an operation to manually trigger a rebuild of the search index in your flows.
• 🔗 Sets the correct references on related fields to allow for Typesense JOINS

Getting started

1. You will need a running Typesense instance.
2. Install this extension (for now only made for use on self-hosted instances).
3. Configure directus to use typesense by setting the TYPESENSE_URL and TYPESENSE_SECRET environment variables.

Minimal example using docker compose:

# Dockerfile
FROM directus/directus

USER root
RUN corepack enable
USER node

RUN pnpm install directus-extension-typesense

# docker-compose.yml
services:
  directus:
    platform: linux/amd64
    build:
      context: ./
    ports:
      - 127.0.0.1:8055:8055
    environment:
      ADMIN_EMAIL: [email protected]
      ADMIN_PASSWORD: d1r3ctu5
      EXTENSIONS_AUTO_RELOAD: true
      DB_FILENAME: /directus/database/db.sqlite
      TYPESENSE_URL: "http://typesense:8108"
      TYPESENSE_API_KEY: "secret"

  typesense:
    platform: linux/amd64
    image: typesense/typesense:29.0
    ports:
      - 127.0.0.1:8108:8108
    volumes:
      - ./typesense-data:/data
    environment:
      TYPESENSE_API_KEY: "secret"
      TYPESENSE_DATA_DIR: "/data"
      TYPESENSE_ENABLE_CORS: true

🔒 Policy based indexing

By default this extension will check the public policy to decide whether data will be added to the search index or not. You can change this though by setting the TYPESENSE_POLICY environment variable to the id of the policy you want it to respect.

🌐 Multilingual content

If you setup content translations this extension will fetch the translations and add them as localised fields to the documents, according to Typesense best practices for locale-specific search (https://typesense.org/docs/guide/locale.html).

// GET <typesense_url>/collections/article/documents/1
{
  "id": "1",
  "title_en": "No one is illegal",
  "title_es": "Nadie es ilegal",
  "title_ar": "لا أحد غير شرعي"
}

🪄 Hooks

This extension comes with hooks, which should keep your index up-to-date. The search index is (re-)built whenever you update any collection and/or permission or load an extension. If you create or update an element, it will be updated in the index. To prevent crashing when running lots of sequential updates, this extension will debounce updates. By default the timeout is 5 seconds, you can adjust this value though by setting the TYPESENSE_WAIT_MS environment variable, so you can change from between more "realtime" updates and more robustness for different update scenarios.

⏯️ Rebuild search index operation

You will also find a "rebuild search index" operation to use in your flows.

🔗 Relational references for Typesense JOINS

When indexing relational fields, a reference will be added. This will enable you to use Typesense JOINS in order to query by relational data:

// GET <typesense_url>/collections/posts/documents/search?q=illegal&filter_by=$posts_tags(id:=[2])&query_by=*
{
  // ...
  "hits": [
    {
      "document": {
        "id": "1",
        "posts_tags": {
          "id": "2",
          "posts_id": "2",
          "tags_id": "2"
        },
        "title_en": "No one is illegal",
        "title_es": "Nadie es ilegal",
        "title_ar": "لا أحد غير شرعي"
      },
      "highlight": {
        "title_en": {
          "matched_tokens": [
            "illegal"
          ],
          "snippet": "No one is <mark>illegal</mark>"
        }
      },
      //...
    }
  ]
}

// GET <typesense_url>/collections/posts/documents/search?q=illegal&filter_by=$posts_tags(id:=[1])&query_by=*
{
  // ...
  "hits": [],
  // ...
}