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.

ALWAYS

• Use npx create-aptos-dapp to scaffold — NEVER create projects from scratch manually
• Ask the user about project type, framework, and network before scaffolding
• Verify .env is in .gitignore before any git operations
• Use the same network for both create-aptos-dapp and aptos init
• Follow the full Build a dApp workflow after scaffolding (contracts, tests, audit, deploy, frontend)

NEVER

• Skip scaffolding — even for "simple" projects, always start with create-aptos-dapp
• Create project structure manually — the boilerplate template handles this
• Display or read private keys — use "0x..." as placeholder
• Run git add . or git add -A without first verifying .env is in .gitignore

Decision Tree

Before running the scaffold command, gather these inputs from the user:

1. Project Name

Derive from the user's description or ask directly. Use kebab-case (e.g., habit-tracker, nft-marketplace).

2. Project Type

3. Framework (fullstack only)

4. Network

5. API Key (optional)

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).

Scaffolding Commands

# Fullstack dApp with Vite (frontend + contracts)
npx create-aptos-dapp  \
  --project-type fullstack \
  --template boilerplate-template \
  --framework vite \
  --network 
# Fullstack dApp with Next.js
npx create-aptos-dapp  \
  --project-type fullstack \
  --template boilerplate-template \
  --framework nextjs \
  --network 
# Contract-only (Move project)
npx create-aptos-dapp  \
  --project-type move \
  --network 

Optional flags:

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

Post-Scaffold Checklist

After scaffolding, complete these steps in order:

• cd
• Verify .env is in .gitignore before any git operations
• Run aptos init --network --assume-yes (use the same network as above)
• Verify: npm run move:compile && npm run move:test
• git init && git add . && git commit -m "Initial commit"

Build a dApp Workflow

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 ...").

• /create-aptos-project -> scaffold with npx create-aptos-dapp (this skill — NEVER skip)
• /write-contracts -> write Move modules
• /generate-tests -> create test suite, verify 100% coverage
• /security-audit -> audit before deployment
• /deploy-contracts -> deploy contract to specified network
• /use-ts-sdk -> orchestrates frontend integration (routes to ts-sdk-client, ts-sdk-transactions,

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-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

Troubleshooting

npx create-aptos-dapp command not found

# Auto-confirm the npx package install prompt
npx --yes create-aptos-dapp  ...

If that still fails, verify Node.js and npm are installed (node -v && npm -v).

Compile failures after scaffold

• Check contract/Move.toml has correct named addresses
• Run aptos init --network --assume-yes if not done
• Verify my_addr is set to "_" in [addresses] section

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).