Skip to main content

Overview

The React Template is TailStack’s frontend-only architecture, providing a modern, high-performance foundation for building client-side applications. It’s perfect for SPAs, dashboards, and applications that consume external APIs.
This template is located at packages/react/ in the TailStack repository.

When to Use This Template

Choose the React template when you:

Separate Backend

Your backend is:
  • A separate service/microservice
  • Third-party API (Firebase, Supabase)
  • Different tech stack (Go, Python, Java)
  • Managed by another team

Frontend Focus

Your project is:
  • Client-side web application
  • Admin dashboard
  • Marketing or landing page
  • Static site with dynamic features

Independent Deployment

You want to:
  • Deploy frontend separately
  • Use CDN for static hosting
  • Scale frontend independently
  • Faster deployment cycles

Specialized Hosting

You’re deploying to:
  • Vercel, Netlify, Cloudflare Pages
  • S3 + CloudFront
  • GitHub Pages
  • Any static hosting

Directory Structure

react/
├── .agent/                          # Gemini agent skills
│   └── skills/
│       ├── tailwind-v4-shadcn/
│       └── vercel-react-best-practices/
├── .claude/                         # Claude agent skills
│   └── skills/                      # (same structure)
├── .cursor/                         # Cursor agent skills
│   └── skills/                      # (same structure)
├── .opencode/                       # OpenCode agent skills
│   └── skills/                      # (same structure)
├── .agents/                         # Trae agent skills
│   └── skills/                      # (same structure)
├── src/
│   ├── api/                         # API client functions
│   ├── components/
│   │   ├── docs/                    # Documentation components
│   │   ├── home/                    # Home page components
│   │   ├── layout/                  # Layout components
│   │   │   ├── footer.tsx
│   │   │   ├── header.tsx
│   │   │   └── sidebar.tsx
│   │   ├── ui/                      # Shadcn UI components
│   │   │   ├── badge.tsx
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── code-block.tsx
│   │   │   ├── input.tsx
│   │   │   ├── scroll-area.tsx
│   │   │   ├── select.tsx
│   │   │   ├── separator.tsx
│   │   │   └── sheet.tsx
│   │   └── weather/                 # Weather demo components
│   ├── config/                      # App configuration
│   ├── constants/                   # Constants and UI variants
│   ├── hooks/                       # Custom React hooks
│   ├── lib/                         # Utility functions
│   │   └── utils.ts                 # cn() for className merging
│   ├── pages/                       # Application pages
│   │   ├── docs/                    # Documentation pages
│   │   ├── home.tsx                 # Home/landing page
│   │   ├── weather.tsx              # Weather demo page
│   │   └── not-found.tsx            # 404 error page
│   ├── types/                       # TypeScript type definitions
│   ├── App.tsx                      # Root application component
│   ├── main.tsx                     # Application entry point
│   └── index.css                    # Global styles + Tailwind
├── public/                          # Static assets
├── index.html                       # HTML entry point
├── .gitignore
├── eslint.config.js                 # ESLint configuration
├── package.json
├── tsconfig.json                    # TypeScript config
├── vite.config.ts                   # Vite configuration
└── README.md

Technology Stack

Core Dependencies

package.json
{
  "dependencies": {
    "react": "^19.2.0",
    "react-dom": "^19.2.0",
    "react-router-dom": "^7.12.0"
  }
}
React 19 features used:
  • React Server Components ready
  • Improved Suspense boundaries
  • Automatic batching
  • New use() hook for async data
React Router 7 provides:
  • File-based routing option
  • Improved data loading
  • Type-safe route params
  • Nested layouts

Shadcn UI Integration

The template comes with shadcn/ui components pre-installed in src/components/ui/:

Button

File: button.tsxVariants: default, destructive, outline, secondary, ghost, linkSizes: default, sm, lg, icon
<Button variant="outline" size="lg">
  Click me
</Button>

Card

File: card.tsxComponents: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>Content</CardContent>
</Card>

Badge

File: badge.tsxVariants: default, secondary, destructive, outline
<Badge variant="secondary">New</Badge>

Input

File: input.tsxAccessible form inputs with proper types
<Input type="email" placeholder="Email" />

Component Pattern

All shadcn components follow this pattern:
src/components/ui/button.tsx
import * as React from "react"
import { cn } from "@/lib/utils"
import { buttonVariants } from "@/constants/ui-variants"
import type { ButtonProps } from "@/types/ui"

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild, children, ...props }, ref) => {
    return (
      <button
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      >
        {children}
      </button>
    )
  }
)
Button.displayName = "Button"

export { Button, buttonVariants }
CVA Pattern: Components use Class Variance Authority for type-safe variant handling. Variants are defined in src/constants/ui-variants.ts for centralized management.

Weather App Demo

The template includes a fully functional weather application at src/pages/weather.tsx:

Features

