bunderstack-start 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirill Chuprov
+
+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,28 @@
+# bunderstack-start
+
+TanStack Start integration for
+[bunderstack](https://github.com/kirill-dev-pro/bunderstack): isomorphic
+fetch wiring, auth client, and query/sync setup for SSR apps.
+
+```sh
+bun add bunderstack-start
+```
+
+Full documentation and examples:
+[github.com/kirill-dev-pro/bunderstack](https://github.com/kirill-dev-pro/bunderstack)
+
+## Shipping TypeScript source
+
+This package publishes raw TypeScript (`exports` point at `.ts` files). Bun
+consumes it natively. If a Node-based bundler or SSR server processes it,
+make sure the package is bundled rather than externalized — e.g. in Vite:
+
+```ts
+ssr: {
+  noExternal: [/^bunderstack/]
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "bunderstack-start",
+  "version": "0.1.0",
+  "description": "TanStack Start integration for bunderstack: isomorphic fetch wiring, auth client, and query/sync setup for SSR apps.",
+  "keywords": [
+    "auth",
+    "bun",
+    "bunderstack",
+    "react",
+    "ssr",
+    "tanstack-start"
+  ],
+  "homepage": "https://github.com/kirill-dev-pro/bunderstack#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kirill-dev-pro/bunderstack.git",
+    "directory": "packages/bunderstack-start"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "bunderstack-query": "0.1.0",
+    "bunderstack-sync": "0.1.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.101.1",
+    "@tanstack/react-start": "^1.168.26",
+    "@types/bun": "^1.3.14",
+    "better-auth": "^1.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-start": ">=1.0.0",
+    "better-auth": "^1.0.0",
+    "typescript": "^5"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    }
+  }
+}

package/src/auth-client.ts

@@ -0,0 +1,16 @@
+import { createAuthClient } from 'better-auth/react'
+
+/**
+ * BetterAuth browser client pointed at the Bunderstack handler's
+ * /api/auth/* routes. Defaults to the current origin in the browser and
+ * APP_URL (or localhost:3000) during SSR.
+ */
+export function createStartAuthClient(options: { baseURL?: string } = {}) {
+  return createAuthClient({
+    baseURL:
+      options.baseURL ??
+      (typeof window !== 'undefined'
+        ? window.location.origin
+        : (process.env.APP_URL ?? 'http://localhost:3000')),
+  })
+}

package/src/index.ts

@@ -0,0 +1,99 @@
+import { QueryClient } from '@tanstack/react-query'
+import {
+  createSyncClient,
+  type AnyBunderstackApp,
+  type BunderstackSyncClient,
+} from 'bunderstack-sync'
+
+import { createIsomorphicFetch } from './isomorphic-fetch'
+
+export { createIsomorphicFetch } from './isomorphic-fetch'
+export { createStartAuthClient } from './auth-client'
+
+export type BunderstackStartOptions = {
+  /** API mount point. Defaults to '/api'. */
+  baseUrl?: string
+  /** Default query staleTime (ms). Defaults to 30_000. */
+  staleTime?: number
+}
+
+/**
+ * One-call client setup for TanStack Start apps: SSR-aware fetch, sensible
+ * QueryClient defaults, and a sync client whose tables and buckets are
+ * inferred from the server app type.
+ *
+ * @example
+ * // src/api.ts — NOT src/client.ts, which is a reserved TanStack Start
+ * // entry-point name (it would replace the hydration entry).
+ * import type { App } from './bunderstack'
+ * export const { createQueryClient, createApi } = bunderstackStart<App>()
+ */
+export function bunderstackStart<TApp extends AnyBunderstackApp>(
+  options: BunderstackStartOptions = {},
+) {
+  const isoFetch = createIsomorphicFetch()
+  return {
+    createQueryClient: () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: { staleTime: options.staleTime ?? 30_000 },
+        },
+      }),
+    createApi: (queryClient: QueryClient): BunderstackSyncClient<TApp> =>
+      createSyncClient<TApp>({
+        queryClient,
+        fetch: isoFetch,
+        baseUrl: options.baseUrl,
+      }),
+  }
+}
+
+type StartRequestContext = { request: Request }
+type StartHandler = (ctx: StartRequestContext) => Promise<Response>
+
+/**
+ * Handlers object for the catch-all API file route.
+ *
+ * @example
+ * // src/routes/api/$.tsx
+ * export const Route = createFileRoute('/api/$')({
+ *   server: { handlers: createApiHandlers(app) },
+ * })
+ */
+export function createApiHandlers(app: {
+  handler: (req: Request) => Promise<Response>
+}): {
+  GET: StartHandler
+  POST: StartHandler
+  PATCH: StartHandler
+  DELETE: StartHandler
+} {
+  const handle: StartHandler = ({ request }) => app.handler(request)
+  return { GET: handle, POST: handle, PATCH: handle, DELETE: handle }
+}
+
+export type SessionUser = {
+  id: string
+  email: string
+  name: string
+  image?: string | null
+}
+
+type SessionApp = {
+  auth: {
+    api: {
+      getSession: (opts: {
+        headers: Headers
+      }) => Promise<{ user: SessionUser | null } | null>
+    }
+  }
+}
+
+/** Resolve the BetterAuth session user for an incoming request (server-side). */
+export async function getSessionUser(
+  app: SessionApp,
+  request: Request,
+): Promise<SessionUser | null> {
+  const session = await app.auth.api.getSession({ headers: request.headers })
+  return session?.user ?? null
+}

package/src/isomorphic-fetch.ts

@@ -0,0 +1,36 @@
+/**
+ * SSR-aware fetch: the browser passes `/api/...` through as-is; on the
+ * server, relative URLs are resolved against the incoming request's origin
+ * (via @tanstack/react-start/server), falling back to APP_URL /
+ * BETTER_AUTH_URL / localhost:3000 outside a request context.
+ *
+ * The dynamic import is marked vite-ignore so client bundles never try to
+ * resolve the server-only module; the `window` guard means it never runs
+ * there either.
+ */
+export function createIsomorphicFetch(options: { fetch?: typeof fetch } = {}) {
+  const inner = options.fetch ?? fetch
+  return async function isomorphicFetch(
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> {
+    if (typeof window !== 'undefined') return inner(input, init)
+    if (typeof input === 'string' && input.startsWith('/')) {
+      let origin: string | undefined
+      try {
+        const mod = await import(
+          /* @vite-ignore */ '@tanstack/react-start/server'
+        )
+        origin = new URL(mod.getRequest().url).origin
+      } catch {
+        // No request context (background job, test) — fall through to env.
+      }
+      origin ??=
+        process.env.APP_URL ??
+        process.env.BETTER_AUTH_URL ??
+        'http://localhost:3000'
+      return inner(new URL(input, origin), init)
+    }
+    return inner(input, init)
+  }
+}