# TanStack Start로 인앱 피드백 폼 만들기 > TanStack Start 인앱 피드백 폼입니다. 세션 미들웨어가 붙은 POST 서버 함수, 컨텍스트로 쓰는 라우트 ID, 요청 헤더에서 읽는 페이지로 구성합니다. 2026-10-25 게시 · https://ikiform.com/ko/guides/feedback-form/tanstack-start 피드백용 POST 서버 함수를 작성하고, 세션을 읽어 사용자를 `context`에 넣는 함수 미들웨어를 붙이세요. 함수는 그 사용자, 요청의 `Referer`에서 얻은 페이지, 매칭된 라우트 ID를 평점에 추가한 뒤 시크릿 키로 폼 백엔드에 전달합니다. 폼을 로그인 레이아웃 라우트에 한 번 마운트하면 어느 화면에 있는지 스스로 압니다. [메인 가이드의 TanStack Start 탭](https://ikiform.com/ko/guides/feedback-form.md#form)은 누구에게서나 페이지 피드백을 받고, 페이지는 브라우저에서 설정합니다. 로그인한 앱 안에서는 더 잘할 수 있습니다. 서버는 누가 묻는지 알고, 라우터는 어느 화면이 열려 있는지 압니다. 계정 설정, 키, 허용 도메인은 [서버 문서 가이드](https://ikiform.com/ko/docs/guides/server.md)에서 한 번에 다룹니다. ## 누가 무엇을 제공하는지 Start에서 서버 함수는 `/_serverFn/` 아래의 HTTP 엔드포인트이며, 컴포넌트는 생성된 클라이언트를 통해 이를 호출합니다. 입력의 어떤 값이든 호출하는 쪽이 다시 쓸 수 있습니다. 그래서 입력에는 사용자가 고른 것만 담고, 신원에 관한 모든 것은 핸들러보다 먼저 서버에서 실행되는 미들웨어에서 가져옵니다. | 값 | 유입 경로 | 신뢰 | | --- | --- | --- | | `rating`, `comment` | 폼의 `FormData` | 사용자 본인의 말 | | `user_id`, `email` | 세션 미들웨어가 설정하는 `context.user` | 서버에서 봉인된 쿠키로부터 읽음 | | `page` | 핸들러 안의 `getRequestHeader("referer")` | 브라우저가 열린 페이지에서 함수를 호출하므로 헤더에 그 URL이 담김 | | `screen` | 가장 깊이 매칭된 `routeId`, 예: `/_app/projects/$projectId/settings` | 묶기 위한 레이블. 저장 전에 패턴으로 확인 | 다이어그램: TanStack Start 서버 함수가 피드백 답변에 사용자와 페이지를 추가하는 과정 1. 폼이 점수와 코멘트를 모으고, 현재 라우트 ID를 추가하고, 서버 함수를 호출합니다. 2. 서버에서 미들웨어가 세션을 읽고 사용자를 컨텍스트로 넘깁니다. 3. 검증기가 FormData를 타입이 있는 객체로 바꾸고, 형식이 잘못된 화면 이름은 버립니다. 4. 핸들러가 사용자가 없으면 거부하고, 사용자와 Referer 헤더의 페이지를 추가합니다. 5. 시크릿 키로 Ikiform에 POST하고 sent를 반환하거나, 폼이 표시할 오류를 반환합니다. 사용자는 서버의 쿠키에서 옵니다. 폼 데이터의 어떤 값도 답변의 작성자를 바꿀 수 없습니다. ## 프로젝트 설정 이 트리는 로그인한 모든 화면을 감싸는 경로 없는 `_app` 레이아웃이 있는 파일 기반 라우팅을 가정합니다. `session.ts`는 Start 인증 가이드의 iron-session 헬퍼이며, 쿠키를 읽는 어떤 세션 라이브러리든 똑같이 동작합니다. `users.ts`의 `findUser`와 `server/user.ts`의 `getCurrentUserFn`은 직접 만든 사용자 조회 함수입니다. `프로젝트 트리`: ```text src/ components/feedback-form.tsx lib/ session.ts user-middleware.ts users.ts routes/ _app.tsx _app/projects/$projectId/settings.tsx server/ feedback.ts user.ts .env ``` Start는 접두사 없는 변수를 서버에서만 `process.env`로 읽습니다. `VITE_` 접두사가 붙은 것은 브라우저용으로 번들링되므로 키에는 절대 붙이면 안 됩니다. 모듈 최상단이 아니라 핸들러 안에서 읽으세요. `.env`: ```bash IKIFORM_SECRET_KEY=ik_sk_your_secret_key SESSION_SECRET=at-least-32-characters-from-your-auth-setup ``` 폼의 **Fields** 탭에 필드 정의를 붙여 넣으세요. 폼에는 그중 두 개가 보이고 나머지 네 개는 서버 함수가 채우며, `email` 필드 덕분에 각 알림의 **Reply**가 사용자에게 갑니다. 폼: In-app feedback - **이 화면은 어떠신가요?** (`rating`, rating, 필수) - **무엇이 더 좋아지면 될까요?** (`comment`, textarea) - **페이지** (`page`, url) - **화면** (`screen`, text) - **사용자** (`user_id`, text) - **이메일** (`email`, email) `rating: 6`이나 정의에 없는 필드를 보내면 미리보기에 서버 함수가 받을 `422`가 표시됩니다. ## 만들기 ### 세션 미들웨어 함수 미들웨어는 자신을 나열한 모든 서버 함수를 감쌉니다. `next({ context })`에 넣은 것은 핸들러에 타입과 함께 도착합니다. 예외를 던지지 않고 `null`을 넘기므로, 핸들러가 폼에 표시할 메시지로 응답할 수 있습니다. `src/lib/user-middleware.ts`: ```ts import { createMiddleware } from "@tanstack/react-start"; import { getAppSession } from "./session"; import { findUser } from "./users"; export const userMiddleware = createMiddleware({ type: "function" }).server(async ({ next }) => { const session = await getAppSession(); const user = session.userId ? await findUser(session.userId) : null; return next({ context: { user: user ? { id: user.id, email: user.email } : null } }); }); ``` ### 서버 함수 `src/server/feedback.ts`: ```ts import { createServerFn } from "@tanstack/react-start"; import { getRequestHeader } from "@tanstack/react-start/server"; import { userMiddleware } from "../lib/user-middleware"; export type FeedbackResult = { status: "sent" } | { status: "error"; message: string }; const ROUTE_ID = /^\/[A-Za-z0-9/$_.-]{0,119}$/; function pageFrom(referer: string | undefined) { try { const url = new URL(referer ?? ""); return url.origin + url.pathname; } catch { return ""; } } export const sendFeedback = createServerFn({ method: "POST" }) .middleware([userMiddleware]) .validator((data: unknown) => { if (!(data instanceof FormData)) throw new Error("Expected form data"); const rating = Number(data.get("rating")); const screen = String(data.get("screen") ?? ""); return { rating: Number.isInteger(rating) && rating >= 1 && rating <= 5 ? rating : null, comment: String(data.get("comment") ?? "").trim().slice(0, 4000), screen: ROUTE_ID.test(screen) ? screen : "unknown", trap: String(data.get("_gotcha") ?? ""), }; }) .handler(async ({ data, context }): Promise => { if (!context.user) return { status: "error", message: "You're signed out. Sign in and send it again." }; if (data.rating === null) return { status: "error", message: "Choose a score first." }; const origin = getRequestHeader("origin"); let response: Response; try { response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`, ...(origin ? { Origin: origin } : {}), }, body: JSON.stringify({ rating: data.rating, comment: data.comment, page: pageFrom(getRequestHeader("referer")), screen: data.screen, user_id: context.user.id, email: context.user.email, _gotcha: data.trap, }), signal: AbortSignal.timeout(8000), }); } catch { return { status: "error", message: "Feedback is unreachable right now. Try again shortly." }; } const result = await response.json().catch(() => null); if (result?.ok) return { status: "sent" }; return { status: "error", message: result?.error?.message ?? "That didn't go through. Try again." }; }); ``` - `.validator`는 원시 `FormData`를 받아 일반 객체를 반환합니다. 잘못된 점수는 예외 대신 `null`이 됩니다. 예외를 던지면 클라이언트에는 일반적인 실패로만 전달됩니다. - `getRequestHeader`는 요청 객체를 넘겨받지 않고도 핸들러 어디서든 들어오는 요청을 읽습니다. - `Origin`은 브라우저의 호출에서 전달됩니다. 아래에서 설명하듯 Ikiform이 POST를 로컬 테스트로 처리할지를 정합니다. - 컨텍스트에는 사용자 레코드 전체가 아니라 ID와 이메일만 넣습니다. 핸들러가 반환하는 것은 직렬화되어 브라우저로 갑니다. ### 폼 `src/components/feedback-form.tsx`: ```tsx import { useMatches } from "@tanstack/react-router"; import { useServerFn } from "@tanstack/react-start"; import { type FormEvent, useState } from "react"; import { type FeedbackResult, sendFeedback } from "../server/feedback"; const SCORES = ["Badly", "Poorly", "Okay", "Well", "Very well"]; export function FeedbackForm() { const send = useServerFn(sendFeedback); const screen = useMatches({ select: (matches) => matches.at(-1)?.routeId ?? "unknown" }); const [result, setResult] = useState(null); const [pending, setPending] = useState(false); async function onSubmit(event: FormEvent) { event.preventDefault(); const data = new FormData(event.currentTarget); data.set("screen", screen); setPending(true); try { setResult(await send({ data })); } catch { setResult({ status: "error", message: "We lost the connection. Try again." }); } finally { setPending(false); } } if (result?.status === "sent") return

Thanks. We read every one.

; return (
How is this screen working for you? {SCORES.map((label, index) => ( ))}