@formadapter/tanstack-start 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ludicrous
+
+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,93 @@
+# `@formadapter/tanstack-start`
+
+TanStack Start server-function integration for FormAdapter. It connects a
+FormAdapter `onSubmit` callback to a POST server function while keeping parsing,
+schema validation, and structured submission errors in `@formadapter/server`.
+
+```sh
+bun add @formadapter/tanstack-start @formadapter/server @tanstack/react-start
+```
+
+## Server function
+
+Build the reusable submission first, then place the thin TanStack Start boundary
+around it:
+
+```ts
+import { createServerFn } from "@tanstack/react-start";
+import { createSubmissionHandler } from "@formadapter/server";
+import {
+  formDataValidator,
+  tanstackStartHandler,
+} from "@formadapter/tanstack-start/server";
+import { profileSchema } from "./profile-schema";
+
+const submission = createSubmissionHandler(
+  profileSchema,
+  async (profile) => database.profile.save(profile),
+  { config: profileConfig },
+);
+
+export const saveProfile = createServerFn({ method: "POST" })
+  .validator(formDataValidator)
+  .handler(tanstackStartHandler(submission));
+```
+
+`formDataValidator` only verifies the transport shape. The reusable submission
+performs authoritative schema and presentation-rule validation so failures come
+back as FormAdapter's shared `SubmissionState` instead of escaping TanStack
+Start's validator as generic errors. Pass the same form config when conditional
+`hidden` or `requiredWhenVisible` rules must also be enforced on the server.
+
+TanStack's handler context is forwarded into the submission context. Middleware
+auth data is available as `context.context`; `method` and `serverFnMeta` are
+preserved too. Treat that data as request context, and still perform
+authorization in the business handler.
+
+Use `createSubmissionHandlerFactory<TanStackStartSubmissionContext<AuthContext>>()`
+when the business callback needs that middleware context inferred. The returned
+context-bound submission requires its invocation context, and
+`tanstackStartHandler` always supplies it.
+
+## Client form
+
+Use the hook in the client component that renders the form:
+
+```tsx
+"use client";
+
+import { useTanStackStartSubmission } from "@formadapter/tanstack-start";
+import { Profile } from "./profile-form";
+import { saveProfile } from "./profile.functions";
+
+export function ProfileEditor() {
+  const onSubmit = useTanStackStartSubmission(saveProfile);
+  return <Profile.Form onSubmit={onSubmit} />;
+}
+```
+
+The hook calls TanStack Start's redirect-aware `useServerFn`, sends the form's
+schema-aware `context.formData`, forwards its `AbortSignal`, and returns the
+server's shared submission state. Options can supply static/dynamic headers, a
+custom fetch implementation, or an alternate `FormData` value. GET server
+functions are rejected because submissions require POST.
+
+`UseTanStackStartSubmissionOptions<Values, Input>` types the `headers` and
+`getFormData` customization callbacks without changing server-result inference.
+
+Client and server exports are intentionally separate. The package root and
+`/client` contain the hook; `/server` contains only the validator and handler
+adapter, so server integration code cannot leak into the client entry.
+
+## Progressive enhancement
+
+TanStack Start exposes a server function's `.url` for raw HTML form actions.
+`useTanStackStartSubmission` copies that URL from the original server function
+onto the returned handler and exposes `{ url, method, encType }` as `metadata`.
+TanStack's `useServerFn` callback itself does not retain this property.
+
+The hook remains a JavaScript-enhanced submission path. Posting a raw HTML form
+to `.url` can provide no-JavaScript transport, but FormAdapter's client-side
+state mapping and inline structured errors do not run in that mode. Applications
+that require full progressive enhancement should design the raw response and
+redirect/error experience explicitly instead of assuming hook behavior applies.

package/dist/client.d.ts

