Document tsconfig setup for local TypeScript plugins

[singhvishalkr]

Closes #3025.

The reporter followed cms/plugins-development/create-a-plugin#setting-a-local-plugin-in-a-monorepo-environment-without-the-plugin-sdk, moved to the strapi-server.ts / strapi-admin.ts entry-point pattern, and hit TS6142: ... but --jsx is not set on the admin TSX files plus TS2307: Cannot find module @strapi/strapi/admin or its corresponding type declarations. The github-actions[bot] reply on the issue confirmed the entry-point pattern is correct and pointed at the underlying TypeScript-configuration gap: project-level ./tsconfig.json already excludes src/plugins/** for the server side (intentional), and ./src/admin/tsconfig.json needs to include the plugin's admin sources so .tsx files are compiled under the JSX-enabled config that extends @strapi/typescript-utils/tsconfigs/admin. Without that include line, the admin files fall through to the server-side config and the two errors above are guaranteed.

This patch adds a short ### TypeScript configuration subsection at the end of the existing monorepo-without-Plugin-SDK section, before the example-repo tip. It covers the two pieces: the server-side default (already correct) and the admin-side include that needs adding, with the same tsconfig.json excerpt the bot referenced from the existing TypeScript guide. I cross-link the existing Configuration with a local plugin section so readers see the no-@strapi/strapi-as-devDependency tip in the same flow.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
documentation	Ready	Preview, Comment	May 6, 2026 11:24am

[pwizla]

Thank you very much! I'm double-checking with engineers, and will get back to you 👀

[boazpoolman]

Hi @singhvishalkr. Can you help me understand how exactly the server-side compilation of the plugin will work? As you mentioned, in the root ./tsconfig.json plugins are excluded from the build process. Which build process will then handle the server-side compilation?

[singhvishalkr]

@boazpoolman Root ./tsconfig.json is the file @strapi/typescript-utils/compile uses when strapi develop runs tsc, and the official templates deliberately exclude src/plugins/** so those sources are not in that emit graph (the create-strapi-app starter even comments that plugins stay out of this server compilation pass). Runtime still requires each plugin's strapi-server.js from loadPlugins in packages/core/core/src/loaders/plugins/index.ts, so server TypeScript has to land as the .js entry Strapi can load (the examples/getstarted local plugin ships strapi-server.js, or you add a plugin-local build or SDK packaging if you keep authoring .ts). My earlier bullet blurred those two layers; I rewrote that paragraph in dca15f3 so the split is explicit.

[boazpoolman]

I'm still a little bit confused here. Because the server tsconfig already excludes any local plugin code, and the admin tsconfig already includes any local plugin admin code.

I guess I'm wondering what this new documentation section will bring for the users. Specifically because it's listed as a sub-item of Setting a local plugin in a monorepo environment without the Plugin SDK, but in your section you're still suggesting to use a build script / SDK for handling the server side TS code.

Recently I discussed this topic with @nclsndr, and we figured the only workaround in order to not have to separately build your local plugins server code is to include it in the server tsconfig. I have an example commit of how that would look here: strapi/community@51566ee

Maby we should document that setup instead?

[singhvishalkr]

(@boazpoolman re your 11:18Z note on the monorepo-without-SDK section) I pushed 335e18e: admin include is step 1 only, step 2 now documents both the stock full-plugin exclude and the narrow src/plugins/**/admin exclude plus dist-backed strapi-server exports, with a link to your strapi/community owner-selector commit as the concrete reference.

[pwizla]

Thanks again for your time and valuable contribution, @singhvishalkr. After discussing it internally with @boazpoolman and @nclsndr , I will actually not merge the described content and close this docs PR. Strapi devs are working on bringing an actual fix (proper TypeScript file loading), so this sounds like a better long-term solution and is preferable to documenting a somewhat tricky/not future-proof workaround. Thank you for your understanding!