Developer workflow

Day-to-day Stacks dApp development with stacksdapp — edit Clarity contracts, run checks and tests, generate TypeScript hooks, and iterate with the debug UI.

Edit Clarity contracts, regenerate bindings, run tests, and redeploy. Requires Clarinet 3.23+ for Clarity 6 devnet. Run stacksdapp doctor if you hit toolchain errors.

​

Contents

• Edit contracts
• Add a contract
• Run tests
• Type-check contracts
• Redeploy after changes
• Project structure
• Code generation
• Frontend features
• Local development

​

Edit contracts

Open any .clar file in contracts/contracts/ and add a function:

(define-public (multiply (n uint))
  (begin
    (var-set counter (* (var-get counter) n))
    (ok (var-get counter))))

Update bindings:

stacksdapp generate

Or run stacksdapp generate --watch while you edit. stacksdapp dev does not regenerate bindings.

Redeploy to apply on-chain changes:

stacksdapp deploy --network testnet --yes

The multiply function appears in the debug UI after regeneration and redeployment.

​

Add a contract

stacksdapp add relayer
stacksdapp add token --template sip010
stacksdapp add nft --template sip009
stacksdapp add legacy --clarity-version 5

Each command creates the .clar file, a Vitest test file, updates Clarinet.toml with the correct epoch, and regenerates bindings.

See Working with contracts for SIP token templates and Clarity versions for version selection.

​

Run tests

stacksdapp test

See Testing for contract and frontend test patterns.

​

Type-check contracts

stacksdapp check

​

Redeploy after changes

Stacks contracts are immutable. Redeploying creates versioned contracts:

stacksdapp deploy --network testnet --yes
# counter-v2, counter-v3, ...

The CLI handles versioning automatically on devnet, testnet, and mainnet unless you pass --no-auto-version. On devnet, a contract can still be on chain after you restart stacksdapp dev.

​

Project structure

my-app/
├── stacksdapp.toml              # project marker + defaults.network
├── AGENTS.md                    # agent pointer
├── package.json                 # npm scripts (dev, generate, deploy, setup-hooks)
├── .githooks/pre-commit         # mnemonic guard
├── .cursor/skills/scaffold-stacks/
├── contracts/
│   ├── Clarinet.toml            # clarity_version = 6, epoch = "4.0"
│   ├── .cache/
│   ├── settings/
│   │   ├── Devnet.toml
│   │   ├── Testnet.toml
│   │   └── Mainnet.toml
│   ├── contracts/
│   │   └── counter.clar
│   └── tests/
│       └── counter.test.ts
└── frontend/
    ├── .env.local
    └── src/
        ├── app/
        ├── components/
        │   └── WalletConnect.tsx
        └── generated/
            ├── contracts.ts
            ├── hooks.ts
            ├── DebugContracts.tsx
            └── deployments.json

​

Code generation

See Code generation for the full pipeline, watch mode, ABI caching, and Hiro API keys.

Summary:

1. Parse ABIs via initSimnet() (cached under contracts/.cache/)
2. Normalize Clarity types to TypeScript
3. Render contracts.ts, hooks.ts, DebugContracts.tsx
4. Write only when content changed

​

Frontend features

​

Debug UI

Every public function gets a typed input form. Read-only functions display results directly.

​

Reusable hooks

import { useCounterIncrement } from '@/generated/hooks'

function CounterComponent() {
  const { data, loading, call } = useCounterIncrement()

  return (
    <button onClick={() => call([])}>
      {loading ? 'Incrementing...' : 'Increment'}
    </button>
  )
}

​

Wallet Connect

WalletConnect.tsx handles Leather and Xverse, including network detection. Wallet signing is for testnet/mainnet. Devnet uses public burner keys with no wallet popup.

​

State management

Jotai atoms sync wallet and network state across the template.

​

Local development

stacksdapp dev                         # terminal 1 — Clarinet chain
stacksdapp deploy --network devnet     # terminal 2
stacksdapp dev --network devnet        # terminal 3 — Next.js

See Local devnet for Choose Wallet, redeploy, and Clarinet version behavior.