GitHub Explorer

A React + TypeScript application to search a GitHub user and explore public repositories.

Core capabilities:

• Search repositories by GitHub username

• Browse repository list with pagination

• Sort repositories by stars

• Open repository details page

Run Locally

1. Install dependencies:

   npm install

2. Create a .env file from example.env and set the API URL:

   cp example.env .env

3. In .env, set:

   VITE_API_URL=https://api.github.com

   This project uses unauthenticated GitHub API requests by default. So exposing the url here

4. Start development server:

   npm run dev

5. Open http://localhost:5173.

Available Scripts

npm run dev            # start local server
npm run build          # type-check + production build
npm run preview        # preview production build
npm run lint           # run ESLint
npm run test           # run Vitest
npm run test:ui        # run Vitest UI
npm run test:coverage  # run tests with coverage

Project Architecture

• UI framework: React + TypeScript

• Routing: React Router

• State management:

• Client/UI state in Zustand (useRepositoriesStore)

• Server/cache state in TanStack Query (useRepositories)

• HTTP client: Axios (src/apis/http-api.ts)

• Styling: Tailwind CSS

• Testing: Vitest + React Testing Library

Key Flows

• / → Home page with search input

• /repositories → Search + repository list + pagination/filter controls

• /repositories/:id → Repository details from selected store state

• * → dedicated 404 page

Pagination Strategy (Why Link Headers)

GitHub’s GET /users/{username}/repos response body does not include pagination metadata such as totalPages, hasNext, or hasPrevious. Pagination information is provided in the HTTP Link response header (for example rel="next" and rel="prev").

Because of that, this project parses the Link header to compute UI pagination state:

• hasNext is derived from whether rel="next" exists

• hasPrevious is derived from rel="prev" or current page number

This logic lives in src/utils/pagination.ts and is used by repository mapping in src/utils/repository-helper.ts.

Sorting Strategy and API Limitations

The endpoint does not provide the exact full-set star sorting behavior needed by the UI for both asc and desc across all repositories.

Behavior by mode:

• starsSort=default:

• Uses server-side pagination (page, per_page)

• Uses Link headers to determine next/previous page availability

• starsSort=asc|desc:

• Fetches all pages first (per_page=100, loop until no rel="next")

• Sorts repositories in memory

• Applies pagination locally after sorting

Implications:

• Sorted mode has a higher initial load time for users with many repositories.

• Sorted mode makes more API calls and may hit unauthenticated rate limits sooner.

• Sorted mode uses a stable query key (["repos", githubUser]), so local page changes do not trigger additional network requests after data is cached.

Additional Notes

• If no repositories are found, the UI shows a not-found state.

• Repository details are sourced from selected Zustand state (no separate single-repository fetch in current implementation).

• If selected repository state is missing on detail route, the UI shows a fallback message.

• Generic API error UI currently displays:

• Something went wrong

• Please contact your system administrator