Skip to content

tempest-react-sdk

Shared React/TypeScript building blocks used across Tempest frontends: an application foundation (Vite + @ alias, declarative routing, Zustand state, TanStack Query cache, providers), UI components, hooks, an HTTP client, an auth store, forms (zod), real-time transports (SSE / WebSocket / Web Push / Service Worker), theme, i18n, telemetry, feature flags, offline storage, an error boundary and a curated set of utilities.

The goal is to start every new React frontend with the same opinionated foundation already in place — no re-configuring Vite, no rewriting the auth store, no re-inventing the SSE reconnect loop. It ships the create-tempest-app CLI that scaffolds a whole wired-up project.

:material-translate: Languages / Idiomas — these docs are bilingual. Use the language switcher at the top of the page to toggle between Português (BR) and English (US).

Get started in 1 minute

Scaffold a new app already wired with the SDK (the CLI ships inside the package — create the folder, then scaffold into it with .):

mkdir my-app
cd my-app
npx -p tempest-react-sdk create-tempest-app .
npm install
cp .env.example .env
npm run dev            # http://127.0.0.1:5173

. is the destination: the current directory. It preserves whatever is already in the folder (git init, README.md) and takes the project name from the directory name — which is why it's the recommended mode. npm create tempest-app does not exist: the CLI is the SDK's bin, so -p tempest-react-sdk is what tells npx where to fetch it from. Both modes, and every piece of the command, are explained in Scaffold.

New here? Follow the Tutorial — User Guide: from scaffold to a complete app, one concept per page.

Already know the SDK and want to know how to organize the app? The Software Design tab teaches the design: layers, folder structure, where each kind of state lives, strong typing, hard limits (.tsx ≤ 150 lines) and the review checklist.

Manual install

In an existing Vite + React + TS project:

npm install tempest-react-sdk

Import the CSS once at your app entrypoint:

import "tempest-react-sdk/styles.css";

react, react-dom and react-router (^7 || ^8) are peer dependencies — all three carry React context, and a second copy breaks at runtime. Everything else — zustand, @tanstack/react-query, zod, react-hook-form, dexie, lucide-react — is a direct dependency, installed automatically with the SDK and externalized in the bundle (your bundler tree-shakes what you don't use). Details in Architecture.

What's inside

Area Pages
Tutorial Start here · Routing · State · Data fetching · Forms · Auth flow
App foundation Scaffold, Vite & alias, Routing, State (Zustand), Providers
Software Design Map — Layers, Folders, Data flow, State, Components, Limits, Typing, Testing, Anti-patterns, Checklist
Guide Architecture, Gallery (demo)
Components Catalogue — Data entry, Actions, Navigation, Overlay, Layout, Data, Feedback, Identity, Utility, Overlays & advanced
Hooks Utility hooks
Integrations HTTP, Auth, Query, SSE, WebSocket, Web Push, Offline, Web Share, Audio
Forms Forms (zod), Forms BR
Style & Theme Styles & Design Tokens, Theme, i18n
Observability Telemetry, Feature Flags, Logger, Error Boundary
Recipes Cookbook, Utilities
Project Testing helpers, Release pipeline

Quickstart (manual)

Mount the app root with <AppProviders> (error boundary + Query + theme + i18n in one block) and <AppRouter> (declarative routes):

import { AppProviders, AppRouter, defineRoutes } from "tempest-react-sdk";
import "tempest-react-sdk/styles.css";

const routes = defineRoutes([{ path: "/", element: <h1>Hello 👋</h1> }]);

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Something went wrong.</p> }}>
      <AppRouter routes={routes} fallback={<p>Loading…</p>} />
    </AppProviders>
  );
}

Repository & npm

The repo README is the npm/GitHub landing page. These docs are the navigable, per-module source of truth.