blitz-js/blitz
⚡️ The Missing Fullstack Toolkit for Next.js
Full-stack React framework toolkit built on Next.js
Blitz applications use RPC for client-server communication, with authentication state synchronized across browser tabs via localStorage events
Under the hood, the system uses 3 feedback loops, 3 data pools, 3 control points to manage its runtime behavior.
Structural Verdict
A 10-component nextjs app with 3 connections. 669 files analyzed. Loosely coupled — components are relatively independent.
How Data Flows Through the System
Blitz applications use RPC for client-server communication, with authentication state synchronized across browser tabs via localStorage events
- CLI Command — User runs blitz command, routed through command mapping to implementation
- Code Generation — Generators create models, queries, mutations from templates
- Authentication — Client manages auth state with token parsing and cross-tab synchronization
- RPC Invocation — Client calls server resolvers through RPC layer with React Query caching
- Error Handling — Error boundaries catch and handle RedirectError and other exceptions
System Behavior
How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
Stores authentication tokens and public user data
Caches RPC query results and mutations
Database connection pool and query interface
Feedback Loops
- Authentication State Sync (polling, balancing) — Trigger: localStorage change event. Action: Update auth state across tabs. Exit: State synchronized.
- Query Retry Logic (retry, balancing) — Trigger: Network request failure. Action: Retry with exponential backoff. Exit: Success or max retries reached.
- Session Reset (cache-invalidation, balancing) — Trigger: Session created event. Action: Clear React Query cache. Exit: Cache cleared.
Delays & Async Processing
- Session Reset Delay (async-processing, ~100ms) — Prevents stale authenticated queries from running after logout
- Cross-tab Message Bus (eventual-consistency) — Authentication state propagates to other browser tabs
Control Points
- NODE_ENV (env-var) — Controls: Query retry behavior in production vs development
- Command Mapping (runtime-toggle) — Controls: Which CLI commands are available
- Test Environment Split (feature-flag) — Controls: Client vs server test execution
Package Structure
This monorepo contains 12 packages:
Example Next.js 13 app demonstrating Blitz authentication with Prisma
Full-featured demo app showcasing complete Blitz toolkit with auth and database
Demo app using PassportJS authentication strategy
Simple web app example with basic routing
Core Blitz CLI and framework utilities
Authentication system with session management and CSRF protection
Next.js integration layer with Jest configuration and error boundaries
RPC system with React Query integration for client-server communication
Code transformation utilities for upgrading and migrating Blitz apps
Shared ESLint configuration for Blitz projects
Code generation system for creating models, queries, mutations, and pages
Template package for creating new Blitz packages
Technology Stack
Core React framework for SSR and routing
Client-side data fetching and caching
Database ORM and client
Testing framework with custom configuration
AST manipulation for codemods
Monorepo build orchestration
Type safety across all packages
Key Components
- PublicDataStore (class) — Manages client-side authentication state with localStorage synchronization across tabs
packages/blitz-auth/src/client/index.tsx - BlitzRpcPlugin (plugin) — Creates React Query client with Blitz-specific configuration and session handling
packages/blitz-rpc/src/query/react-query/index.ts - ErrorBoundary (component) — Handles RedirectError and other React errors with Next.js router integration
packages/blitz-next/src/error-boundary.tsx - commands (config) — Maps CLI command names to their implementation modules
packages/blitz/src/cli/index.ts - createJestConfigForNext (function) — Configures Jest with Next.js support and separate client/server test environments
packages/blitz-next/jest/index.js - findFunction (utility) — Locates function declarations in AST for code transformations
packages/codemod/src/utils.ts - AppGenerator (module) — Generates new Blitz applications with authentication and database setup
packages/generator/src/index.ts - parsePublicDataToken (function) — Decodes base64 authentication tokens to extract user public data
packages/blitz-auth/src/client/index.tsx - invoke (function) — Core RPC invocation mechanism for calling server-side resolvers
packages/blitz-rpc/src/client/index.ts - upgradeLegacy (cli-command) — Codemod for upgrading legacy Blitz applications to newer versions
packages/codemod/src/index.ts
Configuration
pnpm-workspace.yaml (yaml)
packages(array, unknown) — default: apps/*,packages/*,integration-tests/*,recipes/*
turbo.json (json)
$schema(string, unknown) — default: https://turbo.build/schema.jsonpipeline.buildapp.dependsOn(array, unknown) — default: ^buildpipeline.buildapp.outputs(array, unknown) — default: dist/**,.next/**pipeline.build.dependsOn(array, unknown) — default: ^buildpipeline.build.outputs(array, unknown) — default: dist/**,.next/**pipeline.test.outputs(array, unknown) — default: coverage/**pipeline.test.dependsOn(array, unknown) — default: ^buildpipeline.lint.outputs(array, unknown)- +3 more parameters
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Nextjs App Repositories
Frequently Asked Questions
What is blitz used for?
Full-stack React framework toolkit built on Next.js blitz-js/blitz is a 10-component nextjs app written in TypeScript. Loosely coupled — components are relatively independent. The codebase contains 669 files.
How is blitz architected?
blitz is organized into 4 architecture layers: Core Framework, CLI & Tooling, Example Applications, Integration Tests. Loosely coupled — components are relatively independent. This layered structure keeps concerns separated and modules independent.
How does data flow through blitz?
Data moves through 5 stages: CLI Command → Code Generation → Authentication → RPC Invocation → Error Handling. Blitz applications use RPC for client-server communication, with authentication state synchronized across browser tabs via localStorage events This pipeline design reflects a complex multi-stage processing system.
What technologies does blitz use?
The core stack includes Next.js (Core React framework for SSR and routing), React Query (Client-side data fetching and caching), Prisma (Database ORM and client), Jest (Testing framework with custom configuration), jscodeshift (AST manipulation for codemods), Turbo (Monorepo build orchestration), and 1 more. A focused set of dependencies that keeps the build manageable.
What system dynamics does blitz have?
blitz exhibits 3 data pools (localStorage, React Query Cache), 3 feedback loops, 3 control points, 2 delays. The feedback loops handle polling and retry. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does blitz use?
5 design patterns detected: Plugin Architecture, Command Pattern, Code Generation, AST Transformation, Multi-Environment Testing.
Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.