Directus File Zip

Pack a list of Directus files from their UUIDs into a ZIP file and save it to Directus Assets.

🚀 Features

• ✅ Works inside Directus Backend (Extensions) and outside via REST API
• ✅ Support for multiple storage drivers (local, S3, etc.)
• ✅ TypeScript support
• ✅ Configurable compression
• ✅ Error handling and validation

📦 Installation

npm install @devix-tecnologia/directus-file-zip

or

pnpm add @devix-tecnologia/directus-file-zip

⚙️ Configuration

Set your Directus access token in your .env file:

DIRECTUS_ACCESS_TOKEN=your_access_token_here
PUBLIC_URL=http://localhost:8055  # Your Directus instance URL

Note: The access token must have proper permissions to read files and create new assets.

📖 Usage

�� Inside Directus Backend (Extension Endpoint)

Use this approach when creating Directus extensions or hooks:

import { directusZipFiles } from '@devix-tecnologia/directus-file-zip';

export default defineEndpoint((router, ctx) => {
  router.get('/', async (req, res) => {
    try {
      // Get all files from Directus storage
      const { FilesService } = ctx.services;
      const filesService = new FilesService({
        schema: req.schema,
      });

      const files = await filesService.readByQuery({});
      const fileIds = files.map((file) => file.id);

      // Create ZIP file
      const compressedId = await directusZipFiles(
        fileIds,
        'compressed.zip',
        'My Compressed Files',
        {
          ApiExtensionContext: ctx,
          storage: 'local', // or 's3', 'gcs', etc.
        },
      );

      res.json({
        success: true,
        fileId: compressedId,
        message: 'ZIP file created successfully',
      });
    } catch (error) {
      res.status(500).json({
        success: false,
        error: error.message,
      });
    }
  });
});

🌐 Outside Directus Backend (REST API)

Use this approach for external applications or scripts:

import { directusZipFiles } from '@devix-tecnologia/directus-file-zip';

async function createZipFile() {
  try {
    const config = {
      accessToken: process.env.DIRECTUS_ACCESS_TOKEN!,
      baseURL: process.env.PUBLIC_URL || 'http://localhost:8055',
    };

    const fileIds = [
      '6e710d5b-1d2b-43f6-941a-32e74d9808b9',
      '8b710d5b-1d2b-43f6-941a-32e74d9808c5',
    ];

    const uploadedFileId = await directusZipFiles(
      fileIds,
      'my-archive.zip',
      'Archive Files',
      config,
    );

    console.log('ZIP file created with ID:', uploadedFileId);
    return uploadedFileId;
  } catch (error) {
    console.error('Error creating ZIP:', error);
    throw error;
  }
}

// Usage
createZipFile();

📋 API Reference

directusZipFiles(fileIds, filename, title, config)

Parameters

| Parameter | Type | Required | Description | | ---------- | ---------- | -------- | ---------------------------------------------- | | fileIds | string[] | ✅ | Array of Directus file UUIDs to include in ZIP | | filename | string | ✅ | Name of the ZIP file (with .zip extension) | | title | string | ✅ | Title/description for the file in Directus | | config | Config | ✅ | Configuration object (see below) |

Config Object

For Backend Extensions:

{
  ApiExtensionContext: DirectusExtensionContext;
  storage?: string; // Storage driver name (default: 'local')
}

For REST API:

{
  accessToken: string; // Directus access token
  baseURL: string; // Directus instance URL
}

Returns

• Promise<string>: UUID of the created ZIP file in Directus

🧪 Development & Testing

Prerequisites

• Node.js 18+
• Docker and Docker Compose
• pnpm (recommended) or npm

Setup Test Environment

1. Start Directus instance:

   docker compose up -d

2. Configure Directus:

   • Go to Directus Admin Panel (http://localhost:8055)
   • Create an admin user
   • Generate an access token with file permissions

3. Set environment variables:

   cp .env.example .env
   # Edit .env and add your DIRECTUS_ACCESS_TOKEN

4. Install dependencies:

   pnpm install

5. Run tests:

   pnpm test      # Run all tests
   pnpm lint      # Check code formatting
   pnpm typecheck # Check TypeScript types

🛠️ Development Scripts

pnpm build     # Build the package
pnpm clean     # Clean build artifacts
pnpm format    # Format code with Prettier
pnpm lint      # Check code formatting
pnpm typecheck # TypeScript type checking
pnpm test      # Run tests with Vitest

🔄 CI/CD & Automated Dependency Updates

Dependency Management with Renovate

This project uses Renovate for automated dependency updates with age filtering:

• 📦 npm packages: Checked weekly on Mondays at 6 AM (São Paulo timezone)
• 🕐 Age filtering: Packages must be at least 5 days old before being adopted
• 🎯 Auto-grouping: Minor and patch updates are grouped together
• 🔒 Security patches: Applied immediately (0 days)

Age filtering by dependency type:

• Production dependencies: 5 days minimum
• Dev dependencies: 3 days minimum
• Major updates: 7 days minimum
• Directus packages: 5 days minimum
• Security patches: 0 days (immediate)

To enable Renovate: Install the Renovate GitHub App on your repository. Configuration is already in renovate.json.

Directus Version Testing Strategy

The project automatically tests against multiple Directus versions to ensure compatibility. To prevent issues with newly released versions, we implement a version age filter:

• Default: New Directus versions are only adopted after 5 days from their release date
• Configurable: Adjust via GitHub repository variable DIRECTUS_VERSION_MIN_AGE_DAYS

Why Age Filtering Matters

• ✅ Stability: Avoids immediate adoption of versions with potential critical bugs
• ✅ Safety: Gives time for the community to identify breaking changes
• ✅ Reliability: Ensures patches and hotfixes are released before we test against them

Configuration

1. PAT Token (Recommended - Enables Automated CI)

Status: Optional, but highly recommended for full automation.

Without PAT_TOKEN: PRs will be created automatically, but CI tests won't run (you'll need to manually verify).

With PAT_TOKEN: PRs will be created AND tests will run automatically before merge.

To enable automated CI tests on version update PRs:

1. Go to GitHub.com → Your profile Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token with permissions:
   • ✓ repo (all)
   • ✓ workflow
3. Copy the token and add it to your repository:
   • Repository Settings → Secrets and variables → Actions → New repository secret
   • Name: PAT_TOKEN
   • Value: paste your token

Why? GitHub's security prevents GITHUB_TOKEN from triggering workflows to avoid infinite loops. A PAT bypasses this limitation.

2. Version Age Filter (Optional)

To customize the minimum age for Directus versions:

1. Go to repository Settings → Secrets and variables → Actions → Variables tab
2. Click New repository variable:
   • Name: DIRECTUS_VERSION_MIN_AGE_DAYS
   • Value: 5 (or any number of days you prefer)

Recommended values:

• Conservative: 14 days
• Balanced: 5 days (default)
• Aggressive: 3 days

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

👥 Authors

• Roberto Seba - [email protected] - @robertoseba
• Sidarta Veloso - [email protected] - @sidartaveloso

🏢 Organization

Devix Tecnologia Ltda.

Made with ❤️ by Devix Tecnologia.