Personal TanStack

A personal website built with TanStack Start + React, featuring real-time visitor analytics, geographic tracking, and a modern dark-themed UI using shadcn/ui components and Tailwind CSS.

Tech Stack

• TanStack Start for file-based routing, server components, and a Nitro-powered SSR build pipeline.
• React 19 + TypeScript for a type-safe component architecture.
• Vite 7 as the dev server and bundler with hot module replacement.
• Tailwind CSS 4 with shadcn/ui for a headless, themeable component library.
• Convex for real-time backend with visitor analytics and geolocation tracking.
• Tabler Icons for a comprehensive icon library.
• TanStack Devtools for inspecting router state and queries during development.
• React Simple Maps for interactive geographic visitor visualization.

Features

• Real-time Visitor Tracking: Tracks unique visitors with persistent IDs stored in localStorage.
• Geographic Analytics: Captures visitor location (city, country, coordinates) via server-side IP lookup.
• Analytics Dashboard: View total visitor counts, country distribution, and top visitor locations.
• Interactive Visitor Map: Visualize visitor distribution on an interactive world map.
• Dark Theme: Built-in dark mode with localStorage persistence and Tailwind CSS dark class support.
• Responsive Design: Fully responsive layout optimized for all screen sizes.

Prerequisites

• Node.js 20+ or Bun 1.1+ installed locally.
• A package manager (bun, pnpm, or npm). The repo includes a bun.lock, so bun offers the smoothest experience.
• A Convex project for the backend analytics features.

Quick Start

1. Install dependencies

   bun install

2. Set up Convex backend

   npx convex dev

3. Start the development server

   bun run dev

4. Open http://localhost:3000 in your browser.

Available Scripts

Use your preferred package runner (bun run, pnpm, npm run):

Command	Description
dev	Launches Vite in development mode on port 3000 with HMR and TanStack devtools.
build	Generates a production build via Vite and the Nitro adapter.
preview	Serves the production build locally using Nitro for SSR.
test	Runs unit and component tests with Vitest + Testing Library.
lint	Lints the project with @tanstack/eslint-config.
format	Checks formatting with Prettier (non-destructive).
check	Formats with Prettier, then runs ESLint with --fix.

Project Structure

.
├─ convex/                  # Convex backend schema and functions
│  ├─ _generated/          # Auto-generated Convex types
│  ├─ schema.ts            # Database schema (visitors table)
│  └─ visitors.ts          # Backend functions for visitor tracking
├─ src/
│  ├─ assets/              # Static assets (profile picture, etc.)
│  ├─ components/
│  │  ├─ ui/               # shadcn/ui primitives built on Base UI
│  │  ├─ visitor-counter.tsx # Real-time visitor counter component
│  │  ├─ visitor-map.tsx   # Interactive geographic visitor map
│  │  ├─ navigation.tsx    # Site navigation
│  │  ├─ footer.tsx        # Footer component
│  │  └─ not-found.tsx     # 404 page component
│  ├─ lib/
│  │  ├─ convex.ts         # Convex client configuration
│  │  ├─ visitor.ts        # Visitor geolocation utilities
│  │  ├─ performance.ts    # Performance optimization utilities
│  │  └─ utils.ts          # General utility helpers
│  ├─ routes/
│  │  ├─ __root.tsx        # Root document shell & HTML head setup
│  │  ├─ index.tsx         # Home route
│  │  ├─ analytics.tsx     # Analytics dashboard route
│  │  └─ $.tsx             # 404 catch-all route
│  ├─ router.tsx           # Router factory using the generated route tree
│  ├─ routeTree.gen.ts     # Auto-generated by TanStack Start (do not edit)
│  └─ styles.css           # Tailwind directives and custom styles
├─ components.json         # shadcn/ui CLI configuration & path aliases
├─ vite.config.ts          # Vite + TanStack Start + Tailwind plugin setup
├─ tsconfig.json           # TypeScript config with path aliases (via `@/`)
└─ bun.lock                # Dependency lockfile (Bun)

Development Notes

• Routing follows TanStack Start's file-based convention; add new pages under src/routes using createFileRoute helpers.
• The generated routeTree.gen.ts will auto-update when you add or remove routes; commit the changes to keep the router in sync.
• Convex backend requires npx convex dev running for development. The schema is defined in convex/schema.ts and functions in convex/visitors.ts.
• Visitor tracking uses server-side IP geolocation via a server function to avoid exposing IP addresses in client code.
• Tailwind CSS utilities are available globally. Extend the design system via src/styles.css or by adding tokens in Tailwind's config if needed.
• shadcn/ui components live in src/components/ui. Run bunx shadcn add <component> to import additional primitives defined in components.json.
• TanStack Devtools are enabled by default in the root shell (src/routes/__root.tsx) and render in the browser for faster debugging.
• A floating theme toggle (ThemeToggle) sits in the top-right corner. It remembers the last choice in localStorage and toggles Tailwind's dark class on <html>.

Deploying

1. Deploy the Convex backend: npx convex deploy
2. Produce a production build: bun run build.
3. Preview locally with SSR: bun run preview.
4. Deploy the output using a Nitro-compatible adapter (e.g., Vercel, Netlify, Cloudflare). Nitro handles server rendering and edge deployment strategies.

Customization

• Modify the analytics dashboard in src/routes/analytics.tsx.
• Customize visitor tracking logic in src/components/visitor-counter.tsx and src/lib/visitor.ts.
• Update the database schema in convex/schema.ts and backend functions in convex/visitors.ts.
• Add new routes for sections such as /about, /blog, or /projects under src/routes.
• Customize theming by adjusting Tailwind tokens and shadcn/ui variants.

For deeper guidance, refer to the official docs: TanStack Start, shadcn/ui, Convex, and Tailwind CSS.