Registry / devops / directus-extension-schema-sync

directus-extension-schema-sync

library3.3.2jsnpmunverified

A Directus extension for synchronizing schema, configuration, and selected data between Directus instances. Version 3.3.2 is the latest stable release, supporting Directus 33, 34, and 35. It splits the schema file into per-collection files for better Git management, and can auto-import/export on startup using a locking mechanism. Unlike built-in Directus snapshots, this extension supports syncing custom data like permissions, flows, dashboards, and user-defined collections. It requires the @directus/api peer dependency and uses a configuration file to define which collections to sync.

devops storage

npm install directus-extension-schema-sync

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DIRECTUS-EXTENSION

directus-extension-schema-sync

devopsjavascriptv3.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import schemaSync from 'directus-extension-schema-sync'

✗ const schemaSync = require('directus-extension-schema-sync')

The package is ESM-only; CommonJS require is not supported.

install

✓ import { install } from 'directus-extension-schema-sync'

The install function is used programmatically or via CLI.

export

✓ import { export } from 'directus-extension-schema-sync'

✗ const { export } = require('directus-extension-schema-sync')

Export is a reserved word in CommonJS; use ESM import to avoid syntax errors.

import

✓ import { import as schemaImport } from 'directus-extension-schema-sync'

✗ const schemaImport = require('directus-extension-schema-sync').import

Import is also a reserved word; alias when importing.

Install the extension, initialize the config and database tables, export current schema/data, then set SCHEMA_SYNC to auto-import on startup.

npm install directus-extension-schema-sync npx directus schema-sync install --force npx directus schema-sync export env SCHEMA_SYNC=IMPORT npx directus start

Debug

Known issues

breakingRequires Directus version 33, 34, or 35; incompatible with Directus 10.x and below. Use version 2.x for older Directus.

fix

For Directus <11, install directus-extension-schema-sync@2.x instead.

affects: >=3.0.0

deprecatedThe SCHEMA_SYNC environment variable is set to IMPORT, EXPORT, or BOTH. In production, IMPORT is recommended; BOTH may cause data loss if multiple instances run.

fix

Set SCHEMA_SYNC to IMPORT in production to avoid concurrent export/import conflicts.

affects: >=3.0.0

gotchaThe extension relies on a row existing in the directus_settings table. If missing, the extension may fail silently.

fix

Ensure Directus is fully initialized or create a settings row before running schema-sync.

affects: >=3.0.0

gotchaWhen using Docker, the schema-sync folder must be mounted as a volume to persist configuration and data files.

fix

Add volume mapping: - ./schema-sync:/directus/schema-sync in docker-compose.

affects: >=3.0.0

breakingThe install command uses --force to overwrite existing config. Without --force, it may skip config generation.

fix

Always include --force when running the install command for the first time.

affects: >=3.0.0

deprecatedDirectus Marketplace installation is not recommended; manual installation via npm or Docker is required.

fix

Follow the npm or Docker installation instructions in the README.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'directus-extension-schema-sync'

Package not installed or not in node_modules.

fix

Run: npm install directus-extension-schema-sync

export: command not found

Running the command outside the Directus CLI context.

fix

Use: npx directus schema-sync export

SCHEMA_SYNC is not set

Missing environment variable for auto-import/export.

fix

Set environment variable: export SCHEMA_SYNC=IMPORT (or EXPORT/BOTH)

Schema Sync: No directus_settings row found

Directus database not initialized with settings.

fix

Ensure Directus is running and a settings row exists, or run the install command.

Upgrade

Version history

3.3.2latest on npm

Audit

Dependencies

@directus/apirequiredPeer dependency; provides Directus core types and APIs required by the extension.

Agent activity

29 hits · last 30 days

node

Resources

githubhttps://github.com/bcc-code/directus-schema-sync ↗

packagedirectus-extension-schema-sync ↗

homepagehttps://github.com/bcc-code/directus-schema-sync#readme ↗