@emahuni/directus.distilled-app-internals

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.distilled-app-internals

Usage

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

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

Importing Composables

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

import { composable } from '@emahuni/directus.distilled-app-internals/composables'
// eg: import { useTemplateData } from '@emahuni/directus.distilled-app-internals/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.distilled-app-internals/composables/composable'
// eg: import { useTemplateData } from '@emahuni/directus.distilled-app-internals/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.distilled-app-internals/constants'
// eg: import { FIELD_TYPES_SELECT } from '@emahuni/directus.distilled-app-internals/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.distilled-app-internals/utils'
// eg: import { renderStringTemplate } from '@emahuni/directus.distilled-app-internals/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.distilled-app-internals/utils'
// eg: import { renderStringTemplate } from '@emahuni/directus.distilled-app-internals/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.distilled-app-internals/__utils__'
// eg: import { Focus } from '@emahuni/directus.distilled-app-internals/__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.distilled-app-internals/__utils__/special-utility';
// eg: import { Focus } from '@emahuni/directus.distilled-app-internals/__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.
"stream" is imported by "../../../../../packages/libraries/directus.distilled-app-internals/node_modules/.pnpm/[email protected]/node_modules/axios/lib/helpers/formDataToStream.js", but could not be resolved – treating it as an external dependency.
"stream" 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.
"stream" is imported by "../../../../../packages/libraries/directus.distilled-app-internals/node_modules/.pnpm/[email protected]/node_modules/axios/lib/helpers/AxiosTransformStream.js", but could not be resolved – treating it as an external dependency.
"stream" is imported by "../../../../../packages/libraries/directus.distilled-app-internals/node_modules/.pnpm/[email protected]/node_modules/axios/lib/helpers/ZlibHeaderTransformStream.js", but could not be resolved – treating it as an external dependency.
"http" 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.
"zlib" 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.
"crypto" is imported by "../../../../../packages/libraries/directus.distilled-app-internals/node_modules/.pnpm/[email protected]/node_modules/axios/lib/platform/node/index.js", but could not be resolved – treating it as an external dependency.
⠋ Building Directus extension..."http" is imported by "http?commonjs-external", but could not be resolved – treating it as an external dependency.
"stream" is imported by "stream?commonjs-external", but could not be resolved – treating it as an external dependency.
"https" is imported by "https?commonjs-external", but could not be resolved – treating it as an external dependency.
✔ Done

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.distilled-app-internals' do import { useItem } from '@emahuni/directus.distilled-app-internals/composable/use-item'. Note that this is an actual culprit that is doing this that you can test this with.

Then if that fails, use an extension.config.js file:

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

import nodePolyfills from 'rollup-plugin-node-polyfills';

export default {
    plugins: [
        nodePolyfills()
    ],
};

I will update when I find a way around this.

Development

WIP or Not Doing

• Removing more composables and utils that may actually be of no use in the extensions ecosystem.
• Use more aggressive terser configuration to reduce dist size.
• Certain composables and utils have been intentionally left out as they are App Studio specific and do not benefit the extension ecosystem.
• A few composables and utils were exposed but with issues that I patched:
  • use-local-storage: This composable currently prevents the build process because of type issues, I have modified it by adding explicit type information.

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