Code generation

How stacksdapp generate converts Clarity ABIs into TypeScript bindings, React hooks, and a live debug UI for Stacks dApp frontends.

stacksdapp generate parses Clarity contract ABIs and writes type-safe TypeScript bindings plus a debug UI under frontend/src/generated/.

​

Contents

• Generate once
• Watch mode
• How it works
• Generated files
• Using hooks in your UI
• Hiro API key (optional)
• Stale deployments
• File watcher during dev

​

Generate once

stacksdapp generate

When package-lock.json exists under contracts/ or frontend/, generate runs npm ci before exporting ABIs.

​

Watch mode

Regenerate on every .clar change without the full dev supervisor:

stacksdapp generate --watch

stacksdapp generate --watch regenerates bindings when you save a contract. stacksdapp dev does not.

​

How it works

​

1. Parse

Extract ABIs from all contracts using initSimnet():

const abi = simnet.getContractAbi("counter");

ABIs are cached in contracts/.cache/. Unchanged sources skip redundant initSimnet runs.

​

2. Normalize

Clarity	TypeScript
uint	bigint
int	bigint
bool	boolean
string-ascii	string
string-utf8	string
principal	string
tuple	object
list	array

​

3. Render

Tera templates produce three files under frontend/src/generated/:

• contracts.ts: typed call wrappers
• hooks.ts: React hooks
• DebugContracts.tsx: live debug panel

​

4. Write

SHA-256 hashing writes only when content changes. This keeps Next.js hot reload fast.

​

Generated files

​

contracts.ts

export const counterContract = (network: string) => ({
  increment: async (options: { sender: string }) => {
    // Type-safe call with proper encoding
  },
  getCount: async () => {
    // Read-only call
  },
});

​

hooks.ts

export const useCounterIncrement = () => {
  return useMutation({
    mutationFn: counterContract(network).increment,
  });
};

​

DebugContracts.tsx

export const DebugContracts = () => (
  <div>
    <ContractPanel name="counter">
      <FunctionButton name="increment" />
      <ReadOnlyField name="getCount" />
    </ContractPanel>
  </div>
);

​

deployments.json

Contract addresses written by stacksdapp deploy.

​

Using hooks in your UI

import { useCounterIncrement } from "@/generated/hooks";

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

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

​

Hiro API key (optional)

For higher rate limits on read-only Stacks calls, set in frontend/.env.local:

NEXT_PUBLIC_HIRO_API_KEY=your_key_here

The template passes this through getReadOnlyNetwork (@stacks/network v7).

​

Stale deployments

If on-chain addresses in deployments.json no longer match your contracts, redeploy:

stacksdapp deploy --network testnet
stacksdapp deploy --network devnet

​

File watcher

stacksdapp dev does not watch contracts. Run this in another terminal:

stacksdapp generate --watch

The watcher:

1. Monitors .clar files
2. Debounces rapid edits
3. Runs code generation
4. Lets Next.js hot reload pick up the new bindings

Do not edit files under frontend/src/generated/ by hand. They are overwritten on the next generate.