Real-Time Data

Fetches weather data from external API
  • Current conditions
  • Temperature and humidity
  • Wind speed and direction
  • Weather descriptions

Search & Location

Location-based weather lookup
  • City name search
  • Auto-complete suggestions
  • Geolocation support
  • Recent searches history

Responsive UI

Beautiful on all devices
  • Mobile-first design
  • Tablet optimized
  • Desktop layouts
  • Dark mode support

Error Handling

Graceful error states
  • Loading skeletons
  • Error boundaries
  • Retry mechanisms
  • User-friendly messages

Code Example

src/pages/weather.tsx (simplified)
import { useState, useEffect } from 'react'
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
import { Input } from '@/components/ui/input'
import { Button } from '@/components/ui/button'
import { fetchWeather } from '@/api/weather'

export default function WeatherPage() {
  const [city, setCity] = useState('')
  const [weather, setWeather] = useState(null)
  const [loading, setLoading] = useState(false)

  const handleSearch = async () => {
    setLoading(true)
    const data = await fetchWeather(city)
    setWeather(data)
    setLoading(false)
  }

  return (
    <div className="container mx-auto p-6">
      <Card>
        <CardHeader>
          <CardTitle>Weather Search</CardTitle>
        </CardHeader>
        <CardContent>
          <div className="flex gap-2">
            <Input 
              value={city} 
              onChange={(e) => setCity(e.target.value)}
              placeholder="Enter city name"
            />
            <Button onClick={handleSearch} disabled={loading}>
              Search
            </Button>
          </div>
          {weather && (
            <div className="mt-4">
              <h2>{weather.name}</h2>
              <p>{weather.main.temp}°C</p>
            </div>
          )}
        </CardContent>
      </Card>
    </div>
  )
}

Routing Architecture

React Router 7 configuration in src/App.tsx:
src/App.tsx
import { BrowserRouter, Routes, Route } from 'react-router-dom'
import HomePage from './pages/home'
import WeatherPage from './pages/weather'
import NotFoundPage from './pages/not-found'
import Layout from './components/layout'

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Layout />}>
          <Route index element={<HomePage />} />
          <Route path="weather" element={<WeatherPage />} />
          <Route path="docs/*" element={<DocsRoutes />} />
          <Route path="*" element={<NotFoundPage />} />
        </Route>
      </Routes>
    </BrowserRouter>
  )
}

Layout System

Nested layouts in src/components/layout/:
  • Header: Navigation, logo, theme toggle
  • Sidebar: Secondary navigation for nested routes
  • Footer: Links, copyright, social media

API Client Architecture

Centralized API functions in src/api/:
src/api/weather.ts
import axios from 'axios'

const API_BASE_URL = import.meta.env.VITE_API_URL || 'https://api.example.com'

export const fetchWeather = async (city: string) => {
  const response = await axios.get(`${API_BASE_URL}/weather`, {
    params: { city }
  })
  return response.data
}
Environment Variables: Use VITE_ prefix for environment variables in .env files. They’re statically replaced at build time.

Agent Skills

The React template includes two agent skills:
Location: .agent/skills/vercel-react-best-practices/Categories:
  1. Component Architecture
  2. Performance Optimization
  3. State Management
  4. Data Fetching
  5. Error Boundaries
  6. Accessibility
  7. Testing Strategies
  8. Build Optimization
Rules: 57 total rules with priority levelsExample Rules:
  • Use React.memo() for expensive components
  • Implement code splitting with lazy()
  • Avoid inline functions in JSX
  • Use Suspense boundaries for async data

Development Workflow

Starting Development

pnpm install
pnpm dev
Vite dev server starts at http://localhost:5173

Build for Production

pnpm build
Outputs to dist/:
  • index.html - Entry HTML
  • assets/*.js - JavaScript bundles
  • assets/*.css - CSS bundles
  • All files have content hashes for caching

Preview Production Build

pnpm preview
Starts a local server to preview the production build.

Deployment Options

Deploy to Vercel

Automatic:
  1. Connect GitHub repository
  2. Vercel auto-detects Vite
  3. Deploys on every push
Manual:
pnpm build
vercel --prod
Configuration: vercel.json
{
  "buildCommand": "pnpm build",
  "outputDirectory": "dist",
  "framework": "vite"
}

Comparison with Core Monorepo

FeatureReact TemplateCore Monorepo
Backend❌ External✅ Included (Express)
Frontend✅ Vite + React✅ Vite + React
DeploymentStatic hostingFull-stack or split
ComplexityLowerHigher
Use CaseFrontend-onlyFull-stack
Skills2 skills3 skills
File SizeSmallerLarger

Next Steps

Core Monorepo

Compare with full-stack architecture

Project Structure

Explore detailed directory layout

Getting Started

Set up your first React project

Deployment Guide

Deploy your React application

Build docs developers (and LLMs) love