Ir para o conteúdo

tempest-react-sdk

Blocos de construção React/TypeScript compartilhados pelos frontends da Tempest: uma fundação de aplicação (Vite + alias @, roteamento declarativo, estado com Zustand, cache com TanStack Query, providers), componentes de UI, hooks, cliente HTTP, store de auth, formulários (zod), transportes em tempo real (SSE / WebSocket / Web Push / Service Worker), tema, i18n, telemetria, feature flags, storage offline, error boundary e um conjunto curado de utilitários.

A meta é começar todo novo frontend React com a mesma fundação opinativa já montada — sem reconfigurar Vite, sem reescrever o store de auth, sem reinventar o loop de reconexão do SSE. Inclui a CLI create-tempest-app que gera um projeto inteiro já cabeado.

:material-translate: Idiomas / Languages — esta documentação é bilíngue. Use o seletor de idioma no topo da página para alternar entre Português (BR) e English (US).

Comece em 1 minuto

Gere um app novo já fiado com o SDK (a CLI vem dentro do pacote — crie a pasta e scaffolde dentro dela com .):

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

O . é o destino: diretório atual. Ele preserva o que já existe na pasta (git init, README.md) e tira o nome do projeto do nome do diretório — por isso é o modo recomendado. npm create tempest-app não existe: a CLI é o bin do SDK, então o -p tempest-react-sdk é o que diz ao npx de onde buscá-la. Os dois modos e cada pedaço do comando estão explicados em Scaffold.

Novo por aqui? Siga o Tutorial — Guia do Usuário: do scaffold ao app completo, um conceito por página.

Já sabe usar o SDK e quer saber como organizar o app? A aba Design de Software ensina o desenho: camadas, estrutura de pastas, onde mora cada estado, tipagem forte, limites objetivos (.tsx ≤ 150 linhas) e o checklist de revisão.

Instalação manual

Em um projeto Vite + React + TS existente:

npm install tempest-react-sdk

Importe o CSS uma vez no entrypoint do app:

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

react, react-dom e react-router (^7 || ^8) são peer dependencies — os três carregam contexto React, e uma segunda cópia quebra em runtime. Todo o resto — zustand, @tanstack/react-query, zod, react-hook-form, dexie, lucide-react — é dependência direta, instalada automaticamente com o SDK e externalizada no bundle (seu bundler faz tree-shake do que não usar). Detalhes em Arquitetura.

O que tem dentro

Área Páginas
Tutorial Comece aqui · Roteamento · Estado · Buscando dados · Formulários · Fluxo de auth
Estrutura de aplicação Scaffold, Vite & alias, Roteamento, Estado (Zustand), Providers
Design de Software Mapa — Camadas, Pastas, Fluxo de dados, Estado, Componentes, Limites, Tipagem, Testes, Anti-padrões, Checklist
Guia Arquitetura, Gallery (demo)
Componentes Catálogo — Entrada, Ação, Navegação, Overlay, Layout, Dados, Feedback, Identidade, Utilitários, Overlays & avançados
Hooks Hooks utilitários
Integrações HTTP, Auth, Query, SSE, WebSocket, Web Push, Offline, Web Share, Áudio
Formulários Forms (zod), Forms BR
Estilo & Tema Estilos & Design Tokens, Tema, i18n
Observabilidade Telemetry, Feature Flags, Logger, Error Boundary
Receitas Cookbook, Utilitários
Projeto Testing helpers, Release pipeline

Início rápido (manual)

Monte a raiz do app com <AppProviders> (error boundary + Query + tema + i18n num bloco só) e <AppRouter> (rotas declarativas):

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

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

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Algo deu errado.</p> }}>
      <AppRouter routes={routes} fallback={<p>Carregando…</p>} />
    </AppProviders>
  );
}

Repositório & npm

O README do repositório é a landing page do npm/GitHub. Esta documentação é a fonte de verdade navegável por módulo.