https://github.com/attackonmorty/github-ranking
Search GitHub's top repositories, users and organizations.
https://github.com/attackonmorty/github-ranking
github-api nextjs
Last synced: 3 months ago
JSON representation
Search GitHub's top repositories, users and organizations.
- Host: GitHub
- URL: https://github.com/attackonmorty/github-ranking
- Owner: AttackOnMorty
- Created: 2023-02-09T13:20:19.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-14T00:34:04.000Z (11 months ago)
- Last Synced: 2025-02-14T01:30:53.657Z (11 months ago)
- Topics: github-api, nextjs
- Language: TypeScript
- Homepage: https://github-ranking.dev
- Size: 211 KB
- Stars: 13
- Watchers: 1
- Forks: 4
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# GitHub Ranking
## Project Overview
GitHub Ranking is a Next.js application that searches and displays GitHub's top repositories, users, and organizations. It uses the GitHub API with Octokit, Ant Design for UI components, SWR for data fetching, and Tailwind CSS for styling.
## Development Commands
**Setup:**
```bash
# Install dependencies
pnpm install
# Copy environment file and add GitHub token
cp .example.env .env
# Edit .env and add your NEXT_PUBLIC_GITHUB_ACCESS_TOKEN
```
**Development:**
```bash
# Start development server with Turbopack
pnpm dev
# Build for production
pnpm build
# Start production server
pnpm start
# Lint code
pnpm lint
```
## Architecture Overview
### Core Structure
- **Next.js 15** with App Router and React 19
- **TypeScript** with strict configuration
- **Ant Design** for UI components with custom theming
- **SWR** for data fetching with aggressive caching (24 hours)
- **Tailwind CSS v4** for styling
- **Octokit** for GitHub API integration
### Key Architectural Patterns
**Data Flow:**
1. API layer (`src/api/`) handles all GitHub API calls via Octokit
2. Custom hooks (`src/hooks/use-github-api.ts`) wrap API calls with SWR caching
3. Components consume data through these hooks
4. Global language context provides programming languages to all components
**Caching Strategy:**
- SWR with 24-hour cache duration for most data
- No revalidation on focus, revalidates on reconnect
- Aggressive deduplication to minimize API calls
**Page Structure:**
- Root redirects to `/repositories`
- Three main views: repositories, users, organizations
- Each has filtering by language, topics/location, and pagination
- Shared table-based UI with responsive columns
### API Integration Details
**GitHub API Limits:**
- Minimum count filters (100) to ensure stable data
- Maximum 1000 results per search (GitHub API limit)
- Page size of 20 items
- Uses personal access tokens for authentication
**Search Patterns:**
- Repositories: `stars:>100` or `forks:>100` + optional language/topic filters
- Users/Organizations: `followers:>100` + optional language/location filters
- Topics: Featured topics or search-based topic discovery
### Component Architecture
**Layout Hierarchy:**
```
RootLayout (AntdRegistry + ConfigProvider + LanguageProvider)
├── Header (navigation)
├── Main Content (max-width container)
└── Footer
```
**Page Components:**
- Each main page (`repositories/`, `users/`, `organizations/`) follows the same pattern:
- Filter controls in table title
- Ant Design Table with pagination
- Loading skeletons during data fetch
- Error boundary with ErrorState component
**Shared Components:**
- `UserAvatar`: GitHub user avatar with fallbacks
- `ErrorState`: Generic error display
- Loading skeletons for each data type
### Environment Configuration
**Required Environment Variables:**
- `NEXT_PUBLIC_GITHUB_ACCESS_TOKEN`: GitHub personal access token
**Build Configuration:**
- Next.js with Turbopack for faster builds
- Image optimization for GitHub avatars
- TypeScript with path aliases (`@/*` → `./src/*`)
### Styling Approach
**Tailwind CSS v4:**
- Uses new `@import 'tailwindcss'` syntax
- Custom CSS properties for theming
- Responsive design with mobile-first approach
- Dark mode support through CSS media queries
**Ant Design Integration:**
- Custom font family inheritance
- Fira Code font for consistent monospace styling
- Custom theme tokens integrated with Tailwind
### Data Types and Constants
**Core Types** (`src/api/types.ts`):
- `Repo`: Repository with owner, stats, and metadata
- `User`: User/organization with profile data
- `Topic`: GitHub topics with display names
**Constants** (`src/constants/`):
- `PAGE_SIZE`: 20 items per page
- `MAX_DATA_COUNT`: 1000 (GitHub API limit)
- `USER_TYPE`: User vs organization classification
### Utilities
**Language Handling:**
- Fetches language list from GitHub Linguist YAML
- Groups popular languages separately in dropdowns
- Context provider makes languages globally available
**Data Formatting:**
- Number formatting (1000+ → "1k")
- Emoji conversion for GitHub-style text
- URL and avatar fallback handling
## Development Notes
When adding new features:
- Follow the established SWR + API hook pattern
- Use existing TypeScript types or extend them
- Maintain responsive design with Ant Design breakpoints
- Consider GitHub API rate limits and caching implications
- Test with different filter combinations
The codebase prioritizes performance through aggressive caching and minimal re-renders, while maintaining a consistent user experience across all ranking views.