@skgo/sveltekit-adapter 0.2.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyler Gannon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @skgo/sveltekit-adapter
+
+The SvelteKit adapter for [skgo](https://github.com/tylergannon/skgo), a
+SvelteKit application server written in Go.
+
+The app stays plain SvelteKit. This adapter builds it into the shape a skgo
+binary embeds: the client bundle, kit's SPA fallback document, the SSR bundle
+the Go process renders pages with, and a manifest naming the routes, remote
+functions and server loads Go must answer.
+
+```sh
+pnpm add -D "github:tylergannon/skgo#v0.2.0&path:internal/adapter"
+```
+
+The tag is the skgo version your `go.mod` requires; pnpm installs the package
+straight from that tag's `internal/adapter`. A project made by `skgo new` has
+this line already. When the package is on npm the spec becomes
+`pnpm add -D @skgo/sveltekit-adapter`.
+
+```js
+// vite.config.ts
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+import skgo from '@skgo/sveltekit-adapter';
+
+export default defineConfig({
+	plugins: [sveltekit({ adapter: skgo(), experimental: { remoteFunctions: true } })]
+});
+```
+
+The adapter and the Go module are one contract in two languages, released
+together under one version. Every build records which adapter wrote it, and a
+skgo binary refuses a build written by a different one, naming both — so an
+install that has fallen behind fails at startup with something a developer can
+act on rather than as an unrelated error later.
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,26 @@
+import { Adapter } from '@sveltejs/kit';
+
+interface AdapterOptions {
+	/**
+	 * The directory the build is written to, relative to the vite root. It
+	 * defaults to `build`, which is what the app's Go embeds.
+	 * @default 'build'
+	 */
+	out?: string;
+	/**
+	 * Whether to write gzip and brotli copies of the assets and the prerendered
+	 * pages beside them. The Go server serves whichever the browser asked for.
+	 * @default true
+	 */
+	precompress?: boolean;
+}
+
+/**
+ * The skgo adapter. It emits the client bundle, kit's SPA fallback document,
+ * the SSR bundle the Go process renders pages with, and the manifest naming
+ * what Go must answer.
+ *
+ * The manifest records which skgo this package is, and the Go that reads it
+ * refuses a build written by a different one, so the two halves cannot drift.
+ */
+export default function skgo(options?: AdapterOptions): Adapter;

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@skgo/sveltekit-adapter",
+	"version": "0.2.7",
+	"description": "SvelteKit adapter for skgo: builds a frontend that a Go binary renders and answers",
+	"keywords": [
+		"adapter",
+		"go",
+		"golang",
+		"skgo",
+		"svelte",
+		"sveltekit"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tylergannon/skgo.git",
+		"directory": "internal/adapter"
+	},
+	"license": "MIT",
+	"homepage": "https://github.com/tylergannon/skgo",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./skgo-adapter.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"types": "index.d.ts",
+	"files": [
+		"index.d.ts",
+		"skgo-adapter.js",
+		"skgo-adapter/app-paths.js",
+		"skgo-adapter/app-server.js",
+		"skgo-adapter/entry.js",
+		"skgo-adapter/env.js",
+		"skgo-adapter/identity.js",
+		"skgo-adapter/polyfill.js"
+	],
+	"peerDependencies": {
+		"@sveltejs/kit": "^3.0.0-next.0"
+	}
+}

package/skgo-adapter/app-paths.js

