# Directus Module Export

GitHub Repo License Directus TypeScript npm Downloads

A Directus module extension for importing collection data from another Directus instance. Simplified for latest Directus versions. ## Features โœจ - **Directus-to-Directus import ๐Ÿ”**: Transfer collection data from another Directus instance into your current project - **Preflight permission check โœ…**: Test collection access before importing - **Token validation ๐Ÿ›ก๏ธ**: Validate admin token against the source server - **History management ๐Ÿ•˜**: Save and reuse domain and token inputs (localStorage) - **Real-time status ๐Ÿ“Š**: Inline progress and concise error messages - **Per-collection import ๐Ÿงฉ**: Import items for a specific collection - **Import limit option โฑ๏ธ**: Optionally limit how many items to import per run - **File field support ๐Ÿ–ผ๏ธ**: Automatically copies single-file fields (by UUID or object) and reuses or uploads as needed - **ID-preserving import ๐Ÿ”**: Attempts to update items by the same `id`; if missing, creates with the same `id` using REST upsert to avoid duplicates - **ZIP export/import ๐Ÿ“ฆ**: Export a collection to a ZIP and re-import elsewhere, including `translations.*` - **Deep translations import ๐ŸŒ**: Imports `translations` via deep writes with `deep=true` - **Folder auto-creation ๐Ÿ“**: Files are placed in a collection-named folder, created if missing ### At a glance

Import Validate Check

## Installation ๐Ÿ“ฆ ### From npm ```bash npm install directus-module-export ``` ## Usage โ–ถ๏ธ ### Quick start โšก 1. Open the module in your Directus admin interface. 2. Enter the source Directus API URL and an admin-access token for that source. 3. (Optional) Click โ€œValidate Tokenโ€ to check the token, or โ€œTest Collectionsโ€ to quickly verify collection permissions. 4. (Optional) Enter a limit to cap the number of items imported per collection. 5. For each collection you want to import, click โ€œImport from another Directusโ€. 6. Monitor the import progress and review the status/output. Any failed items will be summarized in the console. 7. (Optional) Use the "History" feature to quickly reuse previously entered domains and tokens, or the "Clear History" options to remove them. Notes: - Provide the token as plain string (no need to prefix with "Bearer "). - The module normalizes tokens internally. ### File importing ๐Ÿ–ผ๏ธ - Supported fields: - Single-file fields referencing Directus files by UUID (string) or object with `id` - Array/many-file relations are skipped (logged as `file_copy_skip`) - Non-UUID strings are ignored as file IDs (prevents color values like `#FFFFFF` being treated as file references) - Reuse vs copy: - If a target item already has a file in a field and it matches the source by checksum (preferred) or file size/type, the existing file is reused - ZIP import avoids uploading the same image when it already exists in Directus files - When reusing, the file may be patched to set `title` (from item title, if present) and move it into the target folder - Upload behavior: - Source file metadata fetched from `/files/{id}`; binary fetched from `/assets/{id}` - Files are uploaded to the target via `/files` with `FormData` (`file`, optional `title`, `folder`) - Files are placed in a folder named after the collection; the folder is auto-created if missing - Title source: uses the item's `title` if available, otherwise first non-empty translation `title` - ZIP import infers MIME type from filename to prevent "Binary Data" files - ZIP import never uploads control files like `items.json` or any `.json` files - Caching: - Per-run cache avoids re-uploading the same source file across multiple items - Per-item cache prevents duplicate uploads within the same item - Update mapping (idempotent, optional): - If the `directus_sync_id_map` collection exists on the target, imports update existing items mapped by source `id`; otherwise new items are created - ZIP import also maintains this mapping to avoid duplicates on re-import - Permissions required: - Source: read `/items/{collection}`, `/files/{id}`, `/assets/{id}` - Target: create/update `/items/{collection}`, `/files`, `/folders`, and (optionally) read/write `directus_sync_id_map` - Error tolerance: - If a file copy fails, the item import continues and the field is left unchanged; details are logged as `file_copy_error` ### Configuration โš™๏ธ #### Domain settings ๐ŸŒ - Recent domains are stored locally for quick reuse. #### Authentication ๐Ÿ” - **Admin token**: Required on the source Directus to READ the collections you import. - **Token validation**: The module verifies token usability before import. ## Security considerations ๐Ÿ”’ - Admin tokens are stored locally in browser storage. - Token validation ensures proper permissions. - Clear history options are available for sensitive data. - Secure API communication is enforced over HTTPS. - Imported data is not sent to third-party services; all transfers are direct between your browser and the specified Directus instances. - Only the collections and fields you select are accessed; no other data is read or modified. - The module does not store or transmit your data outside your environment. - For best security, use temporary admin tokens and clear history after use. ## Development ๐Ÿงฐ ### Prerequisites - Node.js >= 16 - Directus Extensions SDK (`@directus/extensions-sdk`) - TypeScript - [Directus CLI](https://docs.directus.io/cli/) (for building and linking extensions) - npm (Node.js package manager) ### Setup ```bash # Install dependencies npm install # Build for development npm run build # Watch for changes npm run dev # Link to Directus instance npm run link ``` ### Project Structure ``` src/ โ”œโ”€โ”€ index.ts # Module definition โ”œโ”€โ”€ module.vue # Main Vue component โ”œโ”€โ”€ types.ts # Shared types โ”œโ”€โ”€ utils/ โ”‚ โ””โ”€โ”€ apiHandlers.ts # API logic for import, validation, and sync โ””โ”€โ”€ shims.d.ts # TypeScript declaration ``` ### Building ```bash # Production build npm run build # Development build with watch npm run dev ``` ## Configuration No environment variables are required. Install and enable the module in your Directus instance per normal extension flow. ### Compatibility - Directus host: >= 11.0.0 < 16.0.0 - `@directus/extensions-sdk` peer range: >= 11 < 16 ## Troubleshooting ๐Ÿ› ๏ธ ### Common issues 1. **Token validation fails** - Ensure the token is valid and the API URL is reachable over HTTPS. 2. **403 Forbidden on a collection** - On the source Directus, grant the tokenโ€™s role READ permission on that collection (and any related collections or files). - On the target Directus, ensure the role can UPDATE/CREATE with explicit `id` and that the collection accepts client-provided primary keys. 3. **History not saving** - Check browser storage permissions; clear cache if needed. ## License ๐Ÿ“ MIT License - see [LICENSE](LICENSE) file for details. ## Support ๐Ÿ’ฌ For issues and questions: - Create an issue on GitHub - Check the documentation - Review the troubleshooting section ## Changelog ๐Ÿ“‘ See [CHANGELOG.md](CHANGELOG.md) for version history and updates. Notable: - 1.1.0: Reworked for Directus v11+, import from Directus-only; removed legacy API import and export flows; improved token handling and preflight checks. ## Notes - Export-to-file functionality is not currently included in this module.