⚡️ Zion (vite-shadcn-template)

A minimal, modern front-end template built with React, Vite, shadcn/ui, Tailwind CSS, and Zustand.

Zion 是一个为现代 Web 项目而生的极简前端模板，内置通用最佳实践，追求快速启动、低依赖耦合与风格统一，适用于个人项目和团队协作开发等。

---

✨ 特性 Features

• 🧱 shadcn/ui - 现代 UI 组件系统，极简可定制
• ⚡️ Vite - 极速开发构建工具
• 🧠 Zustand - 简洁直观的状态管理
• 🎨 Tailwind CSS - 实用主义原子化 CSS
• 🗂️ 规范目录结构，适合扩展与维护
• 🧩 预配置的实用工具函数、类型声明、环境变量、合约 ABI 管理等

---

🚀 快速开始

• Clone project

pnpm dlx degit Pony-Unicorn/vite-shadcn-template my-project

cd my-project

pnpm i

• Development

pnpm run dev

• Deploy - cloudflare page

pnpm run deploy

---

🧱 Core Dependencies

• react - The library for web and native user interfaces
• vite - Vite 是一个超快的前端构建工具，赋能下一代 Web 应用的发展
• react-router - multi-strategy router for React bridging

🎨 User Interface

• TailwindCSS – Utility-first CSS framework for rapid UI development
• Radix – Primitives like modal, popover, etc. to build a stellar user experience
• ui.shadcn.com components are included in the /components/ui folder
• lucide – Beautiful & consistent icons Made by the community.
• Motion – A modern animation library
• Font animation reference
• Simple Icons - popular brands svg

🛠️ Tooling

• Node Js: Use .nvmrc file for management, the version is lts/iron, it is recommended to use fnm as version management
• pnpm - 包管理器必须使用 pnpm，版本为建议为 lts 版本
• .gitignore -指定有意不跟踪的文件
• ESLint - statically analyzes your code to quickly find problems.
• prettier - Prettier is an opinionated code formatter
• husky - 在提交或推送时，自动化 检查提交信息、检查代码 和 运行测试。
• assetpack - It can be used to transform, combine, compress assets.

⚙️ Environment Configuration

• .env - define environment variables validation for your app.

Third-Party Libraries

• axios - 网络请求
• swr 用于数据请求的 React Hooks 库
• dayjs - 轻量的处理时间和日期的库
• react-hook-form - Form validation library
• zod - TypeScript-first schema validation with static type inference
• zustand - state management libraries for React

🌐 Domain-specific

• Wagmi - Wagmi Reactivity for Ethereum apps
• viem - Ethereum library
• @reown/appkit - Wallet connection manager

🤖 AI Development

• cursor - AI 代码编辑器
  • .cursor/rules: Rules for Cursor AI-assisted development
  • .cursorignore: Files to ignore during AI code operations

🛰️ Deployment

• vercel - vercel Configuring projects

• Cloudflare Pages - Cloudflare Pages

  • 推荐使用 Cloudflare Pages 部署
  • Download your Pages project config npx wrangler pages download config <PROJECT_NAME>

📁 项目目录结构

src/
├── assets/                  # 静态资源（图标、图片等）

├── components/              # 通用组件
│   ├── ui/                  # shadcn/ui 自动生成的 UI 组件
│   ├── layouts/             # 页面布局组件（如 MainLayout、AuthLayout）
│   ├── shared/              # 多页面复用组件（如 Header、Footer）
│   └── elements/            # 小型功能组件（如 Modal、Toast、Loading）

├── constants/               # 所有配置文件和常量
│   ├── api.ts               # 接口地址配置
│   ├── MyToken.abi.json/ts  # 合约 ABI 文件
│   ├── app.ts               # 应用配置（如主题、模式）
│   └── uiLabels.ts          # 按钮/标题等文案常量

├── context/                 # 所有 Context\Provider 相关的逻辑
│   └── AppKitProvider.tsx   # AppKit evm wallet

├── hooks/                   # 自定义 Hook
│   └── useDebounce.ts

├── lib/                     # shadcn/ui 自动生成内容
│   ├── axios.ts             # axios 实例
│   └── utils.ts             # `cn` 函数等自动生成工具

├── pages/                   # 页面组件
│   ├── home/
│   │   ├── index.tsx
│   │   └── components/      # home 页面专属组件
│   │       ├── Hero.tsx
│   │       └── Features.tsx
│   ├── dashboard/
│   │   ├── index.tsx
│   │   └── components/
│   └── login.tsx            # 简单页面可不建子目录

├── store/                   # Zustand 状态管理
│   └── useUserStore.ts

├── types/                   # 类型声明与接口定义
│   ├── user.d.ts            # 全局声明类型
│   ├── api.d.ts             # 接口响应结构，建议所有 api 接口声明在这里

├── utils/                   # 自定义工具函数
│   ├── common.ts            # 通用工具函数
│   ├── format.ts            # 日期/金额、钱包地址等所有格式化工具类
│   ├── validate.ts          # 所有验证工具类

├── index.css                # 全局样式文件，只允许有这一个 css 文件
├── App.tsx                  # 根组件，集中配置路由
├── main.tsx                 # 应用入口文件

✅ Todo List

• husky