sayren 0.13.1 → 0.15.0

package/dist/boilerplate/.claude/skills/sayren/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: sayren
+description: Load before adding, implementing or changing any feature or page of this sayren storefront. Lists the current sayren skills and loads the ones the task needs.
+---
+
+# sayren skills
+
+The sayren skills are maintained centrally and change without updating this project.
+Do not rely on memory or earlier copies. Load them at the start of each task.
+
+1. List the skills (name and when to use each):
+   `npx -y sayren@latest skill list`
+2. Read every skill that matches the task, in full, and follow it:
+   `npx -y sayren@latest skill <name>`
+
+If the sayren MCP server is connected, the tools `list_skills` and `get_skill` return the same content.
+
+Follow the project's `CLAUDE.md` first. The skills add the sayren-specific details.

package/dist/boilerplate/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sayren": {
+      "type": "http",
+      "url": "https://mcp.sayren.io/mcp"
+    }
+  }
+}

package/dist/boilerplate/CLAUDE.md

@@ -0,0 +1,26 @@
+# CLAUDE.md — sayren 스토어프론트 보일러플레이트
+
+이 폴더는 sayren 스토어프론트 보일러플레이트다(`npx sayren create`, 호스팅 「처음부터」). 인프라와 상점 이름·상품 목록을 보이는 홈만 있고 화면은 쇼핑몰마다 새로 만든다.
+상점·상품·주문 데이터는 sayren이 보관하고, 이 앱은 스토어프론트 SDK(`@sayren/storefront-sdk`)로 읽는다.
+
+## 이미 있는 것
+- TanStack Start + React 19 + Tailwind v4(`src/theme.css`의 `@theme` 토큰). 라우트는 `src/routes/`(파일 기반).
+- SDK 연결: 서버 `src/lib/api.server.ts`(`apiFor()`), 브라우저 `src/lib/api.ts`, 설정 `src/lib/config.server.ts`(환경 변수 `SAYREN_API_URL`·`SAYREN_STORE_CODE`, 로컬은 `.env`).
+- 홈: `src/routes/index.tsx` — 상점 이름과 상품 목록(첫 페이지). 금액 표시는 `src/lib/format.ts`(`formatMoney`).
+- 기본 조회와 훅: `src/lib/queries.ts`(queryOptions) · `src/hooks/use-catalog.ts`(`useStore`·`useCategories`·`useProducts`·`useProduct`).
+- 문구: `messages/ko.json` + `src/i18n`(`m.키()`). 화면 문구는 코드에 쓰지 않고 이 파일에 둔다.
+- 방문 분석: 루트가 `startAnalytics`로 시작한다(`src/lib/analytics.ts`). 서버 쿠키는 `src/lib/cookies.server.ts` 한 곳이다.
+- 스크롤 연출용 `gsap`·`lenis`가 설치돼 있다.
+
+## 만들 때의 규칙
+- 셀러가 요청한 화면만 만든다. 장바구니·주문서·결제·구매자 로그인은 셀러가 요청할 때까지 만들지 않는다.
+  요청을 받으면 SDK의 장바구니·주문서·`/payments`·`/auth` 모듈로 만들고 `sdk-cart`·`sdk-checkout`·`sdk-payments`·`sdk-buyer-auth` 스킬과 규칙 검증(`verify_site`)을 따른다.
+- 데이터는 라우트 loader에서 `queryClient.ensureQueryData(...)`로 먼저 받고 화면은 훅으로 읽는다. `fetch`로 api를 직접 부르지 않는다.
+- 금액·재고·주문 가능 여부는 응답 값을 그대로 보인다. 화면에서 계산하지 않는다.
+- `process.env`는 `*.server.ts`에서만 읽는다. 모듈 최상위에서 `window`·`document`를 읽지 않는다.
+- 색·글꼴·모서리는 `src/theme.css` 토큰으로만 쓴다.
+- 기능·화면을 추가·구현·변경하기 전에 `sayren` 스킬(`.claude/skills/sayren`)을 먼저 쓴다. 중앙 스킬 목록(`npx -y sayren@latest skill list`)에서 작업에 맞는 스킬을 골라 본문(`npx -y sayren@latest skill <이름>`)을 읽고 따른다(스킬은 이 프로젝트를 고치지 않고 바뀐다).
+
+## 확인
+- `pnpm typecheck` · `pnpm test` · `pnpm build`
+- 원격 MCP(`.mcp.json`, sayren 계정 로그인)로 상점 데이터를 읽고 `verify_site`로 규칙을 확인한다.

