StaticFish Utils 🐟

A collection of developer utilities built with Bun, React, TanStack, and shadcn/ui.

Features • Quick Start • Available Utilities • Development

✨ Features

• 🌓 Dark/Light Mode - Toggle between themes, respects system preference
• 📱 Responsive Design - Works on desktop, tablet, and mobile
• 🔗 URL State Sharing - Share your utility configurations via URL
• 🔍 Search & Filter - Quickly find utilities or font styles
• ⚡ Hot Reload - Instant development feedback with Bun's HMR
• 📊 320+ ASCII Fonts - View text in every available figlet style
• 🔢 Sort Options - Default or alphabetical font ordering

🚀 Quick Start

# Install dependencies
bun install

# Start development server
bun run dev

# Build for production
bun run build

# Start production server
bun start

Visit http://localhost:3000

📁 Project Structure

staticfish-utils/
├── src/
│   ├── routes/              # TanStack Router file-based routes
│   │   ├── __root.tsx      # Root layout with sidebar
│   │   ├── index.tsx        # Homepage
│   │   └── ascii-art.tsx    # ASCII Art generator utility
│   ├── components/
│   │   ├── ui/             # shadcn/ui components
│   │   ├── Sidebar.tsx      # Navigation sidebar
│   │   ├── ThemeToggle.tsx   # Dark/light mode toggle
│   │   └── ThemeProvider.tsx # Theme context provider
│   ├── stores/
│   │   └── utilities.ts     # App state management
│   ├── hooks/
│   │   └── use-url-state.ts # URL state sharing hook
│   └── lib/
│       ├── ascii-art.ts     # ASCII art conversion logic
│       └── utils.ts        # Utility functions
├── styles/
│   └── globals.css        # Global styles with CSS variables
├── public/               # Static assets
└── src/index.ts          # Bun server with API routes

🛠 Available Utilities

ASCII Art Generator

Convert any text into ASCII art with 320+ font styles displayed simultaneously.

Features:

• View all fonts at once (no need to click through each one)
• Real-time search to find specific fonts
• Sort by default order or alphabetically (A-Z)
• Copy individual font outputs to clipboard
• Download any font as a .txt file
• Share configurations via URL
• Debounced generation for performance

URL Parameters:

• text - Input text to convert
• sort - Sort order: default or alphabetical

Example URLs:

/ascii-art?text=Hello&sort=alphabetical

🏗 Adding a New Utility

1. Create a Route File

Create a new file in src/routes/your-utility.tsx:

import { createFileRoute } from '@tanstack/react-router';

export const Route = createFileRoute('/your-utility')({
  component: YourUtility,
});

function YourUtility() {
  return (
    <div>
      <h1>Your Utility</h1>
      {/* Your utility content */}
    </div>
  );
}

2. Register the Utility

Add to src/stores/utilities.ts:

export const utilitiesStore = createStore<UtilitiesState>({
  utilities: [
    // ... existing utilities
    {
      id: 'your-utility',
      name: 'Your Utility',
      path: '/your-utility',
      description: 'Brief description of what your utility does',
      icon: 'IconName',     // From lucide-react
      category: 'Category',
      featured: true,       // Shows on homepage
    },
  ],
  recentlyUsed: [],
  searchQuery: '',
  sidebarOpen: true,
});

3. Track Usage (Optional)

Add to your utility component:

import { utilitiesActions } from '@/stores/utilities';

function YourUtility() {
  useEffect(() => {
    utilitiesActions.addToRecentlyUsed('your-utility');
  }, []);

  // ... component code
}

🔗 URL State Sharing

The use-url-state hook synchronizes state with URL query parameters for easy sharing.

Available Hooks

import {
  useURLStringState,
  useURLNumberState,
  useURLBooleanState,
  useURLObjectState,
} from '@/hooks/use-url-state';

Usage Examples

// String state
const [text, setText] = useURLStringState('text', 'Hello');

// Number state
const [count, setCount] = useURLNumberState('count', 10);

// Boolean state
const [enabled, setEnabled] = useURLBooleanState('enabled', false);

// Object state (JSON)
const [config, setConfig] = useURLObjectState('config', { key: 'value' });

Custom Hook

Create custom URL state hooks:

export function useURLCustomState() {
  return useURLStringState('custom', 'default-value', 500); // 500ms debounce
}

🎨 Theming

Dark/Light Mode

Themes are managed via next-themes:

import { useTheme } from 'next-themes';

function MyComponent() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      Toggle Theme
    </button>
  );
}

CSS Variables

Colors are defined in styles/globals.css with CSS variables:

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  /* ... more colors */
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  /* ... dark mode colors */
}

🔌 API Endpoints

ASCII Art API

Generate ASCII Art

POST /api/ascii-art
Content-Type: application/json

{
  "text": "Hello",
  "font": "Standard",
  "horizontalLayout": "default",
  "verticalLayout": "default"
}

Response:

{
  "ascii": "  _   _      \n | | | | ___ \n ..."
}

Generate All Fonts

POST /api/ascii-art/all
Content-Type: application/json

{
  "text": "Test"
}

Response:

{
  "results": {
    "Standard": "ASCII art...",
    "Big": "ASCII art...",
    "...": "..."
  },
  "total": 323
}

Get Available Fonts

GET /api/ascii-art

Response:

{
  "fonts": [
    "BlurVision ASCII",
    "Stacey",
    "DOS Rebel",
    "...",
    "Standard"
  ]
}

🛠 Development

Scripts

bun install        # Install dependencies
bun run dev        # Start dev server with HMR
bun run build      # Build for production
bun start         # Start production server
bunx tsc --noEmit # Type check

Adding shadcn/ui Components

bunx shadcn@latest add [component-name]

Available components: button, input, card, textarea, select, scroll-area, etc.

Code Style

• TypeScript strict mode enabled
• Use existing shadcn/ui components
• Follow existing patterns for new utilities
• Keep utility functions in src/lib/
• Store shared state in src/stores/

📦 Tech Stack

Category	Technology
Runtime	Bun
Framework	React 19
Routing	TanStack Router
State Management	TanStack Store
UI Components	shadcn/ui
Styling	Tailwind CSS 4
Icons	Lucide React
Theme Management	next-themes
Notifications	Sonner
ASCII Art	figlet

🚀 Performance

• Zero-Bundle Size Overhead - TanStack libraries are tree-shakeable
• Lazy Loading - Routes load on demand
• Optimized Debouncing - 300-500ms delays prevent API spam
• Bun's HMR - Sub-100ms hot module replacement
• Minimal Client-Side - ASCII generation happens on server

📝 License

MIT License - feel free to use this project for learning or building your own utilities.

🤝 Contributing

1. Fork the repository
2. Create a new branch (git checkout -b feature/amazing-utility)
3. Add your utility
4. Test thoroughly
5. Commit changes (git commit -m 'Add amazing utility')
6. Push to branch (git push origin feature/amazing-utility)
7. Open a Pull Request

---

Built with ❤️ using Bun, React, and TanStack