create-vara-app: the scaffold that learns your contract for you

Most starter kits hand you a shell and a checklist. This one hands you a frontend that already understands the contract. The interesting move is not the React shell, it is the fact that the scaffold reads the Sails IDL first and uses that as the source of truth.

The scaffold is already listening

A fresh project is not blank. The template carries a demo contract in programs/demo, a reference React app in frontend, and the generator logic in scripts. That makes the scaffold feel less like a starter and more like a conversation between contract and UI.

That is the real product. create-vara-app is not a prettier create-react-app clone. It is a contract-aware generator that turns metadata into usable UI surfaces, which is why a change in the contract can surface as a type error instead of a silent mismatch.

One IDL, many generated surfaces

The heavy lifting lives in scripts/scaffold-client.ts and scripts/scaffold-types.ts. The generator walks the Sails IDL with sails-js-parser, maps Rust primitives into TypeScript, and applies a naming convention that turns contract methods into readable client calls.

// scripts/scaffold-types.ts
u32    -> number
u64    -> string
u128   -> string
ActorId -> `0x${string}`

// scripts/scaffold-client.ts
GetState  -> queryState()
Increment -> txIncrement()

That mapping looks small. It is not. It decides whether the frontend can keep up when the contract changes. If a Rust signature shifts, the generated TypeScript surface shifts too, which means the breakage happens early and loudly instead of drifting into production.

Why the event layer matters in an actor-model chain

Vara is not just a different chain. It has a message-driven shape, so state changes can arrive asynchronously and in bursts. That is why the scaffold's EventsProvider matters. It discovers events from the IDL, buffers them locally, and keeps the interface feeling alive without asking the developer to wire every listener by hand.

useEffect(() => {
  const unsubscribe = subscribeToEvents((event) => {
    pushEvent(event)
    setRefreshTrigger((value) => value + 1)
  })

  return unsubscribe
}, [programId])

The repo makes that live layer feel intentional, not bolted on. The demo contract includes delayed self-messaging, and the frontend responds through a refresh pattern instead of pretending the chain is synchronous. That is the right trade for this stack.

How the generator keeps frontend and contract in lockstep

The app bootstraps a Sails client through use-sails.ts and a shared initializer in lib/sails-client.ts. It reuses the parsed client when the network or programId stays the same, then rebuilds it when those inputs change. The point is simple: the frontend should track the contract, not drift beside it.

The other quiet win is the debug surface. Instead of making you build a contract explorer after the fact, the scaffold exposes the methods it already knows about. That shortens the path from scaffolded project to something you can actually poke at.

What it does better than generic starters

The table is the point. create-vara-app is not trying to be the broadest tool. It is trying to remove the sharpest piece of glue work for one stack, and it does that by being opinionated about Vara, React, and Sails.

Where it came from, and what it still leaves to you

The project comes from the Gear Foundation's Vara ecosystem, and the docs describe it as a pre-configured solution for quickly launching dApps on Vara. The codebase backs that claim with unusually serious scaffolding: the repository includes 37 Vitest tests for the codegen pipeline and 10 GTest integration tests for the Rust contract.

It is still early. The repo leans on beta-era Sails components, and a scaffold can only carry you so far. What it does well is remove the boring mismatch between contract and frontend, which is exactly where a lot of dApp projects lose time and coherence.