RFC: 2023 Upgraded Documentation

[Nick-Lucas]

Preface

Currently the docs have a lot of really well written content, and some which needs a little love. The biggest problem is they're often written from the perspective of APIs, rather than needs, and sometimes lack the foundation of knowledge about RPC and how tRPC is similar to or better than alternatives. The result is that as a user, having a problem to solve is hard to then correlate back to the docs.

For a realistic but oversimplified example:

• We communicate like: "createContext: this is a useful tool to do x y and z"
• Developers though ask: "My Services: how do I get these into my procedures in a correct way?"

We should focus the written docs on answering questions to the latter, and use our shiny new generated API Docs to handle the former.

This discussion should serve a couple goals:

1. Contain the high level plan as reference, which I'll update with feedback incorporated - eventually we should create a Project to track progress
2. Be a discussion forum for high level feedback on the docs

The Plan (WIP)

Below are the sections we propose need covering

• Overview & Concepts: Just enough about each concept to be able to understand it for the remainder of the docs. Keep it short, shallow, and quick to understand. Link to other docs.
  • What is RPC? What mindset should I adopt?
    • don't think about HTTP/REST error codes and patterns
    • it's just a function call, though query/mutation are useful added concepts
    • Link to RPC Spec
  • Anatomy of tRPC
    • Anatomy of a "Procedure"
      • Meta and Context
      • Input / Output Validation
      • Queries, Mutations, Subscriptions (sign post to main docs for these)
    • Transformers
    • Middlewares
    • Adapters
    • Error Handling
    • Links
  • A modified version of this diagram that isn't Next.js-specific: https://www.c-ehrlich.dev/img/youtube/trpc-data-flows.png
  • Suggested videos & community resources
  • Comparisons (to GraphQL, OpenAPI, Zodios, Blitz, etc)
  • How does tRPC work internally? (tinyrpc blog post & codebase)
  • maybe something cool can be done with MDX here to make it interactive?
    • Kitchen Sink!!
• Getting Started docs: enhance quickstart guide #3947
  • Project Setup
    • Monorepo Setup - a simple skeleton project using npm workspaces, tsc & vite.
    • Installation of tRPC
  • API Setup
    • Target file structure skeleton
      • "By the end of this guide you should have a file structure which looks like this"
    • Initialise tRPC
    • Create a router instance
    • Add a query procedure
    • Add a mutation procedure
    • Running tRPC (show standalone adapter as example)
      • Link to other adapters in docs
  • Using your tRPC API
    • Consuming in a Service Client
    • Consuming in a React Client
    • Consuming in a NextJS Client
    • Calling routes from within tRPC
    • Consuming in...
• tRPC & Common Patterns & How-to Guides
  • Writing Queries (Backend, & usage example for each client)
  • Writing Mutations (Backend, & usage example for each client)
  • Writing Subscriptions (Backend, & usage example for each client)
  • Writing Middlewares (Backend, & usage example for each client)
  • Dependency Injection docs: recommendations on how to handle "dependency injection" #3958
  • Throwing and Handling Errors
  • Router Factories / re-using common routers
  • Breaking up large routers
    • Merging Routers
    • Nesting Routers
  • Error handling & shaping
    • Throwing a TRPCError
    • Using a middleware to re-throw error base classes as TRPCError (check if this is possible)
    • Error formatter
    • Catching/logging errors via Adapter
• Monorepo Solutions & Guides
  • How to set it up in workspaces
    • tsconfig / depending on app
    • correctly import the AppRouter, and correct ways to link your projects to do this
  • How to set it up in Nx
    • App vs Library Routers
    • tsconfig / depending on app
  • How to set it up in Turborepo
  • Tips:
    • My client doesn't see the types for my procedure / gives this vague error about not finding the type
    • I need to constantly restart my language server / dev server when backend changes
• tRPC API @trpc/server docs
  • Setting it up (point back to Getting Started guide for more depth, make this a boilerplate reference)
  • keep most of the same content
  • subscriptions / websockets ()
• Vanilla @trpc/client docs
  • Overview, what is it, when to use it docs: foundational work #4009
  • Setting it up (assuming API already exists) docs: foundational work #4009
  • keep most of the same content
• React @trpc/react-query docs
  • Overview, what is it, when to use it docs: foundational work #4009
  • Setting it up (assuming API already exists) docs: foundational work #4009
  • keep most of the same content
• Next @trpc/next docs
  • Overview, what is it, when to use it docs: foundational work #4009
  • Setting it up (assuming API already exists) docs: foundational work #4009
  • keep most of the same content
• Frequently Asked Questions
• API Reference
  • Could trim down other topics and lean on this for API docs.
  • Could also break this up and move it into the discrete package pages maybe?

[Nick-Lucas]

So what I'll do is if people keep feeding back, I'll keep updating the first comment. Interested in thoughts from people like @KATT on how to go about the project, I would personally avoid trying to kick off a long lived develop branch given how much the live docs receive little tweaks.

If we can find a path of releasing updated docs and having a working site at all points, that might be best. I think most of it could be worked on quite gradually, the main exception possible being QuickStart/Getting Started which will need a significant chunk dropped in one day, but I'm frankly up for that challenge :)

[KATT]

Ship it

[Nick-Lucas]

Roger that Boss, opening a PR now with this tree structure as the entire contents. Deleting the rest. Less is more. Let's go!

[ixahmedxi]

