+page.svelte{greeting}
\n```\n## Examples\n\nThis repository contains a handful of examples:\n\n- [simple](https://github.com/icflorescu/trpc-sveltekit/tree/main/examples/simple)\n- [bookstall](https://github.com/icflorescu/trpc-sveltekit/tree/main/examples/bookstall)\n- [websocket](https://github.com/icflorescu/trpc-sveltekit/tree/main/examples/websocket)\n\n---\n\n## EXPERIMENTAL WebSocket support\n(courtesy of [@SrZorro](https://github.com/SrZorro))\n\nSvelteKit [doesn't (yet) offer WebSockets support](https://github.com/sveltejs/kit/issues/1491), but if you're using `@sveltejs/adapter-node`, `tRPC-SvelteKit` can spin up an experimental WS server to process tRPC procedure calls (see the [implementation details](#websockets-implementation-details) to find out how this works under the hood).\n\n### Caveats\n\n- Works with [@sveltejs/adapter-node](https://www.npmjs.com/package/@sveltejs/adapter-node) **exclusively**;\n- The URL is hardcoded to `/trpc`;\n- When in websocket mode, all tRPC methods are handled by it; this could be changed at some point so that only `subscriptions` are handled by the WebSockets server;\n- Prerendering is not supported, since in the current implementation no WebSockets server is created when building/prerendering.\n\n### Install the package and its dependencies:\n\n```bash\nyarn add trpc-sveltekit @trpc/server @trpc/client @sveltejs/adapter-node ws\n```\n\n### Setup workarounds\n\nIn your `vite.config.ts`, add:\n\n```ts\nimport { sveltekit } from '@sveltejs/kit/vite';\nimport type { UserConfig } from 'vite';\n\nimport { vitePluginTrpcWebSocket } from 'trpc-sveltekit/websocket'; // β\n\nconst config: UserConfig = {\n plugins: [\n sveltekit(),\n vitePluginTrpcWebSocket // β\n ]\n};\n\nexport default config;\n```\n\nIn your `svelte.config.js`, modify:\n\n```ts\nimport adapter from '@sveltejs/adapter-node'; // β\n// import adapter from '@sveltejs/adapter-auto'; // β\n```\n\nCreate this file next to `package.json` your server entrypoint:\n\n```js\n// wsServer.js\nimport { SvelteKitTRPCWSServer } from \"trpc-sveltekit/websocket\";\n\nSvelteKitTRPCWSServer(import.meta.url);\n```\n\nIn your `package.json` `scripts`, modify the `start` command:\n\n```json\n{\n \"scripts\": {\n \"start\": \"node ./wsServer\"\n }\n}\n```\n\n### Create your tRPC router & context\n\n- [Create your tRPC router](#create-your-trpc-router)\n- [Create a tRPC context](#create-a-trpc-context)\n\n### Call this function from your SvelteKit app [server hooks](https://kit.svelte.dev/docs/hooks#server-hooks):\n\n```ts\n// hooks.server.ts\nimport { createContext } from '$lib/trpc/context';\nimport { router } from '$lib/trpc/router';\nimport { createTRPCWebSocketServer } from \"trpc-sveltekit/websocket\";\n\nimport { building } from '$app/environment';\n\nif (!building) createTRPCWebSocketServer({ router, createContext })\n```\n\n### Define a helper function to easily use the tRPC client in your pages:\n\n```ts\n// lib/trpc/client.ts\nimport type { Router } from '$lib/trpc/router';\nimport { createTRPCWebSocketClient } from \"trpc-sveltekit/websocket\";\n\nlet browserClient: ReturnType+page.svelte{greeting}
\n```\n\n\n\n### Implementation details\n\nAll the related code to the websocket implementation is located at `package/src/websocket`.\n\n#### `vitePlugin.ts`\n\nExports a vite plugin that handles in dev mode the websocket lifecycle.\n\n- On init: `configureServer`\n - `createWSSGlobalInstance`\n - Listen for `upgrade` events in vite dev server, so we can upgrade `/trpc` to our tRPC server\n\nOn init we create a `WebSocketServer` with the property `noServer` so we can handle the upgrade to our tRPC and don't break the default vite websocket.\n\nWe store a reference in `globalThis` to the web socket server, so we can later get a reference from SvelteKit side.\n\n> To store the websocket server without colliding with existing stuff in `globalThis` at `src/websocket/svelteKitServer.ts` we create a `Symbol` \n> so we can reference the tRPC websocket like so: `globalThis[Symbol.for('trpc.sveltekit.wss')]`\n\nThen we set up an event listener to the vite dev http server to handle the `upgrade` event from `onHttpServerUpgrade`. It will check that the path is `/trpc`, if so it will upgrade our request to our tRPC websocket server.\n\n#### `svelteKitServer.ts`\n\nExports functions to handle the lifecycle of the tRPC websocket server:\n\n- `createWSSGlobalInstance`\n- `onHttpServerUpgrade`\n\n> The firsts 2 methods are already explained in the `vitePlugin.ts` section.\n\n- `SvelteKitTRPCWSServer`\n\nThe Vite plugin only works while the Vite dev server is running. When building for production we need to take a diferent aproach.\n\nWhen we build a SvelteKit app, it will output a `./build` directory.\n\nThis function takes `import.meta.url` as an argument from the root directory of the project (next to `package.json`) and then converts it to `__dirname`.\n\nFirst it creates a websocket server attached to `globalThis`, as explained, then imports dynamically from `${__dirname}/build` directory the `index.js` file, that exports a `server` property that contains an http server.\n\nWe attach to this server `onHttpServerUpgrade` so we handle in the production server the tRPC websocket.\n\n#### `server.ts`\n\nThe function `createTRPCWebSocketServer` handles the creation of the websocket tRPC handler getting the `wss` from `globalThis`.\n\nThis current implementation in case we are prerendering would fail as vite does not call `configureServer` on the build step, so no `wss` server is found in `globalThis`.\n\nThis is why, when calling this method, we have to add a guard on the client/consumer code:\n\n```ts\nimport { building } from '$app/environment';\n\nif (!building) // π Prevent from calling when building/prerendering\n createTRPCWebSocketServer({ router, createContext })\n```\n\n#### `client.ts`\n\n`createTRPCWebSocketClient`\n\nCreates the tRPC proxy client and links to the `wss`.\n\n> Currently all the tRPC requests are handled via websockets, [but this could be changed to only handle subscriptions](https://trpc.io/docs/links).\n\n---\n\n## Contributors\n\n[](https://github.com/icflorescu/trpc-sveltekit/graphs/contributors)\n\n## Acknowledgements\n\nHuge thanks to [Alex / KATT](https://github.com/KATT), the author of [tRPC](https://trpc.io/), for being the first sponsor of this project! π \n\n## Stand with Ukraine\n\nOn 24th of February 2022 [Russia unlawfully invaded Ukraine](https://en.wikipedia.org/wiki/Russo-Ukrainian_War). This is an unjustified, unprovoked attack on the sovereignty of a neighboring country, but also an open affront to international peace and stability that has the potential to degenerate into a nuclear event threatening the very existence of humanity. I am an EU (Romanian) citizen, but I am doing everything in my power to stop this madness. I stand with Ukraine. The entire Svelte community β€οΈπΊπ¦. Here's [how you can show your support](https://www.stopputin.net/).\n\n## License\n\nThe [ISC License](https://github.com/icflorescu/trpc-sveltekit/blob/master/LICENSE).\n\n[npm-url]: https://npmjs.org/package/trpc-sveltekit\n[repo-url]: https://github.com/icflorescu/trpc-sveltekit\n[stars-url]: https://github.com/icflorescu/trpc-sveltekit/stargazers\n[closed-issues-url]: https://github.com/icflorescu/trpc-sveltekit/issues?q=is%3Aissue+is%3Aclosed\n[license-url]: LICENSE\n[npm-image]: https://img.shields.io/npm/v/trpc-sveltekit.svg?style=flat-square\n[license-image]: http://img.shields.io/npm/l/trpc-sveltekit.svg?style=flat-square\n[downloads-image]: http://img.shields.io/npm/dm/trpc-sveltekit.svg?style=flat-square\n[stars-image]: https://img.shields.io/github/stars/icflorescu/trpc-sveltekit?style=flat-square\n[last-commit-image]: https://img.shields.io/github/last-commit/icflorescu/trpc-sveltekit?style=flat-square\n[closed-issues-image]: https://img.shields.io/github/issues-closed-raw/icflorescu/trpc-sveltekit?style=flat-square\n[language-image]: https://img.shields.io/github/languages/top/icflorescu/trpc-sveltekit?style=flat-square\n[sponsor-image]: https://img.shields.io/badge/sponsor-violet?style=flat-square\n[sponsor-url]: https://github.com/sponsors/icflorescu\n","readmeFilename":"README.md"}