Proposal: Expose all Internal APIs

[Copystrike]

Hi everyone,

Following a great conversation on Discord with @JarrodMFlesch, I'd like to propose a feature.

API Stability and Developer Flexibility

One of the strengths of Payload is its well-defined and stable API. However, this can sometimes feel limiting for developers coming from more "open" ecosystems like WordPress, where almost any internal function is accessible. While I understand and appreciate the need to prevent breaking changes, there are legitimate use cases where accessing internal components or utilities is necessary to build highly custom experiences.

Currently, if a function or component isn't explicitly exported, we are blocked. This might be because it’s intentionally reserved for internal use only, hasn't been prioritized for the public API yet, or was simply forgotten to be exported. In any of these cases, the result is that development for complex projects can be slowed down, and advanced customizations are prevented.

The Proposal

I propose that Payload expose internals under a clearly marked, unsupported namespace. This approach is inspired by React with its __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED handle.

We could adopt a convention like:
@payloadcms/<package>/internal-no-support-at-your-own-risk/* Or just 'internal'.

Both ways would make it explicitly clear to any developer using this path that:

1. It is not officially supported.
2. There are no stability guarantees.
3. It is subject to breaking changes in any patch or minor version.
4. Usage is entirely at their own risk.

Technical Implementation

It could be wired up in each package’s package.json using the exports field:

// in a package like @payloadcms/ui/package.json
{
  "...": "...",
  "publishConfig": {
    "access": "public",
    "exports": {
      "...": "...",
      // ... other existing public exports

      // Proposed new internal export path
      "./internal-no-support-at-your-own-risk/*": {
        "import": "./dist/*",
        "types": "./dist/*",
        "default": "./dist/*"
      }
    },
    "publishConfig": {
      "exports": {
      "...": "...",
      // Proposed new internal export path
      "./internal-no-support-at-your-own-risk/*": {
        "import": "./dist/*",
        "types": "./dist/*",
        "default": "./dist/*"
      }
    }
  }
}

This change would unlock a new level of customization for power users, while maintaining the integrity and stability of Payload's public API.

Enhancing Developer Experience

A valid concern with exposing internals is that they could pollute editor auto-import suggestions for developers who have no intention of using them.

To solve this, we can leverage the built-in VS Code (and TypeScript) feature for excluding files from auto-imports.

Here is what the configuration would look like in .vscode/settings.json:

{
  // Exclude Payload's internal, unsupported APIs from auto-import suggestions.
  // Comment this to see them in your editor auto-import suggestions.
  "typescript.preferences.autoImportFileExcludePatterns": [
    "**/@payloadcms/*/internal-no-support-at-your-own-risk/**"
  ],
  "javascript.preferences.autoImportFileExcludePatterns": [
    "**/@payloadcms/*/internal-no-support-at-your-own-risk/**"
  ]
}

More info about this settings can be found here

This change would unlock a new level of customization for power users, while maintaining the integrity of Payload's public API and the quality of life for all developers.

Looking forward to hearing the community's and maintainers' thoughts on this!

[Patrickroelofs]

Having to set things in .vscode/settings.json seems like a bad idea to me, webstorm, nvim and many other editors or IDE's should be supported too.

[Copystrike]

When initially researching this, I also found solutions for most editors like WebStorm and Neovim. The VS Code settings were just the most straightforward example to demonstrate the approach.

For WebStorm, you can define a custom scope excluding **/@payloadcms/*/internal-no-support-at-your-own-risk/** in .idea/scopes/AutoImportExcludes.xml:

<project version="4">
  <component name="NamedScopesHolder">
    <scope name="AutoImportExcludes" pattern="file[my]:**/@payloadcms/*/internal-no-support-at-your-own-risk/**" />
  </component>
</project>

I think it’s fair to say most mature editors have this functionality to handle exclusions.

In my opinion, this should be treated as an extra feature that Payload offers over legacy PHP-based CMSs like WordPress, which can’t even hide internals from suggestion systems.

[amoscicki]

so do I get that right that we could kind of hot swap what payload imports internally in its runtime and say tell it something like "whenever you are using X use Y instead"?

[AlessioGr]

(We did not discuss this internally yet, this is just my own opinion).

I'm in favor of some kind of payload/internal export. We've had this with payload/dist in the past, but that disappeared when we switched to package.json#exports + modern moduleResolution.

I don't think we need to worry about the import suggestions here - it's up to the user to configure this. There's nothing wrong with import suggestions from /dist/ or /internal/ if the user is willing to address potential breaking changes in minor version bumps. This can be addressed by the user with vscode configuration or eslint rules.

We could ship our plugin template with such vscode configuration / an eslint rule, as plugins really should try to avoid using internal APIs for better compatibility.

The only thing I'm worried about is performance. We need to make sure that this does not wreck typescript performance / slow down finding auto-imports. This has been a big in the issue in the past and got resolved by getting rid of /* exports and exporting as much stuff from package.json#main over package.json#exports as possible.

[Copystrike]

I totally agree that providing an internal namespace gives power users flexibility while preserving the integrity of the stable public API + It definitely need to benchmark and make sure there are no regressions.

I also like the idea of bundling the suggested editor config or ESLint rules into the plugin template. It strikes a nice balance between guiding best practices and still leaving room for advanced users to dig into internals if needed.

[amoscicki]

I think a lot of performance problem worries boil down to how quickly tsgo port for the compiler and lsp will get to stable release. This could be a good counterweight to those problems. My personal experience with some advanced inference for more complex types has usually landed on compromising by writing some codegen solutions at critical points, instead of relying solely on typescript because whilst it was working, the performance hit was very noticeable at certain level of complexity and some Devs I worked with didn't have powerful enough machines to just shrug it off.