Overall it looks like a big improvements to me and as @KATT said, SHIP IT. But one more thought, I really like the though of adding a dedicated nx/turborepo setup guide as these are the most common tools that will be used with tRPC because it works great in monorepos.

There are however two technologies that tRPC is used with very very often and these are prisma and next-auth, could we have sections about setting these up with tRPC via the context?

[Nick-Lucas]

Yes! One of the big areas I'm trying to figure out in my mind is around this.

I'm thinking the right way is to provide a main setup guide in a fairly generic technology like Workspaces, but discrete integration guides for ecosystems like Workspaces, Nx, Next, etc, which don't go into much depth beyond "put your appRouter here". If done wrong this runs the risk of not really improving the onboarding experience for the real world though. Would love some views :)

[c-ehrlich]

For monorepos there are a lot of questions for me

• do we pitch "here is how to create a new nx/turbo/etc project with tRPC" or "here's how to add it to a new nx/turbo/etc project"?
• which tech stack do we show in docs for this? Next.js? Fastify and a React SPA? Something else?
• how much should we defer to the docs of each monorepo solution? (imo as much as possible)

RE: Prisma, NextAuth, etc - I think one way to do this would be to have a more general section on integrating things with tRPC. It's basically always the same pattern:

• instantiate the thing
• include in context, either through regular context instantiation or context swapping in middleware
• that's it, you can now call it on the backend
• include in the frontend the same way you would do in a non trpc app (ie [...nextauth].ts file, any providers, etc)

I do think it might make sense to have a page like this. Maybe write it in a way that points out the repeating patterns. "It's just context" is missing the point, which is that the current docs are shaped too much like the API and not enough like the goals people have.

[criejs]

Very clear structure. From novice to proficient and tRPC in action.

[Nick-Lucas]

https://nehalist.io/trpc-review/#learning-curve-documentation

Some great feedback on the docs here, which we should action :)

[c-ehrlich]

Thoughts RE: non-React integrations (#4082):

I like linking to other integrations in an easy to find place (ie next to the React/Next integrations), and there are quite a few now (I've seen Vue/Nuxt, Solid, and Svelte, maybe there are others also?).

Layout Proposal 1:

• Add a "Other Frontend Integrations" section below "Next.js Integration" which has subheadings for Vue, Solid, etc

Layout Proposal 2:

• Create a "Frontend Usage" section which contains "React Query Integration", "Next.js Integration", and an additional heading for each other framework

That being said I do think:

1. There's a difference between @trpc/next, and an external package developed by someone else. Any integration we include in the docs that doesn't start with @trpc/ should make this very obvious.
2. We need to be careful to not "become/replace the docs" for other projects. This doesn't help anyone. I would link to them, maybe add a paragraph describing what they are, but not much more. Their own maintainers will write better docs for them.

[Nick-Lucas]

Either would work for me, the first one is probably the cleanest right now while we don't have many 1st party integrations. The concept I had in mind was something similar, like:

• Backend Usage
• Client Usage
• Client Integrations
  • React Query
  • Next.js
  • 1 page for each future 1st party lib
  • Community Libraries

[c-ehrlich]

Makes sense.

One more thing that's been on my mind regarding naming: If I was new and trying to understand the basics of using tRPC from an app developer's pov, "Client Usage" sounds more important than "Client Integrations". But all the stuff you actually need to know (unless you're rolling your own setup) is in "Client Integrations".

I understand that the vanilla client comes "before" the integration conceptually, but most peoples actual experience will be:

• learn basic concepts (procedure/query/mutation, frontend hooks, maybe context and middleware)
• get started from a template
• build stuff with these core concepts
• eventually get to a point where they need to care about the plumbing for some reason

Don't have any better suggestions for naming, but will try to think about it.

[Nick-Lucas]

Yes, thinking about this recently I've been concluding the same, I initially moved the vanilla client away from referring to itself as "vanilla" in the docs, but that might end up muddying the waters when we tighten up our treatment on integrations? Maybe we frame it as a type of integration, and seat it alongside the other integrations?

The Vanilla branding was probably quite good in that way, but we also have a chance to tweak the framing:

• Vanilla Client
• tRPC Client
• Imperative Client
• Standard Client
• Basic Client

[c-ehrlich]

I like the existing "Vanilla Client". "Basic Client" is good too. I don't feel strongly about either being better or worse. Regarding the other names:

• "tRPC Client": don't like this at all, are the others not tRPC clients?
• "Imperative Client": true, but I don't think being imperative is what separates it from other clients
• "Standard Client": Are the others non standard? Arguably so, but not sure this helps with education.

Other suggestions: Raw Client? Barebones Client? Not in love with either of these, but something to indicate that it's the most minimal client you can use and can run basically anywhere at the expense of not having the QoL of the integrations.

Regarding structure, how about this?

• Client Usage
  • Introduction (which leads most people to the React/Next integrations)
  • Vanilla Client
    • (some subheadings that are currently here are moved to "Advanced Concepts")
  • React Query Integration
  • Next.js integration
  • Other Integrations (or "Third Party Integrations"?)
  • Advanced Concepts
    • Aborting Procedure calls (add a note for RQ/Next behavior)
    • Creating Custom Headers
    • CORS & Cookies

[angelhdzmultimedia]

I propose renaming the "Using Next.js" tab into "Integrations", so Nuxt can be added to the game.
This Nuxt 3 package https://github.com/wobsoriano/trpc-nuxt. helped me finally understand tRPC and it's awesome.

Nice project! 🔥🎉❤ Wishing you all health, peace, and success.