Templates

The MVP ships official templates. For a step-by-step caatinga init walkthrough, see Template project.

• react-vite-counter — single Soroban counter dApp. Stable for the alpha flow.
• zk-starter — ZK dApp with Circom/Groth16 verifier (via caatinga zk init). Stable for the ZK walkthrough.

Multi-contract deploy (dependsOn, ${contracts.*.contractId}) is supported in caatinga.config.ts — see ADR 0005 and Config.

Every template must include caatinga.template.json:

{
  "name": "react-vite-counter",
  "version": "0.1.0",
  "description": "Minimal Vite + React + Soroban counter dApp.",
  "caatinga": {
    "compatibleCore": "^0.2.0",
    "templateVersion": 1
  },
  "frontend": {
    "framework": "vite-react",
    "packageManager": "npm"
  },
  "contracts": {
    "path": "contracts",
    "default": "counter"
  },
  "files": {
    "config": "caatinga.config.ts",
    "artifacts": "caatinga.artifacts.json"
  }
}

templateVersion is currently 1. The packageManager field accepts "npm", "pnpm", "yarn", or "bun".

compatibleCore is checked against the current @caatinga/core version before files are copied. Official templates in this repository must pin compatibleCore to ^<coreVersion> (the same range defaultCompatibleCoreRange() derives from CAATINGA_CORE_VERSION); CI enforces that pin so a core bump cannot ship with stale template metadata. Missing manifests fail with CAATINGA_TEMPLATE_MANIFEST_NOT_FOUND; invalid manifests fail with CAATINGA_INVALID_TEMPLATE_MANIFEST; incompatible manifests fail with CAATINGA_TEMPLATE_INCOMPATIBLE.

Official templates are maintained in this repository. Community templates should be treated as executable source code: inspect the files before running install scripts or connecting wallets.

Generated projects include:

• contracts/counter
• src
• caatinga.config.ts
• caatinga.artifacts.json
• Vite and TypeScript config
• dependencies for generated bindings, @caatinga/client, and Stellar Wallets Kit smoke wiring

caatinga generate writes a self-contained TypeScript binding package at {bindingsOutput}/{contractName}/ (generated by @stellar/stellar-sdk generate). Import from ./contracts/generated/counter (or the matching contract name) rather than a flat {contractName}.ts file.

Maintainers: the canonical override contract, CI enforcement, and file-sync list live in Install-time dependency overrides.

pnpm 10.26+ / 11.x

caatinga.template.json declares packageManager: "npm", but the react-vite-counter template also ships pnpm-workspace.yaml so generated apps can install with pnpm 10.26+ or 11.x:

allowBuilds:
  esbuild: true

ignoredOptionalDependencies:
  - "@safe-global/safe-apps-provider"
  - "@safe-global/safe-apps-sdk"

overrides:
  uuid: "^14.0.0"
  ws: "^8.21.0"
  "@reown/appkit-utils>@safe-global/safe-apps-sdk": "-"
  "@reown/appkit-utils>@safe-global/safe-apps-provider": "-"
  "@safe-global/safe-apps-sdk>@safe-global/safe-gateway-typescript-sdk": "-"

• allowBuilds.esbuild: true — pnpm blocks dependency lifecycle scripts by default; Vite pulls in esbuild. Without this, pnpm install fails with ERR_PNPM_IGNORED_BUILDS.
• overrides.uuid — avoids deprecated transitive uuid@8 from optional wallet SDK dependencies. package.json also ships npm overrides for the same pin when using npm.
• overrides.ws — required. Pins ws@^8.21.0 across the Reown/viem chain (transitive via Stellar Wallets Kit). Without this, npm audit reports ~14 high DoS advisories (GHSA-96hv-2xvq-fx4p) after install. See Install override contract.
• Safe overrides — block optional EVM/Safe packages from Reown AppKit (transitive via Stellar Wallets Kit). Irrelevant for Stellar wallets; removes the deprecated @safe-global/safe-gateway-typescript-sdk warning on npm install. package.json ships equivalent nested npm overrides for npm users.
• Trezor/HOT overrides — SWK lists @trezor/connect-web and @hot-wallet/sdk as direct dependencies but Caatinga does not register them (no hardware-wallet support yet). npm overrides replace them with local stubs under src/stubs/; pnpm uses "-" path overrides in pnpm-workspace.yaml. This avoids critical protobufjs advisories (Trezor) and NEAR/elliptic noise (HOT) without affecting Freighter, LOBSTR, WalletConnect, etc. Do not remove — see Install override contract.

The reasoning behind each workaround (and how to apply them outside the template) is documented in Wallets — Stellar Wallets Kit bundler workarounds. For custom Vite apps, prefer @caatinga/client/vite helpers (walletStubViteAliases, walletStubOverrides, walletStubPnpmWorkspaceYaml).

Set CAATINGA_TEMPLATES_DIR during local development to point the CLI at a custom templates directory.

Alpha smoke path

The official template documents both paths:

1. CLI: build -> deploy (bindings auto-generate) -> invoke
2. Browser/client: generated bindings + caatinga.artifacts.json + @caatinga/client + Stellar Wallets Kit adapter

The template wires wallet state through WalletProvider/useWallet from @caatinga/client/react (persistent session, silent reconnect) — see Wallets. It does not generate caatinga generate --interop output in alpha.

Browser-facing templates should import errors and artifact types from @caatinga/core/browser (see react-vite-counter/src/caatinga.ts). Keep the full @caatinga/core entry for Node-only config (caatinga.config.ts, CLI workflows).