Adopt an existing project

Migrate an existing Clarinet repo to Scaffold Stacks with stacksdapp init — add TypeScript bindings, frontend hooks, and deploy tooling without starting from scratch.

Run stacksdapp init from the repository root to add the Scaffold Stacks frontend, TypeScript bindings, debug UI, git hooks, and agent skill to an existing Clarinet project.

Contents

• Requirements
• What init does
• Standard Clarinet layout
• Already scaffold layout
• Layout conflicts
• Init vs upgrade
• Next steps

Requirements

• Clarinet 3.23+ (for Clarity 6 devnet support)
• Run from the repo root where Clarinet lives today

Verify with:

stacksdapp doctor

What init does

1. Normalizes layout to contracts/Clarinet.toml and frontend/ when needed
2. Adds missing frontend template files
3. Writes stacksdapp.toml if missing
4. Installs git pre-commit hook (mnemonic guard)
5. Installs bundled AI agent skill (.cursor/skills/scaffold-stacks/, AGENTS.md)
6. Runs npm install in frontend/ and contracts/
7. Runs stacksdapp generate

If frontend/ already exists but frontend/scripts/export-abi.mjs is missing, init exits with an error. Add that script, or move frontend/ temporarily, then run init again.

Standard Clarinet layout

Before:

my-dapp/
├── Clarinet.toml
├── contracts/
│   └── token.clar          # path in TOML: contracts/token.clar
├── settings/
│   └── Devnet.toml
├── tests/
│   └── token.test.ts
├── package.json
├── tsconfig.json
└── vitest.config.ts

cd my-dapp
stacksdapp init

After (typical):

my-dapp/
├── stacksdapp.toml
├── AGENTS.md
├── .githooks/pre-commit
├── contracts/
│   ├── Clarinet.toml       # moved from repo root
│   ├── contracts/
│   │   └── token.clar      # moved from contracts/token.clar
│   ├── settings/
│   ├── tests/
│   └── package.json
├── frontend/
│   └── scripts/
│       └── export-abi.mjs
└── (root Clarinet.toml removed after move)

Entries like path = "contracts/token.clar" in Clarinet.toml still resolve. The file ends up at contracts/contracts/token.clar, with Clarinet.toml under contracts/.

Already scaffold layout

my-dapp/
├── stacksdapp.toml
├── contracts/
│   └── Clarinet.toml
├── frontend/
│   ├── package.json
│   └── scripts/export-abi.mjs
└── ...

cd my-dapp
stacksdapp init

Normalization is skipped. Missing files are filled in, then npm install and stacksdapp generate run.

Layout conflicts

init fails if both of these exist:

• ./settings
• ./contracts/settings

Merge or remove one set, then rerun.

Init vs upgrade

Command	Use case
stacksdapp init	First time bringing an existing Clarinet project onto Scaffold Stacks
stacksdapp upgrade	Already scaffolded; refresh deps, bindings, hooks, and agent skill

Next steps

stacksdapp check
stacksdapp test
stacksdapp deploy --network testnet --yes

For local development with auto-deploy:

stacksdapp dev --auto-deploy

After cloning, enable git hooks:

npm run setup-hooks