Skip to content

README.md

Latest commit

 

History

History
101 lines (82 loc) · 5.73 KB

README.md

File metadata and controls

101 lines (82 loc) · 5.73 KB
Raw

Basilic: API-First TypeScript FullStack Starter

Build production-ready APIs and apps with typed SDKs, out-of-the-box authentication, a portable architecture, AI tooling, and crypto integrations. Fastify • OpenAPI • Next.js • Expo — one stack, multiple platforms.

🚧 Active development — Explore, fork, and contribute. 🏗️

Features

  • 🤖 AI-first dev workflow — Agent rules, skills, MCP integrations, and automated CodeRabbit reviews
  • 🔌 REST API & JWT — OpenAPI spec, Swagger UI, JWT and API key auth for all clients
  • 📦 SDK generation — Type-safe clients from OpenAPI via HeyAPI
  • 🧩 Web3 & AI starters — Ready-to-use templates for Next.js, React, Expo, and Fastify
  • 🔓 Zero vendor lock-in — Run on VPS, AWS, Vercel, or local
  • 🎨 Turbo monorepo + design system — ShadcnUI components with shared utilities
  • ⚙️ Preconfigured dev tools — Biome, Git workflows, hooks, and security checks
  • 🛡️ Security & quality — Automated checks in CI (Gitleaks, OSV, DeepSec)
  • ⛓️ Multichain — EVM, Solana; shared validation and chain-specific tooling
  • 📐 Conventions — Cursor rules per domain, @repo/error, Pino logging, shared TS and style
  • 🧑‍💻 TypeScript-first — End-to-end types from database to frontend

Technology stack

  • AI: AI SDK, OpenAI, Claude, Grok
  • Frontend: Next.js 16, React 19, Tailwind, ShadcnUI
  • Backend: Fastify, PostgreSQL, Supabase
  • Web3: Viem, Wagmi, Solana wallet tooling in shared packages
  • DevOps: Node.js 24.x (LTS Krypton), pnpm, TurboRepo, TypeScript, Biome, ESLint

Apps

  • API — Type-safe REST API built with Fastify & OpenAPI
  • Web App — Next.js app with monorepo integration
  • Mobile App — Expo UI scaffold (shared @repo/ui; not an API client yet)
  • Documentation — Fumadocs-based docs site for architecture, ADRs, and development workflows

Packages

  • @repo/core — Runtime-agnostic API client and types generated from OpenAPI specs
  • @repo/cli — TypeScript CLI for API (API key auth; ideal for agentic integrations)
  • @repo/react — React Query hooks for @repo/core API functions
  • @repo/ui — Shared UI component library (Shadcn/ui, Tailwind)
  • @repo/utils — Shared utilities (async, data, debug, error, logger, web3)
  • @repo/error — Error reporting and utilities (captureError, getErrorMessage)
  • @repo/email — Email template library built with React Email
  • @repo/notif — Notification scaffold (unused; package kept for future work)

Scripts

Run with pnpm <script>.

Setup

  • setup — Full setup (install, hooks, gitleaks, osv, env templates, database, deepsec, Playwright Chromium)
  • setup:gitleaks, setup:osv — Install Gitleaks, OSV scanner
  • setup:playwright — Install Playwright Chromium for API and web E2E
  • setup:env — Copy .env.<qualifier>.example templates to dest files when missing
  • setup:database — Database tools (Docker, Supabase CLI)
  • setup:deepsec — Install DeepSec workspace (.deepsec/)
  • reset — Local API database: Supabase reset + Drizzle migrations + seed (pnpm --filter @repo/api reset). See apps/api/README.md

Primary

  • build — Build packages and apps
  • dev — Start dev (core, react, error, utils, api, web)
  • qa — Full check: install (if needed) → checktypes → lint → OpenAPI drift → build → test (unit) → test:e2e (Fastify + Next, SKIP_BUILD=1) Format / Lint
  • checktypes — Type-check all packages
  • format — Format code (Biome)
  • lint — Lint with Biome + ESLint
  • lint:biome, lint:biome:fix — Biome check, fix
  • lint:eslint, lint:eslint:fix — ESLint check, fix
  • lint:fix — Fix both linters Test
  • test — Run unit tests (packages + apps)
  • test:e2e — E2E (Fastify + Next) CI
  • Lint and security.yml run on every PR. DeepSec reviews the PR diff on same-repo PRs from OWNER, MEMBER, or COLLABORATOR (deepsec.yml). App E2E (web-e2e, api-e2e) and package tests (packages-test) run only when relevant code changes. Mobile: EAS build, preview on main, PR OTA—see GitHub Actions and Mobile CI/CD. Security
  • security:block-files — Block sensitive file patterns
  • security:secrets — Scan staged files for secrets
  • security:secrets:full — Full Gitleaks scan
  • security:osv — OSV vulnerability scan
  • security:audit — pnpm audit (high+)
  • security:check — Run security check script
  • security:deepsec:scan — DeepSec regex scan (no AI)
  • security:deepsec:process:diff — DeepSec AI review vs origin/main (GPT-5.6 Sol)
  • security:deepsec:process:diff:grok — Same review with Cursor Grok 4.6
  • security:deepsec:process — DeepSec full-repo AI review (GPT-5.6 Sol)
  • security:deepsec:report — DeepSec findings summary Hooks
  • hooks:pre-commit — Pre-commit: security + Biome staged
  • hooks:security — Block files, scan secrets, OSV Misc
  • update-deps — Update pnpm and all dependencies

Documentation

Full docs: basilic-docs.vercel.app

  • Dev Environments — Local vs remote (ports 3000, 3001, 8081; start:localhost, start:tunnel)