package/dist/boilerplate/README.md

@@ -0,0 +1,12 @@
+# sayren 스토어프론트 보일러플레이트
+
+`npx sayren create <이름>`으로 만든 sayren 스토어프론트입니다. 상점 이름과 상품 목록을 보이는 홈만 있고, 화면은 쇼핑몰에 맞게 새로 만듭니다.
+
+```bash
+pnpm install
+pnpm dev
+```
+
+상점 연결 값(`SAYREN_STORE_CODE`·`SAYREN_API_URL`)은 `.env`에 있습니다.
+
+작업 규칙은 `CLAUDE.md`에 있습니다. 기준 문서(스킬)는 sayren이 중앙에서 관리하며 `.claude/skills/sayren`이 읽는 방법을 안내합니다.

package/dist/boilerplate/_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+.output/
+.tanstack/
+.nitro/
+.env
+.env.*
+.sayren/

package/dist/boilerplate/biome.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.14/schema.json",
+  "root": true,
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": [
+      "**",
+      "!**/node_modules",
+      "!**/dist",
+      "!**/.output",
+      "!**/.tanstack",
+      "!**/.nitro",
+      "!**/.vinxi",
+      "!**/.wrangler",
+      "!**/routeTree.gen.ts"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always"
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  }
+}

package/dist/boilerplate/messages/en.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "format_price": "{amount}",
+  "home_no_products": "No products yet.",
+  "root_error_title": "Couldn't load this page",
+  "root_go_home": "Go to home",
+  "root_not_found_title": "Page not found",
+  "site_store_fallback": "Store"
+}

package/dist/boilerplate/messages/ko.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "format_price": "{amount}원",
+  "home_no_products": "등록된 상품이 없습니다",
+  "root_error_title": "화면을 불러오지 못했습니다",
+  "root_go_home": "홈으로",
+  "root_not_found_title": "페이지를 찾을 수 없습니다",
+  "site_store_fallback": "쇼핑몰"
+}

package/dist/boilerplate/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sayren/cli-boilerplate",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 4010 --strictPort",
+    "build": "vite build",
+    "start": "vite preview --port 4010 --strictPort",
+    "lint": "biome check --write . && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@avarlabs/editor": "^0.1.3",
+    "@hookform/resolvers": "^5.9.1",
+    "@sayren/storefront-sdk": "^0.35.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-query": "^5.103.1",
+    "@tanstack/react-router": "^1.170.38",
+    "@tanstack/react-router-ssr-query": "^1.167.3",
+    "@tanstack/react-start": "^1.168.56",
+    "embla-carousel-react": "^8.6.0",
+    "gsap": "^3.15.0",
+    "lenis": "^1.3.26",
+    "lucide-react": "^1.50.0",
+    "nuqs": "^2.10.1",
+    "query-string": "^9.5.1",
+    "react": "^19.3.0",
+    "react-daum-postcode": "^4.0.0",
+    "react-dom": "^19.3.0",
+    "react-hook-form": "^7.88.0",
+    "tailwindcss": "^4.3.3",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "@types/node": "^24.13.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
+  }
+}

package/dist/boilerplate/public/_headers

@@ -0,0 +1,5 @@
+# Workers 정적 자산 응답 헤더(https://developers.cloudflare.com/workers/static-assets/headers/).
+# /assets/는 빌드가 만든 파일 이름에 내용 해시가 붙은 파일만 둔다 — 내용이 바뀌면 이름이 바뀌므로 1년 동안 다시 묻지 않는다.
+# 해시 없는 파일(파비콘 등)과 서버가 그리는 HTML은 기본값(max-age=0, must-revalidate)이다. public/assets/에 파일을 두지 마십시오.
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable

package/dist/boilerplate/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><title>상점</title><rect width="32" height="32" rx="7" fill="#202429"/><path d="M9 12h14l-1.4 11.2a2 2 0 0 1-2 1.8h-7.2a2 2 0 0 1-2-1.8z" fill="#fff"/><path d="M12.5 12V10.5a3.5 3.5 0 0 1 7 0V12" fill="none" stroke="#fff" stroke-width="1.8"/></svg>

