Documentation

npx @devvmichael/create-stacks-app my-dapp

cd my-dapp

npm install

# Start the frontend dev server
cd frontend
npm run dev

# From project root
cd contracts
clarinet devnet start

my-dapp/
├── contracts/                # Clarity smart contracts
│   ├── contracts/            # .clar contract files
│   │   └── counter.clar      # Selected contract template(s)
│   ├── tests/                # Vitest + Clarinet SDK tests
│   │   └── counter.test.ts
│   ├── Clarinet.toml         # Clarinet configuration
│   ├── settings/
│   │   ├── Devnet.toml       # Devnet wallet/settings
│   │   └── Simnet.toml       # Simnet settings (for tests)
│   ├── deployments/
│   │   └── default.simnet-plan.yaml
│   └── package.json          # Test runner scripts
├── frontend/                 # Your chosen framework
│   ├── app/                  # Pages & routes (Next.js)
│   ├── components/           # UI components
│   ├── hooks/                # Stacks Connect v8 hooks
│   │   ├── use-stacks.ts     # Wallet connection
│   │   ├── use-contract-read.ts  # Read-only calls
│   │   └── use-contract-call.ts  # Public function calls
│   ├── lib/
│   │   ├── stacks.ts         # Core Stacks utilities
│   │   └── contracts.ts      # Contract config definitions
│   ├── .env                  # Network config (devnet default)
│   ├── .env.example          # Env template
│   └── package.json
├── .editorconfig
├── .prettierrc
├── .gitignore
└── README.md

;; Counter Contract
;; A simple contract demonstrating state management in Clarity

;; Data variables
(define-data-var counter uint u0)
(define-data-var owner principal tx-sender)

;; Error codes
(define-constant ERR-NOT-OWNER (err u403))

;; Increment the counter by 1
(define-public (increment)
  (ok (var-set counter (+ (var-get counter) u1))))

;; Decrement the counter by 1
(define-public (decrement)
  (let ((current (var-get counter)))
    (asserts! (> current u0) (err u400))
    (ok (var-set counter (- current u1)))))

;; Reset the counter to 0 (owner only)
(define-public (reset)
  (begin
    (asserts! (is-eq tx-sender (var-get owner)) ERR-NOT-OWNER)
    (ok (var-set counter u0))))

;; Set the counter to a specific value (owner only)
(define-public (set-counter (value uint))
  (begin
    (asserts! (is-eq tx-sender (var-get owner)) ERR-NOT-OWNER)
    (ok (var-set counter value))))

;; Read-only functions
(define-read-only (get-counter)
  (ok (var-get counter)))

(define-read-only (get-owner)
  (ok (var-get owner)))

import { networkName } from "./stacks";

export interface ContractConfig {
  address: string;
  name: string;
  network: string;
}

const contractAddress =
  process.env.NEXT_PUBLIC_CONTRACT_ADDRESS ||
  "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM";

export const counterContract: ContractConfig = {
  address: contractAddress,
  name: "counter",
  network: networkName,
};

export const tokenContract: ContractConfig = {
  address: contractAddress,
  name: "token",
  network: networkName,
};

export const nftContract: ContractConfig = {
  address: contractAddress,
  name: "nft",
  network: networkName,
};

import { useContractRead } from "@/hooks/use-contract-read";
import { useContractCall } from "@/hooks/use-contract-call";
import { counterContract } from "@/lib/contracts";

// Read the counter value
const { data, isLoading } = useContractRead(counterContract, "get-counter");

// Call increment
const { call, txId } = useContractCall(counterContract, "increment");
await call(); // Opens wallet for signing

cd contracts
npm test

import { describe, expect, it } from "vitest";
import { Cl } from "@stacks/transactions";

const accounts = simnet.getAccounts();
const deployer = accounts.get("deployer")!;
const wallet1 = accounts.get("wallet_1")!;

describe("Counter Contract", () => {
  it("should start at zero", () => {
    const result = simnet.callReadOnlyFn(
      "counter", "get-counter", [], deployer
    );
    expect(result.result).toBeOk(Cl.uint(0));
  });

  it("should increment counter by 1", () => {
    const block = simnet.callPublicFn(
      "counter", "increment", [], deployer
    );
    expect(block.result).toBeOk(Cl.bool(true));

    const result = simnet.callReadOnlyFn(
      "counter", "get-counter", [], deployer
    );
    expect(result.result).toBeOk(Cl.uint(1));
  });

  it("should prevent non-owner from resetting", () => {
    const block = simnet.callPublicFn(
      "counter", "reset", [], wallet1
    );
    expect(block.result).toBeErr(Cl.uint(403));
  });
});

# Deploy to testnet
npx @devvmichael/create-stacks-app deploy testnet

# Deploy to mainnet
npx @devvmichael/create-stacks-app deploy mainnet

# With a specific private key
npx @devvmichael/create-stacks-app deploy testnet --private-key <key>

cd contracts
clarinet devnet start

# Network: devnet | testnet | mainnet
NEXT_PUBLIC_NETWORK=devnet

# Contract deployer address (default: Clarinet devnet deployer)
NEXT_PUBLIC_CONTRACT_ADDRESS=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

# Network: devnet | testnet | mainnet
VITE_NETWORK=devnet

# Contract deployer address
VITE_CONTRACT_ADDRESS=ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

npx @devvmichael/create-stacks-app [project-name] [options]

Options:
  -t, --template <name>      Frontend template (nextjs, react)
  -c, --contracts <list>     Contracts to include (counter,token,nft)
  --typescript / --no-typescript
  --tailwind / --no-tailwind
  --no-git                   Skip Git initialization
  --package-manager <pm>     npm, pnpm, or yarn
  --skip-install             Skip dependency installation
  -y, --yes                  Skip prompts, use defaults

npx @devvmichael/create-stacks-app add <type> <name>

Options:
  --sip010        Create a SIP-010 fungible token contract
  --sip009        Create a SIP-009 NFT contract
  -t, --template  Use a specific template (marketplace, defi)

Examples:
  npx @devvmichael/create-stacks-app add contract my-token --sip010
  npx @devvmichael/create-stacks-app add contract my-nft --sip009

npx @devvmichael/create-stacks-app deploy <network>

Options:
  --private-key <key>  Private key (or set STACKS_PRIVATE_KEY env var)

Examples:
  npx @devvmichael/create-stacks-app deploy testnet
  npx @devvmichael/create-stacks-app deploy mainnet --private-key <key>