sails-frontend

What this skill does

# Sails Frontend

## Goal

Keep frontend work on the typed Sails path first: generated `lib.ts` plus `@gear-js/react-hooks`, with `@gear-js/api` reserved for low-level fallback cases that the Sails stack does not cover cleanly.

## Inputs

- `assets/frontend-bootstrap-checklist.md`
- `../../references/sails-frontend-and-gear-js.md`
- `../../references/sails-idl-client-pipeline.md`
- `../../references/sails-cheatsheet.md`
- `../../references/sails-idl-v2-syntax.md` — IDL v2 syntax for understanding generated client contracts
- `../../references/sails-gtest-and-local-validation.md`
- `../../references/scale-binary-decoding-guide.md`
- `../../references/voucher-and-signless-flows.md`

## Minimal Path (simple apps)

For a straightforward app (counter, single-service CRUD) where the contract is already built:

1. `npx create-vara-app my-dapp --idl path/to/service.idl`
2. `cd my-dapp && npm install && npm run dev`
3. Verify: one read query renders, one write action shows disabled/pending/success/error states
4. Done — the scaffold handles providers, wallet, typed wrappers, and env validation

Skip the rest of this skill unless you need to customize screens, add Next.js support, wire vouchers, or handle advanced flows.

## Bootstrap with create-vara-app

When a Sails app needs a frontend — whether the project is brand-new or an existing repo without one — start with `create-vara-app`.

**Prerequisite:** the contract must be built first so the `.idl` file exists. If the `.idl` is not available yet, build the contract (`cargo build`) or use `create-vara-app` without `--idl` to scaffold with a demo contract.

```bash
npx create-vara-app my-dapp --idl path/to/service.idl
```

npm: https://www.npmjs.com/package/create-vara-app
GitHub: https://github.com/gear-foundation/create-vara-app

This scaffolds a Vite + React + TypeScript frontend with:
- Typed query/transaction wrappers from the IDL
- Wallet integration (SubWallet, Polkadot.js, Talisman)
- Live event subscriptions
- Client-side input validation
- Debug panel with runtime IDL explorer

Without `--idl`, scaffolds with a demo contract. With `--idl`, parses the service name and generates typed components automatically.

After the contract changes, re-run the scaffold from the project root:

```bash
npx tsx scripts/scaffold-client.ts
```

Detection: if the project has `scripts/scaffold-client.ts`, it was bootstrapped with `create-vara-app`. Use the scaffold script for regeneration. Otherwise use `sails-cli`.

After bootstrap, continue with the Standard Path below to customize screens, add queries, or wire advanced flows.

## Standard Path

1. Treat the program `.idl` as the frontend source of truth.
2. Generate or refresh the typed client. If `scripts/scaffold-client.ts` exists, run `npx tsx scripts/scaffold-client.ts` from the project root. Otherwise use `sails-cli` before wiring screens, hooks, or forms.
3. Compose the React root around TanStack Query plus Gear providers: query client, API provider, account provider, and alert provider.
4. Prefer `useProgram` with the generated `Program` class for typed service access.
5. Use `useProgramQuery` for Sails queries and `useProgramEvent` only where live subscriptions are actually needed.
6. Use `usePrepareProgramTransaction` to obtain `gasLimit`, `extrinsic`, or fee data before send when the UX needs validation or previews.
7. Use `useSendProgramTransaction` for commands, await `result.response`, and surface pending, success, and failure states in the UI instead of relying only on extrinsic submission.
8. Pass `voucherId` only when the flow is intentionally voucher-backed or prepaid. Treat full gasless or signless UX as a separate product decision; use the dedicated EZ-transactions path when the product spec requires it.
9. Drop to low-level `@gear-js/api` only for dynamic multi-IDL control, metadata work, raw mailbox or voucher flows, or direct `api.message.send`, `api.programState.read`, and `api.programState.readUsingWasm` cases. On those paths, identify whether the bytes are IDL-driven, metadata-driven, or `state.meta.wasm`-driven before decoding.

## Next.js App Router Compatibility

When the target frontend is a Next.js App Router project:

- `@gear-js/api`, `sails-js`, and wallet subdependencies use browser globals and WASM that break in Server Components. Add them to `transpilePackages` in `next.config.js` and mark all Gear provider/hook files with `'use client'`.
- If `@gear-js/react-hooks` or its wallet subdependencies cause persistent server-build failures after `transpilePackages`, fall back to a lower-level `sails-js` + `@gear-js/api` integration path with runtime-only `await import(...)` boundaries in client components. If falling back, commit to the lower-level path for the entire project.
- On the lower-level fallback path, add `@polkadot/util` and `@polkadot/util-crypto` as explicit dependencies — they are no longer pulled in transitively without the hooks stack.
- `next/font/google` fetches fonts at build time and will fail in offline CI or proof-loop environments. Use `next/font/local` or system fonts instead.
- Run `next build` before `tsc --noEmit` in App Router projects; route types are generated during the build step.

See `../../references/sails-frontend-and-gear-js.md` for the full Next.js compatibility guide.

## Repo Layout For Mixed Workspaces

In monorepos with both a Rust Sails program and a web frontend, check for `app/` directory collisions. The Rust program crate conventionally uses `app/` and Next.js App Router also expects `app/`. Common resolution: keep the Rust `app/` crate and place the frontend in `frontend/` or `web/`.

## sails-js-parser Initialization

When using `sails-js` for runtime IDL parsing (not the generated `lib.ts` client path), the `Sails` class requires an explicit parser instance from the separate `sails-js-parser` package. See `../../references/sails-frontend-and-gear-js.md` for the initialization pattern.

## API Surface Validation

Before handoff, validate the installed `sails-js` API surface against the conventions in `../../references/sails-frontend-and-gear-js.md`. Key points:

- The transaction builder method is `signAndSend()`, not `sendAndWait()`.
- Function arguments are positional, not wrapped in objects.
- Confirm `program.<serviceName>.<functionName>` exists on the generated client before wiring UI.

## Dependency Freshness Policy

Before generating or editing a Vara frontend, resolve package versions from the target project and the current package metadata, not from memory.

Order of precedence:
1. Existing repo lockfile and `package.json`
2. Current `peerDependencies` of `@gear-js/react-hooks` and related packages
3. Current published package versions if this is a new project

Rules:
- Do not pin Gear/Vara frontend package versions from memory.
- If the repo already has a lockfile, preserve it unless there is a clear compatibility issue.
- If starting a new frontend, first determine the current compatible package set, then write `package.json`.
- If using `@gear-js/wallet-connect`, also verify the required UI package set and required styles.
- Name the resolved versions explicitly in the output.

## Wallet UI Styling Rule

If the frontend uses packaged Gear wallet/UI components such as:
- `@gear-js/wallet-connect`
- `@gear-js/ui`
- `@gear-js/vara-ui`

then import the required package styles at the app entrypoint before considering the wallet integration complete.

Minimum check:
- wallet button renders correctly
- modal is visually positioned and styled correctly
- alert container is visible and not collapsed

## Wallet Readiness Rule

For wallet-bound actions, distinguish at least these states in the UI:

- wallets are still loading
- no Vara-compatible wallet extension is available
- wallet exists but no account is connected
- account is connected and ready for signing

Do not collapse these states into a single generic “wallet not ready” message.

Disabled signed actions should expose a v