package/dist/boilerplate/src/hooks/use-catalog.ts

@@ -0,0 +1,28 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import {
+  categoriesQuery,
+  type ProductSearch,
+  productQuery,
+  productsQuery,
+  storeQuery,
+} from "../lib/queries";
+
+/**
+ * 기본 훅 — 화면은 이 훅으로 데이터를 읽는다. 라우트 loader에서 같은 queryOptions로 `ensureQueryData`를 먼저 부르면
+ * 서버 렌더에 데이터가 실려 첫 화면이 바로 그려진다(`loader-first` 규칙).
+ */
+export function useStore() {
+  return useSuspenseQuery(storeQuery()).data;
+}
+
+export function useCategories() {
+  return useSuspenseQuery(categoriesQuery()).data;
+}
+
+export function useProducts(search: ProductSearch = {}) {
+  return useSuspenseQuery(productsQuery(search)).data;
+}
+
+export function useProduct(productId: string) {
+  return useSuspenseQuery(productQuery(productId)).data;
+}

package/dist/boilerplate/src/i18n/index.ts

@@ -0,0 +1,99 @@
+import en from "../../messages/en.json";
+import ko from "../../messages/ko.json";
+
+/**
+ * 화면 문구(이슈 #73) — 문구는 `messages/{locale}.json`에만 쓰고 코드에서는 `m.키()`로 부른다.
+ * 키는 `{영역}_{이름}`이고 값의 `{name}`은 인자로 채운다(`m.cart_count({ count: 3 })`).
+ * 형식은 inlang 메시지 형식이라 Paraglide 같은 도구로 옮겨도 그대로 읽힌다.
+ *
+ * 언어를 더하려면 `messages/en.json`을 만들고 아래 `CATALOGS`와 `LOCALES`에 더한다. 빠진 키는 기본 언어(ko) 문구를 쓴다.
+ * 언어는 요청마다 `?lang=` → `Accept-Language` → `ko` 순서로 정한다(`src/start.ts`, 서버). 브라우저는 서버가 정한
+ * `<html lang>`을 읽어 같은 언어로 이어 그린다.
+ *
+ * 모듈 최상위에서 `m.*()`를 부르지 않는다 — 서버에서는 요청마다 언어가 다르다. 라벨 표는 `lazyMessages`로 만든다.
+ */
+export const LOCALES = ["ko", "en"] as const;
+export type Locale = (typeof LOCALES)[number];
+export const BASE_LOCALE: Locale = "ko";
+export const LOCALE_QUERY_PARAM = "lang";
+
+type Catalog = typeof ko;
+export type MessageKey = Exclude<keyof Catalog, "$schema">;
+export type MessageArgs = Readonly<Record<string, string | number>>;
+
+const CATALOGS: Record<Locale, Partial<Record<MessageKey, string>>> = { ko, en };
+
+/** `ko-KR`·`KO` → `ko`. 지원하지 않으면 undefined */
+export function toLocale(value: string | null | undefined): Locale | undefined {
+  if (!value) return undefined;
+  const tag = value.trim().toLowerCase().replace("_", "-");
+  return (LOCALES as readonly string[]).find((l) => l === tag || l === tag.split("-")[0]) as
+    | Locale
+    | undefined;
+}
+
+/** 요청 언어 — `?lang=` → `Accept-Language`(q값 순) → 기본 언어 */
+export function resolveLocale(url: URL, acceptLanguage: string | null): Locale {
+  const query = toLocale(url.searchParams.get(LOCALE_QUERY_PARAM));
+  if (query) return query;
+  const accepted = (acceptLanguage ?? "")
+    .split(",")
+    .map((part) => {
+      const [tag, ...params] = part.trim().split(";");
+      const q = Number(params.find((p) => p.trim().startsWith("q="))?.split("=")[1] ?? 1);
+      return { tag: tag ?? "", q: Number.isFinite(q) ? q : 0 };
+    })
+    .filter((entry) => entry.tag && entry.q > 0)
+    .sort((a, b) => b.q - a.q);
+  for (const { tag } of accepted) {
+    const locale = toLocale(tag);
+    if (locale) return locale;
+  }
+  return BASE_LOCALE;
+}
+
+let serverLocale: (() => Locale | undefined) | undefined;
+
+/** 서버의 요청 언어 저장소를 연결한다(`locale.server.ts`) */
+export function setServerLocaleGetter(getter: () => Locale | undefined): void {
+  serverLocale = getter;
+}
+
+/** 지금 언어 — 서버는 요청 언어, 브라우저는 서버가 정한 `<html lang>` */
+export function getLocale(): Locale {
+  if (typeof document === "undefined") return serverLocale?.() ?? BASE_LOCALE;
+  return toLocale(document.documentElement.lang) ?? BASE_LOCALE;
+}
+
+/** `{name}` 자리를 채운다. 값이 없는 자리는 그대로 둔다 */
+export function formatMessage(template: string, args?: MessageArgs): string {
+  if (!args) return template;
+  return template.replace(/\{(\w+)\}/g, (whole, name: string) =>
+    Object.hasOwn(args, name) ? String(args[name]) : whole,
+  );
+}
+
+export function t(key: MessageKey, args?: MessageArgs): string {
+  const template = CATALOGS[getLocale()][key] ?? CATALOGS[BASE_LOCALE][key] ?? key;
+  return formatMessage(template, args);
+}
+
+/** `m.키(인자)` — 키 오타는 타입 검사가 잡는다 */
+export const m = Object.fromEntries(
+  (Object.keys(ko) as (keyof Catalog)[])
+    .filter((key): key is MessageKey => key !== "$schema")
+    .map((key) => [key, (args?: MessageArgs) => t(key, args)]),
+) as { readonly [K in MessageKey]: (args?: MessageArgs) => string };
+
+/**
+ * 라벨 표 — 값을 읽을 때마다 문구를 만든다(서버에서 요청 언어를 따른다). 타입은 `Record<K, string>`이다.
+ */
+export function lazyMessages<K extends string>(
+  table: Record<K, () => string>,
+): Readonly<Record<K, string>> {
+  const labels = {} as Record<K, string>;
+  for (const key of Object.keys(table) as K[]) {
+    Object.defineProperty(labels, key, { enumerable: true, get: () => table[key]() });
+  }
+  return Object.freeze(labels);
+}

