A fast, modular Web3 starter built with React Router, shadcn/ui, Tailwind CSS, Motion, and the latest in wallet tooling: Wagmi, viem, and @reown/appkit.
Bolt 是一款专为 Web3 DApp 开发打造的现代前端模板，内置最先进的钱包接入工具与设计系统，结合主流最佳实践，旨在帮助开发者以更快速度构建高质量的链上应用。
- 每月 10 号定期更新所安装的前端依赖（如 npm 包等），以保持项目的安全性和兼容性。更新内容包括但不限于：
- 安全补丁与漏洞修复
- 小版本功能更新
- 与主要依赖库的适配更新
- 如遇重大版本更新，会根据变更内容评估其影响，并视情况推迟合并。
- 欢迎社区成员在该日之前提交依赖更新的建议或 PR 🙌
- 🧱 React Router + shadcn/ui — 强大且现代的全栈 UI 架构
- 🎨 Tailwind CSS — 原子化 CSS，快速搭建响应式 UI
- 🌀 Framer Motion — 炫酷且顺滑的动画体验
- 🔐 Wagmi + viem — 下一代 EVM 钱包交互工具
- 🚀 @reown/appkit — 一站式 DApp 构建集成方案
- 🧹 Prettier — 代码风格统一
- ⚙️ 约定式目录结构 — 支持合约 ABI、env 环境变量、类型声明等规范组织
- ⏱ 开箱即用 — 快速启动，支持拓展与定制
快速启动，模块清晰，组件现代，Bolt 是你构建下一代 Web3 应用的理想起点。
- Clone project
pnpm dlx degit Pony-Unicorn/web3-framework my-project
cd my-project
pnpm i- Development
pnpm run dev- Deploy - cloudflare page
pnpm run deploy- react - The library for web and native user interfaces
- react router - React Router
- TailwindCSS – Utility-first CSS framework for rapid UI development
- Radix – Primitives like modal, popover, etc. to build a stellar user experience
- shadcn/ui - components are included in the
/components/uifolder - lucide – Beautiful & consistent icons Made by the community.
- Motion – A modern animation library
- Font animation reference
- Simple Icons - popular brands svg
- Node Js: Use .nvmrc file for management, the version is lts/iron, it is recommended to use fnm as version management
- pnpm - The package manager must be pnpm, and the recommended version is the LTS version.
- .gitignore - Git ignore files
- prettier - Prettier is an opinionated code formatter
- .env - define environment variables validation for your app.
- development .env.development.local
- production .env.production.local
- ky - Tiny & elegant JavaScript HTTP client based on the Fetch API
- TanStack Query - React Hooks library for data requests
- dayjs - Lightweight processing time and date library
- react-hook-form - Form validation library
- zod - TypeScript-first schema validation with static type inference
- zustand A small, fast, and scalable bearbones state management solution.
- Wagmi - Wagmi Reactivity for Ethereum apps
- viem - Ethereum library
- @reown/appkit - Wallet connection manager
- rules - 官方规则参考
- cursor - AI Code Editor
.cursor/rules: Rules for Cursor AI-assisted development.cursorignore: Files to ignore during AI code operations
- vercel - vercel Configuring projects
- Cloudflare Pages - Cloudflare Pages
- Recommend using Cloudflare Pages for deployment
- Download your Pages project config
npx wrangler pages download config <PROJECT_NAME>
- tweakcn - 近乎完美的主题生成器，自定义颜色、字体和布局，以及 AI 生成并实时预览
- tinte - 自带 4000+ 主题同时支持 AI 生成
- rlabs generate - 功能单一的主题生成器，默认也有很多主题可选
- 10000+ Themes - 10000+ 的主题
app/
├── app.css # 全局样式文件，只允许有这一个 css 文件
├── features/ # 业务模块，例如首页、登录、用户中心等
│ └── dashboard/
│ ├── ChartPanel.tsx # 专属组件
│ ├── StatsCard.tsx # 专属组件
│ ├── useProfile.ts # 专属 hook
│ └── types.ts # 专属类型定义
├── components/ # 通用组件
│ ├── ui/ # shadcn/ui 自动生成的 UI 组件
│ ├── react-bits/ # react-bits 自动生成的 UI 组件
│ ├── shared/ # 多页面复用组件（如 Header、Footer）
│ └── elements/ # 小型功能组件（如 Modal、Toast、Loading）
├── constants/ # 所有配置文件和常量
│ ├── api.ts # 接口地址配置
│ ├── MyToken.abi.json/ts # 合约 ABI 文件
│ ├── app.ts # 应用配置（如主题、模式）
│ ├── env.ts # 环境变量
│ └── uiLabels.ts # 按钮/标题等文案常量
├── context/ # 所有 Context\Provider 相关的逻辑
│ └── AppKitProvider.tsx # AppKit evm wallet
├── hooks/ # 自定义 Hook
│ ├── useComputedState.ts # 维护「真实值」与「派生显示值」
│ └── useDebounce.ts
├── lib/ # 第三方库的封装（如 ky、shadcn/ui 工具函数的封装）属于“外部库的适配器”
│ ├── ky.ts # ky 实例，对 ky 的二次封装
│ └── utils.ts # shadcn/ui 的 `cn` 函数自动生成
├── types/ # 类型声明与接口定义
│ ├── user.d.ts # 全局声明类型
│ └── api.d.ts # 接口响应结构，建议所有 api 接口声明在这里
├── utils/ # 通用工具函数，例如格式化地址、校验邮箱等，属于“业务无关的自定义纯工具”
│ ├── common.ts # 通用工具函数
│ ├── format.ts # 日期/金额、钱包地址等所有格式化工具类
│ └── validate.ts # 所有验证工具类
docs/
├── api.md # api 文档
├── overview.md # 项目概述
├── architecture.md # 项目架构
llms/ # llms 文档目录
├── shadcn-ui-llms.txt # shadcn/ui 例 curl -L https://ui.shadcn.com/llms.txt -o shadcn-ui-llms.txt
- 使用 shadcn 命令行安装其他组件，自定义安装路径
-p app/components/react-bits - 查看当前有哪些包已过时
pnpm outdated - 升级到 semver 范围内的最新版本
pnpm up - 将依赖升级到最新版本
pnpm up -L axios
- 修改 ai 相关文档
- 修改描述文档
- 修复控制台错误
- 优化 UI
- 添加合约读取写入界面
- 添加 zustand
- 部署 cf 命令
- ky，对幂等请求加自动重试，结合后端库，TypeScript：给返回值一个“强类型出口”
- 添加 @tanstack/react-query 和 @lukemorales/query-key-factory 示例，读操作不要使用 toast（刷新可使用），使用静态组件显示（封装查询失败的组件），写操作手动触发，可使用 toast 组件，参考https://tanstack.com/query/latest/docs/framework/react/quick-start 需要手动点击刷新的 enabled: false,设置，useQueries 等常用给出示例
- 新建脚本script目录，常用脚本，例如下载 llms 文件，规则等文件
- 安全性，token 基于 only Cookie
- 字体: 字体下载到本地使用避免开发中获取不到谷歌字体问题