@carvajalconsultants/headstart 1.0.0

package/README.md

@@ -0,0 +1,210 @@
+# Headstart
+
+Library to assist in integrating PostGraphile with Tanstack Start and URQL.
+
+This library is made up of:
+
+- An URQL Exchange that queries grafast for SSR pages (so we don't make an unecessary HTTP request)
+- A Grafserv adapter to work with Tanstack Start, including Web Socket support.
+- SSR Exchange to be used on the server and client for hydration
+
+## Installation
+
+1. Initialize Tanstack Start as per: https://tanstack.com/router/latest/docs/framework/react/start/getting-started
+
+2. Install Postgraphile as a library as per: https://tanstack.com/router/latest/docs/framework/react/start/getting-started
+   Specifically, the `graphile.config.ts` and `pgl.ts`. If you need WebSocket support, make sure to add a plugin in `graphile.config.ts` as per: https://postgraphile.org/postgraphile/next/subscriptions
+
+3. Enable WebSockets in `app.config.ts` if you need it:
+
+```
+// app.config.ts
+import { defineConfig } from "@tanstack/start/config";
+
+export default defineConfig({
+	server: {
+		experimental: {
+			websocket: true,
+		},
+	},
+});
+```
+
+4. Make sure to add the `/api` endpoint to the grafserv configuration so that Ruru GraphQL client works correctly:
+
+```
+// graphile.config.ts
+const preset: GraphileConfig.Preset = {
+    ...
+	grafserv: {
+        ...
+		graphqlPath: "/api",
+		eventStreamPath: "/api",
+	},
+    ...
+};
+```
+
+5. Add the api.ts file so that it calls our GraphQL handler. This will receive all GraphQL requests at the /api endpoint.
+
+```
+// app/api.ts
+import { createGraphQLRouteHandler } from "@carvajalconsultants/headstart";
+import { pgl } from "../pgl";
+
+export default createGraphQLRouteHandler(pgl);
+```
+
+6. Now we need to configure URQL for client and server rendering, first we start with the server. Create this provider:
+
+```
+// app/graphql/serverProvider.tsx
+import { Client, Provider } from "urql";
+import { grafastExchange, ssr } from "@carvajalconsultants/headstart";
+import { pgl } from "../../pgl";
+
+/**
+ * Configure URQL for server side querying with Grafast.
+ *
+ * This removes the need to make an HTTP request to ourselves and simply executes the GraphQL query.
+ */
+export const client = new Client({
+	url: ".",
+	exchanges: [ssr, grafastExchange(pgl)],
+});
+```
+
+7. Create the server side router which uses Grafast to execute queries:
+
+```
+// app/serverRouter.tsx
+import { ssr } from "@carvajalconsultants/headstart";
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import { Provider } from "urql";
+import { client } from "./graphql/serverProvider";
+import { routeTree } from "./routeTree.gen";
+
+export function createRouter() {
+	const router = createTanStackRouter({
+		routeTree,
+		context: {
+			client,
+		},
+
+		// Send data to client so URQL can be hydrated.
+		dehydrate: () => ({ initialData: ssr.extractData() }),
+
+        // Wrap our entire route with the URQL provider so we can execute queries and mutations.
+		Wrap: ({ children }) => <Provider value={client}>{children}</Provider>,
+	});
+
+	return router;
+}
+```
+
+8. Modify the TSR server-side rendering function to use this new router:
+
+```
+// app/ssr.tsx
+/// <reference types="vinxi/types/server" />
+import { getRouterManifest } from "@tanstack/start/router-manifest";
+import {
+	createStartHandler,
+	defaultStreamHandler,
+} from "@tanstack/start/server";
+
+import { createRouter } from "./serverRouter";
+
+export default createStartHandler({
+	createRouter,
+	getRouterManifest,
+})(defaultStreamHandler);
+```
+
+9. Add the client side router which uses the fetch exchange to execute queries, mutations, etc.:
+
+```
+// app/clientRouter.tsx
+import { ssr } from "@carvajalconsultants/headstart";
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import { Provider } from "urql";
+import { client } from "./graphql/clientProvider";
+import { routeTree } from "./routeTree.gen";
+
+export function createRouter() {
+	const router = createTanStackRouter({
+		routeTree,
+		context: {
+			client,
+		},
+		hydrate: (dehydrated) => {
+			// Hydrate URQL with data passed by TSR, this is generated by dehydrate function in server router.
+			ssr.restoreData(dehydrated.initialData);
+		},
+
+        // Wrap our entire route with the URQL provider so we can execute queries and mutations.
+		Wrap: ({ children }) => <Provider value={client}>{children}</Provider>,
+	});
+
+	return router;
+}
+```
+
+10. Tell TSR to use our client side router:
+
+```
+// app/client.tsx
+/// <reference types="vinxi/types/client" />
+import { StartClient } from "@tanstack/start";
+import { hydrateRoot } from "react-dom/client";
+import { createRouter } from "./clientRouter";
+
+const router = createRouter();
+
+// biome-ignore lint: Safe enough to assume root element will be there
+hydrateRoot(document.getElementById("root")!, <StartClient router={router} />);
+```
+
+11. Last but not least, you're ready to start using URQL on your components and pages. First we create the route using the loader option so we can pre-load data:
+
+```
+export const Route = createFileRoute("/")({
+	...
+	validateSearch: zodSearchValidator(paramSchema),
+
+	loaderDeps: ({ search: { page } }) => ({ page }),
+	loader: ({ context, deps: { page } }) =>
+		context.client.query(
+			gql`...`
+			{ first: CHARITIES_PER_PAGE, offset: (page - 1) * CHARITIES_PER_PAGE },
+		),
+	...
+});
+```
+
+12. Now in your component, you can query with URQL as you normally would:
+
+```
+const Home = () => {
+	const { page } = Route.useSearch();
+
+	const [{ data, error }] = useQuery({
+		query: gql`...`,
+		variables: {
+			first: CHARITIES_PER_PAGE,
+			offset: (page - 1) * CHARITIES_PER_PAGE,
+		},
+	});
+
+	// Subscribe to any data changes on the server
+	useSubscription({ query: allCharitiesSubscription });
+}
+```
+
+## Deployment
+
+1. Run `bun run build`
+2. `cd .output/server`
+3. `rm -rf node_modules`
+4. `bun install`
+5. `bun run index.mjs`

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@carvajalconsultants/headstart",
+  "version": "1.0.0",
+  "description": "Library to assist in integrating PostGraphile with Tanstack Start and URQL.",
+  "license": "MIT",
+  "author": "Miguel Carvajal <omar@carvajalonline.com>",
+  "repository": "github:carvajalconsultants/headstart",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "lint": "biome check --write"
+  },
+  "dependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@tanstack/start": "^1.100.0",
+    "postgraphile": "^5.0.0-beta.37",
+    "urql": "^4.2.1",
+    "vinxi": "^0.5.2"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.14",
+    "typescript": "^5.7.3"
+  }
+}

