"beginning"

SATUS

The modern Next.js starter that brings it all together

A batteries-included Next.js starter with React 19, Tailwind v4, and the full Darkroom OS pre-configured. React Compiler enabled, optional WebGL, and integrations for Sanity, Shopify, and HubSpot.

880GitHub Stars

81Projects Using

bunx degit darkroomengineering/satus my-project

Website GitHub npm Docs

What's Included

Framework

Next.js 16
React 19
TypeScript 5

Styling

Tailwind v4
CSS Modules
CSS Variables

Darkroom OS

Lenis — smooth scroll
Tempus — RAF orchestration
Hamo — performance hooks
Elastica — physics engine

Performance

React Compiler
Turbopack
Image Optimization

Integrations

Sanity CMS
Shopify Storefront
HubSpot Forms

Optional

Developer Experience

Biome linting
Debug mode (Cmd+O)
Component library

Key Features

React Compiler

Automatic memoization enabled. No more useMemo, useCallback, or React.memo needed.

Smooth Scroll

Lenis pre-configured with Tempus integration for optimal RAF management.

Performance Hooks

Hamo hooks included for measurements without re-renders.

Debug Mode

Press Cmd/Ctrl + O to toggle debug overlay with grid, stats, and more.

WebGL Ready

Optional global canvas with lazy loading. Ready for Three.js when you need it.

Type Safe

Strict TypeScript config with no any allowed. Full type coverage.

Biome

Lightning-fast linting and formatting. No ESLint or Prettier config to maintain.

Component Library

Image, Link, and Button components with proper patterns built in.

CSS Grid System

Responsive grid utilities with mobile and desktop breakpoints.

Quick Start

Create a new project

# Clone the template
bunx degit darkroomengineering/satus my-project

# Navigate to project
cd my-project

# Install dependencies
bun install

# Start development server
bun dev

Or Use as GitHub Template

Create your own repository with the full Satus setup, including git history.

Use This Template

Project Structure

satus/
├── app/                    # Next.js App Router
│   ├── layout.tsx         # Root layout with providers
│   └── page.tsx           # Homepage
│
├── components/
│   ├── image/             # Optimized Image component
│   ├── link/              # Enhanced Link component
│   ├── layout/
│   │   ├── header/        # Site header
│   │   ├── footer/        # Site footer
│   │   └── wrapper/       # Page wrapper with Lenis
│   └── ui/                # UI primitives
│
├── lib/
│   ├── hooks/             # Custom React hooks
│   ├── integrations/      # CMS/API clients
│   ├── styles/
│   │   ├── config.ts      # Style configuration
│   │   ├── fonts.ts       # Font definitions
│   │   └── css/           # Generated CSS
│   └── utils/             # Utility functions
│
├── public/
│   └── fonts/             # Local font files
│
└── next.config.ts         # Next.js configuration

Configuration

Styles Config

All style variables are defined in lib/styles/config.ts and automatically generated into CSS.

lib/styles/config.ts

export const colors = {
  black: '#000000',
  white: '#ffffff',
  red: '#e30613',
  // Add your brand colors
}

export const themes = {
  light: {
    primary: '#ffffff',
    secondary: '#000000',
    contrast: '#e30613',
  },
  dark: {
    primary: '#000000',
    secondary: '#ffffff',
    contrast: '#e30613',
  },
}

export const breakpoints = {
  dt: 800, // Desktop breakpoint
}

Fonts

lib/styles/fonts.ts

import localFont from 'next/font/local'

const mono = localFont({
  src: [
    {
      path: '../../public/fonts/ServerMono/ServerMono-Regular.woff2',
      weight: '400',
      style: 'normal',
    },
  ],
  variable: '--next-font-mono',
})

// Add more fonts as needed
const fonts = [mono]
export const fontsVariable = fonts.map((f) => f.variable).join(' ')

Smooth Scroll Setup

Lenis is pre-configured in the Wrapper component. Just wrap your page content.

app/page.tsx

import { Wrapper } from '@/components/layout/wrapper'

export default function Page() {
  return (
    <Wrapper theme="dark" lenis={{}}>
      <main>
        {/* Your content */}
      </main>
    </Wrapper>
  )
}

Using Scroll Values

'use client'

import { useLenis } from 'lenis/react'

function ScrollProgress() {
  useLenis(({ progress }) => {
    // progress is 0 to 1
    document.body.style.setProperty('--scroll', progress.toString())
  })

  return null
}

Integrations

Sanity CMS

Content management with real-time preview and visual editing support.

// lib/integrations/sanity/client.ts
import { createClient } from '@sanity/client'

export const sanityClient = createClient({
  projectId: process.env.SANITY_PROJECT_ID,
  dataset: 'production',
  useCdn: true,
})

Shopify

E-commerce with the Storefront API for headless commerce.

// lib/integrations/shopify/client.ts
import { createStorefrontApiClient } from '@shopify/storefront-api-client'

export const shopifyClient = createStorefrontApiClient({
  storeDomain: process.env.SHOPIFY_STORE_DOMAIN,
  apiVersion: '2024-01',
  publicAccessToken: process.env.SHOPIFY_PUBLIC_TOKEN,
})

Debug Mode

Press Cmd/Ctrl + O to toggle the debug overlay with:

Grid overlay for layout debugging
FPS counter and performance stats
Scroll position indicator
Component boundaries

Debug tools are automatically tree-shaken in production builds.

Best Practices

Don't memoize manually

React Compiler handles it. Remove useMemo, useCallback, and React.memo.

Use Image wrapper

Always use @/components/image instead of next/image directly.

Use Link wrapper

Use @/components/link for consistent link behavior.

CSS Modules for complex

Use Tailwind for simple styles, CSS Modules for complex components.

Server Components by default

Only add 'use client' when you need interactivity or hooks.