Improving Strapi's type system: looking for real apps and early feedback #27747

Q4. "What breaks", we had an issue that wasn't completely fixed where the order in which properties are added to the schema differs. A fix based on the computer locale was added but it was lacking a consistent locale. Might be a quick win to add it here

I'll try to be as thorough as possible. Note that we haven't actually deployed a finished CMS yet; we're still in development, but we're working with typescript exclusively, including as strict settings as we can manage from the typescript compiler, eslint, etc.

Q1: We import the Core type from @strapi/strapi in 17 places so far, and pull subtypes from it all over the place. E.g. all of our configuration files use Core.Config.<ConfigType> or Partial<Core.Config.<ConfigType>> as their exported values or function return types. src/index.ts:register accepts an argument of type Core.Strapi. All of our middlewares use Core.Middleware. Our admin configuration and tests also import UID from @strapi/strapi explicitly for Live Preview configuration - the handler checks the UID value to determine if the content type is eligible for Live Preview. Finally, src/admin/app.ts imports type StrapiApp from @strapi/strapi/admin and uses that in its exported bootstrap function.

Also within config/admin.ts for the Live Preview configuration, we need to explicitly cast the status property (from PreviewHandlerParams from its default string down to 'draft' | 'published' in order to use it in a call to strapi.documents.findOne(). In one of our middlewares, we need to cast a response from strapi.db.query.findOne() from Promise<any> to Promise<LinkComponentQueryResult | null>. In tests for the same middleware, we cast strapi.service('admin::api-token-content-api') as ApiTokenContentApiService. In a test for our local typescript-aware test Strapi instance (discussed more below), we cast getStrapi().db.connection.client as { connectionSettings: { filename: string }; }; instead of its default value of any, and similarly getStrapi().app as Record<string, unknown>. For both of these, getStrapi() is a method that is set up to return Core.Strapi.

Q2: We don't allow any or @ts-expect-error anywhere in our codebase. We fall back to as unknown as only during tests right now, and only because we want to mock out a partial strapi server in one test:

globalThis.strapi = {
  documents: () => ({ findOne: mockFindOne }),
} as unknown as Core.Strapi;

This does bring up a much larger issue that I want to make sure isn't missed: testing in typescript against a real Strapi instance was a real pain to get set up. Since Strapi's runtime loaders all expect compiled javascript, we needed to create our own loaders to be able to load our actual typescript configuration so that we could test against our actual code, not have our tests rely on a build step, and link test coverage back correctly. We've had to build custom typescript loaders that dynamically import typescript files and hand their exports to Strapi's registries. These imports are all typed as unknown (which is why I bring it up as part of this question).

Q3: We have the generated types included in our typescript project, so that they are used to typecheck actual production and test code, but only the parts that are actually used. We haven't run into any issues with the types, aside from the need mentioned above to narrow down the status: string property to 'draft' | 'published' in order to actually check against the real call to strapi.documents.findOne(). We have a few tests that exercise create, update, and status with literal content types that correctly typecheck. We do not currently use Document Service fields, populate, filters, or locale.

Q4: We commit generated types. All of our content type edits have been done through the admin interface so far, so this pattern has worked for us without issue. If we do start running into any issues, we'll probably update our typecheck script to regenerate types before running tsc.

Q5: tsc --noEmit on its own takes 3-4 seconds running locally, but that only typechecks the production code for the CMS server. The admin panel and tests are separate typescript projects. Running all 3 together (3 separate tsc calls, usually run with npm run typecheck) takes 9-12 seconds. This is running on an Apple M1 Max with 64GB of memory, Node 24.13.0 and typescript 5.9.3. Our as-yet-incomplete schema contains 3 content types, 12 components, and 1 dynamic zone attribute.

Q6: N/A

Q7: Honestly, we haven't had that many issues with using strict typing with Strapi for production code. It would be great if types were a little more discoverable; I've been leaning heavily on LLMs to help discover the right types to use. The bigger gap that I see is on the testing side. Production code seems to support strict typescript without much issue, but testing using typescript requires quite a bit of custom setup.

Follow-up on the questions, as promised. I compile with the strictest settings I can, and most of the pain comes from two compiler flags plus a few gaps in build and tooling.

Q2. Where we fall back

• noPropertyAccessFromIndexSignature. strapi.service(), strapi.controller() and friends resolve through index signatures. With the flag on, every property access on the result is an error, so each lookup needs a cast or bracket access. #27807 (registered server contracts) looks like the fix; I'll try it on the experimental tag.

  Here is what I do today instead, trimmed down from a real app. I augment Strapi with one non-generic overload per lookup:

  import type { Core } from '@strapi/strapi';
  import type upload from '@strapi/upload/strapi-server';
  
  // Deep .d.ts path: the exports map rejects `@strapi/types/dist/core` (TS2664, #26934),
  // and augmenting the re-exported `Core` namespace doesn't merge.
  declare module '@strapi/types/dist/core/index.d.ts' {
    interface Strapi {
      service(uid: 'api::invoice.invoice'): ReturnType<typeof invoiceService>;
      controller(uid: 'api::invoice.invoice'): InvoiceController;
  
      // Services without a content type
      api(name: 'payment'): Core.Module & {
        service(name: 'card'): CardService;
        service(name: 'wire'): WireService;
      };
  
      // A generic `service<K extends keyof …>(name: K)` never wins: `Core.Plugin` already declares
      // `service<T extends Service>(name: string): T`, which matches first. Only literal overloads bind.
      plugin(name: 'upload'): Core.Plugin & {
        service(name: 'upload'): ReturnType<ReturnType<typeof upload>['services']['upload']>;
      };
    }
  }
  
  // Overloads fail silently back to the index signature, so every one is asserted.
  type Assert<T extends true> = T;
  type IsNarrowed<T> = string extends keyof T ? false : true;
  declare const strapi: Core.Strapi;
  const card = strapi.api('payment').service('card');
  type _Card = Assert<IsNarrowed<typeof card>>;

  Problems with this approach:

  • Every service has to be listed by hand.
  • Augmentations have to target a dist/.../index.d.ts path.
  • Plugin service types come from importing @strapi/<plugin>/strapi-server, which is an internal entry point.
  • A typo or a missing overload quietly falls back to the untyped Service, which is why every overload needs a type-level assertion.

• exactOptionalPropertyTypes. Almost any call into a typed Strapi API fails as soon as an optional property might hold undefined, e.g. passing { locale } where locale: string | undefined:

  const locale: string | undefined = ctx.query.locale;
  // TS2379 under exactOptionalPropertyTypes
  await strapi.documents('api::article.article').findMany({ locale });

  #27288 widens the document input types. Adding | undefined to an optional property isn't a breaking change for inputs. Without the flag, ?: T and ?: T | undefined are the same type, and with it, the widening only removes errors. It breaks only when a type Strapi produces is assigned to a consumer type declared without | undefined (the variance point from the #27314 review), so the widening is limited to pure inputs. #27314 turns the flag on inside the monorepo, so regressions get caught at the source.

• strapi.db.query(). Returns any, same as @grandivory reported. Every result needs a cast to a local type, and that cast can drift silently. If an attribute is renamed or removed in the schema, or the select / populate changes, the cast still compiles and the code reads fields that are no longer there. Nothing ties the local type to the schema or to the query that produced the result.

• Intermediary types resolve to any in an isolated install. Some types in the published declarations come from dependencies that aren't declared, so they only resolve when a hoisted node_modules happens to provide them. With pnpm or another strict layout they silently become any, and strictness is lost without a single error. #27249 declares the missing per-workspace dependencies and adds a CI guard (see also #27745).

• No type for authoring a schema file. Struct.CollectionTypeSchema describes the loaded schema, so it requires uid, modelType, modelName and globalId. Strapi infers all four, and none of them belong in a schema file. The only way to type the file is Partial<>, which also makes kind, info and attributes optional, so a mistake there goes unnoticed:

  // src/api/article/content-types/article/schema.ts
  export default {
    kind: 'collectionType',
    info: { singularName: 'article', pluralName: 'articles', displayName: 'Article' },
    attributes: { title: { type: 'string' } },
  } satisfies Partial<Struct.CollectionTypeSchema>; // an empty object would pass too

  An input/definition type for the file, separate from the loaded one, would fix this. It's the same split @Convly described in #18429, where a custom field's type changes once the schema is loaded.

• Model lifecycle hooks are loosely typed. The only type available is Event from @strapi/database. @strapi/types has nothing for lifecycles. Event isn't connected to any schema: params.data, params.where, params.select, params.populate and result are all any, model is the untyped Meta, and action is the full union no matter which hook runs. So beforeCreate({ params }) can't tell you which fields data has, and afterFindMany({ result }) doesn't know it gets an array. Typing lifecycles.ts per content type (the event narrowed by UID and action) would remove the casts in every hook we have.

• Request query, params and body. They're untyped and unvalidated. ctx.request.body and ctx.query are effectively any, so each controller either casts or re-validates by hand. A route-level schema that yields both the runtime validation and the static type would remove most of our remaining casts.

Q3. Document Service / status

@grandivory's status: string vs 'draft' | 'published' is a symptom of a wider problem: Strapi's reserved names can collide with schema attributes. #26890 now warns on a user-defined status attribute when draft & publish is on. I think reserved/internal field names should be rejected from schemas outright, so types for Strapi's own params never have to account for them.

Q4. Generated types

The output location is fixed. strapi ts:generate-types --out-dir can change it, but strapi develop always writes types/generated, so apps that keep their types elsewhere end up with two copies. #27823 adds a typescript.outDir config key that develop respects. I'd also back @Convly's point about the locale-dependent property order, which produces noisy diffs for anyone who commits the output.

It would also help to generate a UID map that works as both a value and a type. Today I keep one by hand:

import type { UID } from '@strapi/strapi';

export const ContentType = {
  Invoice: 'api::invoice.invoice',
  Payment: 'api::payment.payment',
  User: 'plugin::users-permissions.user',
} satisfies Record<string, UID.ContentType>;

export declare namespace ContentType {
  export type Invoice = typeof ContentType.Invoice;
  export type Payment = typeof ContentType.Payment;
  export type User = typeof ContentType.User;
}

strapi.documents(ContentType.Invoice);                 // value: no string literals scattered around
service(uid: ContentType.Invoice): InvoiceService;     // type: usable in overloads and generics

satisfies catches a UID that no longer exists, but a newly added content type is only picked up if someone remembers to add it. The generator already knows every UID, so it could emit this for content types and components. It would have to be a .ts / .js module rather than .d.ts, since it carries a runtime value.

Q6. Plugins and providers

• Providers have no shared types. The provider contract (init / send / verify / getCapabilities) and the settings and capabilities shapes are redefined in the plugin and in every provider package, and they drift apart. A third-party provider has nothing to implement against. #27129 adds Providers.Email to @strapi/types and routes the email plugin and all five email providers through it. Upload would follow the same pattern.
• Local TypeScript plugins aren't supported. A plugin declared with resolve: './src/plugins/x' is loaded from the app root. In a TS project that root holds the uncompiled .ts sources, and the template tsconfig excludes src/plugins/** from the server compile, so plugin server code never reaches dist. #26725 (experimental) loads local plugins from strapi.dirs.dist.root, and narrows the template exclude to the plugins' admin files. It reuses the existing tsc to dist pipeline instead of adding a runtime transpiler. It's the plugin-side version of the "loaders expect compiled JS" problem @grandivory described.
• RBAC actions are typed as plain strings. Plugins register permissions through actionProvider.registerMany(...), and the Action type accepts any section / category combination, even though the runtime only accepts four sections and requires category for settings alone. #27502 turns it into a union discriminated on section and derives the yup validator from the same tuple. Plugins only benefit once the admin permission service is reachable with a type, which is the service() lookup problem from Q2.
• users-permissions ships no types. The plugin is still JavaScript, so its services, controllers, the plugin::users-permissions.user shape and the JWT and auth helpers reach apps untyped. It's the plugin almost every app extends: custom auth flows, register overrides, and policies that read ctx.state.user. #26106 scaffolds TypeScript for the plugin (per-target tsconfigs, no @ts-nocheck, no noImplicitAny: false), and follow-up PRs convert the files incrementally. #20 Tries to differentiate ID and DocumentID via a flavor.

Q6. GraphQL plugin

Instead of extending @strapi/plugin-graphql, we're working toward migrating to a GraphQL plugin built on Pothos, because Nexus is loosely typed too. Our extension code gets little type safety from it, and the plugin's own published types inherit the same looseness:

• extension.use() returns an elided any. Configuration.types is NexusGen[], which is Nexus's empty global typegen interface, not a type definition. resolvers, resolversConfig and typeRegistry are typed as object.
• shadowCRUD(uid: string) takes a string, not a UID.ContentType. disableActions(actions = []) infers never[], so a typed caller can't pass an action.
• The plugin exports no named types. Its .d.ts files are inferred and point deep into @strapi/types/dist/... (declared only as a devDependency), nexus/dist/... and lodash (no @types/lodash declared). Under an isolated install, most of that resolves to any.
• The service is reached through the untyped strapi.plugin('graphql').service('extension'), so it has to be cast before use.
• nexus has had no release since 1.3.0 in March 2022.

With Pothos, a resolver's parent, args and context are inferred from the builder, and plugins such as scope-auth and dataloader are typed end to end. The only bridge into the current plugin we see is to print the schema to SDL, extract a resolver map, and pass both through use({ typeDefs, resolvers }). Pothos types can't reference Strapi's generated GraphQL types that way, so the typing stops at that boundary.

If the plugin ever moves off Nexus, or accepts a GraphQLSchema from extensions instead of Nexus-only types, we'd be happy to test it on the experimental tag.

Q7. What good looks like

• Named, exported intermediary types. Many public types are only reachable through inference. They have no exported name you can write down, so you can't turn on isolatedDeclarations, which requires explicit annotations on exports. Giving those types names would unblock the flag, and it would probably help tsc times on large schemas as well.

• Services as an interface, implemented by a class, wired by the factory. In our app, a service's contract is an interface and the implementation is a class that implements it. The Strapi factory is the DI mechanism: it resolves the dependencies and passes them to the constructor.

  // contract: what callers and the registry see
  export interface InvitesService {
    create(args: CreateInviteArgs): Promise<Invite>;
    accept(args: { token: string; userId: number }): Promise<void>;
  }
  
  // implementation: dependencies come in through the constructor, typed by their contracts
  export class DefaultInvitesService implements InvitesService {
    readonly #db: Core.Strapi['db'];
    readonly #notifications: NotificationsService;
  
    constructor(deps: { db: Core.Strapi['db']; notifications: NotificationsService }) {
      this.#db = deps.db;
      this.#notifications = deps.notifications;
    }
  
    async create(args: CreateInviteArgs): Promise<Invite> { /* ... */ }
    async accept(args: { token: string; userId: number }): Promise<void> { /* ... */ }
  }
  
  // factory = DI: resolve dependencies from Strapi, construct, expose only the contract
  export default ({ strapi }: { strapi: Core.Strapi }): InvitesService =>
    new DefaultInvitesService({
      db: strapi.db,
      notifications: strapi.api('deposit').service('notifications'),
    });

  What this gives us:

  • The registry and every consumer depend on InvitesService, a named type, not on ReturnType<typeof factory>. Exports carry explicit annotations, which is what isolatedDeclarations needs.
  • A change to the implementation can't silently change the contract. If they drift, implements fails in the class, not somewhere at a call site.
  • Dependencies are explicit and typed by their own contracts. A test constructs DefaultInvitesService with fakes, with no Strapi instance and no mocked global.strapi (the testing pain @grandivory described).
  • Only the factory knows about Strapi. The class doesn't reach into strapi at call time, and it keeps private state in #fields.

  Suggestion: let the registries in #27807 be declared against named contracts, and check factories against them, instead of inferring the contract from the implementation. A rough sketch:

  // registry entry: a named contract
  interface AppServices {
    'api::invite.invite': InvitesService;
  }
  
  // the factory is checked against the registered contract (helper name is illustrative)
  export default (({ strapi }) => new DefaultInvitesService({ /* ... */ })) satisfies Core.ServiceFactory<'api::invite.invite'>;

• Choosing the tsconfig for the build. Right now the CLI always reads tsconfig.json. I tried a --tsconfig option in #27300 (closed).

• Configurable admin location. Along with the previous point, this would let server and admin be two adjacent TS projects. Today src/admin has to sit inside the server project, which excludes it and then reads a nested tsconfig.json of its own. That works, but only because the server config carries exclude rules, and every tool (IDE, linters, test runners) has to resolve the nesting the same way. Two sibling folders, each owning its whole tree, would need no excludes at all.

• Strict flags as a supported target. exactOptionalPropertyTypes and noPropertyAccessFromIndexSignature should compile cleanly against the published .d.ts, checked in CI with a consumer fixture.

• Stricter create-strapi-app templates. The server tsconfig.json in the templates has no compilerOptions.types, so TypeScript auto-includes every @types/* package in node_modules and all of their global augmentations. One visible result is that consumers get two competing ctx.request.body augmentations: koa-body through the Strapi imports, and @types/koa-bodyparser through the implicit types. See #26544 (comment). The templates should start from "types": ["node"] and let apps add what they need, with the admin tsconfig scoped the same way.

• Names that don't shadow globals, inside the monorepo too. @strapi/upload defines its File type twice, in server/src/types.ts and in shared/contracts/files.ts, and the two have drifted. The bare name File also collides with the DOM global.File, so it isn't obvious which one you're holding. I tried consolidating them into a single UploadFile with a deprecated File alias in #27128 (closed).

• A way to opt out of the deprecated global.strapi type. @strapi/types declares var strapi in its entry point, so importing any type also brings in the global. An app that injects strapi everywhere still compiles with a bare strapi. call, and nothing flags the leftovers. In programs that also include DOM types, the global merges with window.strapi into BrowserStrapi & Core.Strapi. #26544 moves the declaration into an opt-in @strapi/types/_internal/globals-server entry for the monorepo, but @strapi/strapi still imports it for apps so that nothing breaks. The global should be opt-in for apps too, or at least removable: an explicit types entry or import to turn it on, and absent by default in 6.x.

• One documented augmentation target: the module that declares the registries. This isn't a TypeScript bug to wait on. A symbol re-exported through a module can't be augmented from that module, only in the module that originally declares it. When augmenting a re-export does seem to work, it's by accident: under TS 7 (tsgo) the result even depends on file order (microsoft/TypeScript#63960). Strapi currently points apps at re-exporting modules. ts:generate-types emits declare module '@strapi/strapi', and the JSDoc in @strapi/types/src/public/registries.ts shows declare module '@strapi/types', so the two disagree, and both target a re-export (see my earlier comment for what that looks like in practice). The declaring module should be exposed as a stable, public subpath rather than a dist/... path, and the generator and docs should both use it.

Regarding incremental tsc and plugins tsconfig that extends @strapi/typescript-utils,
there is a issue with tsBuildInfoFile which breaks incremental

#27672

Feedback from trying 0.0.0-experimental.82fa9a6 (#27807) on a real app: a pnpm monorepo with one Strapi 5 app and four local plugins, TypeScript 5.9.3 with strict and exactOptionalPropertyTypes, Node 24. With strictTypes on and our types migrated to the registries, the app and plugins type-check, build, pass their tests and boot. These are the things we hit along the way.

Type generation

1. plugins.d.ts is generated with strictTypes off. Everything else matches the previous release byte for byte, but this file appears as a new one.
2. plugins.d.ts contains machine-local paths under pnpm. Plugins that are direct dependencies get package specifiers, but transitive ones (content-manager, content-releases, content-type-builder, i18n, review-workflows) get a relative path into the global store:

   import type {} from "../../../../../../../../../../../Library/pnpm/store/v11/links/@strapi/i18n/0.0.0-experimental.82fa9a6…/<hash>/node_modules/@strapi/i18n/dist/server/src/index.d.ts";

   The file can't be committed or shared between machines. Those entries are also redundant: @strapi/strapi/strict-types already references the same bundled packages by name. Skipping the packages it covers would fix both.
3. An empty middlewares.d.ts is not a module. With no app middlewares the file holds only a comment, so import type {} from "./middlewares" fails with TS2306, unlike the other generated files. The generated files never import it themselves, so this only bites an app that loads the files one by one (as we did at first).
4. The strict contracts import the app's sources (typeof import("../../src/api/…")). That's expected, but it means generated types can only live inside the app. We used to generate into a separate workspace package that our plugins consume, and with strict mode on that package would have depended on the app and on every plugin (a dependency cycle). We moved the output back to types/generated, so no action needed; mentioning it in case others relocate generated types.

Contracts and lookups

5. Without registered schemas, the documents API params are lopsided. A plugin that reads one of the app's content types can't see the app's schemas, so Params.Data.Input<uid> is {} there. create then accepts any data unchecked, while update's Partial<Input> rejects every field (TS2353 on a literal, TS2559 on a variable). With the UID typed as UID.ContentType, object sorts like sort: { id: "asc" } or [{ id: "asc" }] are also rejected, though "id:asc" passes. This probably predates the PR, but strict mode is what pushes plugins to stop borrowing the app's schemas. We ended up typing those reads with our own row types and narrowing the document service once.
6. A service factory that uses the scoped strapi.api(name) lookup of its own API hits TS7023. Our api::payment.card and api::payment.wire factories call strapi.api("payment").service("settlement"). Resolving that lookup pulls in the whole api::payment.* registry, including the factory's own entry, which is ReturnType<typeof factory>, so the inferred return type becomes circular. The flat form, strapi.service("api::payment.settlement"), does not trigger it, and an explicit return type on the factory also avoids it. Worth a line in a migration note.
7. The action provider's category changed from required to category?: string. That matches the runtime rule, but apps that registered plugin actions with category: undefined and a @ts-expect-error now get an unused-directive error, and under exactOptionalPropertyTypes the explicit undefined is rejected. Omitting the key is the fix on our side; declaring it category?: string | undefined would keep such calls compiling.
8. The upload contract requires a full formidable File. Programmatic uploads with a hand-built { filepath, originalFilename, size, mimetype } need a cast, although the service reads only those fields. This is unchanged since 5.57, but strict mode is what surfaces it.

Packaging

9. @strapi/core's strapi::* middleware contracts pull koa middleware types into every consumer. dist/middlewares/{compression,favicon,ip,public,security}.d.ts are now loaded by every program with strict mode on. They import koa-compress, koa-favicon, koa-ip, koa-static and koa-helmet, but @types/koa-compress, @types/koa-static and @types/koa (which koa-helmet and koa-ip need) are only devDependencies of @strapi/core. Under pnpm's isolated layout those types don't resolve from the consumer (and skipLibCheck hides it).

Templates

10. The example and example-js templates' scripts/seed.js passes a malformed file to the upload service. getFileData returns originalFileName, where formidable's field is originalFilename, and uploadFile passes files: file where the service takes an array. It works today because fileInfo.name is set explicitly, but an app that copies the template, type-checks its JS (checkJs) and turns on strict mode gets type errors in that script.

Thank you for this initiative. TS in strapi 5 is half good half frustrating too ^^. I'm in the middle of a (long and painful) v4 -> v5 migration, so my feedback is not complete since I still have 5 custom local plugins to migrate, but here is my feedback for now.

Q1. Which Strapi types do you import, and from which package?

Core, Data and Modules from '@strapi/strapi'.

• Core :

   // Core.Strapi to prevent repetition in every middleware and in src/index.ts
   export type StrapiWrapper = { strapi: Core.Strapi };
  
   // Core.config.* in /config/*.ts files 
   // (recently documented after this issue : https://github.com/strapi/documentation/issues/3513)
   export default ({env}: Core.Config.Shared.ConfigParams): Core.Config.Admin => ({ /*...*/ });