package/src/grafastExchange.ts

@@ -0,0 +1,93 @@
+import { execute, hookArgs } from "grafast";
+import {
+	CombinedError,
+	type Exchange,
+	type Operation,
+	type OperationResult,
+} from "urql";
+import { filter, fromPromise, mergeMap, pipe } from "wonka";
+
+import type { Maybe } from "grafast";
+import type { PostGraphileInstance } from "postgraphile";
+
+export const grafastExchange = (pgl: PostGraphileInstance): Exchange => {
+	return () => (ops$) => {
+		return pipe(
+			ops$,
+
+			// Skip anything that's not a query since that's all we can run
+			filter((operation) => operation.kind === "query"),
+
+			mergeMap((operation) => fromPromise(runGrafastQuery(pgl, operation))),
+		);
+	};
+};
+
+/**
+ * Run the URQL query with Grafast, without making an HTTP request to ourselves (which is unnecessary overhead).
+ *
+ * @param pgl Postgraphile instance that we will run the URQL query with.
+ * @param operation URQL operation, typically a query that will be run with Grafast.
+ * @returns Query data, which is used to pass along in the Exchange chain.
+ */
+const runGrafastQuery = async (
+	pgl: PostGraphileInstance,
+	operation: Operation,
+): Promise<OperationResult> => {
+	try {
+		const { variables: variableValues, query: document } = operation;
+
+		const args = {
+			resolvedPreset: pgl.getResolvedPreset(),
+			schema: await pgl.getSchema(),
+			document,
+			variableValues: variableValues as Maybe<{
+				readonly [variable: string]: unknown;
+			}>,
+		};
+		// Add the Graphile context to our args so Grafast can run
+		await hookArgs(args);
+
+		// Run the query with Grafast, to get the result from PostgreSQL
+		const result = await execute(args);
+
+		if (!result || typeof result !== "object" || !("data" in result)) {
+			throw new Error("Unexpected result format from execute");
+		}
+
+		const { data, errors, extensions } = result;
+
+		if (errors && errors.length > 0) {
+			return {
+				operation,
+				data,
+				error: new CombinedError({ graphQLErrors: [...errors] }),
+				extensions,
+				stale: false,
+				hasNext: false,
+			};
+		}
+
+		return {
+			operation,
+			data,
+			error: undefined,
+			extensions,
+			stale: false,
+			hasNext: false,
+		};
+	} catch (error) {
+		console.error("Error in runGrafastQuery:", error);
+
+		return {
+			operation,
+			data: undefined,
+			error: new CombinedError({
+				networkError: error instanceof Error ? error : new Error(String(error)),
+			}),
+			extensions: undefined,
+			stale: false,
+			hasNext: false,
+		};
+	}
+};

