ByteNoteByteNote
字

字节笔记本

2026年2月22日

CodeGuide Starter Kit - Next.js 15 全栈启动模板

#开源工具

本文介绍 CodeGuide Starter Kit，一个基于 Next.js 15 的现代化全栈 Web 应用启动模板。该项目集成了认证、数据库、AI 能力和暗黑模式，帮助开发者快速构建生产级应用。

项目简介

CodeGuide Starter Kit 是由 CodeGuide.dev 开发的开源启动模板，旨在为开发者提供一个功能完备、架构现代的 Web 应用起点。截至目前，该项目在 GitHub 上已获得 514+ stars 和 109+ forks，主要使用 TypeScript 编写。

该项目特别适合：

  • 需要快速启动全栈项目的开发者
  • 希望学习现代 Next.js 技术栈的工程师
  • 需要使用 AI 集成的应用场景

核心特性

  • 🔐 认证系统：基于 Clerk 的完整认证流程，包含中间件保护
  • 🗄️ 数据库集成：Supabase 数据库与第三方认证深度整合
  • 🤖 AI 聊天界面：支持 OpenAI/Anthropic 的 AI 对话功能
  • 🎨 丰富组件库：40+ 个 shadcn/ui 组件（New York 风格）
  • 🌙 暗黑模式：支持系统偏好检测的暗黑主题
  • 🎯 设置仪表板：内置服务状态监控和配置向导
  • 🚀 App Router：基于 Next.js 15 App Router 的现代化架构
  • 🔒 行级安全：RLS 策略示例，使用 Clerk 用户 ID
  • 📱 响应式设计：基于 TailwindCSS v4 的移动端适配
  • 🎨 自定义字体：Geist Sans、Geist Mono、Parkinsans

技术栈

技术用途
Next.js 15React 全栈框架（App Router）
TypeScript类型安全的开发语言
Clerk用户认证与授权
SupabasePostgreSQL 数据库与后端服务
Tailwind CSS v4原子化 CSS 样式框架
shadcn/ui高质量 React 组件库
Vercel AI SDKAI 功能集成
next-themes主题管理

安装指南

前置要求

  • Node.js 18+
  • Clerk 账号（用于认证）
  • Supabase 账号（用于数据库）
  • 可选：OpenAI 或 Anthropic API Key（用于 AI 功能）

快速开始

bash
# 克隆仓库
git clone https://github.com/CodeGuide-dev/codeguide-starter-lite.git
cd codeguide-starter-lite

# 安装依赖
npm install
# 或 yarn install
# 或 pnpm install

# 配置环境变量
cp .env.example .env.local

# 启动开发服务器
npm run dev

访问 http://localhost:3000 查看应用。

环境变量配置

创建 .env.local 文件并填写以下变量：

bash
# Clerk 认证
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key
CLERK_SECRET_KEY=your_secret_key

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# AI 集成（可选）
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

项目结构

text
codeguide-starter-kit/
├── src/
│   ├── app/                    # Next.js App Router 页面
│   │   ├── api/chat/          # AI 聊天 API 端点
│   │   ├── globals.css        # 全局样式
│   │   ├── layout.tsx         # 根布局
│   │   └── page.tsx           # 首页 + 设置仪表板
│   ├── components/            # React 组件
│   │   ├── ui/                # shadcn/ui 组件
│   │   ├── chat.tsx           # AI 聊天界面
│   │   ├── theme-provider.tsx # 主题上下文
│   │   └── theme-toggle.tsx   # 暗黑模式切换
│   ├── lib/                   # 工具函数
│   │   ├── supabase.ts        # Supabase 客户端
│   │   ├── user.ts            # 用户工具
│   │   ├── utils.ts           # 通用工具
│   │   └── env-check.ts       # 环境验证
│   └── middleware.ts          # Clerk 路由保护
├── supabase/
│   └── migrations/            # 数据库迁移（含 RLS 示例）
├── CLAUDE.md                  # AI 编码助手文档
├── SUPABASE_CLERK_SETUP.md    # 集成设置指南
└── components.json            # shadcn/ui 配置

数据库集成

该项目采用现代化的 Clerk + Supabase 集成方案：

  • 第三方认证：使用 Clerk 的官方集成（非废弃的 JWT 模板）
  • 行级安全：RLS 策略使用 auth.jwt() ->> 'sub' 匹配 Clerk 用户 ID
  • 迁移示例：包含多种 RLS 模式（用户私有、公开/私有、协作）
  • 服务端客户端：自动处理 Clerk Token

AI 编码助手集成

项目针对 AI 编码助手（如 Claude Code）进行了优化：

  • CLAUDE.md：提供全面的项目上下文和开发模式
  • 设置指南：详细的集成步骤说明
  • 迁移示例：RLS 策略模板
  • 清晰的文件结构：统一的命名约定
  • TypeScript 集成：完整的类型定义

使用示例

启动开发服务器

bash
npm run dev

构建生产版本

bash
npm run build

数据库迁移

bash
# 使用 Supabase CLI 执行迁移
supabase db push

相关资源

许可证

MIT License - 详见项目 LICENSE 文件。

开源工具
上一篇

腾讯云 Cloud Studio - 开箱即用的云端 IDE

下一篇

CodeGuide Starter Kit - Next.js 15 全栈启动模板

分享: