🌪️ Spindrift

Heritable borders for React components that just work

A vaguely more tolerable React debugging experience with granular control

🌟 Why Spindrift?

Tired of wrestling with CSS just to debug your component layouts? Spindrift gives you laser-focused control over visual debugging borders without the performance overhead of recursive cloning.

You get a brand-new Div and Span component with rather underwhelming superpowers but hey, if you're anything like me, CSS is a scourge on the face of the earth and is the only thing stopping you from just doing things.

<Div from>
  <span>✨ Bordered</span>
  <div>✨ Also bordered</div>
  <Div to>
    <span>🚫 No border</span>
  </Div>
</Div>

Note: This is actively being developed. API may change in early versions.

✨ Features

🎯 CSS-only Performance Zero runtime overhead with pure CSS

🔧 Context-based Control
Global enable/disable and theming

📦 Tree-shakeable Import only what you need

🎨 Tailwind Integration Built-in plugin for seamless setup

🔒 TypeScript Native Full type safety with polymorphic components

⚡ Production Ready Auto-disable in production builds

📋 Prerequisites

• ⚛️ React 18+
• 🎨 Tailwind v4

📦 Installation

# npm
npm install spndrft

# pnpm
pnpm add spndrft

# yarn
yarn add spndrft

🚀 Quick Start

1️⃣ Setup Provider

"use client";

import { SpindriftProvider } from "spndrft";

function App() {
  return (
    <SpindriftProvider enabled={process.env.NODE_ENV !== "production"}>
      <YourApp />
    </SpindriftProvider>
  );
}

2️⃣ Add Styles

/* globals.css */
@import "spndrft/css";

3️⃣ Use Components

import { Div, Span } from "spndrft";

function MyComponent() {
  return (
    <Div from>
      <Span>🎯 This will have borders</Span>
      <Div>🎯 This will also have borders</Div>
      <Div to>
        <Span>⭕ This won't have borders</Span>
        <div>⭕ Neither will this</div>
      </Div>
    </Div>
  );
}

📖 API Reference

SpindriftProvider

The main provider component for global configuration.

interface SpindriftProviderProps {
  enabled?: boolean; // Default: process.env.NODE_ENV !== 'production'
  className?: string; // Default: 'spindrift'
  children: ReactNode;
}

Div & Span

React elements enhanced with Spindrift capabilities.

interface ComponentProps
  extends React.ComponentPropsWithoutRef<"div" | "span"> {
  from?: boolean; // 🟢 Start applying borders from this element
  to?: boolean; // 🔴 Stop applying borders at this element
}

🎯 Usage Patterns

Run the full example locally:

pnpm examples

🌟 Basic Usage

import { Div } from "spndrft";

// Apply borders to this div and all children
<Div from>
  <div>Child 1 📦</div>
  <div>Child 2 📦</div>
</Div>;

🎮 Nested Control

import { Div } from "spndrft";

<Div from>
  <div>✅ Has border</div>
  <Div to>
    <div>❌ No border</div>
    <Div from>
      <div>✅ Has border again</div>
    </Div>
  </Div>
</Div>;

🚀 Production Builds

// ✅ Always enabled
<SpindriftProvider enabled={true}>

// ❌ Always disabled
<SpindriftProvider enabled={false}>

// 🎯 Custom logic
<SpindriftProvider enabled={isDevelopment || isStorybook}>

🔧 TypeScript

Spindrift comes with comprehensive TypeScript support out of the box. Types are well-defined and provide excellent IntelliSense support.

⚡ Performance

| Feature | Benefit | | ------------------------ | ----------------------------------------------------- | | Zero cloning | Uses CSS selectors instead of recursive React cloning | | Constant time | O(1) rendering performance regardless of tree depth | | Tree-shakeable | Only bundles components you actually use | | Production optimized | Can be completely removed from production builds |

📄 License

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

If Spindrift helps you debug faster, consider giving it a ⭐!

Report Bug • Request Feature • Discussions