@emahuni/directus.app.guts

A collection of composables and utility functions distilling core parts of the Directus App. This package exposes composables and utils from the Directus App source for use in Directus extensions and other integrations within Directus App Studio. The version of this package uses semver with an additional '-app-n.n.n' to denote the version of the distilled Directus App package that it directly correlates to.

Why

The Directus App internally uses a set of composables and utilities that power its components and various functionalities. However, these valuable resources are not exposed to the extensions ecosystem. This package digs into the source and exposes these internal composables and utilities, so you can leverage the well-written Directus codebase to build your own extensions. As Directus matures, this package will be updated to reflect those changes.

Installation

Make sure you are using pnpm as your package manager:

pnpm add @emahuni/directus.app.guts

Usage

This package exports different modules that can be imported into your project using barrel files:

import { composable, utility, CONSTANT, specialUtility } from '@emahuni/directus.app.guts'

IMPORTANT

• This package is not intended to be used as a standalone package. It is intended to be used as a dependency of another package.
• When used as a dependency, the version of this package should match the version of the Directus App that it is using.
• The API that use extensions or packages that consume this package should use @emahuni/directus as the entry point to their server. The reason for this is that Directus API doesn't expose rollup configuration for its bundling process. @rollup/plugin-commonjs is required to correctly bundle the code because of the way that the Directus App is written when using the internal code that this package exposes. You can optionally add the commonjs plugin yourself in Directus Api code in node_modules as a patch, but the better solution is to use @emahuni/directus as the entry point to your server as it already has this plugin configured and resolves any external dependencies correctly.

Importing Composables

If you prefer to be specific, i.e., not execute any non-composable in the process:

import { composable } from '@emahuni/directus.app.guts/composables'
// eg: import { useTemplateData } from '@emahuni/directus.app.guts/composables'

If you prefer to be even more specific, i.e., not execute any other composable code except what you really need (recommended):

import { composable } from '@emahuni/directus.app.guts/composables/composable'
// eg: import { useTemplateData } from '@emahuni/directus.app.guts/composables/use-template-data'

Exposed Composables Docs

Effort was made to document composables

Importing Constants

If you prefer to be specific, i.e., not execute anything else except the constants file in the process:

import { CONSTANT } from '@emahuni/directus.app.guts/constants'
// eg: import { FIELD_TYPES_SELECT } from '@emahuni/directus.app.guts/constants'

Exposed Constants Docs

Effort was made to document constants

Importing Utils

If you prefer to be specific, i.e., not execute any non-utility in the process:

import { utility } from '@emahuni/directus.app.guts/utils'
// eg: import { renderStringTemplate } from '@emahuni/directus.app.guts/utils'

If you prefer to be even more specific, i.e., not execute any other composable code except what you really need (recommended):

import { utility } from '@emahuni/directus.app.guts/utils'
// eg: import { renderStringTemplate } from '@emahuni/directus.app.guts/utils/render-string-template'

Exposed Utils Docs

Effort was made to document utils

Importing utils

If you prefer to be specific, i.e., not execute any non-special-utility in the process:

import { specialUtility } from '@emahuni/directus.app.guts/__utils__'
// eg: import { Focus } from '@emahuni/directus.app.guts/__utils__'

If you prefer to be even more specific, i.e., not execute any other special util code except what you really need (recommended):

import { specialUtility } from '@emahuni/directus.app.guts/__utils__/special-utility';
// eg: import { Focus } from '@emahuni/directus.app.guts/__utils__/focus'

Exposed _utils_ Docs

Effort was made to document __utils__

Build Issues

When building your extension that imports this library, you will sometimes get these errors (especially when building bundles, have not confirmed on other extension types):

"https" is imported by "../../../../../packages/libraries/directus.distilled-app-internals/node_modules/.pnpm/[email protected]/node_modules/axios/lib/adapters/http.js", but could not be resolved – treating it as an external dependency.
...
✔ Done

Specifically for the built-ins, the build will work, and the extension itself will work. However, the problem is when in development mode with a watch. It will hang on the second build after a watch trigger. This is happening because of the mixture of node and browser code... and the other is not compatible with node code. Especially when the code is importing something that imports @directus/composables.

Firstly, try to import the specific module you are trying to use, e.g.: Instead of import { useItem } from '@emahuni/directus.app.guts' do import { useItem } from '@emahuni/directus.app.guts/composable/use-item'. Note that this is an actual culprit that is doing this that you can test this with.

The following is the recommended solution.

The other bulletproof approach is to use an extension.config.js file:

1. Install @azimutlabs/rollup-plugin-external: pnpm add -D @azimutlabs/rollup-plugin-external
2. Create the extension.config.js file in the root of your extension.
3. Paste the following code in it:

import { rollupPluginExternal } from '@azimutlabs/rollup-plugin-external';

export default {
    plugins: [
        rollupPluginExternal({
            useDependencies    : false,
            usePeerDependencies: true,
            useBuiltins        : true,
        }),
    ],
};

This means that Rollup will avoid bundling any dependencies that are not explicitly imported. Crucially, it will also leave out peer dependencies and Node.js built-ins. This resolves the issue where the build hangs on the second run.

The dependencies that are excluded from the bundle should be declared under peerDependencies in your package.json. After that, make sure you use the @emahuni/directus package as the entry point for your server. This ensures that any dependencies installed in your API, which the extension relies on, are properly resolved.

Example

If your extension imports await-until like this:

import awaitUntil from 'await-until';

…and you added it as a devDependency, it will not be bundled with your extension. Instead, you must also add it to peerDependencies and install await-until as a dependency in your API project (because it is now a peer requirement).

This approach makes every extension that follows the same pattern lightweight, while sharing the same await-until dependency across all extensions. It will only be downloaded once and loaded on demand in the browser, keeping the Directus API lean and efficient.

Why This Matters

At present, Directus bundles every dependency used by an extension directly into the extension itself. This leads to code duplication, bloated builds, and inefficiency. Worse still, when Directus aggregates all extensions into one large bundle for the browser, the same dependency (like await-until) ends up included multiple times. This is the solution to that problem.

Development

Scripts

The package includes several scripts to help with building and development:

• Build: Clean the distribution folder and build the package.

  pnpm run build

• Development Watch: Clean the distribution folder and watch for changes.

  pnpm run dev

• Sync Clone: Pulls the latest version of the Directus App from the source based on this packages version (* now broken needs fixing).

  pnpm run sync-clone

Build Process

The build process uses Vite and Rollup. The commands clean the dist folder using rimraf before building the bundle. Ensure you have all necessary dependencies installed via pnpm.

Contributing

Contributions are welcome! Please open an issue or submit a pull request with your improvements.

License

MIT

Author

Emmanuel Mahuni - GitHub | Email