@@ -0,0 +1,46 @@
+import { SubmissionState } from "@formadapter/core";
+
+//#region src/client.d.ts
+interface FormAdapterSubmissionContext<Input = unknown> {
+  readonly input: Input;
+  readonly formData: FormData;
+  readonly signal: AbortSignal;
+}
+interface TanStackStartCallOptions {
+  readonly data: FormData;
+  readonly signal?: AbortSignal;
+  readonly headers?: HeadersInit;
+  readonly fetch?: typeof fetch;
+}
+/** The stable public surface used from a TanStack Start server function. */
+type TanStackStartServerFn<Result extends SubmissionState = SubmissionState> = ((options: TanStackStartCallOptions) => Promise<Result>) & {
+  readonly url: string;
+  readonly method?: "GET" | "POST";
+};
+interface TanStackStartSubmissionMetadata {
+  readonly url: string;
+  readonly method: "post";
+  readonly encType: "multipart/form-data";
+}
+type HeadersOption<Values = unknown, Input = unknown> = HeadersInit | ((values: Values, context: FormAdapterSubmissionContext<Input>) => HeadersInit | undefined);
+interface UseTanStackStartSubmissionOptions<Values = unknown, Input = unknown> {
+  /** Override the FormData sent to the server function. */
+  readonly getFormData?: (values: Values, context: FormAdapterSubmissionContext<Input>) => FormData;
+  readonly headers?: HeadersOption<Values, Input>;
+  readonly fetch?: typeof fetch;
+}
+type TanStackStartSubmissionHandler<Result extends SubmissionState = SubmissionState, Values = unknown, Input = unknown> = ((values: Values, context: FormAdapterSubmissionContext<Input>) => Promise<Result>) & {
+  /** Copied from the original server function, not the useServerFn callback. */readonly url: string;
+  readonly metadata: TanStackStartSubmissionMetadata;
+};
+declare function getTanStackStartSubmissionMetadata(serverFn: {
+  readonly url: string;
+}): TanStackStartSubmissionMetadata;
+/**
+* Creates a FormAdapter `onSubmit` handler backed by TanStack Start's
+* redirect-aware `useServerFn` invocation.
+*/
+declare function useTanStackStartSubmission<Result extends SubmissionState, Values = unknown, Input = unknown>(serverFn: TanStackStartServerFn<Result>, options?: UseTanStackStartSubmissionOptions<Values, Input>): TanStackStartSubmissionHandler<Result, Values, Input>;
+//#endregion
+export { FormAdapterSubmissionContext, TanStackStartCallOptions, TanStackStartServerFn, TanStackStartSubmissionHandler, TanStackStartSubmissionMetadata, UseTanStackStartSubmissionOptions, getTanStackStartSubmissionMetadata, useTanStackStartSubmission };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,48 @@
+"use client";
+import { useCallback, useMemo } from "react";
+import { useServerFn } from "@tanstack/react-start";
+//#region src/client.ts
+function getTanStackStartSubmissionMetadata(serverFn) {
+	return {
+		encType: "multipart/form-data",
+		method: "post",
+		url: serverFn.url
+	};
+}
+/**
+* Creates a FormAdapter `onSubmit` handler backed by TanStack Start's
+* redirect-aware `useServerFn` invocation.
+*/
+function useTanStackStartSubmission(serverFn, options = {}) {
+	if (serverFn.method !== void 0 && serverFn.method !== "POST") throw new Error("FormAdapter submissions require a TanStack Start POST server function.");
+	const invoke = useServerFn(serverFn);
+	const url = serverFn.url;
+	const { fetch: customFetch, getFormData, headers } = options;
+	const submit = useCallback(async (values, context) => {
+		const resolvedHeaders = typeof headers === "function" ? headers(values, context) : headers;
+		return invoke({
+			data: getFormData?.(values, context) ?? context.formData,
+			signal: context.signal,
+			...resolvedHeaders !== void 0 ? { headers: resolvedHeaders } : {},
+			...customFetch !== void 0 ? { fetch: customFetch } : {}
+		});
+	}, [
+		customFetch,
+		getFormData,
+		headers,
+		invoke
+	]);
+	const metadata = useMemo(() => getTanStackStartSubmissionMetadata({ url }), [url]);
+	return useMemo(() => Object.assign(submit, {
+		metadata,
+		url
+	}), [
+		metadata,
+		submit,
+		url
+	]);
+}
+//#endregion
+export { getTanStackStartSubmissionMetadata, useTanStackStartSubmission };
+
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["\"use client\";\n\nimport {\n  useCallback,\n  useMemo,\n} from \"react\";\nimport { useServerFn } from \"@tanstack/react-start\";\n\nimport type { SubmissionState } from \"@formadapter/core\";\n\nexport interface FormAdapterSubmissionContext<Input = unknown> {\n  readonly input: Input;\n  readonly formData: FormData;\n  readonly signal: AbortSignal;\n}\n\nexport interface TanStackStartCallOptions {\n  readonly data: FormData;\n  readonly signal?: AbortSignal;\n  readonly headers?: HeadersInit;\n  readonly fetch?: typeof fetch;\n}\n\n/** The stable public surface used from a TanStack Start server function. */\nexport type TanStackStartServerFn<\n  Result extends SubmissionState = SubmissionState,\n> = ((options: TanStackStartCallOptions) => Promise<Result>) & {\n  readonly url: string;\n  readonly method?: \"GET\" | \"POST\";\n};\n\nexport interface TanStackStartSubmissionMetadata {\n  readonly url: string;\n  readonly method: \"post\";\n  readonly encType: \"multipart/form-data\";\n}\n\ntype HeadersOption<Values = unknown, Input = unknown> =\n  | HeadersInit\n  | ((\n      values: Values,\n      context: FormAdapterSubmissionContext<Input>,\n    ) => HeadersInit | undefined);\n\nexport interface UseTanStackStartSubmissionOptions<\n  Values = unknown,\n  Input = unknown,\n> {\n  /** Override the FormData sent to the server function. */\n  readonly getFormData?: (\n    values: Values,\n    context: FormAdapterSubmissionContext<Input>,\n  ) => FormData;\n  readonly headers?: HeadersOption<Values, Input>;\n  readonly fetch?: typeof fetch;\n}\n\nexport type TanStackStartSubmissionHandler<\n  Result extends SubmissionState = SubmissionState,\n  Values = unknown,\n  Input = unknown,\n> = ((\n  values: Values,\n  context: FormAdapterSubmissionContext<Input>,\n) => Promise<Result>) & {\n  /** Copied from the original server function, not the useServerFn callback. */\n  readonly url: string;\n  readonly metadata: TanStackStartSubmissionMetadata;\n};\n\nexport function getTanStackStartSubmissionMetadata(\n  serverFn: { readonly url: string },\n): TanStackStartSubmissionMetadata {\n  return {\n    encType: \"multipart/form-data\",\n    method: \"post\",\n    url: serverFn.url,\n  };\n}\n\n/**\n * Creates a FormAdapter `onSubmit` handler backed by TanStack Start's\n * redirect-aware `useServerFn` invocation.\n */\nexport function useTanStackStartSubmission<\n  Result extends SubmissionState,\n  Values = unknown,\n  Input = unknown,\n>(\n  serverFn: TanStackStartServerFn<Result>,\n  options: UseTanStackStartSubmissionOptions<Values, Input> = {},\n): TanStackStartSubmissionHandler<Result, Values, Input> {\n  if (serverFn.method !== undefined && serverFn.method !== \"POST\") {\n    throw new Error(\n      \"FormAdapter submissions require a TanStack Start POST server function.\",\n    );\n  }\n\n  const invoke = useServerFn(serverFn);\n  const url = serverFn.url;\n  const { fetch: customFetch, getFormData, headers } = options;\n  const submit = useCallback(\n    async (\n      values: Values,\n      context: FormAdapterSubmissionContext<Input>,\n    ): Promise<Result> => {\n      const resolvedHeaders = typeof headers === \"function\"\n        ? headers(values, context)\n        : headers;\n      const call: TanStackStartCallOptions = {\n        data: getFormData?.(values, context) ?? context.formData,\n        signal: context.signal,\n        ...(resolvedHeaders !== undefined ? { headers: resolvedHeaders } : {}),\n        ...(customFetch !== undefined ? { fetch: customFetch } : {}),\n      };\n      return invoke(call);\n    },\n    [customFetch, getFormData, headers, invoke],\n  );\n  const metadata = useMemo(\n    () => getTanStackStartSubmissionMetadata({ url }),\n    [url],\n  );\n\n  return useMemo(\n    () => Object.assign(submit, { metadata, url }),\n    [metadata, submit, url],\n  );\n}\n"],"mappings":";;;;AAsEA,SAAgB,mCACd,UACiC;AACjC,QAAO;EACL,SAAS;EACT,QAAQ;EACR,KAAK,SAAS;EACf;;;;;;AAOH,SAAgB,2BAKd,UACA,UAA4D,EAAE,EACP;AACvD,KAAI,SAAS,WAAW,KAAA,KAAa,SAAS,WAAW,OACvD,OAAM,IAAI,MACR,yEACD;CAGH,MAAM,SAAS,YAAY,SAAS;CACpC,MAAM,MAAM,SAAS;CACrB,MAAM,EAAE,OAAO,aAAa,aAAa,YAAY;CACrD,MAAM,SAAS,YACb,OACE,QACA,YACoB;EACpB,MAAM,kBAAkB,OAAO,YAAY,aACvC,QAAQ,QAAQ,QAAQ,GACxB;AAOJ,SAAO,OAAO;GALZ,MAAM,cAAc,QAAQ,QAAQ,IAAI,QAAQ;GAChD,QAAQ,QAAQ;GAChB,GAAI,oBAAoB,KAAA,IAAY,EAAE,SAAS,iBAAiB,GAAG,EAAE;GACrE,GAAI,gBAAgB,KAAA,IAAY,EAAE,OAAO,aAAa,GAAG,EAAE;GAE3C,CAAC;IAErB;EAAC;EAAa;EAAa;EAAS;EAAO,CAC5C;CACD,MAAM,WAAW,cACT,mCAAmC,EAAE,KAAK,CAAC,EACjD,CAAC,IAAI,CACN;AAED,QAAO,cACC,OAAO,OAAO,QAAQ;EAAE;EAAU;EAAK,CAAC,EAC9C;EAAC;EAAU;EAAQ;EAAI,CACxB"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { FormAdapterSubmissionContext, TanStackStartCallOptions, TanStackStartServerFn, TanStackStartSubmissionHandler, TanStackStartSubmissionMetadata, UseTanStackStartSubmissionOptions, getTanStackStartSubmissionMetadata, useTanStackStartSubmission } from "./client.js";
+export { type FormAdapterSubmissionContext, type TanStackStartCallOptions, type TanStackStartServerFn, type TanStackStartSubmissionHandler, type TanStackStartSubmissionMetadata, type UseTanStackStartSubmissionOptions, getTanStackStartSubmissionMetadata, useTanStackStartSubmission };

