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:
|
[](https://github.com)
|
||||||
- 💜 **Awesome Purple**: `#DA22FF`
|
[](https://github.com)
|
||||||
- 💗 **Awesome Pink**: `#FF69B4`
|
[](https://github.com)
|
||||||
- 💛 **Awesome Gold**: `#FFD700`
|
[](https://github.com)
|
||||||
|
|
||||||
## 🌟 Features Implemented
|
**🚀 Powered By The Funk:** Next.js 15 • Tailwind CSS 4 • shadcn/ui • SQLite3 • Web Workers • PWA Magic
|
||||||
|
|
||||||
### ✅ 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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**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