package/src/graphQLRouteHandler.ts

@@ -0,0 +1,112 @@
+import { CloseCode, makeServer } from "graphql-ws";
+import { makeGraphQLWSConfig } from "postgraphile/grafserv";
+import { grafserv } from "postgraphile/grafserv/h3/v1";
+import { defineEventHandler, getHeader, toWebRequest } from "vinxi/http";
+
+import type { IncomingMessage } from "node:http";
+import type { StartAPIHandlerCallback } from "@tanstack/start/api";
+import { type Hooks, type Peer, defineHooks } from "crossws";
+import type { GrafservBase } from "grafserv";
+import type { H3Grafserv } from "grafserv/h3/v1";
+import type { PostGraphileInstance } from "postgraphile";
+import type { WebSocket } from "ws";
+
+/**
+ * This is an H3 handler that does all of the GraphQL request processing in TSR (including Subscriptions).
+ *
+ * Code is basically from: https://discord.com/channels/489127045289476126/498852330754801666/1260251871877271704
+ */
+
+/**
+ * TODO: make it generic when crossws implements the WS API (Peer.close, Peer.protocol)
+ * instead of accessing the socket directly through context (server agnostic)
+ * https://github.com/unjs/crossws/issues/23
+ * https://github.com/unjs/crossws/issues/16
+ */
+function makeWsHandler(instance: H3Grafserv): Partial<Hooks> {
+	const graphqlWsServer = makeServer(makeGraphQLWSConfig(instance));
+
+	return {
+		open(peer) {
+			// TODO Getting the socket like this causes problems deploying to bun. We really need a better websocket implementation with crossws
+			// Websocket from the H3 instance, so this is the browser client
+			const socket = peer.websocket as Required<WebSocket>;
+
+			// a new socket opened, let graphql-ws take over
+			const closed = graphqlWsServer.opened(
+				{
+					protocol: socket.protocol, // will be validated
+					send: (data) =>
+						new Promise((resolve, reject) => {
+							socket.send(data, (err: Error) =>
+								err ? reject(err) : resolve(),
+							);
+						}),
+					close: (code, reason) => {
+						socket.close(code, reason);
+					},
+					onMessage: (cb) => {
+						socket.on("message", async (event) => {
+							try {
+								await cb(event.toString());
+							} catch (err) {
+								try {
+									socket.close(CloseCode.InternalServerError, err.message);
+								} catch {
+									// noop
+								}
+							}
+						});
+					},
+				},
+				// pass values to the `extra` field in the context
+				//{ peer, socket, request },
+				{},
+			);
+			// socket.once("close", (_socket, code: number, reason: Buffer) => closed(code, reason.toString()));
+		},
+	};
+}
+
+// Make sure this is not instantiated more than once
+let serv: GrafservBase;
+
+/**
+ * Actual H3 endpoint handler that intercepts requests to /api/graphql and processes with Postgraphile.
+ *
+ * @param pgl Postgraphile instance that has the connection to the database.
+ * @param cb Start API handler callback, usually defaultAPIFileRouteHandler from Start.
+ */
+export const createStartAPIHandler = (
+	pgl: PostGraphileInstance,
+	cb: StartAPIHandlerCallback,
+) => {
+	if (!serv) {
+		// Initialize Grafserv which is the one that actually processes the GraphQL requests.
+		serv = pgl.createServ(grafserv);
+	}
+
+	return defineEventHandler({
+		handler: async (event) => {
+			const request = toWebRequest(event);
+
+			// Sad interception until we can get the socket instance in the Tanstack Start API
+			if (request.url.indexOf("/api/graphql") > -1) {
+				const acceptHeader = getHeader(event, "accept");
+
+				if (acceptHeader === "text/event-stream") {
+					// SSE events are handled here
+					return serv.handleEventStreamEvent(event);
+				}
+
+				// Process query and mutation GraphQL requests here
+				return serv.handleGraphQLEvent(event);
+			}
+
+			return await cb({ request });
+		},
+
+		// Initialize the handler that manages WebSocket subscriptions
+		websocket: makeWsHandler(serv),
+	});
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./graphQLRouteHandler";
+export * from "./grafastExchange";
+export * from "./ssrExchange";

package/src/ssrExchange.ts

@@ -0,0 +1,16 @@
+import { ssrExchange } from "urql";
+
+const isServerSide = typeof window === "undefined";
+
+/**
+ * URQL Exchange for server-side rendering.
+ *
+ * It is used on the client and server.
+ *
+ * On the server, it rounds up the data so that it can be sent to the client to hydrate.
+ *
+ * On the client side, it assists in hydrating the data so we don't hit the server with data we already have.
+ */
+export const ssr = ssrExchange({
+	isClient: !isServerSide,
+});