Skip to content

Conversation

@joggienl
Copy link
Contributor

I took a stab at this because currently, my self-hosted Directus instances won't start after
installing certain extensions.

It happens when you use pnpm install to install the extensions. Note: the installation goes well,
the server just won't start. It is caused by the extensions' dependencies. Particularly with zod (
see #232). This issue emerged with Directus 11.10.3.

I also noticed that installing extensions via the Marketplace works fine. This is because (if I
found out correctly) the Marketplace does not use pnpm install to install the extensions but
rather downloads and extracts the extension's tarball.

Solution

In #232 I described that it might be useful to update the GitHub workflow to just cleanup the
package.json files to not include any dependencies (or peerDependencies) but I think the cleaner
approach would actually be to walk through the extensions and remove all runtime dependencies
(considering they are not used).

So, this PR implements a comprehensive dependency cleanup across all extensions to ensure they only
declare runtime dependencies when actually needed at runtime. The strategy is to bundle all
third-party libraries
into the extension's dist output rather than requiring them at runtime.

Key changes:

  • Moved all bundleable dependencies to devDependencies: Third-party libraries like Google Maps
    API, Algolia SDK, Elasticsearch client, Vue utilities, etc. are now bundled during build time
  • Eliminated unnecessary runtime dependencies: Most extensions now ship with zero runtime
    dependencies
  • Kept only truly required runtime deps: Only packages that cannot be bundled (like the
    whiteboard interface's special postinstall case) retain runtime dependencies

Impact

With these changes, pnpm install --production will:

  • Install extensions without pulling in unnecessary devDependencies
  • Avoid dependency conflicts like the zod issue
  • Reduce Docker image bloat by not installing build-time tooling in production
  • Ensure consistent behavior across different installation methods

Extensions Updated (40+)

All extensions have been audited and updated, including popular ones like:

  • AI operations bundle (OpenAI, Anthropic SDKs now bundled)
  • Address completion interface (Google Maps API bundled)
  • Collaborative editing (yjs, ioredis, and other deps bundled)
  • Various chart panels and custom interfaces

Exception: whiteboard-interface remains unchanged due to its special postinstall build process
requiring fabric at runtime.

Special note: @directus-labs/collaborative-editing had peerDependencies that I removed. I'm
not 100% sure if this is correct.

Verification

Each extension was built and its dist output inspected to ensure no unresolved external imports
remain, confirming that bundling worked correctly and runtime dependencies are truly not needed.
This change aligns with the Extensions SDK's bundling capabilities and follows the principle that
extensions should be self-contained with minimal runtime footprint.

Fixes #232

…n files for consistency. Added new contributor: joggienl.
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR implements a comprehensive dependency cleanup across all Directus extensions to resolve installation issues with pnpm install, particularly when runtime dependencies cause conflicts (like the zod issue). The strategy is to bundle all third-party libraries into the extension's dist output rather than requiring them at runtime.

  • Moved bundleable dependencies to devDependencies: Third-party libraries like Google Maps API, Algolia SDK, Elasticsearch client, Vue utilities, etc. are now bundled during build time
  • Eliminated unnecessary runtime dependencies: Most extensions now ship with zero runtime dependencies
  • Removed peerDependencies where appropriate: Including collaborative-editing extension's peerDependencies

Reviewed Changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

File Description
contributors.yml Added new contributor to the project
packages/*/package.json (30+ files) Moved runtime dependencies to devDependencies for bundling, eliminating unnecessary runtime deps

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

"vue-router": "4.5.0"
},
"dependencies": {
"vitest": "^3.1.3",
Copy link

Copilot AI Sep 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The dependencies appear to be mixed with devDependencies in a single section. Build tools like prettier, typescript, and vitest should remain separate from runtime dependencies like @directus/memory and @directus/sdk. Consider organizing these into proper devDependencies and dependencies sections.

Suggested change
"vitest": "^3.1.3",
"vitest": "^3.1.3"
},
"dependencies": {

Copilot uses AI. Check for mistakes.
Copy link
Contributor Author

@joggienl joggienl Sep 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not having dependency was the reason for this change. I am not sure about the inners of this extension in the sense of: are these dependencies actually needed at runtime?

I have actually installed this extension without installing the dependencies or devDependencies and it seems to work fine.

So perhaps the list of dependencies should be checked for if they are needed during dev or during production. But this change at least fixes the issue to be able to start Directus when manually installing it!

@Nitwel
Copy link
Contributor

Nitwel commented Oct 10, 2025

Generally I do agree with this change though testing this may take a while. In theory the installation of extensions via npm only really cares about the dist folder anyways so I'm wondering if there's a way in npm to install extensions without installing it's dependencies which could be a simpler more flexible solution.

I'm also wondering if we should update the docs to better inform on this or remove the dependencies when deploying an extension. 🤔

@joggienl
Copy link
Contributor Author

Generally I do agree with this change though testing this may take a while. In theory the installation of extensions via npm only really cares about the dist folder anyways so I'm wondering if there's a way in npm to install extensions without installing it's dependencies which could be a simpler more flexible solution.

I'm also wondering if we should update the docs to better inform on this or remove the dependencies when deploying an extension. 🤔

Unfortunately there is not a way with (p)npm to install without dependencies (beats the purpose of the package manager I suppose?). The control we do have is to be specific about only wanting runtime dependencies (dependencies only and no devDependencies). This can be done with pnpm install --prod for example.

Updating the docs: yes. Installing extensions is a bit underestimated imo (complexity of it, the maintenance burden but also the security implications of it).

There is more in this issue on the main directus repository as well: directus/directus#25766 (comment)

As for a tool to help it is easy to say (p)npm can't do it (which is true) but not the full story: you can either download tar archives directly from the registry (for example with pnpm view @directus-labs/command-palette-module@1.1.0 dist.tarball) and extract that to a desired location. There is also a package called pacote that should be able to do that in less steps (supposed to be used by npm itself).

Hope this helps in addition to this all :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Command Palette Module incompatible with Directus 11.10.x - Zod v3/v4 version conflict

3 participants