• Modules :

   // `Modules.Documents.Params.PublicationStatus.Kind` to get 'published'|'draft' type 
   // in custom service method (undocumented)
   function getMyCT(documentId: string,  status?: Modules.Documents.Params.PublicationStatus.Kind) { /*...*/ }
  
   // `Modules.Documents.Middleware.Middleware` in Document Service Middlewares 
   // to get proper parameters type inference (undocumented) 
   // see https://discord.com/channels/811989166782021633/1541096696212226248/1541191582919950426
   export const myDSM: DocumentMiddleware = async (ctx, next) => { /* ctx and next are typed */ }
  
   // Modules.Documents.Params.Data.Input<...> in Document Service Middlewares 
   // to fix params.data media fields typing (undocumented)
   // see https://discord.com/channels/811989166782021633/1555568388233756683
   type CustomInput = Partial<Modules.Documents.Params.Data.Input<'api::......'>>;
   type ValidCustomInput = Omit<CustomInput, 'media' | 'thumbnail'> & {
   	media: FileCT; // FileCT is type alias for Data.ContentType<'plugin::upload.file'>, see below
   	thumbnail?: FileCT;
   };

• Data :

   // `Data.ContentType<'plugin::upload.file'>` (undocumented) 
   // to get proper media field typing (see ValidCustomInput above)
   export type FileCT = Data.ContentType<'plugin::upload.file'>;
  
   // `Data.ContentType` to :
   // 1. get a type that can represent multiple CT sharing a common field, 
   // see https://discord.com/channels/811989166782021633/963236405641887744/1526956662450290889
   export type StableIdDocument = { stableId?: number } & Data.ContentType;
   // 2. get CT typing in admin frontend (Data.ContentType<'api::.....'> does not work in admin dashboard)
   type MyCT = Data.ContentType & {
   	title: string;
   	otherField: string;
   	// ...
   };
   // 3. apply same fix as with `data.params` Input type mentioned earlier to fix media field type
   type FixedCT = Omit<
   	Data.ContentType<'api::....'>,
   	'media' | 'thumbnail'
   > & {
   	media?: FileCT;
   	thumbnail?: FileCT;
   };