@@ -0,0 +1,40 @@
+// The `$app/paths` the SSR bundle sees.
+//
+// Like app-server.js, it is a module of the `goja` environment and of no
+// other: the adapter's plugin resolves `$app/paths` to this file only while
+// that environment is building, so kit's own `ssr` build keeps kit's module.
+//
+// `resolve` and `asset` are kit's own (runtime/app/paths/server.js),
+// unchanged — they are pure string logic over the app's compiled-in base and
+// assets path, needing nothing this engine lacks — and they arrive here by
+// re-export rather than by copy.
+//
+// `match` is the one substitution. Kit's own asks a manifest for the route,
+// through `get_hooks().reroute` and `manifest._.matchers()`/`find_route`
+// (utils/routing.js). Neither exists here: skgo does its own routing in Go,
+// and Go already owns the exact table every page, load and endpoint request
+// matches against, so building a second one for the engine would be the
+// reimplementation this project's own rules forbid. What is below mirrors
+// kit's own preparation of the pathname — decode it, strip the base — and
+// then asks Go for the match, the same way a query or a command asks Go to
+// run it.
+//
+// skgo has no reroute hook (Go does the routing, so `get_hooks` is always
+// `{}`) and no param matchers (a matcher is a JavaScript function and skgo
+// runs none — Loads.match and Endpoints.match both already match on the
+// pattern alone), so both of kit's other inputs to match() are empty in this
+// engine too, not just unavailable.
+import { asset, resolve, base } from 'skgo:kit/paths-server';
+import { decode_pathname } from 'skgo:kit/url';
+
+export { asset, resolve };
+
+export async function match(url) {
+	const target = typeof url === 'string' ? new URL(url, 'https://skgo.internal/') : url;
+	let pathname = decode_pathname(target.pathname);
+	if (base && pathname.startsWith(base)) {
+		pathname = pathname.slice(base.length) || '/';
+	}
+	const raw = globalThis.__skgo_match(pathname);
+	return JSON.parse(raw);
+}

package/skgo-adapter/app-server.js

