From e3f6bd106c88d6c52fd49c0301437913dab88699 Mon Sep 17 00:00:00 2001 From: Otto Ahoniemi Date: Wed, 20 Mar 2024 15:03:53 +0200 Subject: [PATCH] Update documentation to support only the enhanceApi function --- .changeset/dry-buses-end.md | 7 +++ README.md | 89 ++++++++++++++++++++----------------- src/api.ts | 10 +++++ 3 files changed, 64 insertions(+), 42 deletions(-) create mode 100644 .changeset/dry-buses-end.md diff --git a/.changeset/dry-buses-end.md b/.changeset/dry-buses-end.md new file mode 100644 index 0000000..aae1b15 --- /dev/null +++ b/.changeset/dry-buses-end.md @@ -0,0 +1,7 @@ +--- +"trpc-rtk-query": minor +--- + +Remove createApi function and support only enhancing existing apis. This way we have to support only +one method of generating hooks for apis. There's now a `createEmptyApi` helper to make it easier to +create a base api without any endpoints, which can be then passed to api. diff --git a/README.md b/README.md index 58f732f..99d843d 100644 --- a/README.md +++ b/README.md @@ -14,19 +14,15 @@ ## **[RTK Query](https://redux-toolkit.js.org/rtk-query/overview) support for [tRPC](https://trpc.io/)** 🧩 -- Automatically generate **typesafe** `RTK Query hooks` from your `tRPC` procedures. +- Automatically generate **typesafe** `RTK Query hooks` (for react) from your `tRPC` procedures. - Perfect for incremental adoption. - Any feedback, issues, or pull requests are highly appreciated ```typescript -import { createApi } from "trpc-rtk-query"; - -const api = createApi({ - client: trpcClient, /* 👈 This is the magic */ - /* ⬇️ You can still pass all the RTK config properties */ - tagTypes: ["User"], - reducerPath: "trpcApi" +const api = enhanceApi({ + api: rtkApi, /* Your api created with rtk query */ + client: trpcClient, /* 👈 The trpc magic happens when passing in the typed client ✨ */ }); export { useUserListQuery } from api; // Automatically typed hooks thanks to the power of tRPC + RTK! @@ -45,12 +41,9 @@ npm install trpc-rtk-query @reduxjs/toolkit @trpc/client @trpc/server yarn add trpc-rtk-query @reduxjs/toolkit @trpc/client @trpc/server ``` -Note the minimum versions for packages: - -- @reduxjs/toolkit: `1.9.7` -- @trpc/client & @trpc/server `10.38.5` +Note the minimum versions for packages, we only support trpc v10 and rtk query v2. -**2. Initialize the `tRPC router`.** +**2. Use your `tRPC router`.** ```typescript /* server.ts */ @@ -94,22 +87,54 @@ const client = createTRPCProxyClient({ ``` -**4. Create a new automatically typed API.** +**4. Create a trpc-rtk query api.** ```typescript // api.ts -import { createApi } from "trpc-rtk-query"; +import { createApi } from "@reduxjs/toolkit/query/react"; +import { enhanceApi } from "trpc-rtk-query"; -const api = createApi({ - client, /* 👈 This is the magic */ - /* ⬇️ You can still pass all the RTK config properties */ - tagTypes: ["User"], - reducerPath: "trpcApi" +// Use function provided by rtk to create your api +const rtkApi = createApi({ + baseQuery: fetchBaseQuery({ baseUrl: "/" }), + endpoints: () => ({}), +}) + +// Enhance the api with hooks +export const api = enhanceApi({ + client, // <- typed client from step 3 + api: rtkApi // <- api from rtk + // pass in any endpoint specific options, such as providesTags or onQueryStarted for optimistic updates + endpointOptions: { + userList: { + providesTags: ["User"] + } + } }); -export { useUserListQuery } from api; // Automatically typed hooks thanks to the power of tRPC + RTK! +export { useUserListQuery } from api; // <- export your typed hooks! ``` +You can also use `createEmptyApi` helper function as follows: + +```typescript +// api.ts +import { createEmptyApi, enhanceApi } from "trpc-rtk-query"; + +// Enhance an empty api with hooks +export const api = enhanceApi({ + client, // <- typed client from step 3 + api: createEmptyApi(), // <- createEmptyApi generates base api without any endpoints. + // pass in any endpoint specific options, such as providesTags or onQueryStarted for optimistic updates + endpointOptions: { + userList: { + providesTags: ["User"] + } + } +}); + +export { useUserListQuery } from api; // <- export your typed hooks! + **5. Add the typesafe API to the store.** This is the same step as you would [normally do](https://redux-toolkit.js.org/rtk-query/overview). @@ -142,26 +167,6 @@ const App = () => { } ``` -### Using existing api - -You might already have an RTK query API instance for a non-tRPC backend. In this case, you can pass the previous API in with the tRPC client, and new endpoints will be generated similarly as above. - -```typescript -import { enhanceApi } from "trpc-rtk-query"; -export const api = enhanceApi({ - client, // <- your typed client from step 1 - api: existingApi // <- your existing api - // pass in any endpoint specific options, such as providesTags or onQueryStarted for optimistic updates - endpointOptions: { - userList: { - providesTags: ["User"] - } - } -}); - -export { useUserListQuery } from api; // <- export your typed hooks -``` - # Development status -This library is currently in the alpha stage. 0.0.x versions are being published to npm for people to try this out, but you shouldn't consider it ready for production anytime soon. See the [0.1.0 project](https://github.com/users/otahontas/projects/2) for what's under development and planned to be done before 0.1.0 can be released. +This library is currently in the alpha stage. 0.x.x versions are being published to npm for people to try this out, but you shouldn't consider it ready for production anytime soon. See the [project status](https://github.com/users/otahontas/projects/2) for what's under development and planned to be done before first major 1.0.0 will be released. diff --git a/src/api.ts b/src/api.ts index 8798539..6739714 100644 --- a/src/api.ts +++ b/src/api.ts @@ -3,6 +3,7 @@ import { type Api, type BaseQueryFn, type EndpointDefinitions, + createApi, } from "@reduxjs/toolkit/query/react"; import { type AnyRouter } from "@trpc/server"; @@ -71,3 +72,12 @@ export const enhanceApi = < endpointOptions: options.endpointOptions, tRPCClientOptions: options, }); + +/* + * Helper to create base api with no endpoints + */ +export const createEmptyApi = () => + createApi({ + baseQuery: () => ({ data: undefined }), + endpoints: () => ({}), + });