Next-Stage is a cutting-edge starter template built on Next.js, designed specifically for developers looking to leverage modern web development practices with AI-assisted workflows.
This template combines the latest technologies and best practices to provide a robust foundation for building type-safe, performant web applications.
Demo: https://next-stage-demo.vercel.app/
🛠️ Technology Stack
| Category | Technology |
|---|---|
| Framework | Next.js (App Router) |
| Language | TypeScript |
| Package Manager | Bun |
| API Framework | Hono |
| UI Components | shadcn/ui |
| Styling | Tailwind CSS |
| Form Management | React Hook Form |
| Validation | Zod |
| Linting & Formatting | Biome |
| Markup Linting | Markuplint |
| E2E Testing | Playwright |
| Supply Chain Security | Bun Security Scanner |
🔑 Key Features
Type-Safe Development Environment
Next-Stage provides end-to-end type safety throughout your application:
- TypeScript Integration: Built with TypeScript strict mode for comprehensive type checking
- Zod Validation: Schema-based validation for forms and API requests with type inference
- TypeScript-Safe API Responses: Structured API response types for consistent client-server communication
Modern Frontend Architecture
The template leverages the latest in frontend development:
- Next.js with App Router: Utilizing React Server Components and the latest features
- React: The latest React with improved performance and new features
- Tailwind CSS: Next-generation utility-first CSS framework
- shadcn/ui Components: Beautiful, accessible UI components built with Radix UI
Robust API Layer with Hono
Next-Stage features a powerful API implementation using Hono:
- Efficient Routing: Clean API route organization with Hono's routing system
-
Request Validation: Integrated Zod validation via
@hono/zod-validator - RPC Implementation: Type-safe Remote Procedure Call functionality for seamless client-server communication
Advanced Form Handling
The template includes a comprehensive form management solution:
- React Hook Form: Performant, flexible form management with minimal re-renders
-
Zod Integration: Type-safe form validation through
@hookform/resolvers
Supply Chain Security
Next-Stage implements proactive protection against supply chain attacks:
- Bun Security Scanner: Configurable security scanning before package installation (uses @socketsecurity/bun-security-scanner by default)
- Minimum Release Age: Enforces a 1-day waiting period for new package versions to allow community detection of malicious packages
Developer Experience Optimizations
Next-Stage prioritizes developer productivity:
- Bun Package Manager: Fast, all-in-one JavaScript runtime and package manager
- Turbopack: Default bundler in Next.js for lightning-fast builds and hot module replacement
- Biome: Modern, fast JavaScript/TypeScript linting and formatting (replaces ESLint + Prettier)
- Markuplint: JSX/TSX markup linting for high-quality, accessible UI components
- Playwright: End-to-end testing with browser automation
🤖 AI-Driven Development
Next-Stage is built with AI-assisted development in mind, providing comprehensive support for multiple AI coding tools.
Universal AI Agent Support
The project includes AGENTS.md following the agents.md standard — a universal format that works across all AI coding agents and tools.
Supported AI Tools
AI Editors
| Editor | Configuration Location |
|---|---|
| Cursor | .cursor/rules/ |
| Windsurf | .windsurf/rules/ |
| GitHub Copilot | .github/copilot-instructions.md |
| Kiro | .kiro/steering/ |
AI CLI Tools
| Tool | Configuration File |
|---|---|
| Claude Code | CLAUDE.md |
| Google Gemini CLI | GEMINI.md |
Rule File Hierarchy
The project maintains a hierarchical rule system for consistent AI-driven development:
-
Base Rules (
_llm-rules/directory):-
core-rule.md: Core task execution methodology -
nextjs-rule.md: Next.js specific development patterns -
test-rule.md: Testing guidelines and best practices
-
-
Universal Format:
-
AGENTS.md: Universal format following agents.md standard
-
-
Tool-Specific Files:
-
CLAUDE.md,GEMINI.md, and generated editor-specific rules
-
Generating Editor-Specific Rules
# Generate rules for specific editors
bun run rules:cursor
bun run rules:windsurf
bun run rules:copilot
bun run rules:kiro
# Generate rules for all supported editors
bun run rules
Next.js DevTools MCP Integration
This project includes Next.js DevTools MCP integration for AI coding assistants that support the Model Context Protocol (MCP).
Key MCP Features:
- MCP tools for automating Next.js upgrades and Cache Components setup
- Pre-configured prompts for common Next.js development tasks
- Direct access to Next.js documentation and best practices
- Browser automation integration with Playwright
- Access to internal state, diagnostics, and errors from running dev servers
📁 Project Structure
next-stage/
├── public/ # Static assets
├── src/
│ ├── app/ # App Router routes
│ │ ├── _components/ # Page-specific components
│ │ ├── _styles/ # Page-specific styles
│ │ ├── layout.tsx # Root layout
│ │ └── page.tsx # Home page
│ ├── components/ # Reusable UI components
│ │ ├── layout/ # Layout components (header, footer)
│ │ └── ui/ # shadcn/ui components
│ ├── config/ # Configuration files
│ ├── lib/ # Utility functions
│ └── types/ # Type definitions
├── e2e/ # E2E tests (Playwright)
├── _llm-rules/ # Base rules for AI-assisted development
├── _llm-docs/ # Documentation for AI-assisted development
├── _tasks/ # Build tasks and scripts
├── AGENTS.md # Universal AI agent instructions
├── CLAUDE.md # Claude CLI specific instructions
├── GEMINI.md # Gemini CLI specific instructions
└── ... # Config files
Colocation Pattern
Next-Stage implements the colocation pattern for better organization:
-
Page-specific resources: Components, actions, and hooks are located within the page directory using underscore prefixes (
_components/,_actions/,_hooks/) - Cross-cutting resources: Domain-independent components are kept in top-level directories
- Clear separation: Underscore prefixes distinguish page-specific directories from route segments
🚀 Getting Started
1. Clone the Repository
bunx create-next-app@latest my-app --example https://github.com/Kazuki-tam/next-stage
2. Install Dependencies
cd my-app
bun install
3. Environment Setup (Optional)
cp .env.example .env.local
# Edit .env.local with your environment variables
4. Start the Development Server
bun dev
5. Open Your Browser
Navigate to http://localhost:3000 to see your application running.
📋 Available Commands
| Command | Description |
|---|---|
bun dev |
Start development server |
bun build |
Build for production |
bun start |
Start production server |
bun run lint |
Run all linters |
bun run format |
Format code with Biome |
bun run check |
Run linting, formatting, and type checking |
bun run test:unit |
Run unit tests |
bun run test:e2e |
Run E2E tests with Playwright |
bun run test:e2e:ui |
Run E2E tests with UI mode |
bun run rules |
Generate AI editor rules |
🚢 Deployment
The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.
Check out the Next.js deployment documentation for more details.
✅ Conclusion
Next-Stage provides a solid foundation for modern web application development with Next.js. Its focus on:
- Type Safety: End-to-end TypeScript with Zod validation
- Developer Experience: Fast builds with Turbopack and Bun
- AI-Driven Development: Comprehensive support for AI coding tools
- Modern Stack: React, Tailwind CSS, and the latest ecosystem
Whether you're building a small project or a large-scale application, Next-Stage gives you the tools and patterns needed to succeed, with a special emphasis on leveraging AI assistance to accelerate your development workflow.
Take the next step in your web development journey with Next-Stage!
Top comments (0)