{"id":47403,"library":"directus-extension-schema-sync","title":"Directus Schema Sync","description":"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.","status":"active","version":"3.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/bcc-code/directus-schema-sync","tags":["javascript","directus","directus-extension","directus-custom-hook","directus-schema","directus-data"],"install":[{"cmd":"npm install directus-extension-schema-sync","lang":"bash","label":"npm"},{"cmd":"yarn add directus-extension-schema-sync","lang":"bash","label":"yarn"},{"cmd":"pnpm add directus-extension-schema-sync","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; provides Directus core types and APIs required by the extension.","package":"@directus/api","optional":false}],"imports":[{"note":"The package is ESM-only; CommonJS require is not supported.","wrong":"const schemaSync = require('directus-extension-schema-sync')","symbol":"default","correct":"import schemaSync from 'directus-extension-schema-sync'"},{"note":"The install function is used programmatically or via CLI.","wrong":null,"symbol":"install","correct":"import { install } from 'directus-extension-schema-sync'"},{"note":"Export is a reserved word in CommonJS; use ESM import to avoid syntax errors.","wrong":"const { export } = require('directus-extension-schema-sync')","symbol":"export","correct":"import { export } from 'directus-extension-schema-sync'"},{"note":"Import is also a reserved word; alias when importing.","wrong":"const schemaImport = require('directus-extension-schema-sync').import","symbol":"import","correct":"import { import as schemaImport } from 'directus-extension-schema-sync'"}],"quickstart":{"code":"npm install directus-extension-schema-sync\nnpx directus schema-sync install --force\nnpx directus schema-sync export\nenv SCHEMA_SYNC=IMPORT npx directus start","lang":"javascript","description":"Install the extension, initialize the config and database tables, export current schema/data, then set SCHEMA_SYNC to auto-import on startup."},"warnings":[{"fix":"For Directus <11, install directus-extension-schema-sync@2.x instead.","message":"Requires Directus version 33, 34, or 35; incompatible with Directus 10.x and below. Use version 2.x for older Directus.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Set SCHEMA_SYNC to IMPORT in production to avoid concurrent export/import conflicts.","message":"The 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.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure Directus is fully initialized or create a settings row before running schema-sync.","message":"The extension relies on a row existing in the directus_settings table. If missing, the extension may fail silently.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Add volume mapping: - ./schema-sync:/directus/schema-sync in docker-compose.","message":"When using Docker, the schema-sync folder must be mounted as a volume to persist configuration and data files.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always include --force when running the install command for the first time.","message":"The install command uses --force to overwrite existing config. Without --force, it may skip config generation.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Follow the npm or Docker installation instructions in the README.","message":"Directus Marketplace installation is not recommended; manual installation via npm or Docker is required.","severity":"deprecated","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'/export':49 '3.3.2':18 '33':26 '34':27 '35':29 'auto':47 'auto-import':46 'better':41 'built':58 'built-in':57 'collect':38,76,91 'configur':10,86 'custom':66,101 'dashboard':71 'data':13,67,108 'defin':75,89 'depend':82 'directus':1,5,15,25,60,95,97,100,104,107 'directus-custom-hook':99 'directus-data':106 'directus-extens':96 'directus-schema':103 'directus/api':80 'extens':6,63,98 'file':34,39,87 'flow':70 'git':42 'hook':102 'import':48 'instanc':16 'javascript':94 'latest':21 'like':68 'lock':54 'manag':43 'mechan':55 'peer':81 'per':37 'per-collect':36 'permiss':69 'releas':23 'requir':78 'schema':2,9,33,105 'select':12 'snapshot':61 'split':31 'stabl':22 'startup':51 'support':24,64 'sync':3,65,93 'synchron':8 'unlik':56 'use':52,84 'user':74 'user-defin':73 'version':17","created_at":"2026-06-07T16:51:20.966644+00:00","updated_at":"2026-06-07T16:51:20.966644+00:00","problems":[{"fix":"Run: npm install directus-extension-schema-sync","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'directus-extension-schema-sync'"},{"fix":"Use: npx directus schema-sync export","cause":"Running the command outside the Directus CLI context.","error":"export: command not found"},{"fix":"Set environment variable: export SCHEMA_SYNC=IMPORT (or EXPORT/BOTH)","cause":"Missing environment variable for auto-import/export.","error":"SCHEMA_SYNC is not set"},{"fix":"Ensure Directus is running and a settings row exists, or run the install command.","cause":"Directus database not initialized with settings.","error":"Schema Sync: No directus_settings row found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/bcc-code/directus-schema-sync#readme","github":"https://github.com/bcc-code/directus-schema-sync","docs":null,"changelog":null,"pypi":null,"npm":"directus-extension-schema-sync","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}