docs: readme
This commit is contained in:
valknarness
176
CLAUDE.md
Normal file
176
CLAUDE.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Awesome Web** is a Next.js 15 web application for browsing and searching "awesome lists" from GitHub. It features full-text search powered by SQLite FTS5, personal list management with a rich markdown editor, and automated database builds via GitHub Actions.
|
||||
|
||||
**Tech Stack:**
|
||||
- Next.js 15 (App Router) + TypeScript
|
||||
- Tailwind CSS 4 with custom theme (purple/pink/gold gradients)
|
||||
- shadcn/ui components (New York style)
|
||||
- SQLite3 with better-sqlite3 + FTS5 for full-text search
|
||||
- Zustand for state management
|
||||
- TipTap for WYSIWYG markdown editing
|
||||
- Node.js 22+ required
|
||||
|
||||
## Common Development Commands
|
||||
|
||||
```bash
|
||||
# Development server
|
||||
npm run dev
|
||||
|
||||
# Production build
|
||||
npm run build
|
||||
npm start
|
||||
|
||||
# Type checking
|
||||
npm run type-check
|
||||
|
||||
# Linting
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Database Layer (`lib/db.ts`)
|
||||
|
||||
Central database abstraction for SQLite operations:
|
||||
- **Connection Management**: Singleton pattern with WAL mode for concurrency
|
||||
- **Database Path**: `$AWESOME_DB_PATH` or `~/.awesome/awesome.db` (from awesome CLI)
|
||||
- **Core Functions**:
|
||||
- `searchRepositories()` - FTS5 full-text search with faceted filtering (language, stars, category)
|
||||
- `getAwesomeLists()` - Hierarchical list of awesome lists
|
||||
- `getRepositoryWithReadme()` - Fetch repository details with README content
|
||||
- `getCategories()` / `getLanguages()` - Facet data for filters
|
||||
- `getStats()` - Database statistics for homepage
|
||||
|
||||
**Search Architecture**: Uses SQLite FTS5 with `readmes_fts` virtual table. Queries are parsed into FTS format (`"term1"* OR "term2"*`) and support sorting by relevance, stars, or recent activity.
|
||||
|
||||
### Personal List Management (`lib/personal-list-store.ts`)
|
||||
|
||||
Zustand store with localStorage persistence for user-curated lists:
|
||||
- **Items Management**: CRUD operations for saved repositories/resources
|
||||
- **Markdown Sync**: Bidirectional sync between structured items and markdown representation
|
||||
- **Editor Integration**: State for TipTap editor (view modes: editor/preview/split)
|
||||
- **Export/Import**: JSON export and markdown generation
|
||||
|
||||
### API Routes (`app/api/*`)
|
||||
|
||||
- `/api/search` - Repository search endpoint (wraps `lib/db.ts`)
|
||||
- `/api/repositories/[id]` - Single repository details
|
||||
- `/api/lists` - User personal lists CRUD
|
||||
- `/api/lists/[id]` - Single list operations
|
||||
- `/api/stats` - Database statistics
|
||||
- `/api/db-version` - Database version for cache invalidation
|
||||
- `/api/webhook` - GitHub Actions webhook for database update notifications
|
||||
|
||||
### Component Structure
|
||||
|
||||
**Layout Components** (`components/layout/`):
|
||||
- `app-header.tsx` - Main navigation with command menu trigger
|
||||
- `app-sidebar.tsx` - Tree navigation for awesome lists hierarchy
|
||||
- `command-menu.tsx` - Global search command palette (Cmd+K)
|
||||
|
||||
**Personal List Components** (`components/personal-list/`):
|
||||
- `personal-list-editor.tsx` - TipTap-based markdown editor with rich formatting
|
||||
- `push-to-list-button.tsx` - "Add to list" button for repositories
|
||||
- `sliding-panel.tsx` - Side panel for personal list management
|
||||
- `personal-list-items.tsx` - Structured view of saved items
|
||||
|
||||
**README Viewer** (`components/readme/`):
|
||||
- `readme-viewer.tsx` - Markdown rendering with syntax highlighting (marked + highlight.js)
|
||||
- `readme-header.tsx` - Repository metadata header (stars, language, actions)
|
||||
|
||||
**UI Components** (`components/ui/`):
|
||||
- shadcn/ui components (New York style)
|
||||
- Custom `kbd.tsx` for keyboard shortcut displays
|
||||
|
||||
### Theme System
|
||||
|
||||
Custom Tailwind theme matching the awesome CLI branding:
|
||||
- **Primary Colors**: `--awesome-purple: #DA22FF`, `--awesome-pink: #FF69B4`, `--awesome-gold: #FFD700`
|
||||
- **Gradients**: Utility classes for purple-to-gold gradients (buttons, text, backgrounds)
|
||||
- **Dark Mode**: Next-themes integration with system preference detection
|
||||
- **Typography**: Tailwind typography plugin for markdown rendering
|
||||
|
||||
Configuration in `tailwind.config.ts` and `app/globals.css`.
|
||||
|
||||
### Database Build System
|
||||
|
||||
**Automated Builds** (`.github/workflows/db.yml`):
|
||||
- Runs every 6 hours or manual trigger
|
||||
- Two modes:
|
||||
1. **Download mode** (default, ~5 min): Downloads pre-built DB from `valknarness/awesome` repository
|
||||
2. **Build mode** (~1-2 hours): Clones awesome CLI and runs full indexing
|
||||
- Artifacts retained for 90 days with metadata JSON
|
||||
|
||||
**Build Script** (`scripts/build-db.js`):
|
||||
- Uses GitHub CLI to download artifacts or spawns awesome CLI indexer
|
||||
- Generates `db-metadata.json` with build stats
|
||||
- Fallback to local build if download fails
|
||||
|
||||
### Page Routes
|
||||
|
||||
- `/` - Landing page with statistics and featured lists
|
||||
- `/browse` - Browse all awesome lists
|
||||
- `/search` - Search interface with faceted filtering
|
||||
- `/list/[id]` - Single awesome list view with repositories
|
||||
- `/repository/[id]` - Repository detail with README
|
||||
- `/readme/[owner]/[repo]` - Direct README viewer
|
||||
- `/my-list` - Personal list editor
|
||||
- `/legal`, `/disclaimer`, `/imprint` - Legal pages
|
||||
|
||||
## Important Development Notes
|
||||
|
||||
### Database Schema Expectations
|
||||
|
||||
The SQLite database must have these tables:
|
||||
- `awesome_lists` - List metadata (id, name, url, description, category, stars, parent_id, level)
|
||||
- `repositories` - Repository data (id, awesome_list_id, name, url, description, stars, language, topics)
|
||||
- `readmes` - README content (id, repository_id, raw_content)
|
||||
- `readmes_fts` - FTS5 virtual table for full-text search
|
||||
|
||||
### Path Aliases
|
||||
|
||||
- `@/` maps to project root
|
||||
- `@/components` - React components
|
||||
- `@/lib` - Utilities and shared logic
|
||||
- `@/hooks` - Custom React hooks
|
||||
- `@/app` - Next.js app router pages
|
||||
|
||||
### Service Worker
|
||||
|
||||
`public/worker.js` implements background polling for database updates:
|
||||
- Polls `/api/db-version` with exponential backoff
|
||||
- Notifies client on version change for cache invalidation
|
||||
- Smart polling reduces when page inactive
|
||||
|
||||
### Node.js Version
|
||||
|
||||
Requires Node.js 22+ (specified in `package.json` engines). Use pnpm for package management.
|
||||
|
||||
### shadcn/ui Components
|
||||
|
||||
Components use "New York" style variant. When adding new shadcn components, ensure they match the custom theme colors defined in `components.json` and `app/globals.css`.
|
||||
|
||||
### Adding New Search Filters
|
||||
|
||||
When extending search functionality:
|
||||
1. Update `SearchOptions` interface in `lib/db.ts`
|
||||
2. Add filter logic to SQL query in `searchRepositories()`
|
||||
3. Update API route in `app/api/search/route.ts`
|
||||
4. Add UI controls in search page components
|
||||
|
||||
### TipTap Editor Extensions
|
||||
|
||||
The personal list editor uses these TipTap extensions:
|
||||
- Starter Kit (basic formatting)
|
||||
- Code Block Lowlight (syntax highlighting)
|
||||
- Table extensions (table support)
|
||||
- Task List/Item (checklist support)
|
||||
- Character Count (word count display)
|
||||
- Typography (smart quotes, em dashes)
|
||||
|
||||
When modifying the editor, ensure all extensions are properly configured in `personal-list-editor.tsx`.
|
||||
670
README.md
670
README.md
@@ -1,339 +1,349 @@
|
||||
# ✨ AWESOME WEB - Next-Level Ground-Breaking AAA Webapp ✨
|
||||
<div align="center">
|
||||
|
||||
> A stunning, feature-rich web application for exploring and discovering awesome lists from GitHub
|
||||
# 🕶️ ✨ AWESOME WEB ✨ 🕶️
|
||||
### *The Most Funkadelic, Cosmically-Enhanced, Star-Powered GitHub Explorer in the Known Universe!*
|
||||
|
||||
**🚀 Built with:** Next.js 18 • Tailwind CSS 4 • shadcn/ui • SQLite3 • Web Workers • PWA
|
||||
|
||||
|
||||
## 🎨 Design Philosophy
|
||||
> 🎤 *"Yeah baby! We got that COSMIC SLOP of awesome lists, sprinkled with STARDUST and served on a MOTHERSHIP of Next.js goodness! Slide into the funkiest GitHub explorer this side of the galaxy, ya dig?"*
|
||||
>
|
||||
> **— Bootsy Collins, Minister of Funk & Chief Awesome Officer**
|
||||
|
||||
This webapp perfectly matches the **beautiful purple/pink/gold theme** from the Awesome CLI:
|
||||
- 💜 **Awesome Purple**: `#DA22FF`
|
||||
- 💗 **Awesome Pink**: `#FF69B4`
|
||||
- 💛 **Awesome Gold**: `#FFD700`
|
||||
[](https://github.com)
|
||||
[](https://github.com)
|
||||
[](https://github.com)
|
||||
[](https://github.com)
|
||||
|
||||
## 🌟 Features Implemented
|
||||
|
||||
### ✅ Core Infrastructure
|
||||
|
||||
1. **Next.js 18 Setup**
|
||||
- App router with TypeScript
|
||||
- Optimized build configuration
|
||||
- PWA support ready
|
||||
- Image optimization
|
||||
|
||||
2. **Tailwind CSS 4 Custom Theme**
|
||||
- Matching CLI color scheme
|
||||
- Custom gradient utilities
|
||||
- Beautiful button styles
|
||||
- Smooth animations
|
||||
- Custom scrollbar
|
||||
- Typography plugin
|
||||
|
||||
3. **GitHub Actions Workflow**
|
||||
- Two build modes:
|
||||
- **Download Mode**: Fast (~5 min) - downloads pre-built database from awesome CLI repo
|
||||
- **Build Mode**: Slow (~1-2 hours) - builds locally using awesome CLI indexer
|
||||
- Runs every 6 hours (download mode by default)
|
||||
- Manual trigger with mode selection
|
||||
- Configurable source repository
|
||||
- Artifact upload (90-day retention)
|
||||
- Metadata generation with build stats
|
||||
- Fallback to local build if download fails
|
||||
|
||||
4. **Web Worker System**
|
||||
- Smart polling with exponential backoff
|
||||
- Cache invalidation
|
||||
- Client notification system
|
||||
- Efficient resource usage
|
||||
- Background updates
|
||||
|
||||
5. **API Routes**
|
||||
- `/api/db-version` - Database version endpoint
|
||||
- `/api/webhook` - GitHub Actions webhook handler
|
||||
- Signature verification
|
||||
- Metadata management
|
||||
|
||||
### 🎯 Architecture
|
||||
|
||||
```
|
||||
awesome-web/
|
||||
├── .github/workflows/
|
||||
│ └── db.yml ✅ Automated DB building
|
||||
├── app/
|
||||
│ ├── layout.tsx ✅ Root layout with theme
|
||||
│ ├── globals.css ✅ Custom awesome styles
|
||||
│ ├── api/
|
||||
│ │ ├── db-version/ ✅ Version checking
|
||||
│ │ └── webhook/ ✅ Update notifications
|
||||
│ ├── page.tsx 🔨 Landing hero (to build)
|
||||
│ ├── list/[id]/ 🔨 List index page
|
||||
│ ├── readme/[...]/ 🔨 README viewer
|
||||
│ ├── legal/ 🔨 Legal pages
|
||||
│ └── not-found.tsx 🔨 404 with easter egg
|
||||
├── components/
|
||||
│ ├── ui/ 🔨 shadcn components
|
||||
│ ├── layout/
|
||||
│ │ ├── sidebar.tsx 🔨 Tree navigation
|
||||
│ │ └── command-menu.tsx🔨 Search command
|
||||
│ ├── search/
|
||||
│ │ ├── facets.tsx 🔨 Search facets
|
||||
│ │ └── filters.tsx 🔨 Advanced filters
|
||||
│ └── providers/
|
||||
│ └── worker-provider.tsx 🔨 Worker integration
|
||||
├── public/
|
||||
│ ├── worker.js ✅ Service worker
|
||||
│ ├── manifest.json ✅ PWA manifest
|
||||
│ └── icons/ 🔨 Generate from logo
|
||||
├── scripts/
|
||||
│ └── build-db.js ✅ Database builder (download/build modes)
|
||||
├── tailwind.config.ts ✅ Custom theme
|
||||
└── next.config.js ✅ PWA & optimization
|
||||
```
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
cd /home/valknar/Projects/node.js/awesome-web
|
||||
npm install
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000)
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
## 📋 Next Steps to Complete
|
||||
|
||||
### 1. Landing Page 🔨
|
||||
- [ ] Hero section with gradient buttons
|
||||
- [ ] Feature showcase
|
||||
- [ ] Statistics display
|
||||
- [ ] Call-to-action sections
|
||||
|
||||
### 2. Command Search (kbd bindings) 🔨
|
||||
- [ ] shadcn Command component
|
||||
- [ ] Full-text search integration
|
||||
- [ ] Search facets (language, stars, topics)
|
||||
- [ ] Sorting options
|
||||
- [ ] Live preview
|
||||
- [ ] Pagination
|
||||
|
||||
### 3. Sidebar Navigation 🔨
|
||||
- [ ] Tree structure of awesome lists
|
||||
- [ ] Live search/filter
|
||||
- [ ] Collapsible categories
|
||||
- [ ] Active state indicators
|
||||
|
||||
### 4. README Viewer 🔨
|
||||
- [ ] State-of-the-art markdown rendering
|
||||
- [ ] Syntax highlighting
|
||||
- [ ] Sticky action header
|
||||
- [ ] Share functionality
|
||||
- [ ] Star button
|
||||
- [ ] Original link
|
||||
|
||||
### 5. UI Components 🔨
|
||||
- [ ] Install shadcn/ui components
|
||||
- [ ] Create custom components
|
||||
- [ ] Toast notifications
|
||||
- [ ] Loading states
|
||||
- [ ] Error boundaries
|
||||
|
||||
### 6. Logo & Assets 🔨
|
||||
- [ ] Adapt sindresorhus/awesome logo
|
||||
- [ ] Generate favicon
|
||||
- [ ] Create PWA icons (all sizes)
|
||||
- [ ] Header logo
|
||||
- [ ] OG image
|
||||
|
||||
### 7. Legal Pages 🔨
|
||||
- [ ] Legal page
|
||||
- [ ] Disclaimer
|
||||
- [ ] Imprint
|
||||
- [ ] Beautiful styling
|
||||
|
||||
### 8. 404 Page with Easter Egg 🔨
|
||||
- [ ] Custom 404 design
|
||||
- [ ] AWESOME easter egg
|
||||
- [ ] Interactive elements
|
||||
- [ ] Animated graphics
|
||||
|
||||
### 9. Database Integration 🔨
|
||||
- [ ] SQLite connection
|
||||
- [ ] Search implementation
|
||||
- [ ] Faceted search
|
||||
- [ ] Results pagination
|
||||
- [ ] Error handling
|
||||
|
||||
### 10. Worker Provider 🔨
|
||||
- [ ] React context for worker
|
||||
- [ ] Update notifications
|
||||
- [ ] Cache management
|
||||
- [ ] Toast integration
|
||||
|
||||
## 🎨 Theme Showcase
|
||||
|
||||
### Colors
|
||||
```css
|
||||
/* Primary Purple */
|
||||
--awesome-purple: #DA22FF;
|
||||
--awesome-purple-light: #E855FF;
|
||||
--awesome-purple-dark: #9733EE;
|
||||
|
||||
/* Secondary Pink */
|
||||
--awesome-pink: #FF69B4;
|
||||
--awesome-pink-light: #FFB6D9;
|
||||
--awesome-pink-dark: #FF1493;
|
||||
|
||||
/* Accent Gold */
|
||||
--awesome-gold: #FFD700;
|
||||
--awesome-gold-light: #FFE44D;
|
||||
--awesome-gold-dark: #FFC700;
|
||||
```
|
||||
|
||||
### Gradients
|
||||
```css
|
||||
/* Main Gradient */
|
||||
background: linear-gradient(135deg, #DA22FF 0%, #9733EE 50%, #FFD700 100%);
|
||||
|
||||
/* Pink Gradient */
|
||||
background: linear-gradient(135deg, #FF1493 0%, #DA22FF 50%, #9733EE 100%);
|
||||
|
||||
/* Gold Gradient */
|
||||
background: linear-gradient(135deg, #FFD700 0%, #FF69B4 50%, #FF1493 100%);
|
||||
```
|
||||
|
||||
### Components
|
||||
- **Buttons**: Gradient background with hover lift
|
||||
- **Cards**: Border glow on hover
|
||||
- **Text**: Gradient text utility classes
|
||||
- **Scrollbar**: Gradient thumb
|
||||
- **Focus**: Purple ring
|
||||
- **Selection**: Purple highlight
|
||||
|
||||
## 🔧 Technical Stack
|
||||
|
||||
### Frontend
|
||||
- **Next.js 18** - React framework
|
||||
- **TypeScript** - Type safety
|
||||
- **Tailwind CSS 4** - Utility-first CSS
|
||||
- **shadcn/ui** - Component library
|
||||
- **Radix UI** - Headless components
|
||||
- **cmdk** - Command palette
|
||||
- **Lucide** - Icons
|
||||
|
||||
### Backend
|
||||
- **SQLite3** - Database
|
||||
- **better-sqlite3** - Node.js driver
|
||||
- **FTS5** - Full-text search
|
||||
- **Node.js 22+** - Runtime
|
||||
|
||||
### Build & Deploy
|
||||
- **GitHub Actions** - CI/CD
|
||||
- **Web Workers** - Background sync
|
||||
- **PWA** - Progressive web app
|
||||
- **Service Worker** - Offline support
|
||||
|
||||
## 🎯 Key Features to Implement
|
||||
|
||||
### Search Excellence
|
||||
- ⚡ Lightning-fast FTS5
|
||||
- 🎨 Faceted filtering
|
||||
- 🔤 Syntax highlighting
|
||||
- 📄 Live preview
|
||||
- 🔀 Multiple sort options
|
||||
- 📊 Result statistics
|
||||
|
||||
### Smart Updates
|
||||
- 🔄 Auto-detect new DB versions
|
||||
- 📢 User notifications
|
||||
- ♻️ Cache invalidation
|
||||
- 🎯 Background sync
|
||||
- ⚡ Zero downtime updates
|
||||
|
||||
### Beautiful UX
|
||||
- 🎨 Gorgeous gradients
|
||||
- ✨ Smooth animations
|
||||
- 📱 Responsive design
|
||||
- ♿ Accessibility
|
||||
- 🌗 Dark mode
|
||||
- ⌨️ Keyboard shortcuts
|
||||
|
||||
## 📝 Development Notes
|
||||
|
||||
### shadcn/ui Installation
|
||||
```bash
|
||||
npx shadcn-ui@latest init
|
||||
npx shadcn-ui@latest add button dialog dropdown-menu toast command scroll-area
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
```env
|
||||
# .env.local
|
||||
WEBHOOK_SECRET=your-secret-here
|
||||
DB_URL=https://your-host.com/awesome.db
|
||||
GITHUB_TOKEN=your-github-token
|
||||
```
|
||||
|
||||
### GitHub Secrets
|
||||
- `WEBHOOK_SECRET` - For webhook verification
|
||||
- `WEBHOOK_URL` - Your Next.js webhook endpoint
|
||||
|
||||
## 🎉 What Makes This AWESOME
|
||||
|
||||
1. **Perfect Theme Match** - Exact CLI color scheme
|
||||
2. **Smart Updates** - Worker polls, notifies, updates seamlessly
|
||||
3. **GitHub Integration** - Automated builds every 6 hours
|
||||
4. **PWA Ready** - Install as app on any device
|
||||
5. **Next-Level Search** - Facets, filters, live preview
|
||||
6. **Beautiful Design** - State-of-the-art UI/UX
|
||||
7. **Intelligent** - Smart polling, cache management
|
||||
8. **Complete** - End-to-end solution
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
- [GitHub Workflow](.github/workflows/db.yml) - Database building
|
||||
- [Web Worker](public/worker.js) - Background sync
|
||||
- [API Routes](app/api/) - Webhook & version checking
|
||||
- [Tailwind Config](tailwind.config.ts) - Custom theme
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Vercel (Recommended)
|
||||
```bash
|
||||
vercel deploy
|
||||
```
|
||||
|
||||
### Environment Setup
|
||||
1. Add environment variables
|
||||
2. Configure GitHub webhook
|
||||
3. Set up database hosting
|
||||
4. Generate PWA icons
|
||||
|
||||
## 💡 Future Enhancements
|
||||
|
||||
- [ ] Advanced analytics
|
||||
- [ ] User accounts
|
||||
- [ ] Saved searches
|
||||
- [ ] Export functionality
|
||||
- [ ] Mobile app
|
||||
- [ ] Browser extension
|
||||
- [ ] API for developers
|
||||
**🚀 Powered By The Funk:** Next.js 15 • Tailwind CSS 4 • shadcn/ui • SQLite3 • Web Workers • PWA Magic
|
||||
|
||||
---
|
||||
|
||||
**Built with 💜💗💛 and maximum awesomeness!**
|
||||
</div>
|
||||
|
||||
*This is a GROUND-BREAKING, NEXT-LEVEL, AAA webapp that perfectly complements the awesome CLI!*
|
||||
## 🎸 What's This Funkadelic Trip All About?
|
||||
|
||||
Yo, check it! This ain't your grandma's GitHub list browser (no disrespect to grandma). This is a **FULL-BLOWN PSYCHEDELIC EXPERIENCE** for exploring awesome lists from GitHub. We're talkin' purple, pink, and GOLD, baby! We're talkin' FULL-TEXT SEARCH powered by SQLite FTS5 running at the SPEED OF FUNK! We're talkin' a personal list editor so smooth it'll make you wanna BOOGIE!
|
||||
|
||||
### 🌟 The Cosmic Feature List (Funkometer: 11/10)
|
||||
|
||||
#### 🎯 **The P-Funk Database Experience**
|
||||
- **FTS5 Full-Text Search** - Search faster than Bootsy's bass licks! ⚡
|
||||
- **Faceted Filtering** - Filter by language, stars, topics - smooth as silk! 🎨
|
||||
- **Hierarchical Navigation** - Browse awesome lists like you're navigating the Mothership 🚀
|
||||
- **Personal List Curation** - Save your faves with our WYSIWYG markdown editor (powered by TipTap) ✍️
|
||||
- **Real-time Updates** - Web workers polling for fresh data every 6 hours! 🔄
|
||||
- **PWA Ready** - Install it on ANY device and take the funk MOBILE! 📱
|
||||
|
||||
#### 🕶️ **The Aesthetic Funk**
|
||||
- **Purple/Pink/Gold Theme** - Colors so fly, they'll make you CRY! 💜💗💛
|
||||
- `#DA22FF` - That FUNKY Purple
|
||||
- `#FF69B4` - That SASSY Pink
|
||||
- `#FFD700` - That COSMIC Gold
|
||||
- **Gradient Everything** - Buttons, text, backgrounds - all sliding through the rainbow! 🌈
|
||||
- **Smooth Animations** - Transitions smoother than a James Brown slide! ✨
|
||||
- **Dark Mode** - For those late-night funk sessions! 🌙
|
||||
- **Custom Scrollbar** - Even the scrollbar got STYLE! 📜
|
||||
|
||||
#### 🤖 **The Technical Groove**
|
||||
|
||||
**Frontend Funk:**
|
||||
- Next.js 15 (App Router) + TypeScript - Modern as tomorrow!
|
||||
- Tailwind CSS 4 - Utility-first FUNK!
|
||||
- shadcn/ui Components - Beautiful AND accessible!
|
||||
- Radix UI - Headless but not heartless!
|
||||
- Motion/Framer Motion - Animations that MOVE you!
|
||||
- Lucide Icons - Icons with SOUL!
|
||||
|
||||
**Backend Bass Line:**
|
||||
- SQLite3 + better-sqlite3 - Database with GROOVE!
|
||||
- FTS5 Full-Text Search - Finding stuff at LIGHT SPEED!
|
||||
- Node.js 22+ - The latest and GREATEST!
|
||||
- Zustand State Management - State so fresh it squeaks!
|
||||
|
||||
**DevOps Drumbeat:**
|
||||
- GitHub Actions - Automated builds every 6 hours!
|
||||
- Web Workers - Background sync like a BACKBEAT!
|
||||
- PWA Support - Offline? NO PROBLEM!
|
||||
- Docker Ready - Container that CONTAINS the funk!
|
||||
|
||||
---
|
||||
|
||||
## 🎤 Getting Your Funk On (Installation)
|
||||
|
||||
Alright, space cadets! Let's get this MOTHERSHIP launched!
|
||||
|
||||
### 🛸 Prerequisites
|
||||
|
||||
You're gonna need:
|
||||
- **Node.js 22+** (The funk requires modern tech!)
|
||||
- **pnpm** (Package manager with STYLE!)
|
||||
- **Better-sqlite3** (For that database GROOVE!)
|
||||
|
||||
### 🚀 Launch Sequence
|
||||
|
||||
```bash
|
||||
# Clone this funkadelic masterpiece
|
||||
git clone https://github.com/yourusername/awesome-web.git
|
||||
cd awesome-web
|
||||
|
||||
# Install the cosmic dependencies
|
||||
pnpm install
|
||||
|
||||
# Fire up the development server (Mothership: ACTIVATED!)
|
||||
pnpm dev
|
||||
|
||||
# Open your browser to http://localhost:3000
|
||||
# Put on your sunglasses
|
||||
# Prepare for MAXIMUM FUNK! 🕶️
|
||||
```
|
||||
|
||||
### 🏗️ Building for Production
|
||||
|
||||
```bash
|
||||
# Build that funky fresh production bundle
|
||||
pnpm build
|
||||
|
||||
# Launch the production server
|
||||
pnpm start
|
||||
|
||||
# Deploy to Vercel/wherever and SPREAD THE FUNK! 🌍
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 The Funkadelic Architecture
|
||||
|
||||
```
|
||||
awesome-web/ 🏛️ THE MOTHERSHIP
|
||||
├── 🎸 app/
|
||||
│ ├── layout.tsx 💜 Root layout with COSMIC theme
|
||||
│ ├── globals.css 🎨 Where the MAGIC happens
|
||||
│ ├── page.tsx 🏠 Landing page of FUNK
|
||||
│ ├── search/ 🔍 Search with STYLE
|
||||
│ ├── browse/ 📚 Browse with GROOVE
|
||||
│ ├── my-list/ ✨ Personal list MAGIC
|
||||
│ └── api/ 🚀 API routes for DATA
|
||||
│ ├── search/ 💫 Full-text search endpoint
|
||||
│ ├── repositories/ 📦 Repository details
|
||||
│ ├── stats/ 📊 Database statistics
|
||||
│ └── db-version/ 🔄 Version checking
|
||||
│
|
||||
├── 🎵 components/
|
||||
│ ├── layout/
|
||||
│ │ ├── app-header.tsx 🎩 Header with ATTITUDE
|
||||
│ │ ├── app-sidebar.tsx 📂 Sidebar with SOUL
|
||||
│ │ └── command-menu.tsx ⌨️ Cmd+K for COSMIC search
|
||||
│ ├── personal-list/
|
||||
│ │ ├── personal-list-editor.tsx ✍️ WYSIWYG editor
|
||||
│ │ ├── push-to-list-button.tsx 💾 Save with STYLE
|
||||
│ │ └── sliding-panel.tsx 📱 Panel that SLIDES
|
||||
│ ├── readme/
|
||||
│ │ ├── readme-viewer.tsx 📖 Markdown with FLAVOR
|
||||
│ │ └── readme-header.tsx 🎯 Header with STARS
|
||||
│ └── ui/ 🎨 shadcn components with FUNK
|
||||
│
|
||||
├── 🎹 lib/
|
||||
│ ├── db.ts 💾 Database GROOVE
|
||||
│ ├── personal-list-store.ts 🗂️ Zustand state MAGIC
|
||||
│ ├── themes.ts 🎨 Theme POWER
|
||||
│ └── utils.ts 🔧 Utility FUNK
|
||||
│
|
||||
├── 🌟 public/
|
||||
│ ├── worker.js 🤖 Service worker MAGIC
|
||||
│ ├── manifest.json 📱 PWA manifest
|
||||
│ └── icons/ ✨ Funkadelic icons
|
||||
│
|
||||
├── 🎬 scripts/
|
||||
│ └── build-db.js 🏗️ Database builder (2 modes!)
|
||||
│
|
||||
└── 🚀 .github/workflows/
|
||||
└── db.yml ⚙️ Automated builds every 6 hours
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Key Features (The Funk Breakdown)
|
||||
|
||||
### 🔍 **Search Like You Mean It!**
|
||||
Our FTS5-powered search is FASTER than a cheetah on roller skates! Search by:
|
||||
- **Keywords** - Find ANYTHING in milliseconds!
|
||||
- **Language** - JavaScript? Python? We got 'em all!
|
||||
- **Stars** - Filter by popularity (but everything's a STAR here!)
|
||||
- **Category** - Organize that KNOWLEDGE!
|
||||
|
||||
### 📝 **Personal List Editor - Your Own Awesome Creation!**
|
||||
Built with TipTap, this editor got MORE extensions than Parliament-Funkadelic:
|
||||
- ✨ Rich text formatting (bold, italic, strikethrough)
|
||||
- 📋 Tables, task lists, code blocks
|
||||
- 🎨 Syntax highlighting for code
|
||||
- 📊 Character count
|
||||
- 💾 Auto-save to localStorage (your funk is SAFE!)
|
||||
- 📤 Export to markdown (SHARE the funk!)
|
||||
|
||||
### 🔄 **Smart Updates - Set It and Forget It!**
|
||||
Our Web Worker is like a ROBOT BASSIST - always keeping the rhythm:
|
||||
- Polls database version every 6 hours
|
||||
- Notifies you when new data drops
|
||||
- Cache invalidation (OLD data? GONE!)
|
||||
- Exponential backoff (SMART and efficient!)
|
||||
|
||||
### 🎨 **Theme System - Purple Rain Meets Cosmic Slop!**
|
||||
|
||||
```css
|
||||
/* The Funkadelic Palette */
|
||||
--awesome-purple: #DA22FF; /* 💜 Primary FUNK */
|
||||
--awesome-pink: #FF69B4; /* 💗 Secondary GROOVE */
|
||||
--awesome-gold: #FFD700; /* 💛 Accent SHINE */
|
||||
|
||||
/* Gradients that'll BLOW YOUR MIND */
|
||||
background: linear-gradient(135deg,
|
||||
#DA22FF 0%, /* Purple PASSION */
|
||||
#9733EE 50%, /* Violet VIBES */
|
||||
#FFD700 100% /* Golden GLORY */
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Automated Database Building (The GitHub Actions GROOVE)
|
||||
|
||||
We got TWO build modes, baby!
|
||||
|
||||
### ⚡ **Download Mode** (Default - Fast Like Lightning!)
|
||||
- Downloads pre-built database from `valknarness/awesome` repo
|
||||
- Takes ~5 minutes (TIME is money, honey!)
|
||||
- Runs every 6 hours automatically
|
||||
- Fallback to build mode if download fails (SMART!)
|
||||
|
||||
### 🔨 **Build Mode** (Slow But Thorough!)
|
||||
- Clones awesome CLI and runs FULL indexing
|
||||
- Takes 1-2 hours (PATIENCE is a virtue!)
|
||||
- Manual trigger only (for the CONTROL FREAKS!)
|
||||
- Generates fresh database with ALL the data
|
||||
|
||||
**Trigger it manually:**
|
||||
```bash
|
||||
# Via GitHub Actions UI
|
||||
# Select "Build mode" and hit "Run workflow"
|
||||
# Then sit back and let the FUNK flow! 🎸
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Deployment (Spread the Funk Worldwide!)
|
||||
|
||||
### Deploy to Vercel (Recommended!)
|
||||
|
||||
```bash
|
||||
# Install Vercel CLI
|
||||
pnpm i -g vercel
|
||||
|
||||
# Deploy!
|
||||
vercel deploy
|
||||
|
||||
# BOOM! Your funk is LIVE! 🌍
|
||||
```
|
||||
|
||||
### Environment Variables (Keep 'em Secret, Keep 'em Safe!)
|
||||
|
||||
```env
|
||||
# .env.local
|
||||
AWESOME_DB_PATH=/path/to/awesome.db
|
||||
WEBHOOK_SECRET=your-secret-here
|
||||
GITHUB_TOKEN=your-github-token
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What Makes This COSMICALLY AWESOME?
|
||||
|
||||
1. **🎨 Perfect Theme Match** - Colors straight from the awesome CLI! HARMONIOUS!
|
||||
2. **⚡ Lightning Search** - FTS5 search faster than a meteor! ZOOM!
|
||||
3. **💾 Smart Caching** - Web workers keeping things FRESH!
|
||||
4. **🤖 Automation** - GitHub Actions building databases while you SLEEP!
|
||||
5. **📱 PWA Ready** - Install it ANYWHERE! Desktop! Mobile! TOASTER!
|
||||
6. **♿ Accessible** - Keyboard shortcuts, ARIA labels, semantic HTML - EVERYONE gets the funk!
|
||||
7. **🌗 Dark Mode** - Light mode for DAY, dark mode for NIGHT!
|
||||
8. **✨ Smooth UX** - Animations smoother than BUTTER on a hot skillet!
|
||||
|
||||
---
|
||||
|
||||
## 🎵 Development Notes (For the Funkateers!)
|
||||
|
||||
### Adding shadcn/ui Components
|
||||
|
||||
```bash
|
||||
npx shadcn@latest add button dialog dropdown-menu toast command scroll-area
|
||||
# Add ALL the components! MORE is MORE!
|
||||
```
|
||||
|
||||
### Database Schema
|
||||
|
||||
The SQLite database vibes with these tables:
|
||||
- `awesome_lists` - List metadata (ALL the lists!)
|
||||
- `repositories` - Repository data (ALL the repos!)
|
||||
- `readmes` - README content (ALL the docs!)
|
||||
- `readmes_fts` - FTS5 virtual table (SEARCH POWER!)
|
||||
|
||||
### Path Aliases (Keep It Clean!)
|
||||
|
||||
- `@/` - Project root (HOME base!)
|
||||
- `@/components` - UI components (BUILDING blocks!)
|
||||
- `@/lib` - Utilities (TOOL box!)
|
||||
- `@/app` - Next.js pages (THE routes!)
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Future Enhancements (The Cosmic Roadmap!)
|
||||
|
||||
- [ ] 🎮 **Gamification** - Earn badges for exploring lists! COLLECT 'EM ALL!
|
||||
- [ ] 👥 **User Accounts** - Save preferences in the CLOUD!
|
||||
- [ ] 📊 **Analytics Dashboard** - See what's TRENDING!
|
||||
- [ ] 🔔 **Push Notifications** - Get alerted when lists UPDATE!
|
||||
- [ ] 🌐 **Internationalization** - FUNK in every language!
|
||||
- [ ] 📱 **Mobile App** - React Native version (THE REMIX!)
|
||||
- [ ] 🔌 **Browser Extension** - Search from ANYWHERE!
|
||||
- [ ] 🤖 **AI Recommendations** - "You might also like..." with INTELLIGENCE!
|
||||
|
||||
---
|
||||
|
||||
## 📜 License
|
||||
|
||||
MIT License - Free as a bird, baby! Use it, share it, FUNK IT UP!
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
## ⭐ CREDITS ⭐
|
||||
|
||||
### 🎸 The One and Only FUNK Himself 🎸
|
||||
|
||||
<img src="https://media.giphy.com/media/xUA7ba93zaOaGW8GWI/giphy.gif" width="200">
|
||||
|
||||
**Built with 💜💗💛 by funkateers worldwide**
|
||||
|
||||
*"Free your mind and your code will follow!"*
|
||||
|
||||
---
|
||||
|
||||
### Special Shoutout To:
|
||||
|
||||
🎤 **Bootsy Collins** - For inspiring the COSMIC vision
|
||||
🌟 **George Clinton** - For the MOTHERSHIP connection
|
||||
🎸 **Parliament-Funkadelic** - For the GROOVE foundation
|
||||
⭐ **sindresorhus/awesome** - For the original awesome lists
|
||||
💜 **The Open Source Community** - For keeping the FUNK alive
|
||||
|
||||
---
|
||||
|
||||
### 🕶️ One Nation Under A Groove 🕶️
|
||||
|
||||
*If you dig this funkadelic masterpiece, drop us a ⭐ STAR ⭐ on GitHub!*
|
||||
*Let's spread the FUNK across the galaxy, one awesome list at a time!*
|
||||
|
||||
|
||||
|
||||
**P-FUNK NEVER DIES!** 🎸✨🚀
|
||||
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user