create-nextjs-aptos-dapp-template

English | 中文

一个基于 Next.js 和 Aptos SDK 构建的现代化 dApp 模板。

技术栈

• 前端框架: Next.js 15 + React 18
• 区块链: Aptos SDK (@aptos-labs/ts-sdk)
• 钱包适配: @aptos-labs/wallet-adapter-react
• 样式: Tailwind CSS
• 状态管理: React Query
• 合约语言: Move

快速开始

可以直接用npx模板生成器

1npx create-nextjs-aptos-dapp-template

1. 安装依赖

推荐使用 bun.js 作为包管理工具：

1bun install

或者使用 npm：

1npm install

2. 环境配置

请注意.env 文件，可以根据需要进行调整：

1# 网络配置 (devnet/testnet/mainnet)
2NEXT_PUBLIC_NETWORK=devnet
3NEXT_PUBLIC_APTOS_NODE_URL=https://fullnode.devnet.aptoslabs.com/v1
4NEXT_PUBLIC_APTOS_FAUCET_URL=https://faucet.devnet.aptoslabs.com
5
6# Movement 网络配置 (devnet/testnet/mainnet)
7# NEXT_PUBLIC_NETWORK=testnet
8# NEXT_PUBLIC_APTOS_NODE_URL=https://aptos.testnet.porto.movementlabs.xyz/v1
9# NEXT_PUBLIC_APTOS_FAUCET_URL=https://faucet.testnet.porto.movementlabs.xyz
10
11# 合约地址 (部署后填入)
12NEXT_PUBLIC_DEVNET_PACKAGE_ID=""
13NEXT_PUBLIC_TESTNET_PACKAGE_ID=""
14NEXT_PUBLIC_MAINNET_PACKAGE_ID=""

3. 编译和部署 Move 合约

1# 进入合约目录
2cd contracts/counter
3
4# 编译合约
5aptos move compile --dev
6
7# 测试合约
8aptos move test --dev
9
10# 部署合约 (需要配置 Aptos CLI)
11aptos move publish --dev

4. 启动开发服务器

1bun run dev
2# 或
3npm run dev

应用将在 http://localhost:3000 上运行。

项目结构

{YOUR_PROJECT_NAME}/
├── app/                   # Next.js App Router
│   ├── layout.tsx         # 应用布局
│   ├── page.tsx           # 主页面
│   ├── providers.tsx      # 钱包和查询提供者
│   └── globals.css        # 全局样式
├── contracts/             # 合约相关
│   ├── counter/           # 计数器合约源码
│   │   ├── sources/       # 合约源文件
│   │   └── Move.toml      # Move 项目配置
│   ├── config.ts          # 合约地址配置
│   ├── index.ts           # Aptos 客户端配置
│   └── query.ts           # 链上数据查询
├── hooks/                 # React Hooks
│   └── useBetterTx.ts     # 交易处理 Hook
├── utils/                 # 工具函数
│   ├── contractBuilder.ts # 合约交互构建器
│   └── index.ts           # 通用工具函数
├── types/                 # TypeScript 类型定义
│   └── counter.ts         # 计数器相关类型
└── components/            # 可复用组件
    └── WalletSelector.tsx # 钱包选择组件

使用指南

钱包连接

使用 @aptos-labs/wallet-adapter-react 进行钱包连接：

1import { useWallet } from '@aptos-labs/wallet-adapter-react'
2
3const { account, connected, signAndSubmitTransaction } = useWallet()

合约交互

发送交易

1import { useBetterSignAndExecuteTransaction } from '@/hooks/useBetterTx'
2import { buildIncrementCounterTx } from '@/utils/contractBuilder'
3
4const { handleSignAndExecuteTransaction, isLoading } = 
5  useBetterSignAndExecuteTransaction({ tx: buildIncrementCounterTx })
6
7// 执行交易
8handleSignAndExecuteTransaction({})
9  .onSuccess((result) => console.log('Success:', result))
10  .onError((error) => console.error('Error:', error))
11  .execute()

查询数据

1import { getCounterValue } from '@/contracts/query'
2
3const counterValue = await getCounterValue(accountAddress)

合约配置管理

所有合约地址和网络配置都集中在 contracts/config.ts 中管理：

1const configs = {
2    devnet: {
3        CounterModule: process.env.NEXT_PUBLIC_DEVNET_PACKAGE_ID,
4    },
5    testnet: {
6        CounterModule: process.env.NEXT_PUBLIC_TESTNET_PACKAGE_ID,
7    },
8    mainnet: {
9        CounterModule: process.env.NEXT_PUBLIC_MAINNET_PACKAGE_ID,
10    }
11}

开发建议

1. 合约开发: 先在 contracts/counter 目录下开发和测试您的 Move 合约
2. 前端集成: 使用 createBetterTxFactory 创建类型安全的交易函数
3. 状态管理: 利用 React Query 进行链上数据的缓存和同步
4. 钱包集成: 项目已集成 Petra 钱包，可根据需要添加其他钱包

PR 合并自动发布

• 当 PR 合并到 main 分支时，自动发布到 NPM
• 根据提交信息自动确定版本号
• 自动创建 GitHub Release

🤝 贡献

1. Fork 这个仓库
2. 提交你的更改
3. 创建 Pull Request
4. 等待自动测试和审核
5. 合并后自动发布

相关资源

• Aptos 开发文档
• Move 语言指南
• Next.js 文档
• 交易处理方法

许可证

MIT