Frontend Conventions (TS/React)¶

import { z } from "zod"

export const planChangeSchema = z.object({
  newPlanCode: z.enum(["FREE", "PRO", "ENTERPRISE"]),
})

export type PlanChangeValues = z.infer<typeof planChangeSchema>

// ❌
const data: any = await response.json()

// ✓
const data: unknown = await response.json()
if (isSubscription(data)) { ... }

// ✓
type Subscription = {
  id: string
  status: "active" | "past_due" | "canceled"
}

// interface 는 특별한 이유 있을 때만

import type { paths, components } from "@/shared/types/api.gen"

type SubscriptionResponse = components["schemas"]["SubscriptionResponse"]
type GetSubscription = paths["/api/v1/subscriptions/{id}"]["get"]

// ✓
export function SubscriptionCard({ subscription }: Props) {
  return <div>...</div>
}

// ❌ class component

type Props = {
  subscription: Subscription
  onCancel?: () => void
}

export function SubscriptionCard({ subscription, onCancel }: Props) {
  ...
}

// ❌ 많은 props
<Dialog
  title="..."
  description="..."
  confirmLabel="..."
  cancelLabel="..."
  onConfirm={...}
  onCancel={...}
/>

// ✓ shadcn pattern
<Dialog open={open} onOpenChange={setOpen}>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>...</DialogTitle>
      <DialogDescription>...</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button variant="outline" onClick={...}>취소</Button>
      <Button onClick={...}>확인</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

import { cn } from "@/shared/lib/utils"

<div className={cn("rounded-md p-4", isActive && "bg-primary", className)} />

// shared/api/query-keys.ts
export const queryKeys = {
  subscriptions: {
    all: ["subscriptions"] as const,
    byId: (id: string) => [...queryKeys.subscriptions.all, id] as const,
    byGuild: (guildId: string) => [...queryKeys.subscriptions.all, "guild", guildId] as const,
  },
  snapshots: {
    all: ["snapshots"] as const,
    byGuild: (guildId: string) => [...queryKeys.snapshots.all, "guild", guildId] as const,
    byId: (id: string) => [...queryKeys.snapshots.all, id] as const,
  },
  // ...
} as const

// features/billing/hooks/useSubscription.ts
export function useSubscription(id: string) {
  return useQuery({
    queryKey: queryKeys.subscriptions.byId(id),
    queryFn: () => apiClient.get(`/subscriptions/${id}`),
    enabled: !!id,
  })
}

// features/billing/hooks/useCancelSubscription.ts
export function useCancelSubscription() {
  const qc = useQueryClient()
  return useMutation({
    mutationFn: (id: string) => apiClient.post(`/subscriptions/${id}/cancel`),
    onSuccess: (_, id) => {
      qc.invalidateQueries({ queryKey: queryKeys.subscriptions.byId(id) })
    },
  })
}

class ApiClient {
  async get<T>(path: string): Promise<T> {
    const res = await fetch(`${API_BASE_URL}${path}`, {
      credentials: "include",
    })
    if (!res.ok) throw new ApiError(res.status, await res.text())
    return res.json()
  }

  async post<T, B = unknown>(path: string, body?: B): Promise<T> { ... }
  // ...
}

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"

const form = useForm<PlanChangeValues>({
  resolver: zodResolver(planChangeSchema),
  defaultValues: { newPlanCode: "PRO" },
})

const onSubmit = async (values: PlanChangeValues) => {
  await changePlan(values)
}

return (
  <Form {...form}>
    <form onSubmit={form.handleSubmit(onSubmit)}>
      <FormField
        control={form.control}
        name="newPlanCode"
        render={({ field }) => (
          <FormItem>
            <FormLabel>플랜</FormLabel>
            <Select onValueChange={field.onChange} value={field.value}>
              <SelectTrigger>...</SelectTrigger>
              <SelectContent>
                <SelectItem value="FREE">Free</SelectItem>
                <SelectItem value="PRO">Pro</SelectItem>
                <SelectItem value="ENTERPRISE">Enterprise</SelectItem>
              </SelectContent>
            </Select>
            <FormMessage />
          </FormItem>
        )}
      />
      <Button type="submit">변경</Button>
    </form>
  </Form>
)

// router.ts
import { createRouter, createRoute, createRootRoute } from "@tanstack/react-router"

const rootRoute = createRootRoute({ component: RootLayout })

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/",
  component: HomePage,
})

const guildRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: "/g/$guildId",
  component: GuildLayout,
})

const subscriptionRoute = createRoute({
  getParentRoute: () => guildRoute,
  path: "/subscription",
  component: SubscriptionPage,
})

const routeTree = rootRoute.addChildren([
  indexRoute,
  guildRoute.addChildren([subscriptionRoute, ...]),
])

export const router = createRouter({ routeTree })

const subscriptionRoute = createRoute({
  path: "/subscription",
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData({
      queryKey: queryKeys.subscriptions.byGuild(params.guildId),
      queryFn: () => ...,
    }),
  component: SubscriptionPage,
})

import { Link, useNavigate } from "@tanstack/react-router"

<Link to="/g/$guildId/subscription" params={{ guildId }}>구독</Link>

const navigate = useNavigate()
navigate({ to: "/g/$guildId/snapshots", params: { guildId } })

// shared/store/sidebar.ts
import { create } from "zustand"

type SidebarState = {
  isOpen: boolean
  toggle: () => void
}

export const useSidebar = create<SidebarState>((set) => ({
  isOpen: false,
  toggle: () => set((s) => ({ isOpen: !s.isOpen })),
}))

// tailwind.config.ts
theme: {
  extend: {
    colors: {
      umbra: {
        shadow: "hsl(var(--umbra-shadow))",
        glow:   "hsl(var(--umbra-glow))",
        accent: "hsl(var(--umbra-accent))",
      },
    },
  },
}

// ❌
<div style={{ marginTop: 8 }} />

// ✓
<div className="mt-2" />

import { Shield, RefreshCw, Settings } from "lucide-react"

<Shield className="h-5 w-5 text-umbra-accent" />

<ErrorBoundary fallback={<ErrorScreen />}>
  <Outlet />
</ErrorBoundary>

const { data, error, isLoading } = useSubscription(id)

if (isLoading) return <Loading />
if (error) return <ErrorMessage error={error} />
return <SubscriptionCard subscription={data} />

const mutation = useCancelSubscription()

<Button
  onClick={() => mutation.mutate(id, {
    onError: (err) => toast.error("해지 실패: " + err.message),
    onSuccess: () => toast.success("해지 예약 완료"),
  })}
>
  해지
</Button>

import { describe, it, expect } from "vitest"
import { render, screen } from "@testing-library/react"
import { SubscriptionCard } from "./SubscriptionCard"

describe("SubscriptionCard", () => {
  it("displays plan code", () => {
    render(<SubscriptionCard subscription={mockSub} />)
    expect(screen.getByText("PRO")).toBeInTheDocument()
  })
})