Supa Framework

Opinionated full-stack framework for building apps with Convex + Expo + React Native.

Spawn a new app in 2 minutes. Get auth, notifications, chat, payments, CI/CD, and native safety out of the box. Focus on your domain logic — Supa handles the rest.

Two surfaces are opt-in rather than default, because each is a second binary with its own build and release story: an Electron desktop app (@supa-media/desktop) and an Apple Watch / Live Activity target for the Expo app (@supa-media/apple-targets). create-supa-app asks about both.

Quick Start

# Clone the framework and run the scaffolder locally
git clone https://github.com/Supa-Media/supa-framework.git
cd supa-framework
pnpm install
node packages/create-supa-app/src/index.js my-app
# Then follow the interactive prompts
cd my-app
pnpm install
pnpm setup:secrets
npx convex dev
pnpm dev

Packages

Published to npmjs under the public @supa-media scope — pnpm add @supa-media/core, no token and no .npmrc scope line required. See PUBLISHING.md.

These were on GitHub Packages, which demands a token even for packages marked public. That put a read:packages credential in front of installing an MIT repo. @supa-media/chat and @supa-media/payments are not on npm yet — they have open correctness bugs noted in their READMEs and nothing consumes them.

Package	Description
@supa-media/core	Runtime providers, hooks, navigation, keyboard handling
@supa-media/convex	Backend auth (OTP), schema helpers, notifications, payments
@supa-media/chat	Real-time messaging with pagination, offline caching
@supa-media/notifications	Push notifications with deep linking
@supa-media/payments	Stripe integration with staging/production separation
@supa-media/desktop	Electron shell: menu-bar tray, panel windows, preload bridge, settings store, offline outbox — with an Electron-free core that tests under plain node
@supa-media/apple-targets	watchOS target + Live Activity scaffolding for the Expo app: App Groups, entitlements, expo-target.config.js, and the phone↔watch transport rules
@supa-media/dev-assistant	"App improves itself" AI contribution pipeline (spec → build → review → merge → deploy)
@supa-media/metro	Metro config factory for pnpm monorepos
@supa-media/native-safety	Native dependency gating for safe OTA updates
@supa-media/linter	ESLint rules for Supa conventions
@supa-media/testing	Reusable test suites for Expo gotchas
@supa-media/dev	Development orchestrator (Convex + Expo)
@supa-media/scripts	CI/deploy helper scripts
@supa-media/claude	Claude Code configuration templates
create-supa-app	Interactive CLI scaffolder (private, run locally via the framework repo)

Apps

Not published — these are the framework's own deployed surfaces, which is why they live in apps/ rather than packages/.

App	Description
apps/fleet-backend	Convex backend for the fleet dashboard: cross-device review marker + run telemetry. Holds no work state — GitHub stays the source of truth.

Reusable GitHub Workflows

Consumer apps call these instead of writing their own CI/CD:

jobs:
  ci:
    uses: Supa-Media/supa-framework/.github/workflows/ci.yml@v1
    with:
      node-version: "22"
      shared-package: "@myapp/shared"
    secrets: inherit

Philosophy

• Opinionated, not flexible — sensible defaults with escape hatches
• Copy real code, don't generate — extracted from production apps
• Enforce conventions — linting and tests catch mistakes before CI
• Updates propagate — pnpm update @supa-media/* brings improvements to all consumers

License

MIT — Copyright (c) 2026 Supa Media LLC. A copy of the licence ships inside every published package tarball.