package/dist/index.js

@@ -0,0 +1,3 @@
+"use client";
+import { getTanStackStartSubmissionMetadata, useTanStackStartSubmission } from "./client.js";
+export { getTanStackStartSubmissionMetadata, useTanStackStartSubmission };

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+import { SubmissionState } from "@formadapter/core";
+
+//#region src/server.d.ts
+interface TanStackStartHandlerContext<Context = unknown> {
+  readonly data: FormData;
+  readonly context: Context;
+  readonly method: "POST";
+  readonly serverFnMeta: unknown;
+}
+type TanStackStartSubmissionContext<Context = unknown> = Omit<TanStackStartHandlerContext<Context>, "data">;
+/** Structural shape of a prebuilt `@formadapter/server` submission. */
+type FormAdapterSubmission<Result extends SubmissionState = SubmissionState, Context = unknown> = (payload: unknown, context: TanStackStartSubmissionContext<Context>) => Promise<Result>;
+type TanStackStartHandler<Result extends SubmissionState = SubmissionState, Context = unknown> = (context: TanStackStartHandlerContext<Context>) => Promise<Result>;
+/** A canonical TanStack Start `.validator(...)` for POSTed FormData. */
+declare function formDataValidator(data: FormData): FormData;
+/**
+* Adapts a prebuilt FormAdapter submission to a TanStack Start `.handler(...)`.
+* The remaining TanStack handler context is forwarded structurally as the
+* submission's optional second argument.
+*/
+declare function tanstackStartHandler<Result extends SubmissionState, Context = unknown>(submission: FormAdapterSubmission<Result, Context>): TanStackStartHandler<Result, Context>;
+//#endregion
+export { FormAdapterSubmission, TanStackStartHandler, TanStackStartHandlerContext, TanStackStartSubmissionContext, formDataValidator, tanstackStartHandler };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,18 @@
+//#region src/server.ts
+/** A canonical TanStack Start `.validator(...)` for POSTed FormData. */
+function formDataValidator(data) {
+	if (typeof FormData === "undefined" || !(data instanceof FormData)) throw new TypeError("Expected FormData from a TanStack Start POST server function.");
+	return data;
+}
+/**
+* Adapts a prebuilt FormAdapter submission to a TanStack Start `.handler(...)`.
+* The remaining TanStack handler context is forwarded structurally as the
+* submission's optional second argument.
+*/
+function tanstackStartHandler(submission) {
+	return async ({ data, ...context }) => submission(data, context);
+}
+//#endregion
+export { formDataValidator, tanstackStartHandler };
+
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["import type { SubmissionState } from \"@formadapter/core\";\n\nexport interface TanStackStartHandlerContext<Context = unknown> {\n  readonly data: FormData;\n  readonly context: Context;\n  readonly method: \"POST\";\n  readonly serverFnMeta: unknown;\n}\n\nexport type TanStackStartSubmissionContext<Context = unknown> = Omit<\n  TanStackStartHandlerContext<Context>,\n  \"data\"\n>;\n\n/** Structural shape of a prebuilt `@formadapter/server` submission. */\nexport type FormAdapterSubmission<\n  Result extends SubmissionState = SubmissionState,\n  Context = unknown,\n> = (\n  payload: unknown,\n  context: TanStackStartSubmissionContext<Context>,\n) => Promise<Result>;\n\nexport type TanStackStartHandler<\n  Result extends SubmissionState = SubmissionState,\n  Context = unknown,\n> = (context: TanStackStartHandlerContext<Context>) => Promise<Result>;\n\n/** A canonical TanStack Start `.validator(...)` for POSTed FormData. */\nexport function formDataValidator(data: FormData): FormData {\n  if (typeof FormData === \"undefined\" || !(data instanceof FormData)) {\n    throw new TypeError(\"Expected FormData from a TanStack Start POST server function.\");\n  }\n  return data;\n}\n\n/**\n * Adapts a prebuilt FormAdapter submission to a TanStack Start `.handler(...)`.\n * The remaining TanStack handler context is forwarded structurally as the\n * submission's optional second argument.\n */\nexport function tanstackStartHandler<\n  Result extends SubmissionState,\n  Context = unknown,\n>(\n  submission: FormAdapterSubmission<Result, Context>,\n): TanStackStartHandler<Result, Context> {\n  return async ({ data, ...context }): Promise<Result> =>\n    submission(data, context);\n}\n"],"mappings":";;AA6BA,SAAgB,kBAAkB,MAA0B;AAC1D,KAAI,OAAO,aAAa,eAAe,EAAE,gBAAgB,UACvD,OAAM,IAAI,UAAU,gEAAgE;AAEtF,QAAO;;;;;;;AAQT,SAAgB,qBAId,YACuC;AACvC,QAAO,OAAO,EAAE,MAAM,GAAG,cACvB,WAAW,MAAM,QAAQ"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@formadapter/tanstack-start",
+  "version": "0.0.0",
+  "description": "TanStack Start server-function integration for FormAdapter.",
+  "keywords": [
+    "forms",
+    "server-functions",
+    "tanstack-start",
+    "typescript"
+  ],
+  "homepage": "https://formadapter.com",
+  "bugs": {
+    "url": "https://github.com/ludicroushq/formadapter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ludicroushq/formadapter.git",
+    "directory": "packages/tanstack-start"
+  },
+  "license": "MIT",
+  "author": "ludicrous",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@formadapter/core": "^0.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-start": ">=1.168.25 <2",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-start": "1.168.25",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo .turbo",
+    "dev": "tsdown --watch",
+    "test": "vitest run --config vitest.config.ts",
+    "test:coverage": "vitest run --config vitest.config.ts --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  }
+}