bsmnt 0.2.8 → 0.2.10

package/src/templates/next-experiments/README.md

@@ -1,221 +1,50 @@
-# Basement Next Starter
+# Basement Next Experiments Starter
 
-A production-ready Next.js starter with React 19, Tailwind CSS v4, TypeScript strict mode, and everything you need to build modern web applications.
-
-## Tech Stack
-
-| Technology | Version | Description |
-|------------|---------|-------------|
-| Next.js | 16.1 | App Router, Turbopack |
-| React | 19 | React Compiler enabled |
-| TypeScript | 5.9 | Strict mode, `noUncheckedIndexedAccess` |
-| Tailwind CSS | 4 | CSS-first configuration |
-| Biome | 2.3 | Linting and formatting |
-| Bun | 1.3 | Package manager and runtime |
-| Zustand | 5.0 | State management |
+Minimal Next.js starter for experiments and rapid prototyping with Tailwind CSS and Basement defaults.
 
 ## Quick Start
 
 ```bash
-# Clone the template
-bunx degit basementstudio/next-starter my-project
-
-# Install dependencies
-cd my-project && bun install
-
-# Start development
+bun install
 bun dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) to see the result.
-
 ## Scripts
 
 | Command | Description |
 |---------|-------------|
-| `bun dev` | Start development server with Turbopack |
-| `bun dev:https` | Start with HTTPS (for secure contexts) |
+| `bun dev` | Start the development server |
+| `bun dev:https` | Start the development server with HTTPS |
 | `bun build` | Build for production |
-| `bun start` | Start production server |
-| `bun generate` | Scaffold new components/hooks |
-| `bun lint` | Run Biome linter |
-| `bun lint:fix` | Fix lint issues |
-| `bun format` | Format code with Biome |
-| `bun typecheck` | Type check with tsgo |
-| `bun test` | Run tests with Bun |
-| `bun analyze` | Analyze bundle size |
+| `bun start` | Start the production server |
+| `bun lint` | Run Biome |
+| `bun lint:fix` | Run Biome with fixes |
+| `bun format` | Format the codebase |
+| `bun typecheck` | Run TypeScript |
+| `bun analyze` | Analyze the Next.js bundle |
 
 ## Project Structure
 
-```
-app/                     # Next.js App Router pages and routes
-  ├── api/               # API routes (draft-mode, revalidate)
-  ├── layout.tsx         # Root layout with metadata, fonts
-  ├── page.tsx           # Homepage
-  ├── sitemap.ts         # Dynamic sitemap generation
-  └── robots.ts          # SEO robots.txt
-
+```txt
+app/
 components/
-  ├── layout/
-  │   ├── header/        # Navigation header
-  │   ├── footer/        # Page footer
-  │   ├── wrapper/       # Page wrapper with theme
-  │   └── theme/         # Theme context provider
-  └── ui/
-      ├── image/         # Enhanced Next.js Image wrapper
-      └── link/          # Smart Link component
-
 lib/
-  ├── hooks/                      # Custom React hooks
-  │   ├── use-device-detection/   # Device/capability detection
-  │   ├── use-media-breakpoint/   # Responsive breakpoint hook
-  │   └── use-prefetch/           # Prefetch utilities
-  ├── integrations/               # Third-party integrations
-  ├── scripts/                    # Build and dev scripts
-  ├── store/                      # Zustand global state
-  ├── styles/                     # Design tokens, CSS config
-  │   ├── colors.ts               # Theme colors
-  │   ├── layout.mjs              # Breakpoints, grid, spacing
-  │   ├── easings.ts              # CSS easing variables
-  │   └── fonts.ts                # Font loading (Geist Mono)
-  └── utils/                      # Utility functions
-      ├── easings.ts              # 30+ animation easing functions
-      ├── math.ts                 # Math utilities
-      ├── strings.ts              # String utilities
-      └── fetch.ts                # Fetch utilities
-```
-
-## Features
-
-### Design System
-
-Pre-configured design tokens ready to use:
-
-**Breakpoints:**
-- `mobile`: 375px
-- `tablet`: 620px
-- `tablet-lg`: 1024px
-- `desktop`: 1440px
-- `desktop-large`: 1920px
-
-**Grid:**
-- Mobile: 4 columns
-- Desktop: 12 columns
-- Gap: 16px
-
-**Colors:**
-- Theme colors: `primary`, `secondary`, `contrast`
-- Accent colors: `red`, `blue`, `green`, `violet`, `pink`
-- Light/dark mode support
-
-**Easings:**
-30+ easing functions (quad, cubic, quart, quint, sine, expo, circ, back, elastic, bounce)
-
-### Smart Components
-
-**`<Image>`** - Enhanced Next.js Image wrapper:
-- Automatic responsive sizes based on breakpoints
-- Blur placeholder with shimmer effect
-- Preload support for LCP images
-- SVG handling
-
-**`<Link>`** - Intelligent link component:
-- Auto-detects external links (opens in new tab)
-- Connection-aware prefetching (4G only, respects data saver)
-- Falls back to button/div when no href
-- Active state detection
-
-**`<Wrapper>`** - Page layout component:
-- Includes Header and Footer
-- Theme provider integration
-- Flexible content area
-
-### Theme Support
-
-Light/dark theme with CSS custom properties:
-
-```tsx
-import { Wrapper } from "@/components/layout/wrapper"
-
-export default function Page() {
-  return (
-    <Wrapper theme="dark">
-      <section>Your content</section>
-    </Wrapper>
-  )
-}
+  hooks/
+  integrations/
+  scripts/
+  store/
+  styles/
+    index.css
+    tokens.css
+    global.css
+    fonts.ts
+    cn.ts
+  utils/
 ```
 
