19 |
--------------------------------------------------------------------------------
/@example/static/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/vishalbalaji/trpc-svelte-query-adapter/54726423b69ba0785c6a9ccfd5ac5c0e6311a55f/@example/static/favicon.png
--------------------------------------------------------------------------------
/@example/svelte.config.js:
--------------------------------------------------------------------------------
1 | import adapter from '@sveltejs/adapter-auto';
2 | import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
3 |
4 | /** @type {import('@sveltejs/kit').Config} */
5 | const config = {
6 | // Consult https://kit.svelte.dev/docs/integrations#preprocessors
7 | // for more information about preprocessors
8 | preprocess: vitePreprocess(),
9 |
10 | kit: {
11 | // adapter-auto only supports some environments, see https://kit.svelte.dev/docs/adapter-auto for a list.
12 | // If your environment is not supported, or you settled on a specific environment, switch out the adapter.
13 | // See https://kit.svelte.dev/docs/adapters for more information about adapters.
14 | adapter: adapter()
15 | }
16 | };
17 |
18 | export default config;
19 |
--------------------------------------------------------------------------------
/@example/tsconfig.json:
--------------------------------------------------------------------------------
1 | {
2 | "extends": [
3 | "../tsconfig.base.json",
4 | "./.svelte-kit/tsconfig.json"
5 | ],
6 | "compilerOptions": {
7 | "allowJs": true,
8 | "checkJs": true,
9 | "esModuleInterop": true,
10 | "forceConsistentCasingInFileNames": true,
11 | "resolveJsonModule": true,
12 | "skipLibCheck": true,
13 | "sourceMap": true,
14 | "strict": true,
15 | "moduleResolution": "bundler",
16 | "plugins": [
17 | {
18 | "name": "typescript-svelte-plugin",
19 | // the following options can be set additionally; they are optional; their default values are listed here
20 | "enabled": true, // enables this plugin
21 | "assumeIsSvelteProject": false // if true, skip detection and always assume it's a Svelte project
22 | }
23 | ]
24 | }
25 | // Path aliases are handled by https://kit.svelte.dev/docs/configuration#alias
26 | // except $lib which is handled by https://kit.svelte.dev/docs/configuration#files
27 | //
28 | // If you want to overwrite includes/excludes, make sure to copy over the relevant includes/excludes
29 | // from the referenced tsconfig.json - TypeScript does not merge them in
30 | }
31 |
--------------------------------------------------------------------------------
/@example/vite.config.ts:
--------------------------------------------------------------------------------
1 | import { sveltekit } from '@sveltejs/kit/vite';
2 | import { defineConfig } from 'vite';
3 |
4 | export default defineConfig({
5 | plugins: [sveltekit()]
6 | });
7 |
--------------------------------------------------------------------------------
/@lib/.npmignore:
--------------------------------------------------------------------------------
1 | **/*
2 | !/src/*
3 | !/package.json
4 | !/README.md
5 | !/LICENSE
6 |
--------------------------------------------------------------------------------
/@lib/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2024 Vishal Balaji D
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/@lib/README.md:
--------------------------------------------------------------------------------
1 | # `tRPC` - `svelte-query` Adapter
2 |
3 | [![NPM version][npm-image]][npm-url]
4 | [![License][license-image]][license-url]
5 | [![Last commit][last-commit-image]][repo-url]
6 |
7 | > **See [#67](https://github.com/vishalbalaji/trpc-svelte-query-adapter/issues/67) for the latest updates on this project**
8 |
9 | > [!NOTE]
10 | > The README on [npmjs](https://npmjs.com/trpc-svelte-query-adapter) might not be fully up to date. Please refer to
11 | > the [README on the Github Repo](https://github.com/vishalbalaji/trpc-svelte-query-adapter/#readme) for the latest setup instructions.
12 |
13 | An adapter to call `tRPC` procedures wrapped with [@tanstack/svelte-query](https://tanstack.com/query/latest/docs/svelte/overview), similar to [@trpc/react-query](https://trpc.io/docs/react-query). This is made possible using [proxy-deep](https://www.npmjs.com/package/proxy-deep).
14 |
15 | ## Installation
16 |
17 | ```sh
18 | # npm
19 | npm install trpc-svelte-query-adapter @trpc/client @trpc/server @tanstack/svelte-query
20 |
21 | # yarn
22 | yarn add trpc-svelte-query-adapter @trpc/client @trpc/server @tanstack/svelte-query
23 |
24 | # pnpm
25 | pnpm add trpc-svelte-query-adapter @trpc/client @trpc/server @tanstack/svelte-query
26 | ```
27 |
28 | If you are using client-side Svelte, you would need to install `@trpc/server` as a `devDependency` using `--save-dev`.
29 |
30 | ## Available Functions
31 |
32 | The following functions from `@trpc/react-query` are ported over:
33 |
34 | - `useQuery` -> `createQuery`
35 | - `useInfiniteQuery` -> `createInfiniteQuery`
36 | - `useMutation` -> `createMutation`
37 | - `useSubscription` -> `createSubscription`
38 | - `useQueries` -> `createQueries`
39 | - `useUtils` -> `createUtils`
40 | - `getQueryKey`
41 |
42 | You can refer to [tanstack-query docs](https://tanstack.com/query/latest/docs/react/overview) and [@trpc/react-query docs](https://trpc.io/docs/react-query) for documentation on how to use them.
43 |
44 | There are also some new procedures that are only relevant for SvelteKit:
45 |
46 | - `createServerQuery`
47 | - `createServerInfiniteQuery`
48 | - `createServerQueries`
49 |
50 | As for these procedures, you can refer to the [Server-Side Query Pre-Fetching](#server-side-query-pre-fetching) section.
51 |
52 | ## Usage
53 |
54 | The following instructions assume the `tRPC` router to have the following procedures:
55 |
56 | ```typescript
57 | export const router = t.router({
58 | greeting: t.procedure
59 | .input((name: unknown) => {
60 | if (typeof name === 'string') return name;
61 |
62 | throw new Error(`Invalid input: ${typeof name}`);
63 | })
64 | .query(async ({ input }) => {
65 | return `Hello, ${input} from tRPC v10 @ ${new Date().toLocaleTimeString()}`;
66 | }),
67 | });
68 |
69 | export type Router = typeof router;
70 | ```
71 |
72 | ### Client-Only Svelte
73 |
74 | 1. Setup `@tanstack/svelte-query` as per [svelte-query docs](https://tanstack.com/query/latest/docs/svelte/overview).
75 | 2. Setup [@trpc/client](https://trpc.io/docs/client) and export the `tRPC` client.
76 | 3. Wrap the exported `tRPC` client with `svelteQueryWrapper` from `trpc-svelte-query-adapter`, as demonstrated in the example below:
77 |
78 | ```typescript
79 | // src/lib/trpc.ts
80 | import type { Router } from '/path/to/trpc/router';
81 | import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
82 |
83 | import { svelteQueryWrapper } from 'trpc-svelte-query-adapter';
84 |
85 | const client = createTRPCProxyClient({
86 | links: [
87 | httpBatchLink({
88 | // Replace this URL with that of your tRPC server
89 | url: 'http://localhost:5000/api/v1/trpc/',
90 | }),
91 | ],
92 | });
93 |
94 | export const trpc = svelteQueryWrapper({ client });
95 | ```
96 |
97 | 4. The exported `tRPC` client can then be used in `svelte` components as follows:
98 |
99 | ```svelte
100 |
105 |
106 | {#if $foo.isPending}
107 | Loading...
108 | {:else if $foo.isError}
109 | Error: {$foo.error.message}
110 | {:else if $foo.data}
111 | {$foo.data.message}
112 | {/if}
113 | ```
114 |
115 | ### SvelteKit and SSR
116 |
117 | For SvelteKit, the process is pretty much the same as for client-only svelte. However, if you intend to call queries from the server in a `load` function, you would need to setup `@tanstack/svelte-query` according to the [the ssr example in the svelte-query docs](https://tanstack.com/query/latest/docs/svelte/ssr#using-prefetchquery).
118 |
119 | Upon doing that, you would also need to pass in the `queryClient` to `svelteQueryWrapper` when initializing on the server, which you can get by calling the `event.parent` method in the `load` function. You can see an example of this in the [Server-Side Query Pre-Fetching](#server-side-query-pre-fetching) section. For this purpose, you might also want to export your client wrapped in a function that optionally takes in `queryClient` and passes it onto `svelteQueryWrapper`.
120 |
121 | Here is an example of what that might look like:
122 |
123 | ```typescript
124 | import type { QueryClient } from '@tanstack/svelte-query';
125 |
126 | const client = createTRPCProxyClient({
127 | links: [
128 | httpBatchLink({
129 | // Replace this URL with that of your tRPC server
130 | url: 'http://localhost:5000/api/v1/trpc/',
131 | }),
132 | ],
133 | });
134 |
135 | export function trpc(queryClient?: QueryClient) {
136 | return svelteQueryWrapper({
137 | client,
138 | queryClient,
139 | });
140 | }
141 | ```
142 |
143 | Which can then be used in a component as such:
144 |
145 | ```svelte
146 |
147 |
153 |
154 |
163 | ```
164 |
165 | The main thing that needs to passed in to `svelteQueryWrapper` is the `tRPC` client itself. So, this adapter should support different implementations of `tRPC` for Svelte and SvelteKit. For example, if you are using [trpc-sveltekit by icflorescu](https://icflorescu.github.io/trpc-sveltekit), all you would need to do after setting it up would be to change the client initialization function from something like this:
166 |
167 | ```typescript
168 | let browserClient: ReturnType>;
169 |
170 | export function trpc(init?: TRPCClientInit) {
171 | const isBrowser = typeof window !== 'undefined';
172 | if (isBrowser && browserClient) return browserClient;
173 | const client = createTRPCClient({ init });
174 | if (isBrowser) browserClient = client;
175 | return client;
176 | }
177 | ```
178 |
179 | to this:
180 |
181 | ```typescript
182 | import { svelteQueryWrapper } from 'trpc-svelte-query-adapter';
183 | import type { QueryClient } from '@tanstack/svelte-query';
184 |
185 | let browserClient: ReturnType>;
186 |
187 | export function trpc(init?: TRPCClientInit, queryClient?: QueryClient) {
188 | const isBrowser = typeof window !== 'undefined';
189 | if (isBrowser && browserClient) return browserClient;
190 | const client = svelteQueryWrapper({
191 | client: createTRPCClient({ init }),
192 | queryClient,
193 | });
194 | if (isBrowser) browserClient = client;
195 | return client;
196 | }
197 | ```
198 |
199 | Which can then be initialized and used in the way that it is described [in its docs](https://icflorescu.github.io/trpc-sveltekit/getting-started).
200 |
201 | #### Server-Side Query Pre-Fetching
202 |
203 | This adapter provides 3 additional procedures: `createServerQuery`, `createServerInfiniteQuery` and `createServerQueries`, which can be used to call their counterpart procedures in the `load` function in either a `+page.ts` or `+layout.ts`. These procedures return a `promise` and therefore can only really be called on the server.
204 |
205 | By default, these 3 procedures will pre-fetch the data required to pre-render the page on the server. However, if you wish to disable this behaviour on certain queries, you can do so by setting the `ssr` option to `false`.
206 |
207 | These procedures can be used as such:
208 |
209 | > [!NOTE]
210 | > [Gotta await top-level promises to pre-fetch data from SvelteKit v2](https://kit.svelte.dev/docs/migrating-to-sveltekit-2#top-level-promises-are-no-longer-awaited).
211 |
212 | ```typescript
213 | // +page.ts
214 | // tRPC is setup using `trpc-sveltekit` for this example.
215 | import { trpc } from '$lib/trpc/client';
216 | import type { PageLoad } from './$types';
217 |
218 | export const load = (async (event) => {
219 | const { queryClient } = await event.parent();
220 | const client = trpc(event, queryClient);
221 |
222 | return {
223 | foo: await client.greeting.createServerQuery('foo'),
224 | queries: await client.createServerQueries(
225 | (t) =>
226 | ['bar', 'baz'].map((name) => t.greeting(name, { ssr: name !== 'baz' })) // pre-fetching disabled for the `baz` query.
227 | ),
228 | };
229 | }) satisfies PageLoad;
230 | ```
231 |
232 | Then, in the component:
233 |
234 | ```svelte
235 |
236 |
245 |
246 | {#if $foo.isPending}
247 | Loading...
248 | {:else if $foo.isError}
249 | {$foo.error}
250 | {:else if $foo.data}
251 | {$foo.data}
252 | {/if}
253 |
254 |
255 | {#each $queries as query}
256 | {#if query.isPending}
257 | Loading...
258 | {:else if query.isError}
259 | {query.error.message}
260 | {:else if query.data}
261 | {query.data}
262 | {/if}
263 |
264 | {/each}
265 | ```
266 |
267 | You can also optionally pass new inputs to the queries and infinite queries from the client side(see [#34](/../../issues/34), [#47]( /../../issues/47 )) like so:
268 |
269 | ```svelte
270 |
288 |
289 |