Appearance
Technology Stack Overview
The workspace contains nine repositories, each with its own build and deploy lifecycle, sharing a common set of tooling preferences and version constraints.
Quick Reference: All Repos
| Repository | Primary Stack | Runtime | Deployment |
|---|---|---|---|
vela-protocol | Rust, Anchor 0.32.1, spl-token-2022, Arcium circuits | Solana BPF | Devnet → Mainnet |
vela-sdk | TypeScript, Bun, Commander, Anchor TS client | npm package + CLI | Published to npm as @vela/sdk |
vela-dashboard | React 19, TanStack Router/Query, Hono, Better Auth, Drizzle | Vite dev server + Cloudflare Worker–compatible backend | Cloudflare Workers (D1) |
vela-admin | React 19, TanStack Router/Query, Hono | Cloudflare Worker | Cloudflare Workers (service binding to dashboard) |
vela-web | Astro 6, React islands, Tailwind v4 | Astro SSG/SSR | Cloudflare Workers |
vela-docs | Astro 6, Starlight 0.38 | Astro SSG | Cloudflare Workers |
vela-widget | Bun build, React checkout app, Wallet Standard | Loader script + Worker-hosted iframe | Cloudflare Workers (js.velapay.com) |
vela-checkout | React 19, Hono, Cloudflare Workers | Vite + Worker | Cloudflare Worker at pay.velapay.com |
vela-portal | React 19, Hono, Better Auth magic links | Vite + Worker | Cloudflare Worker at portal.velapay.com |
vela-webhook | Hono, Cloudflare Workers | Worker + Queues | Cloudflare Workers |
vela-synthetic | Hono, Cloudflare Workers Cron Triggers | Worker | Cloudflare Workers |
Shared Workspace Preferences
These show up across every TypeScript repo in the workspace. They are not aspirational — they are checked in.
| Preference | Where | Why |
|---|---|---|
| Bun | All TS repos | Package manager, TS runtime, and test runner. bun test everywhere, bun.lock everywhere. No npm, no yarn, no pnpm. |
| TypeScript 5.8+ | All TS repos | Shared implementation language. Bun runs it natively; tsc --noEmit for type checking. |
| Cloudflare Workers | Dashboard, admin, web, docs, widget, checkout, portal, webhook, synthetic | Dominant deployment target. Wrangler for dev/prod. D1 for state. Service bindings for interop. |
| React 19 | Dashboard, admin, widget, checkout, portal | Shared UI layer. TanStack Router/Query for routing and data in the app surfaces. |
| Hono | Dashboard, admin, checkout, portal, webhook, synthetic | API layer. Runs everywhere Bun and Workers do. Replaces Express in every context. |
| Biome | SDK, widget, protocol (TS side) | Formatting + linting in a single tool. 100× faster than ESLint + Prettier. |
| Drizzle ORM | Dashboard, checkout, portal | D1-first ORM. SQLite dialect now, Postgres migration path later. |
Key Version Truths
These are pinned for compatibility reasons and must not be bumped without cross-repo impact analysis.
| Package | Version | Why It's Pinned |
|---|---|---|
anchor-lang / @coral-xyz/anchor | 0.32.1 | Program framework. IDL must match deployed program. Anchor 1.0 RC removes #[interface] attribute needed for transfer hooks — not production-ready. |
@solana/web3.js | v1.x | Anchor TS client requires v1. Kit (@solana/kit) is incompatible with the Anchor client. Migration when Anchor 1.0 ships Kit support. |
@solana/spl-token | ^0.4.14 | Token-2022 helpers. Works with web3.js v1. |
| React | 19.x | All app surfaces. TanStack Start supports 18/19; we use 19. |
| Tailwind CSS | v4.2.x | CSS-first config (no tailwind.config.js). 5× faster full builds. @theme directive for design tokens. |
| Arcium client | 0.9.3 | @arcium-hq/client — matches MXE cluster version for encrypted instruction building. |
| Bun | 1.3.11+ | Workspace package manager. Native TS, built-in test runner, auto-loads .env. |
Version Compatibility Matrix
Derived from STACK.md and verified against checked-in package.json / Cargo.toml files.
| Component A | Compatible With | Notes |
|---|---|---|
| Anchor CLI 0.32.1 | Solana CLI 2.3.0+ (Agave) | Tested target. Use agive-install, not deprecated solana-install. |
| Anchor CLI 0.32.1 | Rust 1.89.0+ | Required for Span::local_file stabilization in IDL generation. |
@coral-xyz/anchor 0.32.1 | @solana/web3.js v1 | v2 (@solana/kit) NOT supported by Anchor TS client. |
@solana/spl-token 0.4.14 | @solana/web3.js v1 | For Kit, use @solana-program/token-2022 instead. |
helius-sdk 2.2.x | @solana/kit 3.0.x (internal) | Uses Kit internally but exposes a clean API; no conflict with web3.js v1 in your code. |
| Drizzle ORM 0.45.x | Cloudflare D1 | Uses D1 batch() API — no interactive transactions. |
| Astro 6.1.x | Starlight 0.38.x | Verified compatible. |
| Better Auth 1.5.x | Drizzle 0.45.x + D1 | Native adapter. No custom config needed. |
Important Nuance: TanStack Start vs. Vite + React
The strategy docs and roadmap describe the merchant dashboard as TanStack Start + Railway. The checked-in code in vela-dashboard is a Vite + React + TanStack Router/Query + Hono shape with Cloudflare Worker–aware deployment paths.
This distinction matters because:
- TanStack Start is a full-stack framework with server functions, SSR, and file-based routing.
- What's actually checked in uses TanStack Router (client-side routing with full type safety) and TanStack Query (server state management) on top of a Vite React app. The API layer is Hono.
- The Cloudflare Worker compatibility is real — Hono runs on Workers, and D1 bindings work through Wrangler dev.
- Railway is mentioned in strategy docs as a heavier compute option, but the current codebase defaults to Cloudflare Workers for everything.
Both approaches share the same UI stack (React 19, TanStack, Hono, Drizzle, D1). The difference is whether SSR happens via TanStack Start server functions or via a simpler Vite build + Worker serving static assets + Hono API routes. The wiki preserves this distinction rather than flattening it.
Pinning Strategy
| Package | Pin Strategy | Reason |
|---|---|---|
| Anchor | Exact (0.32.1) | Program framework — must match deployed program IDL |
@coral-xyz/anchor | Exact (0.32.1) | Must match Anchor CLI and deployed program |
@solana/web3.js | ^1.x | Stable v1 API, patches are safe |
@solana/spl-token | ^0.4.x | Active development, minor bumps add features |
| TanStack Router/Query | ^1.x | Stable, semantic versioning respected |
| Hono | ^4.12.x | Stable, semantic versioning respected |
| Drizzle ORM | ^0.45.x | Pre-1.0, but stable API surface |
| Astro | ^6.1.x | Major version locked, patches safe |
| Starlight | ^0.38.x | Pre-1.0, updates frequently |
| Better Auth | ^1.5.x | 1.x stable, patches/minors safe |
helius-sdk | ^2.2.x | 2.x stable, patches safe |
| Arcium client | 0.9.3 | Exact — must match MXE cluster |
What's Not Used (and Why)
These come up often in the Solana/web ecosystem but are deliberately excluded:
| Excluded | Why |
|---|---|
eslint + prettier | Replaced by Biome — single tool, 100× faster |
vitest / jest | bun:test is built-in, zero config, native TS |
next-auth / auth.js | Better Auth has superior D1/Hono integration, self-hosted |
prisma | No D1 support; Drizzle is lighter and D1-native |
@solana/kit directly | Anchor TS client requires web3.js v1; Kit migration at Anchor 1.0 |
@solana/wallet-adapter-* in SDK | Wallet adapters are for frontends, not library packages |
dotenv | Bun auto-loads .env files |
tsx / ts-node | Bun runs TypeScript natively |
nodemon | Bun has --hot flag |
| Cloudflare Pages | Workers get all new features; Pages is the deprecated path |
Development Workflow
Typical Development Loop
1. bun install # Install dependencies (workspace-root or per-repo)
2. bun test # Run tests (bun:test built-in)
3. bun run check # Type check (tsc --noEmit)
4. bun run lint # Lint + format (Biome)
5. wrangler dev # Local Cloudflare dev server (Workers repos)
6. wrangler deploy # Deploy to Cloudflare (production)Testing Stack by Repo
| Repo | Test Runner | Framework | Purpose |
|---|---|---|---|
vela-protocol | cargo test | LiteSVM (Rust crate) | Unit tests for individual instructions |
vela-protocol | bun test (ts-tests/) | anchor-litesvm 0.2.1 + litesvm 0.6.0 | TypeScript integration tests, E2E flows |
vela-sdk | bun test | bun:test | SDK method unit tests |
vela-dashboard | bun test | bun:test | API route tests, component tests |
vela-web | bun test | bun:test | Build verification |
vela-docs | bun test | bun:test | Build verification |
Monorepo vs Multi-Repo Structure
The workspace is not a monorepo — each repo has its own deploy lifecycle, its own package.json, its own CI pipeline. The root bun.lock exists for workspace-level scripts, but each repo independently manages its own dependencies.
The shared workspace preferences (Bun, TypeScript, Cloudflare, React 19, Biome) are conventions enforced by documentation and code review, not by a shared build tool or lerna-like orchestrator.