Skip to content

Bounty: Add Documentation for React.js Frontend #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
maxrross wants to merge 1 commit into from
Closed

Bounty: Add Documentation for React.js Frontend #81

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
238 changes: 211 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,225 @@
# vite React TypeScript tailwindcss starter
# Kleo Connect Frontend

Template for vite, React + tailwindcss + TypeScript projects with some tools preconfigured.
Kleo Connect is the React frontend for the Kleo browser extension experience. It signs users in through the Kleo Chrome extension, stores the authenticated wallet address and token locally, and renders profile, activity, data quality, milestone, referral, leaderboard, privacy, and "My Data" views for the connected account.

## About
The app is built with Vite, React 18, TypeScript, Tailwind CSS, React Router, Chart.js, Recharts, React Leaflet, wallet utilities, and the Kleo API.

Template for vite, React + tailwindcss + TypeScript projects with some tools preconfigured.
![Kleo dashboard screenshot](assets/screenshot.png)

![Screenshot](assets/screenshot.png)
## Table of Contents

### Libraries
- [Requirements](#requirements)
- [Quick Start](#quick-start)
- [Environment Variables](#environment-variables)
- [Available Scripts](#available-scripts)
- [Application Routes](#application-routes)
- [Project Structure](#project-structure)
- [Key Workflows](#key-workflows)
- [Testing and Quality Checks](#testing-and-quality-checks)
- [Deployment](#deployment)
- [Contributing](#contributing)
- [Troubleshooting](#troubleshooting)

- [React 18](https://reactjs.org/)
- [React Router 6](https://reactrouter.com)
- [tailwindcss 3](https://tailwindcss.com/)
- [tailwindcss forms plugin](https://tailwindcss-forms.vercel.app/)
- [TypeScript 4.9.5](https://www.typescriptlang.org/)
- [vite 4](https://vitejs.dev/)
- [vitetest](https://vitest.dev/)
## Requirements

### Tools
- Node.js 18 or newer
- npm 9 or newer
- The Kleo Connect Chrome extension for authenticated profile flows
- Access to any API keys required by the integrations you are testing

- [commitlint 17](https://commitlint.js.org)
- [Conventional Commits 1](https://www.conventionalcommits.org)
- [editorconfig](https://editorconfig.org/)
- [eslint 8](https://eslint.org/)
- [husky 8](https://typicode.github.io/husky/#/)
- [Prettier 2](https://prettier.io/)
- [VS Code settings](https://code.visualstudio.com/)
The repository includes `package-lock.json`, so npm is the recommended package manager for reproducible installs.

## Usage
## Quick Start

Create a new project from this template by clicking the "Use this template" button:
```bash
git clone https://github.com/Kleo-Network/kleo-connect.git
cd kleo-connect
npm install
cp .env.example .env
npm run dev
```

Vite starts the app with `--host`, so it is available on the printed local and network URLs. The default local URL is usually `http://localhost:5173`.

For the full sign-in flow, install the Kleo Connect extension from the Chrome Web Store and make sure `window.kleoConnect` is available in the browser tab running the app.

## Environment Variables

All client-side environment variables must use the `VITE_` prefix so Vite exposes them to the frontend bundle.

Copy `.env.example` to `.env` and fill in only the values needed for the feature you are running:

| Variable | Used for |
| --- | --- |
| `VITE_GOOGLE_OAUTH_CLIENT_ID` | Google OAuth integration |
| `VITE_GOOGLE_OAUTH_CLIENT_SECRET` | Google OAuth integration |
| `VITE_CALENDLY_INTEGRATION_API_KEY` | Calendly integration |
| `VITE_CALENDLY_CLIENT_SECRET` | Calendly integration |
| `VITE_CALENDLY_WEBHOOK_SIGNING_KEY` | Calendly webhook verification |
| `VITE_INSTAGRAM_APPLICATION_ID` | Instagram integration |
| `VITE_INSTAGRAM_APP_SECRET` | Instagram integration |
| `VITE_LINKEDIN_APPLICATION_ID` | LinkedIn integration |
| `VITE_LINKEDIN_APPLICATION_SECRET` | LinkedIn integration |
| `VITE_TWITTER_APPLICATION_ID` | Twitter/X integration |
| `VITE_TWITTER_KEY` | Twitter/X integration |
| `VITE_TWITTER_SECRET` | Twitter/X integration |
| `VITE_TWITTER_CLIENT_ID` | Twitter/X OAuth client |
| `VITE_GITHUB_CLIENTID` | GitHub integration |
| `VITE_GOOGLE_MAP_KEY` | Google Maps features |
| `VITE_RPC_URL` | Irys or blockchain RPC calls |
| `VITE_REDIRECTED_URL` | OAuth redirection target |
| `VITE_UPLOAD_API_DOMAIN` | Decentralized upload host |
| `VITE_KLEO_THIRDWEB_CLIENT_KEY` | Thirdweb client configuration |
| `VITE_KLEO_THIRDWEB_SECRET` | Thirdweb client configuration |

The shared config object lives in `src/common/config.ts`. API calls currently use the production base URL in `src/common/hooks/useFetch.ts`:

```ts
export const baseUrl = 'https://fastapi.kleo.network/api/v1'
```

For local backend testing, change that value to your local API URL before running the frontend.

## Available Scripts

```bash
npm run dev
```

Starts the Vite development server.

```bash
npm run build
```

Runs the TypeScript compiler and creates the production build in `dist/`.

```bash
npm run serve
```

Serves the production build locally with Vite Preview on port 3000.

```bash
npm run lint
```

Runs ESLint across JavaScript and TypeScript source files.

```bash
npm test
```

Runs the Vitest test suite.

![](assets/template-usage.png)
## Application Routes

Routes are defined in `src/App.tsx`.

| Route | Purpose |
| --- | --- |
| `/` | Redirects authenticated users to their profile and unauthenticated users to signup |
| `/signup/:step` | Extension install check and Kleo sign-in flow |
| `/profile/:address` | Authenticated profile dashboard |
| `/my-data/:address` | Authenticated user data page |
| `/privacy` | Privacy policy |
| `*` | Fallback redirect based on authentication state |

Authentication state is read from `localStorage` using the `token` and `address` values set during extension sign-in.

## Project Structure

```text
.
├── assets/ # README and template screenshots
├── src/
│ ├── assets/ # App images, SVGs, fonts, and animations
│ ├── common/
│ │ ├── charts/ # Shared chart components
│ │ ├── components/ # Shared UI components such as Navbar and alerts
│ │ ├── constants/ # Static signup, browsing, event, and website data
│ │ ├── hooks/ # Fetch, wallet, debounce, and body-scroll hooks
│ │ ├── config.ts # Environment-backed integration config
│ │ ├── interface.ts # Shared TypeScript interfaces
│ │ └── utils.ts # Formatting and URL helper functions
│ ├── pages/
│ │ ├── PrivacyPolicy/ # Privacy policy page
│ │ ├── profile/ # Dashboard and profile subcomponents
│ │ └── signup/ # Onboarding and extension sign-in flow
│ ├── App.tsx # Top-level routes and auth redirect logic
│ └── main.tsx # React root and BrowserRouter setup
├── __tests__/ # Vitest tests
├── index.html # Vite HTML entrypoint
├── tailwind.config.js # Tailwind theme and utilities
├── vite.config.ts # Vite plugins, aliases, and polyfills
└── package.json # Scripts and dependencies
```

## Key Workflows

### Extension Sign-In

The signup flow in `src/pages/signup/Onboarding/Authentication/index.tsx` checks whether `window.kleoConnect` exists. When the extension is installed, the Sign In button calls `window.signIn()`, stores the returned `address` and `token` in `localStorage`, and redirects to `/profile/:address`.

### Profile Validation

The profile page in `src/pages/profile/index.tsx` waits for `window.kleoConnect`, calls the extension sign-in method, and verifies that the address from the URL, local storage, and extension all match. If they do not match, the user is redirected back to signup.

### API Requests

Shared API behavior is implemented in `src/common/hooks/useFetch.ts`. The hook prepends the Kleo API base URL, adds the local auth token as the `Authorization` header, tracks loading/error/success state, and exposes a manual `fetchData` function for follow-up requests.

### Dashboard Features

The profile dashboard composes cards and charts from `src/pages/profile/components/`, including points and data quantity, data quality, milestones, snapshots, referrals, leaderboard state, privacy controls, and activity graph sharing.

## Testing and Quality Checks

Run the same checks before opening a pull request:

```bash
yarn
yarn dev
yarn test
npm run lint
npm test
npm run build
```

`npm run build` is the most complete local verification because it runs TypeScript compilation before producing the Vite production bundle.

## Deployment

1. Configure the production environment variables in the hosting provider.
2. Run `npm install`.
3. Run `npm run build`.
4. Deploy the generated `dist/` directory.
5. Configure the host to serve `index.html` for unknown routes, because this is a single-page React app using browser routing.

The current Vite base path is `/` in `vite.config.ts`. Update `base` if the app is deployed under a subpath.

## Contributing

1. Create a feature branch from `production`.
2. Keep changes focused on one issue or feature.
3. Follow the existing React, TypeScript, Tailwind, and hook patterns.
4. Prefer shared helpers in `src/common/` over duplicating logic in page components.
5. Run lint, tests, and build locally before submitting.
6. Open a pull request with a clear summary, linked issue, and verification notes.

The project uses Conventional Commits through commitlint, so commit messages should use prefixes such as `feat:`, `fix:`, `docs:`, `refactor:`, or `test:`.

## Troubleshooting

### The Sign In button stays disabled

The app only enables sign-in after the Kleo extension exposes `window.kleoConnect`. Install the extension, refresh the page, and use the "I have already installed" button if the page loaded before the extension was available.

### Profile redirects back to signup

The profile route validates the URL address, local storage address, and extension address. Clear local storage, sign in again, and make sure the profile URL matches the active extension account.

### API calls fail locally

Confirm the backend base URL in `src/common/hooks/useFetch.ts`, the required `VITE_` variables, and the token stored in local storage. The default base URL points to the production Kleo API.

### Build errors mention missing environment values

Make sure `.env` exists and contains every variable needed by the feature being built. Vite only exposes variables that start with `VITE_`.