create-vechain-dapp

Create VeChain dApp

Scaffold a production-ready VeChain dApp with wallet connection, dark mode, and GitHub Pages deployment.

CRITICAL RULES

1. Read reference files FIRST. Based on the user's chosen mode, read the appropriate reference files before creating any files. Briefly mention which files you are reading so the user can confirm the skill is active.
2. Always read shared.md — it contains the source code templates used by both modes.
3. Replace all placeholders in every template before writing files. See Variable Substitution below.
4. After compaction or context loss, re-read this SKILL.md to restore awareness of the reference table and operating procedure.

Stack

Layer	Technology
Framework	Next.js 14 (App Router, static export)
UI	Chakra UI v3, next-themes
Wallet	@vechain/vechain-kit (VeWorld + WalletConnect)
State	React Query
Contracts	Hardhat + @vechain/sdk-hardhat-plugin + OpenZeppelin UUPS (monorepo only)
Build	Turborepo (monorepo only)
Deploy	GitHub Pages via GitHub Actions
Node	20 LTS

Operating procedure

Phase 1 — Gather requirements

Ask the user (use structured questions if available):

1. Project name — kebab-case (e.g. my-vechain-dapp)
2. Mode — standalone (frontend only) or monorepo (Turbo + contracts)
3. Network — test or main (default: test)
4. Target directory — where to create the project (default: current directory)

Phase 2 — Scaffold

Read the appropriate reference files and create all files.

Standalone mode:

1. Read references/shared.md
2. Read references/standalone.md
3. Create files in {{TARGET_DIR}}/{{PROJECT_NAME}}/

Monorepo mode:

1. Read references/shared.md
2. Read references/monorepo.md
3. Create frontend files in {{TARGET_DIR}}/{{PROJECT_NAME}}/apps/frontend/
4. Create other files at monorepo root and in packages/

Variable substitution

Replace these placeholders in ALL templates:

Placeholder	Value
{{PROJECT_NAME}}	kebab-case project name
{{PROJECT_TITLE}}	Title-case project name (for UI display)
{{NETWORK_TYPE}}	test or main

Phase 3 — Install and verify

cd {{PROJECT_NAME}}
nvm use
yarn install

Standalone: yarn dev (localhost:3000), yarn build (static export → out/)

Monorepo: make solo-up (start Thor solo node, requires Docker), then yarn dev (auto-deploys contracts to solo), yarn build, yarn contracts:compile, yarn contracts:test. Stop with make solo-down, reset with make solo-clean.

Phase 4 — Git init

git init && git add . && git commit -m "Initial scaffold: VeChain dApp"

Success criteria

• yarn dev starts without errors
• Page renders with Navbar and wallet connect button
• Dark/light mode toggle works
• yarn build produces static output
• .github/workflows/deploy.yml is present

Key patterns

Client-only VeChain Kit

VeChain Kit cannot run server-side. The entire app shell (ClientApp) is loaded via dynamic(() => ..., { ssr: false }) in layout.tsx. All VeChain Kit imports inside ClientApp children work normally since the parent is already client-only.

Static export for GitHub Pages

next.config.js uses output: "export" with configurable basePath/assetPrefix via NEXT_PUBLIC_BASE_PATH env var. GitHub Actions defaults to /${{ github.event.repository.name }} for GitHub Pages. Set to empty string for custom domains. Important: metadata.icons and raw <img src> paths do NOT auto-prepend basePath — prefix them manually.

Chakra UI version pinning

Pin @chakra-ui/react to an exact version (currently 3.30.0). VeChain Kit uses Chakra v2 internally, and newer v3 releases can break VeChain Kit's button/modal theming.

Provider chain

ChakraProvider → ColorModeProvider → QueryClientProvider → VeChainKitProvider → App

Contract architecture (monorepo only)

All contracts in the monorepo scaffold are UUPS upgradeable using OpenZeppelin's upgradeable contracts and a custom VeChainProxy.sol (ERC1967). Key files:

• scripts/helpers/upgrades.ts — core deploy/upgrade proxy helpers. Copy as-is from the template. All deploy scripts, upgrade scripts, and tests depend on it.
• contracts/VeChainProxy.sol — ERC1967 proxy contract. Copy as-is.
• scripts/deploy/deploy.ts — production deployment using deployProxy from helpers.
• scripts/upgrade/ — interactive CLI upgrade system with versioned config registry.

For contract architecture, upgrade patterns, storage safety, security, and testing — follow the smart-contract-development skill. It is the authoritative reference for all Solidity development patterns on VeChain.

Config package and auto-deployment (monorepo only)

The monorepo uses a packages/config package that centralizes contract addresses and network settings per environment. Key mechanics:

• local.ts is git-ignored — each dev's solo deployment produces different addresses. A mock is auto-generated on first run.
• NEXT_PUBLIC_APP_ENV controls which config file is loaded (local, testnet, mainnet).
• yarn dev runs against solo, yarn dev:testnet against testnet, yarn dev:mainnet against mainnet.
• Turbo pipeline ensures: generate mock config → compile contracts → check/deploy on target network → write addresses to matching config file → start frontend.
• checkContractsDeployment.ts runs before dev for any environment — if contracts aren't deployed, it deploys them and writes addresses to the correct config file (local.ts, testnet.ts, or mainnet.ts).

VeChain Kit integration

• VeChainKitProvider wraps the app with network config and wallet options
• WalletButton from vechain-kit renders the connect/account button
• useWallet, useSendTransaction, useCallClause for wallet/contract interaction
• Refer to the vechain-kit skill for advanced patterns (hooks, theming, social login)
• Refer to the vechain-core skill for SDK patterns (fee delegation, multi-clause)

Reference files

Read the matching files BEFORE creating any files. See Critical Rules above.

Topic	File	Read when...
Shared source code	references/shared.md	Always — contains all component/provider templates
Standalone config	references/standalone.md	User chose standalone mode (frontend only)
Monorepo config	references/monorepo.md	User chose monorepo mode (Turbo + contracts)