From 4495d5a13d81258885f1dc089fb719e855308af5 Mon Sep 17 00:00:00 2001
From: Hermes Agent <hermes-agent@local.invalid>
Date: Tue, 12 May 2026 00:05:14 -0600
Subject: [PATCH] docs: add SvelteKit backend instrumentation guide

---
 docs-content/getting-started/1_overview.md    |   3 +
 .../fullstack-frameworks/sveltekit.md         | 144 ++++++++++++++++++
 2 files changed, 147 insertions(+)
 create mode 100644 docs-content/getting-started/fullstack-frameworks/sveltekit.md

diff --git a/docs-content/getting-started/1_overview.md b/docs-content/getting-started/1_overview.md
index ebc52c8..473113b 100644
--- a/docs-content/getting-started/1_overview.md
+++ b/docs-content/getting-started/1_overview.md
@@ -33,6 +33,9 @@ Installing highlight.io in javascript will automatically instrument frontend err
     <DocsCard title="SvelteKit"  href="./browser/6_sveltekit.md">
         {"Get started in your SvelteKit app"}
     </DocsCard>
+    <DocsCard title="SvelteKit Fullstack"  href="./fullstack-frameworks/sveltekit.md">
+        {"Get full-stack SvelteKit session replay, errors, logs, and traces"}
+    </DocsCard>
     <DocsCard title="Electron"  href="./browser/7_electron.md">
         {"Get started in your Electron app"}
     </DocsCard>
diff --git a/docs-content/getting-started/fullstack-frameworks/sveltekit.md b/docs-content/getting-started/fullstack-frameworks/sveltekit.md
new file mode 100644
index 0000000..507fbb5
--- /dev/null
+++ b/docs-content/getting-started/fullstack-frameworks/sveltekit.md
@@ -0,0 +1,144 @@
+---
+toc: SvelteKit
+title: SvelteKit Fullstack Walkthrough
+slug: sveltekit
+createdAt: 2026-05-12T00:00:00.000Z
+updatedAt: 2026-05-12T00:00:00.000Z
+---
+
+## Overview
+
+Use the browser SDK for SvelteKit session replay and client-side errors, then initialize the Node.js SDK in SvelteKit's server hooks so server-side errors, logs, and traces can be connected back to the same Highlight session.
+
+1. Initialize `highlight.run` in `hooks.client.ts`.
+2. Initialize `@highlight-run/node` in `hooks.server.ts`.
+3. Wrap requests with Highlight headers so server spans and errors are associated with frontend sessions.
+4. Export `handleError` to report SvelteKit server errors.
+
+## Installation
+
+```shell
+# with npm
+npm install highlight.run @highlight-run/node
+
+# with yarn
+yarn add highlight.run @highlight-run/node
+
+# with pnpm
+pnpm add highlight.run @highlight-run/node
+```
+
+## Client instrumentation
+
+Initialize the browser SDK in `src/hooks.client.ts`. Set `tracingOrigins` and `networkRecording` so Highlight can attach request headers that connect browser sessions to backend traces and errors.
+
+```typescript
+// src/hooks.client.ts
+import { H } from 'highlight.run'
+
+H.init('<YOUR_PROJECT_ID>', {
+	environment: 'production',
+	version: 'commit:abcdefg12345',
+	serviceName: 'sveltekit-client',
+	tracingOrigins: true,
+	networkRecording: {
+		enabled: true,
+		recordHeadersAndBody: true,
+	},
+})
+```
+
+See [Fullstack Mapping](https://www.highlight.io/docs/getting-started/frontend-backend-mapping) for details about connecting frontend requests with backend errors and traces.
+
+## Server instrumentation
+
+Initialize the Node.js SDK once from `src/hooks.server.ts`. Use `handle` to wrap each SvelteKit request with Highlight's request headers, and use `handleError` to report exceptions thrown while rendering pages or running server `load` functions, actions, and endpoints.
+
+```typescript
+// src/hooks.server.ts
+import type { Handle, HandleServerError } from '@sveltejs/kit'
+import { H } from '@highlight-run/node'
+
+H.init({
+	projectID: '<YOUR_PROJECT_ID>',
+	serviceName: 'sveltekit-server',
+	environment: 'production',
+})
+
+export const handle: Handle = async ({ event, resolve }) => {
+	return H.runWithHeaders(Object.fromEntries(event.request.headers), async () => {
+		const { span } = H.startWithHeaders('sveltekit.request', {
+			'http.method': event.request.method,
+			'http.url': event.url.toString(),
+			'sveltekit.route.id': event.route.id ?? 'unknown',
+		})
+
+		try {
+			return await resolve(event)
+		} finally {
+			span.end()
+		}
+	})
+}
+
+export const handleError: HandleServerError = ({ error, event }) => {
+	const parsed = H.parseHeaders(Object.fromEntries(event.request.headers))
+
+	if (error instanceof Error) {
+		H.consumeError(error, parsed?.secureSessionId, parsed?.requestId)
+	} else {
+		H.consumeError(
+			new Error(`Unknown SvelteKit error: ${JSON.stringify(error)}`),
+			parsed?.secureSessionId,
+			parsed?.requestId,
+		)
+	}
+}
+```
+
+If you already have a `handle` hook, keep your existing logic inside the `H.runWithHeaders` callback or use SvelteKit's `sequence` helper to compose hooks.
+
+```typescript
+// src/hooks.server.ts
+import { sequence } from '@sveltejs/kit/hooks'
+import type { Handle } from '@sveltejs/kit'
+import { H } from '@highlight-run/node'
+
+const highlightHandle: Handle = async ({ event, resolve }) =>
+	H.runWithHeaders(Object.fromEntries(event.request.headers), () => resolve(event))
+
+const authHandle: Handle = async ({ event, resolve }) => {
+	// Your existing auth/session logic.
+	return resolve(event)
+}
+
+export const handle = sequence(highlightHandle, authHandle)
+```
+
+## Reporting manual server errors
+
+For errors caught inside a server `load`, form action, endpoint, or helper, parse the incoming request headers and pass the session identifiers to `H.consumeError`.
+
+```typescript
+import { H } from '@highlight-run/node'
+
+export async function load({ request }) {
+	try {
+		// server-side work
+	} catch (error) {
+		const parsed = H.parseHeaders(Object.fromEntries(request.headers))
+		if (error instanceof Error) {
+			H.consumeError(error, parsed?.secureSessionId, parsed?.requestId)
+		}
+		throw error
+	}
+}
+```
+
+## Verify the setup
+
+1. Visit a page in your SvelteKit app and confirm a session appears in Highlight.
+2. Trigger a server-side error from a `load` function, action, or endpoint.
+3. Confirm the error appears in [Highlight Errors](https://app.highlight.io/errors).
+4. Confirm the server error is linked to the same frontend session replay when the request includes Highlight tracing headers.
+5. Check [Highlight Traces](https://app.highlight.io/traces) for the `sveltekit-server` service and request spans.
-- 
2.43.0