-Access theme in components:
-
-```tsx
-import { useTheme } from "@/components/layout/theme"
-
-function Component() {
-  const { name, setThemeName } = useTheme()
-  // ...
-}
-```
-
-### Performance Optimizations
-
-- **React Compiler** - Automatic memoization (no manual `useMemo`/`useCallback`)
-- **Turbopack** - Fast development builds
-- **Bundle Analyzer** - `bun analyze` to inspect bundle size
-- **Optimized Imports** - Auto-optimization for GSAP, Three.js, Lenis, Zustand
-- **Security Headers** - CSP, HSTS, XSS protection pre-configured
-- **Image Optimization** - AVIF, WebP with custom quality settings
-
-### Developer Experience
-
-- **Component Scaffolding** - `bun generate` to create components/hooks
-- **HTTPS Dev Server** - `bun dev:https` for secure contexts
-- **Strict TypeScript** - `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`
-- **Biome** - Fast linting and formatting with custom rules
-- **Tests** - Bun test runner with utilities
-
-## Configuration
-
-### Styles
-
-Edit design tokens in `lib/styles/`:
-
-- `colors.ts` - Theme and accent colors
-- `layout.mjs` - Breakpoints, grid, spacing
-- `typography.ts` - Font definitions
-- `easings.ts` - CSS easing variables
-
-After editing, regenerate CSS:
-
-```bash
-bun setup:styles
-```
-
-### Next.js
-
-Configuration in `next.config.ts`:
-
-- React Compiler enabled
-- Typed routes
-- SVG loader (@svgr/webpack)
-- Security headers
-- Image optimization settings
-
-## Deployment
-
-### Vercel (Recommended)
-
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/basementstudio/next-starter)
-
-### Other Platforms
-
-```bash
-bun build
-bun start
-```
-
-The app runs on port 3000 by default.
-
-## License
+## Styling
 
-MIT
+- Import `@/lib/styles/index.css` once in `app/layout.tsx`.
+- Edit `lib/styles/tokens.css` for theme variables, breakpoints, and custom Tailwind utilities.
+- Edit `lib/styles/global.css` for reset rules and app-wide global styles.
+- `lib/styles/fonts.ts` handles font variables.