package/dist/boilerplate/src/i18n/locale.server.ts

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { type Locale, setServerLocaleGetter } from "./index";
+
+/** 요청마다 정한 언어를 그 요청이 끝날 때까지 유지한다(동시에 들어온 요청끼리 섞이지 않는다) */
+const storage = new AsyncLocalStorage<Locale>();
+setServerLocaleGetter(() => storage.getStore());
+
+export function runWithLocale<T>(locale: Locale, fn: () => T): T {
+  return storage.run(locale, fn);
+}

package/dist/boilerplate/src/lib/analytics.ts

@@ -0,0 +1,60 @@
+import {
+  type Analytics,
+  type AnalyticsOptions,
+  type AnalyticsTrackInput,
+  createAnalytics,
+} from "@sayren/storefront-sdk/analytics";
+import { useEffect } from "react";
+
+/**
+ * 방문 분석 — 브라우저 전용. 루트가 한 번 시작하고, 화면은 `useTrack`으로 행동을 남긴다.
+ *
+ * 장바구니·결제 시작·구매는 여기서 보내지 않는다. 스토어프론트 API가 요청을 처리하면서 서버에서
+ * 기록한다(`api.server.ts`가 방문자·세션 쿠키를 헤더로 싣는다).
+ */
+
+/** 루트 loader(서버 함수)가 내려주는 값 */
+export interface AnalyticsConfig {
+  apiBaseUrl: string;
+  storeCode: string;
+  /** localhost에서도 보낸다(`SAYREN_ANALYTICS_DEBUG=1`) */
+  debug: boolean;
+}
+
+let instance: Analytics | null = null;
+/**
+ * 시작 전에 들어온 행동. React는 자식 effect를 부모보다 먼저 돌리므로 첫 화면의 `useTrack`이
+ * 루트의 시작보다 앞선다.
+ */
+let pending: AnalyticsTrackInput[] = [];
+
+export function startAnalytics(config: AnalyticsConfig): Analytics {
+  if (instance) return instance;
+  const options: AnalyticsOptions = {
+    baseUrl: config.apiBaseUrl,
+    storeCode: config.storeCode,
+    debug: config.debug,
+    // 쿠키 동의 배너를 붙이는 상점은 "pending"으로 시작하고 배너에서 setConsent를 부른다
+    consent: "granted",
+  };
+  instance = createAnalytics(options);
+  for (const input of pending) instance.track(input);
+  pending = [];
+  return instance;
+}
+
+export function track(input: AnalyticsTrackInput) {
+  if (instance) instance.track(input);
+  else pending.push(input);
+}
+
+/**
+ * 화면이 보일 때 행동을 한 번 남긴다. 내용이 같으면 리렌더·StrictMode 이중 실행에도 다시 보내지
+ * 않는다(SDK도 같은 페이지뷰 안의 중복을 거른다). `null`이면 아무것도 보내지 않는다.
+ */
+export function useTrack(input: AnalyticsTrackInput | null) {
+  const key = input ? JSON.stringify(input) : "";
+  useEffect(() => {
+    if (key) track(JSON.parse(key) as AnalyticsTrackInput);
+  }, [key]);
+}

