Skip to main content
Version: 11.x

FAQ / Troubleshooting

Collection of frequently asked questions with ideas on how to troubleshoot & resolve them.

Feel free to contribute to this page with improvements or create a new discussion on GitHub if you have a question that isn't answered here. Also, have look through the GitHub Discussions and our Discord if your question isn't answered here.

It doesn't work! I'm getting any everywhere​

  • Make sure you have no type errors in your code
  • Make sure you have "strict": true in your tsconfig.json
  • Make sure your @trpc/*-versions match in your package.json
  • Make sure you are using the TypeScript-version required by tRPC (>=5.6.2)
  • Make sure your editor is using the same TypeScript version as your package.json

How do I make a middleware change the type of my Context?​

See Context Extension.

Is tRPC production ready?​

Yes. tRPC is very stable and is used by thousands of companies, even big ones like Netflix & Pleo are using tRPC in production.

Why doesn't tRPC work in my monorepo?​

This is difficult question to answer, but since tRPC doesn't have any build step, it's unlikely that the problem is on tRPC's side.

Here are some things to check:

  • Make sure you have the same version of all @trpc/* across all your project
  • Make sure you have "strict": true in all your tsconfig.jsons
  • Make sure you have no type errors in your app
  • In the case that you have a dedicated server and client tsconfig.json files without a bundled server monorepo package, make sure you have "paths": [...] in your client tsconfig.json like your server tsconfig.json,so that the client can find the same file.

You can also have a look at our Awesome tRPC-collection to find several open-source projects that are using tRPC in a monorepo.

Is a monorepo mandatory?​

No, a monorepo is not mandatory but you will lose some of the benefits of using tRPC if you don't use it since you will lose guarantees that your client and server works together.

One way you can leverage tRPC is to publish a private npm package with the types of your backend repo and consume them in your frontend repo.

Related discussion: https://github.com/trpc/trpc/discussions/1860

Can I dynamically return a different output depending on what input I send?​

No, not currently, in order for tRPC to do that automatically, we need something called "Higher kinded types" which is not yet supported in TypeScript.

Related discussion: https://github.com/trpc/trpc/discussions/2150

Can I apply a middleware to a full router?​

No, but you can use base procedures instead, which offers more flexibility than if this was done on a per-router-level.

Does tRPC work with Next.js 13 App Layouts & RSC?​

Yes, tRPC works with Next.js 13 App Layouts & React Server Components, but we have not built any official examples of it yet.

For more information, you can read & follow this issue where we've referenced a few examples of it.

Am I safe with using features marked as as unstable_?​

tl;dr: Yes!

If you encounter a feature in tRPC that is marked as unstable_ it means that the API is unstable and might change in minor version bumps, but:

  • Specifics of the implementation might change in minor changes - its name and options might change
  • If it exists in tRPC it's already used it in production
  • We very much encourage you to use it
  • If any changes are done to unstable_-feature, they will be included in the release notes (& you'll see type errors)
  • Please report any suggestion on the API design or issues on github.com/trpc/trpc/issues or in the #🧪-unstable-experimental-features on our Discord

Am I safe with using features marked as as experimental_?​

If you encounter a feature in tRPC that is marked as experimental_ it means that the API is unstable and is very likely to change during any bump of tRPC.

  • Wide range of the feature and its usage might change
  • The feature might not be well-tested
  • We might drop the feature entirely
  • It's up to you to read the latest docs and upgrade without a guided migration path
  • Changes might not be well-documented in the release notes
  • Bugs are not guaranteed to be fixed

We do, however, love input! Please report any suggestion on the API design or issues in the #🧪-unstable-experimental-features on our Discord.

Is tRPC strict with semver?​

Yes, tRPC is very strict with semantic versioning and we will never introduce breaking changes in a minor version bump.

With this, we also consider changes on exported TypeScript types as major changes, apart from ones marked as @internal in the JSDoc.

Why is tRPC on such a high version already?​

When tRPC started and had very few users and we often iterated on the API design whilst being strict with semver.

  • The first 9 versions of tRPC were released in the first 8 months of the project.
  • Version 10 which we released 14 months after v9 should be seen as the real "version 2" of tRPC where we did any fundamental changes to the API decisions. (2 is 10 in binary, amirite?)

We expect the API to be stable now and are planning to release codemods for any breaking changes in the future, just like we did with the v9->v10 upgrade.

Anything else you want to know?​

Please write a feature request on GitHub, write in GitHub Discussions, or Discord. You're also free to suggest improvement of this page or any other page using the "Edit this page" button at the bottom of the page.