Q2. Where do you fall back to any, as unknown as, or @ts-expect-error? Please share code when possible.

• @ts-expect-error for unstable_useContentManagerContext().form.values because form is typed as unknown and then denies access to form.values
• any for global middleware ctx parameter as instructed in documentation here : https://docs.strapi.io/cms/plugins-development/server-policies-middlewares#server-level-middlewares :

   export default ({ strapi }: StrapiWrapper) => {
   	return async (ctx: any, next: () => Promise<void>) => {

• @ts-expect-error for adminApi.useGetRelationsQuery() (undocumented api but only way I found to get field values at runtime) :

   import { adminApi } from '@strapi/strapi/admin';
   const data = adminApi.useGetRelationsQuery(/* ... */);

• @ts-expect-error in Document Service Middleware :
  • when trying to access ctx.params.data[fieldName] where fieldName is a dynamic string. Only allows hard coded field names (impossible/too hard to type when both content type and field name are dynamic)
  • same with ctx.contentType.attributes[fieldName] when contentType is unknown
  • when trying to query document api by using ctx.uid and trying to populate fields :

     const fieldsToPopulate:string[] = strapi.service(ctx.uid).getSomeFields();
     const currentDocument = await strapi.documents(ctx.uid).findOne({
     		documentId: ctx.params.documentId,
     		// @ts-expect-error: TS doesn't see that we will only get existing fields in the uid CT 
     		// (guaranteed by CT service)
     		populate: fieldsToPopulate,
     	});

  • when trying to programmatically add a field to ctx.params.data and the CT is dynamic :

     if (!('myField' in ctx.contentType.attributes)) {
     	return;
     }
     // we know myField exists in CT but...
     // @ts-expect-error: TS doesn't see that myField is valid for the current CT : 
     // `Property 'myField' does not exist on type 'Partial<Input<"admin::api-token">>'`
     params.data.myField = 'some value'

    same applies to next() result :

     const result = await next();
     if ('myField' in ctx.contentType.attributes 
     	&& result && typeof result === 'object' && 'id' in result
     ){
     	// @ts-expect-error: Property 'stableId' does not exist on type 
     	// '{ id: ID; documentId: string; locale?: string | null | undefined; createdAt?: DateTimeValue | null | undefined; publishedAt?: DateTimeValue | null | undefined; updatedAt?: DateTimeValue | ... 1 more ... | undefined; }'
     	result.myField = 'some value';
     }
     return result;

    and to document service api :

     if (!('myField' in ctx.contentType.attributes)) {
     	return;
     }
     // ...
     await strapi.documents(ctx.uid).update({
     	documentId: result.documentId,
     	// @ts-expect-error: TS doesn't see that myField is valid for the current CT : 
     	// `Object literal may only specify known properties, and 'adminLabel' does not exist in type 
     	// 'Partial<Input<"admin::api-token" | "admin::api-token-permission" | "admin::permission" | "admin::role" | "admin::session" | "admin::transfer-token" | "admin::transfer-token-permission" | ... 17 more ... | "plugin::users-permissions.user">>'`
     	data: { myField: 'some value' }
     });

• not a any/unknown/ts-expect-error issue, but had to copy/paste internal upload plugin type to get programmatic upload to work :

   // copied from https://github.com/strapi/strapi/blob/93476f908c08d6d3d5215c06483829e3c6da1b32/packages/core/upload/server/src/types.ts#L3
   type UploadFile = Partial<FormidableFile> & {
   	path?: string;
   	tmpWorkingDirectory?: string;
   	provider?: string;
   };
   const response = await strapi.plugins.upload.services.upload.upload( // undocumented in v5 doc
   	{
   		data: {},
   		files: {
   			filepath: thumbnail.filePath,
   			originalFilename: thumbnail.fileName,
   			name: thumbnail.fileName,
   			mimetype: mime.getType(thumbnail.filePath),
   			size: stats.size,
   		} as UploadFile,
   	}
   );

Q3. Document Service: do fields, populate, filters, status and locale type correctly against your schemas? Where do they not?

almost. As mentioned in Q1, DS api fails to type media fields, they are always typed as any. current hack is to force type :

type MyFixedCT = Omit<
	Data.ContentType<'api::....'>, 'media'
> & {
	media?: Data.ContentType<'plugin::upload.file'>;
};
const doc:MyFixedCT|null = strapi.documents('api::....')
	.findOne({ documentId:'xxx', populate: ['media']})
if (doc) {
	console.log(doc.media?.folder, doc.media?.url);
}

Q4. Do you commit generated types, regenerate them in CI, or both? What breaks?

commit, no break.

Q5. How long does tsc --noEmit take, and how big is your schema (content types, components, dynamic zones)?

2sec. / 7 CT (no components, no dynamic zones)

Q6. Plugin authors: what is missing to type a plugin's server side and admin side?

still has to investigate this (in the process of migrating project)

Q7. What would a good version of this look like for you?

no precise idea but generally a better documentation.

hope this can help

Proposal: audit each package's public API and types before strictTypes ships

#27807 turns the types a package already exposes into contracts that apps compile against. Most of those contracts are inferred from the implementation, and they reach apps through the strapi-server entries and the generated plugins.d.ts. Today nobody really depends on them, because lookups return loose types. With the flag on, apps will. From then on, removing a member, narrowing a parameter or making a field required is a breaking change, and fixing it takes a deprecation cycle.

So I'd propose a pass over each package's public API before the feature is released. The pass makes sure the types are aligned with the runtime, correct, and free of things nobody uses.

What this looks like in practice

I did this for email and upload, as a stack of three PRs:

• #27129: Providers.Email in @strapi/types, used by the email plugin and the five email providers.
• #28100: Providers.Upload in @strapi/types, used by the upload plugin and the three upload providers.
• #28103: a type for each stage a file goes through in the upload flow, from the request to the database row.

These are the kinds of problems they found. I'd expect the same in other packages:

• Copies that drifted.
  • The email provider contract was declared in the plugin and again in every provider. Each copy disagreed on whether cc, bcc and html are required, and on whether defaultReplyTo is optional.
  • Upload had a File interface in each of the three providers, another in server/src/types.ts, and another in shared/contracts/files.ts.
• Types that describe a shape that never exists at runtime.
  • checkFileSize was typed as receiving the raw request file, but it receives the normalized one. Since the koa-body upgrade in 2024, its error has read undefined exceeds size limit of …. The type made the wrong field look valid.
  • The AI metadata service built a fake request file with a cast.
  • A media type guard claimed a single file for values that are arrays.
• Wrong optionality and units.
  • url was optional where a provider requires it.
  • size is in kilobytes in some places and in bytes in others, with nothing saying which.
• Exports nothing uses.
  • The aws-s3 provider exported a File type that no package imports.
  • Upload had a formidable devDependency that nothing in the package imports.
• Names that shadow globals. File collides with the DOM File.
• Contracts that are never checked against the real object. strapi.plugin('upload').provider has no type, and several boundaries passed values through as any or !. Removing those casts is what surfaced most of the items above.

Proposal

1. Gate. strictTypes stays experimental until every package that registers contracts has been audited. A tracking issue lists the packages from feat(types): opt in to registered server contracts #27807 (core, admin, Content Manager, Content Releases, Content-Type Builder, email, i18n, Review Workflows, upload, GraphQL, Documentation, Sentry), and users-permissions once it registers contracts.
2. Checklist for each package.
   • Inventory: list everything reachable from the published entry points: registered services, controllers, policies and middlewares, exported types, and the shapes that .d.ts files reference.
   • Usage: for each member, check whether anything inside or outside the monorepo uses it, or whether it is documented. Anything unused gets removed or made internal before it becomes a contract.
   • Runtime accuracy: required, optional, nullable and units match what the runtime produces. Remove the casts at the boundaries, because they hide exactly these mismatches.
   • One source of truth: shapes shared across packages live in @strapi/types, as Providers.* does, and are not copied.
   • Named contracts: services in the registries implement a named interface instead of ReturnType<typeof factory>. An inferred contract publishes every helper the implementation happens to return. (This is the same point as my Q7 comment above.)
   • Naming: nothing shadows globals. A renamed type keeps a @deprecated alias that points to its replacement.
3. How each PR stays reviewable.
   • One PR per package.
   • A PR changes types only by default. Diffing the compiled output against develop proves it.
   • Any runtime change the types expose is listed in the PR with its reason, or moved to a separate fix PR.
   • New contracts are checked with satisfies at the source, so they are verified where they are written.

The email and upload PRs above can serve as the pilot. I'm happy to take other packages next.