Back to Details

create-aptos-project

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Aptos Project Skill

创建Aptos项目Skill

Purpose

用途

Scaffold new Aptos projects using 
npx create-aptos-dapp
. This is the mandatory first step when a user wants to build any new Aptos app, dApp, or project — regardless of how they phrase it.
使用
npx create-aptos-dapp
搭建新的Aptos项目脚手架。当用户想要构建任何新的Aptos应用、dApp或项目时，无论用户如何表述，这都是强制的第一步。

ALWAYS

必须遵守

  1. Use 
    npx create-aptos-dapp
     to scaffold — NEVER create projects from scratch manually
  2. Ask the user about project type, framework, and network before scaffolding
  3. Verify 
    .env
    is in 
    .gitignore
     before any git operations
  4. Use the same network for both 
    create-aptos-dapp
    and 
    aptos init
  5. Follow the full Build a dApp workflow after scaffolding (contracts, tests, audit, deploy, frontend)
  1. 使用
    npx create-aptos-dapp
    搭建脚手架    ——绝对不要手动从零开始创建项目
  2. 搭建前询问用户项目类型、框架和网络
  3. 执行任何git操作前，确认
    .env
    已加入
    .gitignore
  4. create-aptos-dapp
    和
    aptos init
    使用相同的网络
  5. 搭建完成后遵循完整的dApp构建工作流（合约、测试、审计、部署、前端）

NEVER

禁止操作

  1. Skip scaffolding — even for "simple" projects, always start with 
    create-aptos-dapp
  2. Create project structure manually — the boilerplate template handles this
  3. Display or read private keys — use 
    "0x..."
    as placeholder
  4. Run 
    git add .
    or 
    git add -A
     without first verifying 
    .env
    is in 
    .gitignore
  1. 跳过脚手架搭建——即使是“简单”项目，也始终要从
    create-aptos-dapp
    开始
  2. 手动创建项目结构——脚手架模板已经处理好了这部分
  3. 展示或读取私钥——使用
    "0x..."
    作为占位符
  4. 未验证
    .env
    已加入
    .gitignore
    就执行
    git add .
    或
    git add -A

Decision Tree

决策树

Before running the scaffold command, gather these inputs from the user:
在运行脚手架命令前，从用户处收集以下信息：

1. Project Name

1. 项目名称

Derive from the user's description or ask directly. Use kebab-case (e.g., 
habit-tracker
, 
nft-marketplace
).
从用户的描述中提取，或直接询问用户。使用短横线命名法（例如：
habit-tracker
、
nft-marketplace
）。

2. Project Type

2. 项目类型

OptionWhen to Use
Fullstack (default)User wants a frontend + smart contracts
Contract-onlyUser only wants Move smart contracts (no frontend)
选项适用场景
全栈（默认）用户需要前端 + 智能合约
仅合约用户只需要Move智能合约（无前端）

3. Framework (fullstack only)

3. 框架（仅全栈项目需要）

OptionWhen to Use
Vite (default)Default choice, lighter setup
Next.jsUser asks for Next.js or SSR
选项适用场景
Vite（默认）默认选择，更轻量的配置
Next.js用户要求使用Next.js或SSR

4. Network

4. 网络

OptionWhen to Use
devnet (default)Development and testing
testnetPre-production, user explicitly asks
mainnetProduction, user explicitly asks
选项适用场景
devnet（默认）开发和测试阶段
testnet预生产环境，用户明确要求时使用
mainnet生产环境，用户明确要求时使用

5. API Key (optional)

5. API密钥（可选）

Ask if the user has a Geomi API key. It's optional for devnet but recommended for testnet/mainnet to avoid rate limits. Get one at https://geomi.dev (create project -> API Resource -> copy key).
询问用户是否有Geomi API密钥。devnet环境下可选，但testnet/mainnet环境推荐使用以避免触发速率限制。可在https://geomi.dev获取密钥（创建项目 -> API资源 -> 复制密钥）。

Scaffolding Commands

脚手架命令

bash
undefined
bash
undefined

Fullstack dApp with Vite (frontend + contracts)

基于Vite的全栈dApp（前端 + 合约）

npx create-aptos-dapp <project-name>
--project-type fullstack
--template boilerplate-template
--framework vite
--network <network>
npx create-aptos-dapp <project-name>
--project-type fullstack
--template boilerplate-template
--framework vite
--network <network>

Fullstack dApp with Next.js

基于Next.js的全栈dApp

npx create-aptos-dapp <project-name>
--project-type fullstack
--template boilerplate-template
--framework nextjs
--network <network>
npx create-aptos-dapp <project-name>
--project-type fullstack
--template boilerplate-template
--framework nextjs
--network <network>

Contract-only (Move project)

仅合约（Move项目）

npx create-aptos-dapp <project-name>
--project-type move
--network <network>

**Optional flags:**

- `--api-key <key>` — Pass a Geomi API key during scaffolding
- `--use-surf` — Enable Surf for type-safe contract interactions

---
npx create-aptos-dapp <project-name>
--project-type move
--network <network>

**可选参数：**

- `--api-key <key>` — 搭建时传入Geomi API密钥
- `--use-surf` — 启用Surf实现类型安全的合约交互

---

Post-Scaffold Checklist

