Gitikus

Gitikus is a frontend dashboard for exploring GitHub repositories through a fast, dashboard-first UI.

It combines repository overview metrics, recent activity, searchable issue and pull request lists, detail views, and runtime repository configuration in a single React application.

Highlights

• Repository dashboard with:
  • open and closed issues
  • open and closed pull requests
  • labels
  • contributors
  • stars, forks, watchers, default branch, CI status, and last update
• Recent issue and pull request previews with direct GitHub links
• Dedicated issue and pull request detail pages
• Dedicated labels and contributors views
• Infinite loading for large lists
• URL-synced filters and pagination state for shareable views
• TanStack Query caching for server state
• Runtime repository and token configuration through the UI
• Unit tests for core components and utilities
• Cypress end-to-end coverage for key user flows
• Storybook examples for isolated UI review
• Separate CI workflows for unit and E2E verification

Tech Stack

• React 19
• TypeScript
• Vite
• Bootstrap 5
• TanStack React Query
• React Router
• Axios
• Vitest
• Cypress
• React Testing Library
• Storybook
• GitHub Actions

Requirements

• Node.js 22.22.0
• npm >= 10

Optional for containerized local development:

• Docker
• Docker Compose

Getting Started

1. Install dependencies:

npm install

2. Optionally create a local env file:

cp .env.example .env

3. Optionally update .env with your preferred repository and GitHub token:

REMOTE_GIT_API_TOKEN=
REMOTE_GIT_REPOSITORY=facebook/react

4. Start the development server:

npm run dev

The app runs at http://localhost:5173.

Configuration

All environment variables are optional.

REMOTE_GIT_API_TOKEN=
REMOTE_GIT_REPOSITORY=

• REMOTE_GIT_API_TOKEN
  • Optional.
  • Intended for local development.
  • Helps avoid GitHub API rate limits.
• REMOTE_GIT_REPOSITORY
  • Optional initial repository.
  • Accepts either owner/repository or a full repository URL `https://github.com/owner/repository.

If no repository is provided through the environment, Gitikus falls back to the app default and can still be changed later through the in-app setup flow or settings page.

Token Notes

REMOTE_GIT_API_TOKEN is read through import.meta.env, which means it becomes part of the frontend build.

For local development, that is fine when the value lives in your untracked .env.

For public deployments:

• do not inject a secret token unless you explicitly accept that it will be client-visible
• or move GitHub API access behind a backend/API layer if you need a private token

Available Scripts

Start the development server:

npm run dev

Create a production build:

npm run build

Preview the production build locally:

npm run preview

Run tests:

npm run test

Run tests in watch mode:

npm run test:watch

Open Cypress with the app server started automatically:

npm run e2e

Open Cypress only. This requires the E2E app server to already be running on http://127.0.0.1:4173:

npm run dev:e2e
npm run e2e:open

Run the Cypress suite headlessly. This also requires the E2E app server to already be running on http://127.0.0.1:4173:

npm run dev:e2e
npm run e2e:run

Start the app and run Cypress end to end:

npm run test:e2e

The E2E server uses Vite --mode e2e, which clears repository and token env defaults so the Cypress flows start from a deterministic app state.

Run linting and formatting checks:

npm run lint
npm run format:check

Run Storybook for isolated UI demos:

npm run storybook

Build the static Storybook site:

npm run build-storybook

Docker Development

Run the app with Docker Compose:

docker compose up

Behavior notes:

• the app is served at http://localhost:5173
• the repository is bind-mounted for live editing
• dependencies are installed inside the container-managed volume
• if dependencies change, restart the service
• if the volume gets out of sync, reset with docker compose down -v

License

MIT. See LICENSE.

Application Behavior

Routing and URL State

/issues and /pulls keep list state in the URL:

• q search text
• state open, closed, or all
• sort updated, created, or comments
• order ascending or descending
• label selected label
• pages number of loaded pages

This allows refresh and sharing without losing the current view.

Runtime Repository Setup

• on first launch, the app can be configured through the setup flow
• repository and token override can also be changed later from the settings view
• repository selection and runtime config are persisted in localStorage

Architecture

High-level data flow:

runtime config/local storage -> repository state -> React Query hooks -> GitHub API -> feature UI -> route pages

The main architectural pieces are:

• @app for router, providers, and the application shell
• @pages for thin route entrypoints only
• @features for user-facing workflows like dashboard, repository config, labels, and contributors
• @entities for GitHub domain API, models, query keys, query hooks, and domain UI
• @shared for generic reusable UI and utilities
• @state for runtime app state like the active repository and sync orchestration

Deployment

Gitikus is a static frontend and can be deployed to any host that can serve the dist/ directory.

The current project setup is compatible with Azure Static Web Apps, but any comparable static host will work.

Live deployment:

• https://happy-plant-0fde9201e.4.azurestaticapps.net/

If you deploy a public build, avoid injecting REMOTE_GIT_API_TOKEN unless you explicitly want it exposed to the browser.