package/dist/boilerplate/src/lib/api.server.ts

@@ -0,0 +1,27 @@
+import { analyticsIdsFromCookie, createStorefrontClient } from "@sayren/storefront-sdk";
+import { getRequest } from "@tanstack/react-start/server";
+import { API_BASE_URL, resolveStoreCode } from "./config.server";
+
+/**
+ * 서버(서버 함수·서버 라우트)에서 쓰는 스토어프론트 API 클라이언트.
+ *
+ * 테넌트는 `X-Store-Code` 헤더로 보낸다. 토큰은 요청마다 넘긴다 — 모듈 전역에 담으면 서버 렌더에서
+ * 다른 사용자의 요청에 섞인다. 방문 분석 쿠키(방문자·세션)를 헤더로 실어 서버가 기록하는 이벤트를 방문과 잇는다.
+ */
+export function apiFor(
+  options: {
+    accessToken?: string | null;
+    cartToken?: string | null;
+    onCartToken?: (token: string) => void;
+  } = {},
+) {
+  const request = getRequest();
+  return createStorefrontClient({
+    baseUrl: API_BASE_URL,
+    storeCode: resolveStoreCode(),
+    accessToken: options.accessToken ?? undefined,
+    cartToken: options.cartToken ?? undefined,
+    onCartToken: options.onCartToken,
+    ...analyticsIdsFromCookie(request.headers.get("cookie")),
+  });
+}

package/dist/boilerplate/src/lib/api.ts

@@ -0,0 +1,7 @@
+import { createStorefrontClient } from "@sayren/storefront-sdk";
+import type { PublicConfig } from "./config";
+
+/** 브라우저용 — 서버 함수가 내려준 설정으로 만든다(결제창·결제 승인·결제 상태 조회에 쓴다) */
+export function browserApi(config: PublicConfig) {
+  return createStorefrontClient({ baseUrl: config.apiBaseUrl, storeCode: config.storeCode });
+}

package/dist/boilerplate/src/lib/config.server.ts

@@ -0,0 +1,23 @@
+import { getRequestHeader } from "@tanstack/react-start/server";
+import { storeCodeFromHost } from "./config";
+
+/**
+ * 서버 전용 설정 — `.server.ts`라 브라우저 번들에 들어가지 않는다. `process.env`를 여기에만 둔다.
+ * 브라우저에 필요한 값은 서버 함수가 내려준다(`PublicConfig`).
+ */
+export const API_BASE_URL = process.env.SAYREN_API_URL ?? "https://api.sayren.io/storefront/v1";
+
+/** localhost에서도 방문 분석을 보낸다 — 기본은 개발 트래픽을 섞지 않으려고 끈다 */
+export const ANALYTICS_DEBUG = process.env.SAYREN_ANALYTICS_DEBUG === "1";
+
+const FIXED_STORE_CODE = process.env.SAYREN_STORE_CODE ?? "";
+
+/** 이 요청의 테넌트 — 고정 값이 먼저이고, 없으면 호스트 서브도메인에서 뽑는다 */
+export function resolveStoreCode(): string {
+  if (FIXED_STORE_CODE) return FIXED_STORE_CODE;
+  const fromHost = storeCodeFromHost(getRequestHeader("host"));
+  if (fromHost) return fromHost;
+  throw new Error(
+    "상점 코드를 알 수 없습니다. SAYREN_STORE_CODE 환경변수를 설정하거나 서브도메인으로 서비스해 주십시오",
+  );
+}

