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.

Never written CSS? Start one step earlier

The tutorial already assumes React, components, hooks and ES modules. If that list reads like loose words, the Web Fundamentals track covers HTML, CSS, browser JavaScript, TypeScript and React in eleven short pages — and it is optional: if you already know React, go straight to the Tutorial.

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
Web Fundamentals Start here · HTML · Forms · CSS · Layout · Custom properties · JavaScript · Async · Modules · TypeScript · React
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.