package/src/templates/next-experiments/app/layout.tsx

@@ -2,10 +2,9 @@ import type { Metadata, Viewport } from "next";
 import { Geist } from "next/font/google";
 import { type PropsWithChildren, Suspense } from "react";
 import { Link } from "@/components/ui/link";
-import { themes } from "@/lib/styles/colors";
 import { fontsVariable } from "@/lib/styles/fonts";
 import AppData from "@/package.json";
-import "@/lib/styles/css/index.css";
+import "@/lib/styles/index.css";
 import { cn } from "@/lib/styles/cn";
 
 const APP_NAME = AppData.name;
@@ -74,7 +73,7 @@ export const metadata: Metadata = {
 
 export const viewport: Viewport = {
   colorScheme: "normal",
-  themeColor: themes.dark.primary,
+  themeColor: "#000000",
 };
 
 export default async function Layout({ children }: PropsWithChildren) {

package/src/templates/next-experiments/app/page.tsx

@@ -1,22 +1,39 @@
 import { Wrapper } from "@/components/layout/wrapper"
 import { Link } from "@/components/ui/link"
-import { colors } from "@/lib/styles/colors"
-import { breakpoints, layout } from "@/lib/styles/layout.mjs"
+
+const COLORS = [
+  { name: "black", value: "#000000" },
+  { name: "white", value: "#ffffff" },
+  { name: "orange", value: "#ff4d00" },
+  { name: "blue", value: "#487cff" },
+  { name: "green", value: "#00ff9b" },
+  { name: "violet", value: "#f101a5" },
+  { name: "pink", value: "#ff73a6" },
+  { name: "gray", value: "#666666" },
+] as const
+
+const BREAKPOINTS = [
+  { name: "mobile", value: 640 },
+  { name: "tablet", value: 768 },
+  { name: "tablet-lg", value: 1024 },
+  { name: "desktop", value: 1440 },
+  { name: "desktop-large", value: 1920 },
+] as const
 
 const TECH_STACK = [
-  { description: "App Router, Turbopack", name: "Next.js", version: "16.1" },
-  { description: "React Compiler enabled", name: "React", version: "19" },
-  { description: "Strict mode", name: "TypeScript", version: "5.9" },
-  { description: "CSS-first config", name: "Tailwind CSS", version: "4" },
-  { description: "Lint + Format", name: "Biome", version: "2.3" },
-  { description: "Package manager", name: "Bun", version: "1.3" },
+  { description: "App Router and modern React patterns", name: "Next.js" },
+  { description: "Server and client components", name: "React" },
+  { description: "Strict typechecking", name: "TypeScript" },
+  { description: "CSS-first styling", name: "Tailwind CSS" },
+  { description: "Linting and formatting", name: "Biome" },
+  { description: "Package management and scripts", name: "Bun" },
 ]
 
 const FEATURES = [
   {
     description:
-      "Pre-configured colors, breakpoints, typography, and 30+ easing functions ready to use.",
-    title: "Design System",
+      "A small Tailwind setup with CSS variables, custom utilities, and theme-ready defaults.",
+    title: "Minimal Styling",
   },
   {
     description:
@@ -30,7 +47,7 @@ const FEATURES = [
   },
   {
     description:
-      "Custom scripts for component scaffolding, style generation, and HTTPS dev server.",
+      "HTTPS dev support and sensible project defaults without extra generators.",
     title: "Developer Experience",
   },
   {
@@ -44,13 +61,10 @@ const SCRIPTS = [
   { cmd: "bun dev", desc: "Start development server" },
   { cmd: "bun dev:https", desc: "Start with HTTPS" },
   { cmd: "bun build", desc: "Build for production" },
-  { cmd: "bun generate", desc: "Scaffold components" },
   { cmd: "bun lint:fix", desc: "Fix lint issues" },
   { cmd: "bun typecheck", desc: "Type check with tsgo" },
 ]
 
-const VERSION = "1.0.0"
-
 export default function Home() {
   return (
     <Wrapper theme="dark">
@@ -58,7 +72,7 @@ export default function Home() {
       <section className="flex min-h-[80vh] flex-col justify-center px-safe pt-header-height">
         <div className="max-w-3xl">
           <p className="font-mono text-contrast text-sm uppercase tracking-wider">
-            Next.js Starter Template v{VERSION}
+            Next.js Starter Template
           </p>
           <h1 className="mt-4 font-semibold text-4xl leading-tight tracking-tight md:text-6xl">
             Basement Next Starter
@@ -96,12 +110,7 @@ export default function Home() {
               key={tech.name}
               className="border border-secondary/10 p-6 transition-colors hover:border-secondary/30"
             >
-              <div className="flex items-baseline justify-between">
-                <span className="font-semibold text-lg">{tech.name}</span>
-                <span className="font-mono text-contrast text-sm">
-                  v{tech.version}
-                </span>
-              </div>
+              <span className="font-semibold text-lg">{tech.name}</span>
               <p className="mt-2 text-secondary/60 text-sm">
                 {tech.description}
               </p>
@@ -137,15 +146,15 @@ export default function Home() {
             Colors
           </h3>
           <div className="mt-4 flex flex-wrap gap-3">
-            {Object.entries(colors).map(([name, value]) => (
-              <div key={name} className="flex items-center gap-2">
+            {COLORS.map((color) => (
+              <div key={color.name} className="flex items-center gap-2">
                 <div
                   className="size-8 rounded border border-secondary/20"
-                  style={{ backgroundColor: value }}
+                  style={{ backgroundColor: color.value }}
                 />
                 <div className="font-mono text-xs">
-                  <div className="text-secondary">{name}</div>
-                  <div className="text-secondary/40">{value}</div>
+                  <div className="text-secondary">{color.name}</div>
+                  <div className="text-secondary/40">{color.value}</div>
                 </div>
               </div>
             ))}
@@ -158,13 +167,15 @@ export default function Home() {
             Breakpoints
           </h3>
           <div className="mt-4 flex flex-wrap gap-4">
-            {Object.entries(breakpoints).map(([name, value]) => (
+            {BREAKPOINTS.map((breakpoint) => (
               <div
-                key={name}
+                key={breakpoint.name}
                 className="border border-secondary/10 px-4 py-2 font-mono text-sm"
               >
-                <span className="text-secondary">{name}</span>
-                <span className="ml-2 text-secondary/40">{value}px</span>
+                <span className="text-secondary">{breakpoint.name}</span>
+                <span className="ml-2 text-secondary/40">
+                  {breakpoint.value}px
+                </span>
               </div>
             ))}
           </div>
@@ -178,19 +189,15 @@ export default function Home() {
           <div className="mt-4 flex gap-8 font-mono text-sm">
             <div>
               <span className="text-secondary/40">Mobile:</span>{" "}
-              <span className="text-secondary">
-                {layout.columns.mobile} columns
-              </span>
+              <span className="text-secondary">4 columns</span>
             </div>
             <div>
               <span className="text-secondary/40">Desktop:</span>{" "}
-              <span className="text-secondary">
-                {layout.columns.desktop} columns
-              </span>
+              <span className="text-secondary">12 columns</span>
             </div>
             <div>
               <span className="text-secondary/40">Gap:</span>{" "}
-              <span className="text-secondary">{layout.gap.desktop}px</span>
+              <span className="text-secondary">16px</span>
             </div>
           </div>
         </div>
@@ -248,9 +255,9 @@ components/
   └── ui/            # Image, Link, SanityImage
 lib/
   ├── hooks/         # useDeviceDetection, useMediaBreakpoint
-  ├── scripts/       # Dev tools, generators
+  ├── scripts/       # Dev tooling
   ├── store/         # Zustand global state
-  ├── styles/        # Design tokens, CSS config
+  ├── styles/        # Tailwind entry, global CSS, fonts
   └── utils/         # Easings, math, strings, fetch`}
           </pre>
         </div>

package/src/templates/next-experiments/biome.json

@@ -214,20 +214,7 @@
       }
     },
     {
-      "includes": ["**/*.module.css"],
-      "linter": {
-        "rules": {
-          "correctness": {
-            "noUnknownProperty": "off"
-          },
-          "style": {
-            "noDescendingSpecificity": "off"
-          }
-        }
-      }
-    },
-    {
-      "includes": ["lib/styles/css/root.css"],
+      "includes": ["lib/styles/tokens.css"],
       "linter": {
         "rules": {
           "suspicious": {

package/src/templates/next-experiments/components/layout/theme/index.tsx

@@ -2,16 +2,14 @@
 
 import { usePathname } from "next/navigation"
 import { createContext, useContext, useEffect, useState } from "react"
-import type { Themes } from "@/lib/styles/colors"
-import { type ThemeName, themes } from "@/lib/styles/config"
+
+export type ThemeName = "light" | "dark"
 
 export const ThemeContext = createContext<{
   name: ThemeName
-  theme: Themes[ThemeName]
   setThemeName: (theme: ThemeName) => void
 }>({
   name: "light",
-  theme: themes.light,
   setThemeName: () => {
     void 0
   },
@@ -55,7 +53,6 @@ export function Theme({
       <ThemeContext.Provider
         value={{
           name: currentTheme,
-          theme: themes[currentTheme],
           setThemeName: setCurrentTheme,
         }}
       >

package/src/templates/next-experiments/components/layout/wrapper/index.tsx

@@ -6,8 +6,7 @@
 import cn from "clsx";
 import { Footer } from "@/components/layout/footer";
 import { Header } from "@/components/layout/header";
-import { Theme } from "@/components/layout/theme";
-import type { ThemeName } from "@/lib/styles/config";
+import { Theme, type ThemeName } from "@/components/layout/theme";
 
 /**
  * Props for the Wrapper component.

package/src/templates/next-experiments/components/ui/README.md

@@ -65,9 +65,8 @@ import { Link } from '@/components/ui/link'
 <Link href="/about">Internal</Link>
 <Link href="https://example.com">External</Link>
 
-// ✅ CSS Modules + Tailwind
-import s from './component.module.css'
-<div className={cn(s.wrapper, 'flex items-center')} />
+// ✅ Tailwind only
+<div className="flex items-center" />
 ```
 
 ## Related

package/src/templates/next-experiments/components/ui/image/index.tsx

@@ -9,7 +9,8 @@
 import cn from "clsx";
 import NextImage, { type ImageProps as NextImageProps } from "next/image";
 import type { CSSProperties, Ref } from "react";
-import { breakpoints } from "@/lib/styles/config";
+
+const DESKTOP_BREAKPOINT = 1440;
 
 /**
  * Enhanced Image component props extending Next.js Image.
@@ -167,7 +168,7 @@ export function Image({
   // Generate responsive sizes if not provided
   const finalSizes =
     sizes ||
-    `(max-width: ${breakpoints.desktop}px) ${mobileSize}, ${desktopSize}`;
+    `(max-width: ${DESKTOP_BREAKPOINT}px) ${mobileSize}, ${desktopSize}`;
 
   // Early return after hooks
   if (!src) return null;

package/src/templates/next-experiments/lib/README.md

@@ -27,7 +27,7 @@ import { colors, themes, breakpoints } from '@/lib/styles/config'
 
 ```bash
 bun dev              # Start dev server
-bun run generate     # Generate pages/components
-bun run setup:project  # Configure integrations
-bun setup:styles     # Regenerate CSS
+bun build            # Create production build
+bun lint:fix         # Fix lint issues
+bun typecheck        # Run type checks
 ```

package/src/templates/next-experiments/lib/hooks/use-device-detection.ts

@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react"
 import { useMedia } from "react-use"
-import { breakpoints } from "@/lib/styles/config"
+
+const MOBILE_BREAKPOINT = 640
 
 /**
  * Hook for detecting device capabilities and characteristics.
@@ -58,7 +59,7 @@ import { breakpoints } from "@/lib/styles/config"
  * ```
  */
 export function useDeviceDetection() {
-  const isMobile = useMedia(`(max-width: ${breakpoints.mobile - 1}px)`, true)
+  const isMobile = useMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`, true)
   const isReducedMotion = useMedia("(prefers-reduced-motion: reduce)")
   const [dpr, setDpr] = useState<number | undefined>(undefined)
   const [isSafari, setIsSafari] = useState<boolean | undefined>(undefined)

package/src/templates/next-experiments/lib/hooks/use-media-breakpoint.ts

@@ -1,5 +1,12 @@
 import { useMedia } from "react-use"
-import { breakpoints } from "@/lib/styles/config"
+
+const BREAKPOINTS = {
+  "desktop-large": 1920,
+  desktop: 1440,
+  "tablet-lg": 1024,
+  tablet: 768,
+  mobile: 640,
+} as const
 
 /**
  * Hook for detecting if the viewport is at a specific breakpoint.
@@ -8,8 +15,8 @@ import { breakpoints } from "@/lib/styles/config"
  * @returns True if the viewport is at the breakpoint
  */
 export function useMediaBreakpoint(
-  breakpoint: keyof typeof breakpoints,
+  breakpoint: keyof typeof BREAKPOINTS,
   defaultState = false
 ) {
-  return useMedia(`(min-width: ${breakpoints[breakpoint]}px)`, defaultState)
+  return useMedia(`(min-width: ${BREAKPOINTS[breakpoint]}px)`, defaultState)
 }

package/src/templates/next-experiments/lib/scripts/dev.ts

@@ -1,7 +1,5 @@
 /**
- * Cross-platform parallel dev script
- * Replaces npm-run-all for running multiple processes simultaneously
- * Works on Windows, macOS, and Linux using Bun's native APIs
+ * Cross-platform Next.js dev launcher.
  */
 
 import { bunExecutable, colorEnv } from "./utils"
@@ -14,39 +12,21 @@ const nextDevArgs = [bunExecutable, "next", "dev"]
 if (isHttps) nextDevArgs.push("--experimental-https")
 if (isInspect) nextDevArgs.push("--inspect")
 
-// Build environment with FORCE_COLOR
 const devEnv = colorEnv()
 
-const processes = [
-  // Style watcher
-  Bun.spawn(
-    [bunExecutable, "--watch", "./lib/styles/scripts/setup-styles.ts"],
-    {
-      stdout: "inherit",
-      stderr: "inherit",
-      env: devEnv,
-    }
-  ),
-
-  // Next.js dev server
-  Bun.spawn(nextDevArgs, {
-    stdout: "inherit",
-    stderr: "inherit",
-    env: devEnv,
-  }),
-]
-
-// Handle graceful shutdown
+const nextDevProcess = Bun.spawn(nextDevArgs, {
+  stdout: "inherit",
+  stderr: "inherit",
+  env: devEnv,
+})
+
 const cleanup = () => {
-  for (const proc of processes) {
-    proc.kill()
-  }
+  nextDevProcess.kill()
   process.exit(0)
 }
 
 process.on("SIGINT", cleanup)
 process.on("SIGTERM", cleanup)
 
-// Wait for any process to exit (if one crashes, we want to know)
-await Promise.race(processes.map((p) => p.exited))
+await nextDevProcess.exited
 cleanup()