npm package: @pablohernanaraujo/bolt
Description: Modern React component library with server-first architecture, built for Next.js and performance
Author: Pablo Araujo
Latest version: 0.1.1

# Bolt ⚡

Modern React component library with server-first architecture, built for Next.js and performance.

[![npm version](https://badge.fury.io/js/@pablohernanaraujo%2Fbolt.svg)](https://badge.fury.io/js/@pablohernanaraujo%2Fbolt)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Tree Shaking](https://img.shields.io/badge/Tree%20Shaking-Supported-green.svg)](https://webpack.js.org/guides/tree-shaking/)

## Features

- 🚀 **Server-First Architecture**: SSR/RSC compatible components
- 🌳 **Tree-Shaking Ready**: Import only what you need
- 📱 **Responsive Design**: Mobile-first approach
- ♿ **Accessibility First**: Built with React Aria Components
- 🎨 **Design Tokens**: Consistent theming system
- 🔧 **TypeScript**: Full type safety out of the box
- ⚡ **Performance**: Zero-runtime CSS with vanilla-extract
- 🧪 **Well Tested**: Comprehensive test coverage with Vitest

## Installation

```bash
# npm
npm install @pablohernanaraujo/bolt

# pnpm
pnpm add @pablohernanaraujo/bolt

# yarn
yarn add @pablohernanaraujo/bolt
```

### Peer Dependencies

```bash
npm install react react-dom
```

## Quick Start

```tsx
import { Button, Modal, ThemeProvider } from '@pablohernanaraujo/bolt';

export default function App() {
  return (
    <ThemeProvider>
      <Button variant="primary" size="medium">
        Click me!
      </Button>
      
      <Modal>
        <Modal.Trigger asChild>
          <Button>Open Modal</Button>
        </Modal.Trigger>
        <Modal.Content>
          <Modal.Header>
            <Modal.Title>Welcome to Bolt</Modal.Title>
          </Modal.Header>
          <Modal.Body>
            <p>This is a modal built with Bolt components.</p>
          </Modal.Body>
        </Modal.Content>
      </Modal>
    </ThemeProvider>
  );
}
```

## Usage Patterns

### 1. Full Bundle Import (Recommended)

Import all components from the main package with automatic tree-shaking:

```tsx
import { Button, Input, Modal, Card } from '@pablohernanaraujo/bolt';
```

**Bundle Impact**: Only the components you actually use will be included in your bundle thanks to ES modules and tree-shaking.

### 2. Granular Imports

For maximum control over bundle size, import components individually:

```tsx
import { Button } from '@pablohernanaraujo/bolt/button';
import { Input } from '@pablohernanaraujo/bolt/input';
import { Modal } from '@pablohernanaraujo/bolt/modal';
```

### 3. Server/Client Component Splitting

Bolt supports Next.js Server Components with surgical client boundaries:

```tsx
// Server Component (default)
import { Button } from '@pablohernanaraujo/bolt/button';

// Client Component (when needed)
import { ButtonClient } from '@pablohernanaraujo/bolt/button/client';

// Or use the server variant explicitly
import { ButtonServer } from '@pablohernanaraujo/bolt/button/server';
```

## Component Categories

### Controls
```tsx
import { 
  Button, 
  IconButton, 
  Checkbox, 
  RadioGroup, 
  Toggle, 
  Link 
} from '@pablohernanaraujo/bolt';
```

### Forms
```tsx
import { 
  Input, 
  Textarea, 
  PasswordInput, 
  PinInput, 
  FileUpload, 
  FormField 
} from '@pablohernanaraujo/bolt';
```

### Layout
```tsx
import { 
  Container, 
  Flex, 
  Grid, 
  HStack, 
  VStack, 
  Center,
  AspectRatio 
} from '@pablohernanaraujo/bolt';
```

### Navigation
```tsx
import { 
  Breadcrumb, 
  Tabs, 
  Pagination, 
  Accordion 
} from '@pablohernanaraujo/bolt';
```

### Overlays
```tsx
import { 
  Modal, 
  Drawer, 
  Popover, 
  Tooltip, 
  Menu 
} from '@pablohernanaraujo/bolt';
```

### Content
```tsx
import { 
  Avatar, 
  Badge, 
  Code, 
  List, 
  Divider 
} from '@pablohernanaraujo/bolt';
```

### Feedback
```tsx
import { 
  Toast, 
  Spinner, 
  Skeleton, 
  Progress 
} from '@pablohernanaraujo/bolt';
```

### Typography
```tsx
import { 
  H1, H2, H3, H4, H5, 
  Body1, Body2, Body3, 
  Subtitle, 
  Caption, 
  Overline 
} from '@pablohernanaraujo/bolt';
```

## Next.js Integration

### App Router (Recommended)

```tsx
// app/layout.tsx
import { ThemeProvider } from '@pablohernanaraujo/bolt';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}
```

### Server Components

```tsx
// app/page.tsx (Server Component)
import { Container, H1, Button } from '@pablohernanaraujo/bolt';

export default function HomePage() {
  return (
    <Container>
      <H1>Welcome to Bolt</H1>
      <Button variant="primary">
        Server-rendered button
      </Button>
    </Container>
  );
}
```

### Client Components

```tsx
'use client';

import { useState } from 'react';
import { Button, Modal } from '@pablohernanaraujo/bolt';

export default function ClientComponent() {
  const [isOpen, setIsOpen] = useState(false);
  
  return (
    <Modal open={isOpen} onOpenChange={setIsOpen}>
      <Modal.Trigger asChild>
        <Button>Open Modal</Button>
      </Modal.Trigger>
      <Modal.Content>
        <Modal.Header>
          <Modal.Title>Interactive Modal</Modal.Title>
        </Modal.Header>
      </Modal.Content>
    </Modal>
  );
}
```

## Theming

### Using Built-in Themes

```tsx
import { ThemeProvider } from '@pablohernanaraujo/bolt';

export default function App() {
  return (
    <ThemeProvider theme="dark">
      {/* Your app */}
    </ThemeProvider>
  );
}
```

### Server-Side Theme Detection

```tsx
// app/layout.tsx
import { cookies } from 'next/headers';
import { ThemeProvider } from '@pablohernanaraujo/bolt';

export default async function RootLayout({ children }) {
  const cookieStore = await cookies();
  const theme = cookieStore.get('theme')?.value || 'light';
  
  return (
    <html data-theme={theme}>
      <body>
        <ThemeProvider theme={theme}>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}
```

## TypeScript Support

Bolt is built with TypeScript and provides complete type definitions:

```tsx
import type { ButtonProps, ModalProps } from '@pablohernanaraujo/bolt';

// All component props are fully typed
const CustomButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

// Granular type imports
import type { ButtonVariant, ButtonSize } from '@pablohernanaraujo/bolt/button';
```

## Bundle Size & Performance

### Tree Shaking

Bolt is designed for optimal tree-shaking:

```tsx
// ✅ Good - Only Button code is bundled
import { Button } from '@pablohernanaraujo/bolt';

// ✅ Also good - Explicit import
import { Button } from '@pablohernanaraujo/bolt/button';

// ❌ Avoid - Could bundle more than needed
import * as Bolt from '@pablohernanaraujo/bolt';
```

### Bundle Size Examples

| Import Pattern | Bundle Size | Gzipped |
|---------------|------------|---------|
| `import { Button }` | ~12KB | ~4KB |
| `import { Button, Input, Modal }` | ~28KB | ~9KB |
| Full component set | ~150KB | ~45KB |

### Performance Features

- **Zero-runtime CSS**: Styles are extracted at build time
- **Server-side rendering**: Components work without JavaScript
- **Progressive enhancement**: Interactive features layer on top
- **Deferred hydration**: Heavy components load when needed

## Browser Support

- **Modern browsers**: Chrome, Firefox, Safari, Edge (latest 2 versions)
- **Mobile browsers**: iOS Safari, Chrome Mobile
- **Node.js**: 18+ for SSR

## Migration Guide

### From Chakra UI

```tsx
// Before (Chakra UI)
import { Button, Box, Text } from '@chakra-ui/react';

// After (Bolt)
import { Button, Container, Body1 } from '@pablohernanaraujo/bolt';
```

### From Material-UI

```tsx
// Before (Material-UI)
import { Button, Container, Typography } from '@mui/material';

// After (Bolt)
import { Button, Container, H1 } from '@pablohernanaraujo/bolt';
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT © [Pablo Araujo](https://github.com/pabloaraujo)

## Links

- [Documentation](https://github.com/pablohernanaraujo/bolt#readme)
- [Storybook](https://github.com/pablohernanaraujo/bolt)
- [GitHub](https://github.com/pablohernanaraujo/bolt)
- [npm](https://www.npmjs.com/package/@pablohernanaraujo/bolt)

---

Built with ⚡ by the Bolt team