package/dist/boilerplate/src/lib/config.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { storeCodeFromHost } from "./config";
+
+describe("상점 코드 해석", () => {
+  it("서브도메인이 있으면 첫 라벨을 쓴다", () => {
+    expect(storeCodeFromHost("mystore.example.com")).toBe("mystore");
+    expect(storeCodeFromHost("mystore.example.com:443")).toBe("mystore");
+  });
+
+  it("서브도메인이 없거나 로컬·IP면 알 수 없다", () => {
+    expect(storeCodeFromHost("example.com")).toBeNull();
+    expect(storeCodeFromHost("localhost:4010")).toBeNull();
+    expect(storeCodeFromHost("127.0.0.1:4010")).toBeNull();
+    expect(storeCodeFromHost(null)).toBeNull();
+  });
+});

package/dist/boilerplate/src/lib/config.ts

@@ -0,0 +1,19 @@
+/**
+ * 브라우저와 서버가 함께 쓰는 값만 둔다. `process.env`는 여기에 두지 않는다 —
+ * 브라우저 번들에 들어가면 `process is not defined`로 화면이 깨진다(서버 값은 `config.server.ts`).
+ */
+
+/** 호스트에서 서브도메인을 뽑는다(`mystore.example.com` → `mystore`) */
+export function storeCodeFromHost(host: string | null | undefined): string | null {
+  if (!host) return null;
+  const hostname = host.split(":")[0] ?? "";
+  if (hostname === "localhost" || /^\d+\.\d+\.\d+\.\d+$/.test(hostname)) return null;
+  const labels = hostname.split(".");
+  return labels.length >= 3 ? (labels[0] ?? null) : null;
+}
+
+/** 서버 함수가 브라우저로 내려주는 값 */
+export interface PublicConfig {
+  apiBaseUrl: string;
+  storeCode: string;
+}

package/dist/boilerplate/src/lib/cookies.server.ts

@@ -0,0 +1,35 @@
+import { deleteCookie, getCookie, setCookie } from "@tanstack/react-start/server";
+
+/**
+ * 서버가 쓰는 쿠키(구매자 세션·비회원 장바구니·소셜 로그인 왕복)의 이름과 속성을 한 곳에서 정한다.
+ *
+ * 프로덕션 빌드는 이름에 `__Host-` 접두사를 붙인다. 브라우저는 이 접두사의 쿠키를 `Secure` + `Path=/` +
+ * `Domain` 없음일 때만 받는다. 그래서 같은 상위 도메인을 쓰는 다른 사이트(예: `other.example.com`)가
+ * `Domain=example.com`으로 심은 쿠키가 이 이름으로 들어오지 못한다. 남이 심은 세션·로그인 상태로
+ * 구매자를 로그인시키는 쿠키 주입을 막는 장치다. 접두사 없는 옛 이름은 읽지 않는다
+ * (읽으면 주입된 쿠키가 다시 통한다). 옛 이름으로 로그인해 있던 구매자는 한 번 다시 로그인한다.
+ *
+ * 개발 서버(http)는 `Secure` 쿠키를 받지 못하는 브라우저가 있어 접두사 없이 쓴다.
+ */
+const SECURE = import.meta.env.PROD;
+
+export const cookieName = (base: string): string => (SECURE ? `__Host-${base}` : base);
+
+export function readServerCookie(base: string): string | undefined {
+  return getCookie(cookieName(base));
+}
+
+export function writeServerCookie(base: string, value: string, maxAgeSec: number) {
+  setCookie(cookieName(base), value, {
+    httpOnly: true,
+    sameSite: "lax",
+    path: "/",
+    secure: SECURE,
+    maxAge: maxAgeSec,
+  });
+}
+
+/** 지울 때도 같은 속성을 준다 — `__Host-` 쿠키는 `Secure`·`Path=/`가 없으면 삭제 헤더도 거부된다 */
+export function clearServerCookie(base: string) {
+  deleteCookie(cookieName(base), { path: "/", secure: SECURE });
+}

