Directus CMS Extensions Folder Structure Guide 2026

Quick Summary: Directus CMS extensions use a specific folder structure that has evolved from legacy type-based directories to a modern package-based system. Each extension requires a package.json file and should be placed in the extensions directory (configurable via EXTENSIONS_PATH). Bundle extensions allow multiple extensions to share dependencies within a single folder structure.

Understanding how Directus organizes extensions can save developers countless hours of debugging. The folder structure determines how the CMS discovers, loads, and manages custom functionality.

Here’s the thing though—Directus recently deprecated the old type-based folder system. That means what worked in earlier versions won’t necessarily work now.

Modern Extensions Folder Structure

According to the official Directus documentation, the default extensions directory sits at ./extensions relative to your project root. Each extension lives in its own subfolder with a required package.json file.

The structure looks like this:

extensions/
├── my-custom-interface/
│   ├── package.json
│   ├── dist/
│   └── src/
├── analytics-panel/
│   ├── package.json
│   ├── dist/
│   └── src/
└── custom-hook/
    ├── package.json
    └── dist/

Real talk: the package.json isn’t optional anymore. Directus uses it to identify and configure each extension programmatically.

Configuration and Environment Variables

The extensions directory location is configurable through the EXTENSIONS_PATH environment variable. This flexibility matters when running Directus in Docker containers or complex deployment environments.

When developing locally with Docker, setting EXTENSIONS_AUTO_RELOAD: true eliminates the need for manual restarts during development.

Legacy vs. Modern Structure

The old system organized extensions by type—interfaces, displays, layouts, panels, and modules each had separate folders. Directus deprecated the legacy type-based folder structure in version 10.3.0, and support for it was fully removed in version 11.0.0.

The modern approach treats each extension as an independent package. This makes programmatic management more reliable and simplifies deployment workflows.

Bundle Extensions for Shared Dependencies

Bundle extensions solve a common problem: multiple extensions needing shared code or dependencies. Instead of duplicating libraries across folders, bundles group related extensions together.

Creating a bundle with create-directus-extension generates a structure where multiple extensions coexist within one package, sharing node_modules and build configurations.

Creating Extensions with Proper Structure

The official CLI tool handles folder structure automatically. Running npx create-directus-extension@latest scaffolds everything needed—package.json, source directories, and build configuration.

But wait. The generated structure includes both src/ and dist/ folders. Source code goes in src/, while the compiled output lands in dist/. Directus loads extensions from the built files, not source.

Get Help When Your Project Starts Getting Hard to Manage

Working with a headless CMS is manageable early on, but things can get complicated once custom logic, integrations, and multiple environments come into play. Keeping the system structured and maintainable as the product grows often requires more than just initial setup. This is where a development team like Mobien can step in, especially when internal capacity is limited or the workload starts to pile up.

Mobian supports teams with backend development, system integration, and ongoing product work, typically working alongside in-house developers rather than replacing them. Their focus is on keeping the technical side stable as new features are added and requirements evolve. 

If your project is getting harder to manage or you need extra development support to keep things moving, contact Mobien and get the right help in place before it slows everything down.

Conclusion

The Directus extensions folder structure has matured into a package-based system that prioritizes reliability and maintainability. Understanding this structure—and migrating away from deprecated type folders—ensures extensions work correctly across versions.

Check the official Directus documentation for current configuration options and explore bundle extensions when managing multiple related customizations.