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 let stacksdapp dev / stacksdapp generate --watch handle it.

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 unless you pass --no-auto-version.

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

See Local devnet for manual deploy, PoX settings, and devnet caveats.