package/dist/boilerplate/src/lib/format.ts

@@ -0,0 +1,19 @@
+import { BASE_CURRENCY, currencySpecOf, minorToMajor } from "@sayren/storefront-sdk";
+import { m } from "../i18n";
+
+const KRW = new Intl.NumberFormat("ko-KR");
+
+/**
+ * 통화 금액 — 금액은 그 통화의 최소 단위 정수다(API 응답 그대로, 화면에서 계산하지 않는다). 원화는 「12,000원」,
+ * 그 밖의 통화는 `Intl` 통화 형식이다(「US$10.99」). 서버와 브라우저 결과가 같도록 로케일을 고정한다
+ */
+export function formatMoney(amount: number, currency: string = BASE_CURRENCY): string {
+  if (currency === BASE_CURRENCY) return m.format_price({ amount: KRW.format(amount) });
+  const { digits } = currencySpecOf(currency);
+  return new Intl.NumberFormat("ko-KR", {
+    style: "currency",
+    currency,
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  }).format(minorToMajor(amount, currency));
+}

package/dist/boilerplate/src/lib/queries.ts

@@ -0,0 +1,61 @@
+import { productSortSchema } from "@sayren/storefront-sdk";
+import { queryOptions } from "@tanstack/react-query";
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+import { apiFor } from "./api.server";
+
+/**
+ * 기본 조회 — TanStack Query의 queryOptions 팩토리다. 라우트 loader(`ensureQueryData`)와 화면(`useSuspenseQuery`, `src/hooks`)이
+ * 같은 팩토리를 써서 queryKey가 갈라지지 않는다. 데이터는 서버 함수로 받는다(첫 요청은 서버가 받아 HTML에 싣는다).
+ * 금액·재고·주문 가능 여부는 응답 값을 그대로 보인다 — 화면에서 계산하지 않는다.
+ */
+
+const getStore = createServerFn({ method: "GET" }).handler(() => apiFor().store.get());
+
+const listCategories = createServerFn({ method: "GET" }).handler(() =>
+  apiFor().catalog.listCategories(),
+);
+
+export const productSearchSchema = z.object({
+  keyword: z.string().optional(),
+  categoryId: z.string().optional(),
+  sort: productSortSchema.optional(),
+  page: z.number().int().min(1).optional(),
+  size: z.number().int().min(1).max(60).optional(),
+});
+export type ProductSearch = z.infer<typeof productSearchSchema>;
+
+const searchProducts = createServerFn({ method: "GET" })
+  .validator(productSearchSchema)
+  .handler(({ data }) =>
+    apiFor().catalog.searchProducts({ ...data, page: data.page ?? 1, size: data.size ?? 24 }),
+  );
+
+const getProduct = createServerFn({ method: "GET" })
+  .validator(z.object({ productId: z.string().min(1) }))
+  .handler(({ data }) => apiFor().catalog.getProduct(data.productId));
+
+/** 상점 이름·로고·연락처 — 상점 플랫폼 설정 › 상점 정보 값 */
+export const storeQuery = () =>
+  queryOptions({ queryKey: ["store"], queryFn: () => getStore(), staleTime: 5 * 60_000 });
+
+/** 카테고리는 자주 바뀌지 않는다 — 5분 동안 다시 받지 않는다 */
+export const categoriesQuery = () =>
+  queryOptions({
+    queryKey: ["catalog", "categories"],
+    queryFn: () => listCategories(),
+    staleTime: 5 * 60_000,
+  });
+
+export const productsQuery = (search: ProductSearch) =>
+  queryOptions({
+    queryKey: ["catalog", "products", search],
+    queryFn: () => searchProducts({ data: search }),
+  });
+
+/** 상품 하나 — 상품 id 또는 상점별 상품번호 */
+export const productQuery = (productId: string) =>
+  queryOptions({
+    queryKey: ["catalog", "product", productId],
+    queryFn: () => getProduct({ data: { productId } }),
+  });