Support customization of Keystone's esbuild configuration (Monorepos)

[acburdine]

Some initial context - the team that I'm on develops a number of different applications, most of which use a Next.js Frontend and Keystone Backend. These applications all live in a single monorepo, managed via Nx using some custom-built Nx plugins. Nx has the concept of "apps", which are the actual deployed applications, and "libs", which are typically shared code libraries.

One of the unique things about Nx is that it doesn't use a package linker (i.e. pnpm or yarn workspaces) under the hood. Instead, it has a Typescript config file at the root of the repo that enables importing of local repo packages via Typescript path aliases. If a framework is configured correctly, this means that none of the local packages have to be "built" prior to their usage in monorepo apps - the typescript path aliases take care of resolving all of the files correctly.

When we first started using Keystone, it was still using babel-typescript via a pirates hook to compile the keystone.ts file. This didn't work with typescript path aliases at all, and as such, we had to write some custom scripts to tsc a given Keystone app's dependencies, then link them into that app's node_modules folder.

Now that Keystone uses esbuild under the hood instead to compile the keystone.ts file - we realized recently that all the tooling exists to support Nx's way of doing things. This actually almost works out of the box too - the only thing preventing Typescript path aliases from working correctly is the esbuild plugin configuration that marks any non-relative path import as an "external" dependency. All of our internal repo packages share a common scope, so all that we had to do to enable tsconfig path support was make a tiny change to these three lines via patch-package:

args => {
  if (args.path.startsWith("@internal-scope/") return;

  return { external: true, path: args.path };
}

after adding that line, building Keystone worked flawlessly without the need to do any prior tsc-ing of local repo packages 🎉

Now obviously pushing that exact change to Keystone itself doesn't make sense 😅 but it got me thinking if there might be some way to enable customizing the esbuild config without compromising on Keystone's excellent DX.

The simplest solution would be to add it to the keystone.ts config, but that doesn't work since it creates a chicken and egg problem.

Some potential ideas I had:

• Allow customizing "ignored" external imports via an environment variable or command-line flag that's passed to keystone dev/keystone build.
• Some sort of json config file to customize how Keystone compiles itself/the Next.js admin (might potentially be useful for Is it possible to serve AdminUI using a base url? #5804 and Allow admin UI base path customization in config #7135 as well?)
• specific JS file used to configure some of the bits of keystone that can't be configured via TS (i.e. something like next.config.js) - this would potentially allow more granular customization of esbuild settings beyond just monorepo typescript support.

I also completely understand if this isn't something that the Keystone team wants to add 😄 I'm happy to maintain my local patch of Keystone to support our use-case if adding something like this would make it more difficult for everyone else to use Keystone.

I'd also be happy to submit a PR with whatever solution makes the most sense (if any). Thanks for making and maintaining a great project!

[marekryb]

I am in the same boat as @acburdine, although for different reason (not monorepo).

I have a project that has similar setup to nextjs-keystone example. Sometimes it is run as single nextjs app and sometimes as separate frontend and backend. Since I have been using the latter initially, I have some custom stuff in keystonte's Admin UI. If this is included, then config.js generated from esbuild is not valid js:

/.../.keystone/config.js:2997
    return <div style={{ minWidth: "100%" }}>
           ^

SyntaxError: Unexpected token '<'

because in tsconfig.json I have "jsx": "preserve".
If I change it to "jsx": "react" then everything passes, but when I run nextjs it automatically changes it back:

The following mandatory changes were made to your tsconfig.json:

        - jsx was set to preserve (next.js implements its own optimized jsx transform)

So for some time now, I have been maintaining my own patch which specifies tsconfig for keystone's esbuild purposes:

 export function getEsbuildConfig(cwd: string): BuildOptions {
   return {
     ...
     platform: 'node',
+    tsconfig: 'tsconfig.keystone.json',
     plugins: [
     ...

Would love to have some esbuild configuration for that or even make a PR, just not sure how to make it happen.

[acburdine]

@marekryb are you seeing that issue when using something like document field custom component blocks? If so, I ran into the same issue but was able to work around it without needing to patch Keystone core. Here's roughly my repo folder structure for the case I had this issue in:

repo/
  tsconfig.json - next.js tsconfig
  keystone.ts
  models/
    ModelA.ts - these are the keystone list configs
    ModelB.ts
    blocks/
      tsconfig.json
      component-blocks.tsx

The tsconfig file inside the blocks folder just had the contents:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "jsx": "react"
  }
}

ultimately, I think if you put the custom blocks in a subfolder and then create a tsconfig.json in that subfolder that extends from the base tsconfig, it should work out of the box.

[marekryb]

Wow, I assumed esbuild works similar to tsc in this regard and didn't even check documentation. Live and learn every day I guess.

One patch less to maintain \o/

Thank you so much @acburdine !

[kennedybaird]

We are working with keystone and would find this useful as well. Thanks for the nice breakdown @acburdine

[dcousens]

I concur that this is a common problem when working with monorepos!
The only downside is this is quite tricky to resolve as we don't the user configuration at this stage of the pipeline.

I have opened the following pull request #9235 to continue this discussion, as this is a feature that has been problematic for us in the past, but like you, we worked around it.