A modern, high-performance React application starter with Next.js 16, React 19, Tailwind CSS v4, and advanced WebGL capabilities. Satūs means "start" or "beginning" in Latin, serving as a foundation for new projects.

Note: This README is for developers working on the Satūs template. For client/team handoff documentation, see PROD-README.md (replace this README in production projects).

# Install dependencies bun install # Create .env.local (see Environment Variables below)# touch .env.local# Start development server with Turbopack bun dev # Build for production bun build # Start production server bun start

• Next.js 16.0.1 - React framework with App Router, Turbopack, and Cache Components
• React 19.2.0 - Latest React with <Activity />, useEffectEvent, and cacheSignal
• React Compiler - Automatic optimization enabled
• TypeScript - Type-safe development
• Tailwind CSS 4.1.16 - CSS-first configuration
• React Three Fiber - React renderer for Three.js
• GSAP - Timeline-based animations
• Biome 2.3.3 - Fast formatter and linter
• Bun - All-in-one JavaScript runtime

Manages off-screen component visibility and defers updates for better performance:

import{Activity}from'react'<Activitymode={isVisible ? 'visible' : 'hidden'}><ExpensiveComponent/></Activity>

Use Cases: Tab systems, accordions, off-screen WebGL scenes

Separates event logic from effect dependencies to prevent unnecessary re-runs:

