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';exportconstRoute=createFileRoute('/your-utility')({component: YourUtility,});functionYourUtility(){return(<div><h1>Your Utility</h1>{/* Your utility content */}</div>);}

2. Register the Utility

Add to src/stores/utilities.ts:

exportconstutilitiesStore=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-reactcategory: 'Category',featured: true,// Shows on homepage},],recentlyUsed: [],searchQuery: '',sidebarOpen: true,});

3. Track Usage (Optional)

Add to your utility component:

import{utilitiesActions}from'@/stores/utilities';functionYourUtility(){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 stateconst[text,setText]=useURLStringState('text','Hello');// Number stateconst[count,setCount]=useURLNumberState('count',10);// Boolean stateconst[enabled,setEnabled]=useURLBooleanState('enabled',false);// Object state (JSON)const[config,setConfig]=useURLObjectState('config',{key: 'value'});

Custom Hook

Create custom URL state hooks:

exportfunctionuseURLCustomState(){returnuseURLStringState('custom','default-value',500);// 500ms debounce}

🎨 Theming

Dark/Light Mode

Themes are managed via next-themes:

import{useTheme}from'next-themes';functionMyComponent(){const{ theme, setTheme }=useTheme();return(<buttononClick={()=>setTheme(theme==='dark' ? 'light' : 'dark')}>
Toggle Theme
</button>);}

CSS Variables

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

:root {
--background:oklch(100);
--foreground:oklch(0.14500);
--primary:oklch(0.20500);
/* ... more colors */
}
.dark {
--background:oklch(0.14500);
--foreground:oklch(0.98500);
/* ... dark mode colors */
}

🔌 API Endpoints

ASCII Art API

Generate ASCII Art

POST /api/ascii-artContent-Type: application/json
{
"text": "Hello",
"font": "Standard",
"horizontalLayout": "default",
"verticalLayout": "default"
}

Response:

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

Generate All Fonts

POST /api/ascii-art/allContent-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