@@ -0,0 +1,152 @@
+// The `$app/server` the SSR bundle sees.
+//
+// It is a module of the `goja` environment and of no other: the adapter's
+// plugin resolves `$app/server` to this file only while that environment is
+// building, so kit's `ssr` build — the one that prerenders — keeps kit's real
+// module. Substituting at source level is the whole reason the bundle is an
+// environment of kit's build rather than a pass over its output: once kit's
+// graph is linked, the boundary this file replaces no longer exists.
+//
+// Kit's own `query`/`command`/`form` wrappers are kept: the argument-keyed
+// cache, `state.remote.implicit`, the `<id>/<payload>` key, the rule that an
+// argument needs a validator, the refusal to run a command during a render and
+// the derived event whose `url`, `params` and `route` throw inside a query are
+// all kit's, unchanged. The only substitution is the user function body —
+// the generated stub that throws — which becomes a call into Go.
+//
+// That inversion is the proof: the generated `.remote.ts` still throws, and the
+// host binding is the only path by which a value can reach the engine.
+//
+// Everything this file does not name is kit's, by `export *`: `read`,
+// `getRequestEvent`, `prerender` and `requested` come from kit's own module,
+// and an export kit adds arrives without an edit here. An explicit export
+// below shadows the star, which is how the four substitutions take effect.
+import * as real from 'skgo:kit/remote';
+import { stringify_remote_arg } from 'skgo:kit/shared';
+import { HttpError, Redirect } from '@sveltejs/kit/internal/server';
+import { parse } from 'skgo:kit/transport';
+
+export * from 'skgo:kit/app-server';
+
+/**
+ * Calls Go asynchronously. Its I/O runs outside the runtime while other
+ * independent queries start; the runtime resumes when Go settles the promise.
+ *
+ * A refusal comes back as one of kit's own control objects rather than a bare
+ * Error, because everything downstream classifies by type: handle_error
+ * keeps an HttpError's body and replaces anything else with Internal Error,
+ * and transformError rethrows a Redirect so that the whole document becomes
+ * the 3xx kit answers with.
+ *
+ * The answer is devalue's flat form, the same bytes Go would have sent the
+ * browser from /_app/remote/..., and it is read back with kit's own parse —
+ * the app's transport decoders. So a query answering with a custom type hands
+ * the component an instance of the app's class, and a method call on it during
+ * a render works for the same reason it works in the browser.
+ */
+async function host(id, payload) {
+	const raw = await globalThis.__skgo_remote(id, payload);
+	const res = JSON.parse(raw);
+	if (res.r) {
+		throw new Redirect(res.r.status, res.r.location);
+	}
+	if (res.e) {
+		throw new HttpError({ status: res.e.status ?? 500, message: res.e.message });
+	}
+	return parse(res.v);
+}
+
+export function query(validate_or_fn, maybe_fn) {
+	const fn = (arg) => host(wrapper.__.id, stringify_remote_arg(arg));
+	const wrapper = maybe_fn ? real.query(validate_or_fn, fn) : real.query(fn);
+	return wrapper;
+}
+
+/**
+ * Calls Go once for a whole batch. Kit's own enqueue has already collected
+ * every call made to this function in one macrotask and deduplicated them by
+ * payload, so args is the batch — and the app's Go function is invoked once
+ * for all of it, which is the only thing that makes a batch query different
+ * from a query.
+ *
+ * The payloads travel as a JSON array in the place a single payload would
+ * occupy, and the answer is {n: [...]} — one envelope per payload, in the
+ * order they were sent, which is the order kit's client matches results to
+ * arguments by.
+ */
+async function host_batch(id, args) {
+	const payloads = args.map((arg) => stringify_remote_arg(arg));
+	const raw = await globalThis.__skgo_remote(id, JSON.stringify(payloads));
+	const res = JSON.parse(raw);
+	if (res.r) {
+		throw new Redirect(res.r.status, res.r.location);
+	}
+	if (res.e) {
+		throw new HttpError({ status: res.e.status ?? 500, message: res.e.message });
+	}
+	const nodes = res.n ?? [];
+	return (_arg, i) => {
+		const node = nodes[i];
+		if (!node) {
+			throw new HttpError({ status: 500, message: 'Internal Error' });
+		}
+		if (node.e) {
+			throw new HttpError({ status: node.e.status ?? 500, message: node.e.message });
+		}
+		return parse(node.v);
+	};
+}
+
+query.batch = (validate_or_fn, maybe_fn) => {
+	const fn = (args) => host_batch(wrapper.__.id, args);
+	const wrapper = maybe_fn ? real.query.batch(validate_or_fn, fn) : real.query.batch(fn);
+	return wrapper;
+};
+
+query.live = (validate_or_fn, maybe_fn) => {
+	// A live query awaited during a render resolves to its first value, which is
+	// what kit's get_first_value takes from the generator before closing it.
+	// Go drives the producer far enough to yield once and answers with that, so
+	// the value is in the markup before any script runs; the stream itself is
+	// the browser's, and it opens after hydration against the same endpoint.
+	//
+	// An asynchronous iterator: the first value waits for Go, and Kit closes
+	// the iterator after consuming it during SSR.
+	const fn = (arg) => {
+		const payload = stringify_remote_arg(arg);
+		let taken = false;
+		return {
+			next: async () => {
+				if (taken) return { value: undefined, done: true };
+				taken = true;
+				return { value: await host(wrapper.__.id, payload), done: false };
+			},
+			return: () => ({ value: undefined, done: true })
+		};
+	};
+	const wrapper = maybe_fn ? real.query.live(validate_or_fn, fn) : real.query.live(fn);
+	return wrapper;
+};
+
+export function command(validate_or_fn, maybe_fn) {
+	const fn = (arg) => host(wrapper.__.id, stringify_remote_arg(arg));
+	const wrapper = maybe_fn ? real.command(validate_or_fn, fn) : real.command(fn);
+	return wrapper;
+}
+
+/**
+ * Kit's own form wrapper, with the instance kept so that a submission the
+ * browser posted without JavaScript can be put back where the instance reads
+ * it.
+ *
+ * The generated stub still throws — Go runs the handler, not this module — so
+ * the register below never runs a form body. It only records which object is
+ * which, because the internals' id is assigned by the epilogue the bundler
+ * appends after this module has been evaluated, and that id is the only handle
+ * Go has.
+ */
+export function form(validate_or_fn, maybe_fn) {
+	const wrapper = maybe_fn === undefined ? real.form(validate_or_fn) : real.form(validate_or_fn, maybe_fn);
+	(globalThis.__skgo_forms ??= []).push(wrapper);
+	return wrapper;
+}