Patterns & Conventions

# 1. Add a file in src/routes/
# Example: apps/full-suite/src/routes/(protected)/_layout/dashboard/new-feature.lazy.tsx

# 2. Save the file — Vite auto-generates routeTree.gen.ts
# 3. Navigate to /dashboard/new-feature in the browser

// new-feature.lazy.tsx
import { createLazyFileRoute } from "@tanstack/react-router"

export const Route = createLazyFileRoute(
  "/(protected)/_layout/dashboard/new-feature"
)({
  component: NewFeaturePage,
})

function NewFeaturePage() {
  return <div>New Feature</div>
}

// pages.$metrics.tsx
import { createFileRoute } from "@tanstack/react-router"

export const Route = createFileRoute(
  "/(protected)/_layout/dashboard/pages/$metrics"
)({
  component: PagesMetricsPage,
})

function PagesMetricsPage() {
  const { metrics } = Route.useParams()
  return <div>Metrics: {metrics}</div>
}

// Context (userEmail, setEmail) is available in all routes
import { useRouteContext } from "@tanstack/react-router"

function MyComponent() {
  const { userEmail } = useRouteContext({ from: "__root__" })
}

// src/store/server/features/websites/queries.ts
import { useQuery } from "@tanstack/react-query"
import { fetchWebsiteList } from "@/model/website"

export const useWebsiteList = (orgId: string) => {
  return useQuery({
    queryKey: ["websiteList", orgId],   // Unique key — include all dependencies
    queryFn: () => fetchWebsiteList(orgId),
    enabled: !!orgId,                   // Only fetch when orgId is truthy
    refetchOnWindowFocus: false,        // Standard — prevents refetch on tab switch
  })
}

// src/store/server/features/scan/mutate.ts
import { useMutation, useQueryClient } from "@tanstack/react-query"
import { startScan } from "@/model/website"

export const useStartScan = () => {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: startScan,
    onSuccess: () => {
      // Invalidate relevant queries to trigger refetch
      queryClient.invalidateQueries({ queryKey: ["scanHistory"] })
    },
  })
}

export const useScanStatus = (auditId: string) => {
  return useQuery({
    queryKey: ["scanStatus", auditId],
    queryFn: () => getScanStatus(auditId),
    refetchInterval: (query) => {
      // Stop polling when scan is complete
      return query.state.data?.status === "completed" ? false : 3000
    },
  })
}

["websiteList", orgId]           // ✅
["scanHistory", websiteId]       // ✅
["user", "me"]                   // ✅
["auditResult", auditId, device] // ✅
"websiteList"                    // ❌ — use arrays, not strings

// src/store/client/dialogue.ts
import { create } from "zustand"

interface DialogueState {
  isAddWebsiteOpen: boolean
  isDeleteConfirmOpen: boolean
}

interface DialogueActions {
  setIsAddWebsiteOpen: (open: boolean) => void
  setIsDeleteConfirmOpen: (open: boolean) => void
}

const useDialogue = create<DialogueState & DialogueActions>((set) => ({
  isAddWebsiteOpen: false,
  isDeleteConfirmOpen: false,
  setIsAddWebsiteOpen: (open) => set({ isAddWebsiteOpen: open }),
  setIsDeleteConfirmOpen: (open) => set({ isDeleteConfirmOpen: open }),
}))

export default useDialogue

// Usage in a component
import useDialogue from "@/store/client/dialogue"

function WebsiteHeader() {
  const { isAddWebsiteOpen, setIsAddWebsiteOpen } = useDialogue()

  return (
    <button onClick={() => setIsAddWebsiteOpen(true)}>
      Add Website
    </button>
  )
}

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

// 1. Define the schema
const loginSchema = z.object({
  email: z.string().email("Please enter a valid email"),
  password: z.string().min(8, "Password must be at least 8 characters"),
})

type LoginForm = z.infer<typeof loginSchema>

// 2. Use the form
function LoginPage() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<LoginForm>({
    resolver: zodResolver(loginSchema),
  })

  const onSubmit = async (data: LoginForm) => {
    await login(data)
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("email")} />
      {errors.email && <p>{errors.email.message}</p>}

      <input type="password" {...register("password")} />
      {errors.password && <p>{errors.password.message}</p>}

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? "Logging in..." : "Login"}
      </button>
    </form>
  )
}

import { emailSchema, urlSchema, passwordSchema } from "common/src/utils/validations"

// src/model/website.ts
const API_URL = import.meta.env.VITE_API_URL

export const fetchWebsiteList = async (orgId: string): Promise<Website[]> => {
  const token = getCookie("access_token")

  const res = await fetch(`${API_URL}api/website/?org_id=${orgId}`, {
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  })

  const json = await res.json()
  if (!json.success) throw new Error(json.message)
  return json.data
}

import { getCookie } from "common/src/utils/common"

const token = getCookie("access_token")
// → "Bearer eyJhbGci..."

// ✅ Correct
<div className="wy-flex wy-items-center wy-gap-4 wy-p-6">

// ❌ Wrong — unprefixed won't work
<div className="flex items-center gap-4 p-6">

import { clsx } from "clsx"
import { twMerge } from "tailwind-merge"

// Helper (often defined as `cn` in utils)
const cn = (...args: Parameters<typeof clsx>) => twMerge(clsx(...args))

// Usage
<div className={cn(
  "wy-rounded-lg wy-p-4",
  isActive && "wy-bg-webyes-primary wy-text-white",
  isDisabled && "wy-opacity-50 wy-cursor-not-allowed",
)}>

wy-bg-webyes-primary    → Primary brand color
wy-bg-webyes-secondary  → Secondary color
wy-bg-webyes-IN         → Info/neutral
wy-bg-webyes-DE         → Destructive/danger