import{useEffect,useEffectEvent}from'react'constonConnected=useEffectEvent(()=>{showNotification('Connected!',theme)// Theme changes won't trigger reconnect})useEffect(()=>{// Only reconnect when url changes},[url])

Provides automatic request cleanup when cache scope expires:

import{cacheSignal}from'react'asyncfunctionfetchUserData(id: string){constsignal=cacheSignal()// Auto-aborts on cache expiryconstresponse=awaitfetch(`/api/users/${id}`,{ signal })returnresponse.json()}

satus/ ├── app/ # Next.js App Router pages and layouts ├── components/ # Reusable UI components ├── hooks/ # Custom React hooks ├── integrations/ # Third-party service integrations │ ├── hubspot/ # HubSpot forms integration │ ├── shopify/ # E-commerce functionality │ └── sanity/ # Headless CMS ├── libs/ # Utility functions and helpers ├── orchestra/ # Debug and development tools │ ├── grid/ # Grid overlay │ ├── minimap/ # Page minimap │ ├── stats/ # Performance stats │ └── theatre/ # Animation tools ├── styles/ # Global styles and configuration ├── webgl/ # 3D graphics and WebGL components └── public/ # Static assets 

• Turbopack for lightning-fast HMR in development
• React Server Components by default
• React Compiler automatically optimizes re-renders and memoization (see React Compiler section)
• Next.js 16 Cache Components for advanced caching strategies
• React 19.2 <Activity /> for off-screen component optimization
• Dynamic imports for code splitting
• Image optimization with a custom thin wrapper around Next.js Image
• Font optimization with Next.js Font

• Tailwind CSS 4.1.16 with CSS-first configuration
• CSS Modules for component styles
• Custom viewport units (mobile-vw, desktop-vw)
• Theme support with CSS variables

• WebGL/Three.js integration with React Three Fiber
• Post-processing effects pipeline
• Shader support with GLSL
• Theatre.js for animation debugging
• Optimized 3D performance

• TypeScript with strict mode
• Biome 2.3.3 for consistent code style
• React Compiler - automatic optimization (no manual memoization needed)
• Hot Module Replacement with Turbopack
• React 19.2 Performance Tracks in Chrome DevTools
• Git hooks with Lefthook
• Debug tools accessible with CMD+O

• Sanity - Headless CMS with visual editing
• Shopify - E-commerce with cart functionality
• HubSpot - Forms and marketing automation

Check which integrations are configured:

bun validate:env # Check environment setup bun cleanup:integrations # List unused integrations

Remove unused integrations to reduce bundle size (~250-400KB potential savings). See Integrations Documentation for detailed removal instructions.

Components use CSS modules with the s import convention:

importsfrom'./component.module.css'functionComponent(){return<divclassName={s.wrapper}/>}

Custom viewport functions for responsive sizing:

.element{width:mobile-vw(150); /* 150px at mobile viewport */height:desktop-vh(100); /* 100px at desktop viewport */ }

CSS variables for consistent theming:

.element{color:var(--color-text); background-color:var(--color-background)}

• Theatre.js Studio - Visual animation editor
• FPS Meter - Performance monitoring
• Grid Overlay - Layout debugging
• Minimap - Page overview

# Development bun dev # Start dev server with Turbopack bun build # Production build bun start # Start production server# Code Quality bun lint # Run Biome linter bun lint:fix # Fix linting issues bun typecheck # TypeScript validation# Utilities bun setup:styles # Generate style files bun validate:env # Check environment variables bun cleanup:integrations # List unused integrations bun analyze # Bundle analysis

Create a .env.local file with your required variables. See integrations/README.md for the complete list of all available environment variables.

• App - Next.js structure and routing
• Integrations - Third-party integrations
• Components - UI components
• Hooks - Custom React hooks
• Libs - Utility libraries
• Styles - Styling system
  • Scripts - Style generation
• WebGL - 3D graphics
• Orchestra - Debug tools

Deploy to Vercel (recommended):

vercel

• Environment variables configured
• Sanity webhooks set up
• GSAP license valid (if using premium)
• SSL certificates configured
• Performance metrics validated

Supports any Next.js-compatible platform: Vercel, Netlify, AWS Amplify, Google Cloud Run, or self-hosted.

Images & Links

• ✅ Always use ~/components/link (auto-detects external, smart prefetch)
• ✅ Always use ~/components/image for DOM (never next/image directly)
• ✅ Use ~/webgl/components/image in WebGL contexts
• See Image Component documentation for details

GSAP & Animation

• Add <GSAPRuntime /> in app/layout.tsx for ScrollTrigger + Lenis
• No manual ticker setup needed
• See GSAP documentation for setup details

React Compiler{#react-compiler}

• Enabled automatically in next.config.ts (reactCompiler: true)
• No need for manual useMemo, useCallback, or React.memo - compiler handles optimization automatically
• Exception: Use useRef for object instantiation to prevent infinite loops

Sanity

• Requires draft mode routes: /api/draft-mode/enable and /api/draft-mode/disable
• Must set NEXT_PUBLIC_BASE_URL for preview resolution

Orchestra

• Toggle debug tools with Cmd/Ctrl + O
• State persists in localStorage and syncs across tabs
• Automatically excluded from production builds

Shopify

• Use exact env var names: SHOPIFY_STORE_DOMAIN, SHOPIFY_STOREFRONT_ACCESS_TOKEN

Next.js 16 Features

• Cache Components enabled (cacheComponents: true)
• Typed routes enabled for better TypeScript support
• Advanced caching strategies available

⚠️ Cache Components Gotchas:{#cache-components-gotchas}

• Server Components Only: Cache Components work only in Server Components, not Client Components
• Suspense Boundaries Required: Cached components must be wrapped in Suspense boundaries
• User-Specific Data: Never cache personalized/user-specific data (risk of data leakage between users)
• Real-Time Data: Opt out of caching for live data (stock prices, live feeds) using cache: 'no-store'
• Development vs Production: Caching behavior differs - test in both environments
• Router Cache vs Data Cache: Next.js has multiple caching layers - test with hard refresh and navigation
• "use cache" Directive: Use 'use cache' directive explicitly when you need component-level caching
• Dynamic Routes: Cache invalidation works differently for dynamic routes - use revalidateTag or revalidatePath

1. Fork the repository
2. Create your feature branch (git checkout -b feature/fix-everything)
3. Commit your changes (git commit -m 'Add fix everything feature')
4. Push to the branch (git push origin feature/fix-everything)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• Built by darkroom.engineering
• Inspired by modern web development best practices
• Community contributions and feedback