Repository files navigation

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

# Install dependenciesbun install# Setup environment variablescp .env.example .env.local# Start development server with Turbopackbun dev# Build for productionbun build# Start production serverbun start

• Next.js - React framework with App Router and Turbopack
• React 19.1.0 - Latest React with simplified ref handling
• TypeScript - Type-safe development
• Tailwind CSS - CSS-first configuration
• React Three Fiber - React renderer for Three.js
• GSAP - Timeline-based animations
• Biome - Fast formatter and linter
• Bun - All-in-one JavaScript runtime

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
• Dynamic imports for code splitting
• Image optimization with a custom thin wrapper around Next.js Image
• Font optimization with Next.js Font

• Tailwind CSS v4 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 for consistent code style
• Hot Module Replacement with Turbopack
• Git hooks with Lefthook
• Debug tools accessible withCMD+O

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

This template includes optional integrations that can be easily removed if not needed for your project:

1. Delete the integration directory fromintegrations/ (e.g.,integrations/shopify/)
2. Remove the corresponding page directory fromapp/(pages)/ (e.g.,app/(pages)/shopify/)
3. Remove any related imports or references in other files
4. Update documentation and environment variables as needed

This keeps the template lightweight and customized to your needs.

Sanity is integrated as a headless CMS with support for visual editing in the Next.js App Router. It uses React Server Components for server-side data fetching and client-side visual editing overlays.

• Dependencies: Managed vianext-sanity,@sanity/presentation,@sanity/visual-editing.
• Studio: Mounted at/studio usingNextStudio.
• Visual Editing: Enabled viapresentationTool insanity.config.ts with draft mode routes/api/draft and/api/disable-draft.
• Client: Configured inintegrations/sanity/client.ts with stega for visual editing.
• Queries: Server-side fetches in page components checkdraftMode() to fetch draft content withpreviewDrafts perspective.
• RSC Compatibility: Data fetching occurs on the server, with<VisualEditing /> component used client-side in layout.

Set these in.env.local (based on.env.example):

NEXT_PUBLIC_SANITY_PROJECT_ID="your-project-id"NEXT_PUBLIC_SANITY_DATASET="production"NEXT_PUBLIC_SANITY_STUDIO_URL="http://localhost:3000/studio"SANITY_API_WRITE_TOKEN="your-write-token"

• Real-time editing: Changes in Studio sidebar reflect instantly in preview
• Draft mode: Toggle between published and draft content
• Disable draft mode: UI component to exit draft mode when not in Studio
• Proper targeting: Components usedata-sanity attributes for editing overlay

For production applications, consider implementing Sanity's Live Content API withdefineLive,sanityFetch, andSanityLive components for optimal real-time performance and cache management.

1. Create a new Sanity project at sanity.io.
2. Update env vars with your project ID and dataset.
3. Configure schemas insanity/schemaTypes/.
4. Set up webhooks for revalidation at/api/revalidate.
5. To enable visual editing:
   • Install Sanity Presentation tool.
   • Ensure draft mode is configured.
   • Adddata-sanity attributes to editable elements.
6. Test by enabling draft mode and using the visual editor.

For detailed guidelines, refer toSanity Integration Guide.

Components use CSS modules with thes 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

# Developmentbun dev# Start dev server with Turbopack# Buildingbun build# Production buildbun analyze# Bundle analysis# Code Qualitybun lint# Run Biome linterbun typecheck# TypeScript checking# Stylingbun setup:styles# Generate style filesbun watch:styles# Watch style changes

Create a.env.local file based on.env.example:

# Sanity CMSNEXT_PUBLIC_SANITY_PROJECT_ID="your-project-id"NEXT_PUBLIC_SANITY_DATASET="production"NEXT_PUBLIC_SANITY_STUDIO_URL="http://localhost:3000/studio"SANITY_API_WRITE_TOKEN="your-write-token"# ShopifySHOPIFY_DOMAIN="your-store.myshopify.com"SHOPIFY_STOREFRONT_TOKEN="your-storefront-token"# HubSpotHUBSPOT_ACCESS_TOKEN="your-access-token"

• Sanity CMS Integration Guide - Complete guide for visual editing, content management, and development
• Component Guidelines
• Styling Guidelines
• WebGL Development
• Integration Guide
• Tailwind CSS v4 Reference

vercel

1. Environment variables are set in Vercel
2. Sanity webhooks are configured
3. GSAP license is valid (if using premium features)
4. SSL certificates are valid
5. Performance metrics are within acceptable ranges

• Vercel Analytics Dashboard
• Lighthouse CI Reports
• Performance monitoring with hooks/use-performance.ts

1. Content changes through Sanity will automatically update via webhooks
2. For code changes, follow the standard Vercel deployment flow
3. Clear cache if needed:https://your-domain.com/api/revalidate

1. Sanity Visual Editor Not Working

   • Check environment variables
   • Verify draft mode configuration
   • Ensure presentation tool is properly configured

2. Style Updates Not Reflecting

   • Runbun setup:styles
   • Clear browser cache
   • Check deployment status

3. Performance Issues

   • Check Theatre.js sequences
   • Verify GSAP animations
   • Monitor WebGL performance

The project supports deployment to any platform that supports Next.js:

• Netlify
• AWS Amplify
• Google Cloud Run
• Self-hosted with Node.js

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 theLICENSE file for details.

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