脚手架搭建后检查清单

After scaffolding, complete these steps in order:
  1. cd <project-name>
  2. Verify 
    .env
    is in 
    .gitignore
    before any git operations
  3. Run 
    aptos init --network <network> --assume-yes
    (use the same network as above)
  4. Verify: 
    npm run move:compile && npm run move:test
  5. git init && git add . && git commit -m "Initial commit"
搭建完成后，按顺序完成以下步骤：
  1. cd <project-name>
  2. 执行任何git操作前确认
    .env
    已加入
    .gitignore
  3. 运行
    aptos init --network <network> --assume-yes
    （使用和上方相同的网络）
  4. 验证编译和测试：
    npm run move:compile && npm run move:test
  5. git init && git add . && git commit -m "Initial commit"

Build a dApp Workflow

dApp构建工作流

ALWAYS follow this workflow when the user wants to build a new Aptos app, dApp, or project. This applies regardless of how the user phrases it ("build me a ...", "create a ...", "make a ...", "I want to build ...").
  1. /create-aptos-project
    -> scaffold with 
    npx create-aptos-dapp
    (this skill — NEVER skip)
  2. /write-contracts
    -> write Move modules
  3. /generate-tests
    -> create test suite, verify 100% coverage
  4. /security-audit
    -> audit before deployment
  5. /deploy-contracts
    -> deploy contract to specified network
  6. /use-ts-sdk
    -> orchestrates frontend integration (routes to ts-sdk-client, ts-sdk-transactions, ts-sdk-view-and-query, ts-sdk-wallet-adapter as needed)
当用户想要构建新的Aptos应用、dApp或项目时，必须遵循此工作流，无论用户如何表述（"build me a ...", "create a ...", "make a ...", "I want to build ..."）。
  1. /create-aptos-project
    -> 使用
    npx create-aptos-dapp
    搭建脚手架（本技能——绝对不要跳过）
  2. /write-contracts
    -> 编写Move模块
  3. /generate-tests
    -> 创建测试套件，确认100%覆盖率
  4. /security-audit
    -> 部署前安全审计
  5. /deploy-contracts
    -> 将合约部署到指定网络
  6. /use-ts-sdk
    -> 协调前端集成（根据需要路由到ts-sdk-client、ts-sdk-transactions、ts-sdk-view-and-query、ts-sdk-wallet-adapter）

What the Boilerplate Includes

模板包含内容

Fullstack Template

全栈模板

  • contract/
    — Move smart contract with 
    Move.toml
    and starter module
  • frontend/
    — React app with Aptos wallet adapter pre-configured
  • package.json
    — Scripts for 
    move:compile
    , 
    move:test
    , 
    move:publish
    , 
    dev
    , 
    build
  • .env
    — Environment variables for network, API key, and publisher account
  • contract/
    — 包含
    Move.toml
    和入门模块的Move智能合约
  • frontend/
    — 预配置了Aptos钱包适配器的React应用
  • package.json
    — 包含
    move:compile
    、
    move:test
    、
    move:publish
    、
    dev
    、
    build
    等脚本
  • .env
    — 存储网络、API密钥和发布者账户的环境变量

Contract-Only Template

仅合约模板

  • contract/
    — Move smart contract with 
    Move.toml
    and starter module
  • package.json
    — Scripts for 
    move:compile
    , 
    move:test
    , 
    move:publish
  • .env
    — Environment variables for network and publisher account
  • contract/
    — 包含
    Move.toml
    和入门模块的Move智能合约
  • package.json
    — 包含
    move:compile
    、
    move:test
    、
    move:publish
    等脚本
  • .env
    — 存储网络和发布者账户的环境变量

Troubleshooting

故障排查

npx create-aptos-dapp
command not found

提示
npx create-aptos-dapp
命令不存在

bash
undefined
bash
undefined

Auto-confirm the npx package install prompt

自动确认npx包安装提示

npx --yes create-aptos-dapp <project-name> ...

If that still fails, verify Node.js and npm are installed (`node -v && npm -v`).
npx --yes create-aptos-dapp <project-name> ...

如果仍然报错，确认Node.js和npm已安装（执行`node -v && npm -v`查看版本）。

Compile failures after scaffold

脚手架搭建后编译失败

  1. Check 
    contract/Move.toml
    has correct named addresses
  2. Run 
    aptos init --network <network> --assume-yes
    if not done
  3. Verify 
    my_addr
    is set to 
    "_"
    in 
    [addresses]
    section
  1. 检查
    contract/Move.toml
    中的命名地址是否正确
  2. 如果未执行过
    aptos init --network <network> --assume-yes
    ，先运行该命令
  3. 确认
    [addresses]
    部分的
    my_addr
    设置为
    "_"

Named address errors

命名地址错误

The boilerplate uses 
my_addr = "_"
which gets resolved from 
.env
at compile time. Ensure 
VITE_MODULE_PUBLISHER_ACCOUNT_ADDRESS
is set in 
.env
(populated by 
aptos init
).
模板默认使用
my_addr = "_"
，会在编译时从
.env
中解析取值。确保
.env
中设置了
VITE_MODULE_PUBLISHER_ACCOUNT_ADDRESS
（由
aptos init
自动填充）。