vinext

vinext is the Next.js API surface, reimplemented on Vite by Cloudflare. This template provides a production-ready starting point optimized for 4.4x faster builds, 57% smaller bundles, and instant deployment to Cloudflare Workers.

Tech Stack

Technology	Version	Purpose
Vite	Latest	Lightning-fast build tool
React	19.x	UI library
TypeScript	5.x	Type safety
Tailwind CSS	v4	Utility-first styling
shadcn/ui	Latest	Accessible component library
GSAP	3.x	Professional animations
React Hook Form	7.x	Form state management
Zod	4.x	Schema validation
Vitest	3.x	Unit & integration testing
Prettier	3.x	Code formatting
Cloudflare Workers	Latest	Edge runtime deployment
pnpm	Latest	Fast, disk-efficient package manager

Features

• Next.js Alternative: A full App Router reimplementation built by Cloudflare for the modern web.
• Blazing Performance: Up to 4.4x faster builds and 57% smaller client bundles vs standard Next.js.
• Edge-First Architecture: Runs natively on Cloudflare Workers for ultra-low latency globally.
• File-Based Routing: Familiar Next.js-style routing powered by Vite — no framework lock-in.
• Design System: Enforced typography (4 sizes, 2 weights), 8pt grid spacing, and 60/30/10 color rule
• Animation Infrastructure: GSAP with useGSAP hook pattern, responsive animations via matchMedia(), and motion tokens
• Component Library: Pre-configured shadcn/ui with Radix UI primitives for accessibility
• Form Handling: React Hook Form + Zod integration with shadcn Form components
• Type Safety: Strict TypeScript with no any types
• Dark Mode: CSS variable-based theming with OKLCH color format

Getting Started

Prerequisites

• Node.js 18.x or later
• pnpm (recommended) or npm

Installation

# Clone the repository
git clone https://github.com/itsyasirkhandev/vinext.git
cd vinext

# Install dependencies
pnpm install

Development

# Start development server
pnpm dev

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

Build

# Production build
pnpm build

# Preview production build locally
pnpm preview

# Run tests
pnpm test

# Run tests (watch mode)
pnpm test:watch

# Run tests (coverage report)
pnpm test:coverage

Linting

# Run ESLint
pnpm lint

# Fix lint errors
pnpm lint --fix

Project Structure

├── app/                    # App Router (file-based routing)
│   ├── layout.tsx          # Root layout
│   ├── page.tsx            # Home page (template overview)
│   ├── error.tsx           # Global error boundary
│   ├── not-found.tsx       # Custom 404 page
│   ├── providers.tsx       # Client providers wrapper
│   ├── globals.css         # Global styles + Tailwind v4 theme
│   └── gemini.md           # App-specific AI agent guidance
│
├── components/             # Shared UI components
│   └── ui/                 # shadcn/ui components
│
├── features/               # Feature-based modules
│   └── <feature>/          # Self-contained feature
│       ├── components/     # Feature-specific components
│       ├── hooks/          # Feature-specific hooks
│       ├── services/       # Feature-specific API calls
│       ├── types/          # Feature-specific types
│       └── index.ts        # Barrel export
│
├── hooks/                  # Shared hooks (2+ features)
├── lib/                    # Infrastructure
│   ├── gsapConfig.ts       # GSAP setup + plugin registration
│   └── utils.ts            # Utility functions (cn, etc.)
│
├── constants/              # App constants
│   └── animationTokens.ts  # Duration, ease, stagger values
│
├── types/                  # Shared TypeScript types
├── schemas/                # Shared Zod validation schemas
│
├── test/                   # Test infrastructure
│   ├── setup.ts            # Global test setup
│   ├── mocks/              # Test mocks
│   └── fixtures/           # Test fixtures
│
├── public/                 # Static assets
│
├── vitest.config.ts        # Vitest test runner config
├── .prettierrc             # Code formatting config
├── .env.example            # Environment variable template
├── rules.md                # Code conventions (MUST READ)
├── design-system.md        # UI/design rules (MUST READ)
├── animations-guide.md     # GSAP animation rules (MUST READ)
└── GEMINI.md               # AI agent guidance

Documentation

Before contributing, read these files in order:

1. rules.md — Code conventions, naming, folder structure, git commits, forms
2. design-system.md — Typography, spacing, colors, components, accessibility
3. animations-guide.md — GSAP setup, hooks, ScrollTrigger, responsive animations

Adding Components

shadcn/ui Components

# Add a component
pnpm dlx shadcn-ui@latest add button
pnpm dlx shadcn-ui@latest add card
pnpm dlx shadcn-ui@latest add form input select

Components install to components/ui/.

Creating Features

# Create a new feature module
mkdir -p features/my-feature/{components,hooks,services,types}
touch features/my-feature/index.ts

Follow the Feature Module Rules for structure and barrel exports.

Design System Quick Reference

Rule	Details
Typography	4 sizes, 2 weights (semibold + regular only)
Spacing	8pt grid — every value divisible by 8 or 4
Colors	60% neutral / 30% complementary / 10% accent
Components	shadcn/ui first — never rebuild what exists
Forms	react-hook-form + zodResolver + shadcn Form
Dark Mode	CSS variables + .dark class

Animation Quick Reference

Rule	Details
Import	Always from @/lib/gsapConfig — never from "gsap"
Hook	useGSAP with { scope: containerRef } — never useEffect
Selectors	anim- prefix on all GSAP target classes
Tokens	Use values from animationTokens.ts — never hardcode
Responsive	gsap.matchMedia() required for breakpoint-specific animations
Accessibility	prefers-reduced-motion check in every animation hook

Code Style

• Prettier for formatting
• ESLint for code quality
• 2-space indentation
• Single quotes (JS/TS), double quotes (JSX attributes)
• Trailing commas (ES5)
• Max 100 chars (soft) / 120 (hard)

Git Conventions

Commit Format

<type>(<scope>): <description>

Types

Type	Use
feat	New feature
fix	Bug fix
docs	Documentation
style	Formatting only
refactor	No new feature or fix
test	Tests
chore	Build, deps, tooling

Examples

feat(auth): add Google OAuth login
fix(cart): prevent negative quantity
refactor(products): extract validation to shared schema

Scripts

Command	Description
pnpm dev	Start development server
pnpm build	Production build
pnpm preview	Preview production build locally
pnpm lint	Run ESLint
pnpm lint --fix	Fix lint errors
pnpm test	Run tests once
pnpm test:watch	Run tests in watch mode
pnpm test:coverage	Run tests with coverage report
pnpm format	Format all files with Prettier
pnpm format:check	Check formatting without changes

Deployment

Deploy to the edge instantly with Cloudflare Workers:

# Deploy to Cloudflare Workers
pnpm deploy

Or use the Cloudflare Dashboard to connect your GitHub repo for automatic deployments on every push.

Learn More

• Vite Documentation — build tool and dev server
• Cloudflare Workers Docs — edge runtime
• shadcn/ui Documentation — component library
• GSAP Documentation — animation library

License

MIT License — feel free to use for personal and commercial projects.

---

Last updated: 2026-02-27