virastack 0.0.1 → 1.0.1

package/templates/tanstack/src/components/ui/tabs.tsx

@@ -0,0 +1,46 @@
+import type { ComponentProps } from "react";
+
+import { Tabs as BaseTabs } from "@base-ui/react/tabs";
+
+import { cn } from "@/lib/utils";
+
+export function Tabs({ className, ...props }: ComponentProps<typeof BaseTabs.Root>) {
+  return (
+    <BaseTabs.Root data-slot="tabs" className={cn("flex flex-col gap-3", className)} {...props} />
+  );
+}
+
+export function TabsList({ className, ...props }: ComponentProps<typeof BaseTabs.List>) {
+  return (
+    <BaseTabs.List
+      data-slot="tabs-list"
+      className={cn(
+        "relative inline-flex h-9 w-fit items-center rounded-lg bg-muted p-[3px] text-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function TabsTrigger({ className, ...props }: ComponentProps<typeof BaseTabs.Tab>) {
+  return (
+    <BaseTabs.Tab
+      data-slot="tabs-trigger"
+      className={cn(
+        "inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md px-2 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] outline-none",
+        "text-foreground data-[selected]:bg-background data-[selected]:shadow-sm",
+        "focus-visible:ring-[3px] focus-visible:ring-ring/50",
+        "disabled:pointer-events-none disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function TabsContent({ className, ...props }: ComponentProps<typeof BaseTabs.Panel>) {
+  return (
+    <BaseTabs.Panel data-slot="tabs-content" className={cn("outline-none", className)} {...props} />
+  );
+}

package/templates/tanstack/src/config/seo.config.ts

@@ -0,0 +1,52 @@
+import { siteConfig } from "@/config/site.config";
+
+/** Shared SEO fields used by the root route `head()` and social meta tags. */
+const defaultSeo = {
+  title: siteConfig.name,
+  titleTemplate: `%s · ${siteConfig.name}`,
+  description: siteConfig.description,
+  keywords: ["TanStack Start", "React", "TypeScript", "Tailwind CSS", "ViraStack", "Boilerplate"],
+  authors: [{ name: "ViraStack", url: siteConfig.url }],
+  creator: "ViraStack",
+  openGraph: {
+    type: "website",
+    locale: "en_US",
+    url: siteConfig.url,
+    title: siteConfig.name,
+    description: siteConfig.description,
+    siteName: siteConfig.name,
+    images: [{ url: siteConfig.ogImage, width: 1200, height: 630, alt: siteConfig.name }],
+  },
+  twitter: {
+    card: "summary_large_image",
+    title: siteConfig.name,
+    description: siteConfig.description,
+    images: [siteConfig.ogImage],
+  },
+} as const;
+
+/** Flatten `defaultSeo` into TanStack Router `head().meta` entries. */
+export function seoHeadMeta() {
+  const og = defaultSeo.openGraph;
+  const twitter = defaultSeo.twitter;
+
+  return [
+    { title: defaultSeo.title },
+    { name: "description", content: defaultSeo.description },
+    { name: "keywords", content: defaultSeo.keywords.join(", ") },
+    { name: "author", content: defaultSeo.creator },
+    { name: "creator", content: defaultSeo.creator },
+    { name: "robots", content: "index, follow" },
+    { property: "og:type", content: og.type },
+    { property: "og:locale", content: og.locale },
+    { property: "og:url", content: og.url },
+    { property: "og:title", content: og.title },
+    { property: "og:description", content: og.description },
+    { property: "og:site_name", content: og.siteName },
+    { property: "og:image", content: og.images[0].url },
+    { name: "twitter:card", content: twitter.card },
+    { name: "twitter:title", content: twitter.title },
+    { name: "twitter:description", content: twitter.description },
+    { name: "twitter:image", content: twitter.images[0] },
+  ];
+}

package/templates/tanstack/src/config/site.config.ts

@@ -0,0 +1,15 @@
+import type { SiteConfig } from "@/types/site-config.types";
+import { env } from "@/env";
+
+// FIXME: replace with your own site metadata.
+export const siteConfig: SiteConfig = {
+  name: env.VITE_APP_NAME,
+  description:
+    "Premium TanStack Start boilerplate built for scalable UI/UX, clean architecture, and agent-ready developer experience.",
+  url: env.VITE_APP_URL,
+  ogImage: `${env.VITE_APP_URL}/og.png`,
+  links: {
+    github: "https://github.com/virastack/start",
+    twitter: "https://x.com/virastack",
+  },
+};

package/templates/tanstack/src/constants/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared constants promoted out of features (Rule of Three).
+ * Feature-scoped constants live under `src/features/[feature]/constants`.
+ */
+export {};

package/templates/tanstack/src/env.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+/**
+ * Type-safe environment variable schema.
+ *
+ * Client-exposed variables MUST be prefixed with `VITE_` (Vite inlines these
+ * at build time). Server-only variables have no prefix and must never be
+ * read via `import.meta.env` on the client.
+ */
+const serverSchema = z.object({
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+});
+
+const clientSchema = z.object({
+  VITE_APP_URL: z.string().url().default("http://localhost:3000"),
+  VITE_APP_NAME: z.string().min(1).default("ViraStack Start - TanStack Edition"),
+});
+
+function readEnv(key: string): string | undefined {
+  if (typeof process !== "undefined" && process.env[key] != null) {
+    return process.env[key];
+  }
+  return (import.meta.env as Record<string, string | undefined>)[key];
+}
+
+const serverParsed = serverSchema.safeParse({
+  NODE_ENV: readEnv("NODE_ENV"),
+});
+
+const clientParsed = clientSchema.safeParse({
+  VITE_APP_URL: readEnv("VITE_APP_URL"),
+  VITE_APP_NAME: readEnv("VITE_APP_NAME"),
+});
+
+if (!serverParsed.success || !clientParsed.success) {
+  console.error(
+    "❌ Invalid environment variables:",
+    serverParsed.error?.flatten().fieldErrors,
+    clientParsed.error?.flatten().fieldErrors,
+  );
+  throw new Error("Invalid environment variables. Check src/env.ts");
+}
+
+export const env = {
+  ...serverParsed.data,
+  ...clientParsed.data,
+};

package/templates/tanstack/src/features/landing/api/get-users.api.ts

@@ -0,0 +1,7 @@
+import { api } from "@/lib/api";
+
+import type { User } from "@/features/landing/types";
+
+export function getUsers(signal?: AbortSignal) {
+  return api.get<User[]>("https://jsonplaceholder.typicode.com/users?_limit=5", { signal });
+}

package/templates/tanstack/src/features/landing/api/index.ts

@@ -0,0 +1,2 @@
+export { getUsers } from "@/features/landing/api/get-users.api";
+export { userKeys } from "@/features/landing/api/query-keys";

package/templates/tanstack/src/features/landing/api/query-keys.ts

@@ -0,0 +1,7 @@
+export const userKeys = {
+  all: ["users"] as const,
+  lists: () => [...userKeys.all, "list"] as const,
+  list: (filters?: object) => [...userKeys.lists(), { filters }] as const,
+  details: () => [...userKeys.all, "detail"] as const,
+  detail: (id: string) => [...userKeys.details(), id] as const,
+};

package/templates/tanstack/src/features/landing/components/CartDemo.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { MinusIcon, PlusIcon, ShirtIcon, Trash2Icon } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import { useCounterStore } from "@/features/landing/stores";
+
+/**
+ * Demonstrates global client state with Zustand via a mini cart UI.
+ */
+export function CartDemo() {
+  const { count, increment, decrement, reset } = useCounterStore();
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-4 rounded-xl border border-border/50 bg-background/50 p-3">
+        <div className="flex h-12 w-12 shrink-0 items-center justify-center rounded-lg bg-primary/10 text-primary">
+          <ShirtIcon className="size-6" />
+        </div>
+        <div className="flex flex-1 flex-col">
+          <h5 className="font-medium text-foreground">Cotton T-Shirt</h5>
+          <p className="text-sm text-muted-foreground">White / XL</p>
+        </div>
+        <div className="flex flex-col items-end gap-1">
+          <span className="font-semibold text-foreground">{count * 350}</span>
+          <span className="text-xs text-muted-foreground">Total</span>
+        </div>
+      </div>
+
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Button
+            variant="outline"
+            size="icon"
+            className="h-8 w-8 rounded-full"
+            aria-label="Decrement"
+            onClick={decrement}
+            disabled={count === 0}
+          >
+            <MinusIcon className="size-4" />
+          </Button>
+          <span className="w-6 text-center font-medium tabular-nums">{count}</span>
+          <Button
+            variant="outline"
+            size="icon"
+            className="h-8 w-8 rounded-full"
+            aria-label="Increment"
+            onClick={increment}
+          >
+            <PlusIcon className="size-4" />
+          </Button>
+        </div>
+        <Button
+          variant="ghost"
+          size="sm"
+          className="h-8 gap-1.5 px-2 text-muted-foreground hover:text-destructive"
+          onClick={reset}
+          disabled={count === 0}
+        >
+          <Trash2Icon className="size-3.5" />
+          <span className="text-xs">Clear</span>
+        </Button>
+      </div>
+    </div>
+  );
+}

package/templates/tanstack/src/features/landing/components/Features.tsx

@@ -0,0 +1,39 @@
+import { RevealGroup, RevealItem } from "@/features/landing/components/Reveal";
+import { FEATURES } from "@/features/landing/data";
+import { featureCardClassName } from "@/features/landing/helpers";
+
+export function Features() {
+  return (
+    <section id="features" className="mx-auto max-w-5xl px-6 py-16">
+      <RevealGroup className="mb-16 text-center">
+        <RevealItem>
+          <h2 className="text-3xl font-semibold tracking-tight text-balance">Features</h2>
+        </RevealItem>
+        <RevealItem>
+          <p className="mx-auto mt-3 max-w-xl text-base text-balance text-muted-foreground">
+            Everything you need to build a modern web application, already configured with the best
+            practices.
+          </p>
+        </RevealItem>
+      </RevealGroup>
+
+      <RevealGroup className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+        {FEATURES.map((feature) => (
+          <RevealItem key={feature.title} className={featureCardClassName}>
+            <div className="mb-2 flex h-12 w-12 items-center justify-center rounded-xl bg-primary/10 transition-transform duration-200 ease-out group-hover:scale-105">
+              {feature.icon}
+            </div>
+            <div className="flex flex-col gap-1.5">
+              <h3 className="text-base font-semibold text-balance text-foreground md:text-lg">
+                {feature.title}
+              </h3>
+              <p className="text-sm leading-relaxed text-pretty text-muted-foreground">
+                {feature.description}
+              </p>
+            </div>
+          </RevealItem>
+        ))}
+      </RevealGroup>
+    </section>
+  );
+}

package/templates/tanstack/src/features/landing/components/Hero.tsx

@@ -0,0 +1,63 @@
+import { siteConfig } from "@/config/site.config";
+
+import { ThemeToggle } from "@/components/shared/ThemeToggle";
+import { Button } from "@/components/ui/button";
+import { Reveal } from "@/features/landing/components/Reveal";
+import { ReactIcon, TailwindIcon, TanstackIcon } from "@/features/landing/icons";
+
+export function Hero() {
+  return (
+    <section className="mx-auto flex max-w-3xl flex-col items-center gap-6 px-6 pt-24 pb-16 text-center">
+      <Reveal mode="mount" delay={0} y={-8}>
+        <span className="rounded-full border border-border px-3 py-1 text-xs font-medium text-muted-foreground">
+          Premium UI/UX · Agent-ready · Zero bloat
+        </span>
+      </Reveal>
+
+      <h1 className="mb-2 text-center text-4xl lg:text-6xl">
+        <span className="font-black text-primary">ViraStack</span>{" "}
+        <span className="font-medium text-teal-500 italic">Start</span>
+        <span className="mt-2 block text-lg font-normal text-muted-foreground lg:text-xl">
+          TanStack Edition
+        </span>
+      </h1>
+
+      <p className="max-w-2xl text-base leading-relaxed text-balance text-muted-foreground sm:text-lg">
+        Built with{" "}
+        <span className="inline-flex items-center gap-1 font-semibold text-foreground">
+          <TanstackIcon className="h-4 w-4" />
+          TanStack Start
+        </span>
+        ,{" "}
+        <span className="inline-flex items-center gap-1 font-semibold text-foreground">
+          <ReactIcon className="h-4 w-4" />
+          React 19
+        </span>
+        , and{" "}
+        <span className="inline-flex items-center gap-1 font-semibold text-foreground">
+          <TailwindIcon className="h-4 w-4" />
+          Tailwind CSS 4
+        </span>{" "}
+        - wired together with <span className="font-medium text-foreground italic">
+          Zustand
+        </span>, <span className="font-medium text-foreground italic">TanStack Query</span>, and{" "}
+        <span className="font-medium text-foreground italic">React Hook Form</span> so you can ship
+        a polished product from day one.
+      </p>
+
+      <Reveal mode="mount" delay={0.1} className="mt-2 flex items-center gap-2">
+        <Button
+          className="h-10 px-4 py-2"
+          nativeButton={false}
+          render={<a href={siteConfig.links.github} target="_blank" rel="noreferrer" />}
+        >
+          <span>⭐</span>
+          <span>Star on GitHub</span>
+        </Button>
+        <div className="h-10 w-10 [&>button]:h-full [&>button]:w-full">
+          <ThemeToggle />
+        </div>
+      </Reveal>
+    </section>
+  );
+}

package/templates/tanstack/src/features/landing/components/LandingPage.tsx

@@ -0,0 +1,17 @@
+import { Features } from "@/features/landing/components/Features";
+import { Hero } from "@/features/landing/components/Hero";
+import { Showcase } from "@/features/landing/components/Showcase";
+
+/**
+ * Demo landing surface. Delete `src/features/landing` and replace
+ * `src/routes/index.tsx` when you start your own product UI.
+ */
+export function LandingPage() {
+  return (
+    <main className="flex-1">
+      <Hero />
+      <Features />
+      <Showcase />
+    </main>
+  );
+}

package/templates/tanstack/src/features/landing/components/ProjectFormDemo.tsx

@@ -0,0 +1,63 @@
+"use client";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { Controller, useForm } from "react-hook-form";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { FieldDescription, FieldError } from "@/components/ui/field";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { projectSchema } from "@/features/landing/schemas";
+import type { ProjectInput } from "@/features/landing/schemas";
+
+export function ProjectFormDemo() {
+  const {
+    control,
+    handleSubmit,
+    reset,
+    formState: { errors, isSubmitting },
+  } = useForm<ProjectInput>({
+    resolver: zodResolver(projectSchema),
+    defaultValues: { name: "" },
+  });
+
+  async function onSubmit(values: ProjectInput) {
+    await new Promise((resolve) => setTimeout(resolve, 600));
+    toast.success(`Created project: ${values.name}`);
+    reset();
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} noValidate className="flex flex-col gap-4">
+      <div className="flex flex-col gap-2.5 text-left">
+        <Label htmlFor="name">Project Name</Label>
+        <Controller
+          control={control}
+          name="name"
+          render={({ field }) => (
+            <Input
+              id="name"
+              type="text"
+              placeholder="virastack-app"
+              aria-invalid={!!errors.name}
+              value={field.value}
+              onChange={(event) => field.onChange(event.target.value)}
+              onBlur={field.onBlur}
+              ref={field.ref}
+            />
+          )}
+        />
+        {errors.name ? (
+          <FieldError>{errors.name.message}</FieldError>
+        ) : (
+          <FieldDescription>Use 3–50 characters for the project name.</FieldDescription>
+        )}
+      </div>
+
+      <Button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? "Creating…" : "Create Project"}
+      </Button>
+    </form>
+  );
+}

package/templates/tanstack/src/features/landing/components/Reveal.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import { motion } from "framer-motion";
+
+import { fadeInUp, staggerContainer, viewport } from "@/features/landing/helpers";
+
+type RevealProps = {
+  children: ReactNode;
+  className?: string;
+  /** Mount animation delay in seconds (hero-style). Ignored when `mode="view"`. */
+  delay?: number;
+  /** `mount` = animate on load; `view` = animate when scrolled into view. */
+  mode?: "mount" | "view";
+  /** Initial Y offset for mount animations. */
+  y?: number;
+  /**
+   * When false (mount mode), only translate — keep opacity at 1 so LCP text
+   * is painted on first frame. Default true.
+   */
+  fadeOpacity?: boolean;
+};
+
+/**
+ * Client-only motion shell. Keep copy/markup in Server Components and wrap
+ * animated regions with this so the page stays SSR-first.
+ */
+export function Reveal({
+  children,
+  className,
+  delay = 0,
+  mode = "view",
+  y = 12,
+  fadeOpacity = true,
+}: RevealProps) {
+  if (mode === "mount") {
+    return (
+      <motion.div
+        className={className}
+        initial={fadeOpacity ? { opacity: 0, y } : { y }}
+        animate={fadeOpacity ? { opacity: 1, y: 0 } : { y: 0 }}
+        transition={{ duration: 0.45, delay, ease: "easeOut" }}
+      >
+        {children}
+      </motion.div>
+    );
+  }
+
+  return (
+    <motion.div
+      className={className}
+      initial="hidden"
+      whileInView="visible"
+      viewport={viewport}
+      variants={fadeInUp}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+export function RevealGroup({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <motion.div
+      className={className}
+      initial="hidden"
+      whileInView="visible"
+      viewport={viewport}
+      variants={staggerContainer}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+export function RevealItem({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <motion.div className={className} variants={fadeInUp}>
+      {children}
+    </motion.div>
+  );
+}

package/templates/tanstack/src/features/landing/components/Showcase.tsx

@@ -0,0 +1,66 @@
+import { siteConfig } from "@/config/site.config";
+
+import { formatDate } from "@/helpers";
+
+import { CartDemo } from "@/features/landing/components/CartDemo";
+import { ProjectFormDemo } from "@/features/landing/components/ProjectFormDemo";
+import { RevealGroup, RevealItem } from "@/features/landing/components/Reveal";
+import { UsersDemo } from "@/features/landing/components/UsersDemo";
+import { featureCardClassName } from "@/features/landing/helpers";
+
+export function Showcase() {
+  return (
+    <section id="showcase" className="mx-auto max-w-5xl px-6 pb-16">
+      <RevealGroup className="mb-10 text-center">
+        <RevealItem>
+          <h2 className="text-3xl font-semibold tracking-tight text-balance">Showcase</h2>
+        </RevealItem>
+        <RevealItem>
+          <p className="mx-auto mt-3 max-w-2xl text-base text-balance text-muted-foreground">
+            Experience the seamless integration of UI components and state management.
+          </p>
+        </RevealItem>
+      </RevealGroup>
+
+      <RevealGroup className="grid grid-cols-1 gap-6 lg:grid-cols-2 lg:items-stretch">
+        <RevealItem className={`${featureCardClassName} h-full min-h-0 [&>*]:min-h-0 [&>*]:flex-1`}>
+          <UsersDemo />
+        </RevealItem>
+
+        <div className="flex flex-col gap-6">
+          <RevealItem className={featureCardClassName}>
+            <div className="mb-4">
+              <h4 className="text-base font-semibold text-foreground md:text-lg">New Project</h4>
+              <p className="mt-1 text-sm text-pretty text-muted-foreground">
+                Validated forms with{" "}
+                <span className="font-semibold text-foreground">React Hook Form</span> and{" "}
+                <span className="font-semibold text-foreground">Zod</span>.
+              </p>
+            </div>
+            <ProjectFormDemo />
+          </RevealItem>
+
+          <RevealItem className={`${featureCardClassName} flex flex-col`}>
+            <div>
+              <h4 className="text-base font-semibold text-foreground md:text-lg">Global State</h4>
+              <p className="mt-1 text-sm text-pretty text-muted-foreground">
+                Shared client state managed with{" "}
+                <span className="font-semibold text-foreground">Zustand</span>.
+              </p>
+            </div>
+            <CartDemo />
+          </RevealItem>
+        </div>
+      </RevealGroup>
+
+      <div className="mt-20 flex flex-col items-center justify-center gap-2 text-sm text-muted-foreground">
+        <p suppressHydrationWarning>
+          © {new Date().getFullYear()} {siteConfig.name}. MIT Licensed.
+        </p>
+        <p className="italic" suppressHydrationWarning>
+          Last built on {formatDate(new Date())}.
+        </p>
+      </div>
+    </section>
+  );
+}