From 4771739a643d3c8a1cf55068dfc18c39bd40a18d Mon Sep 17 00:00:00 2001 From: Thanh Nguyen Date: Fri, 15 May 2026 18:47:41 +0700 Subject: [PATCH] docs: expand project README --- README.md | 164 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 137 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 462e31e..6e0c092 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,151 @@ -# vite React TypeScript tailwindcss starter +# Kleo Connect -Template for vite, React + tailwindcss + TypeScript projects with some tools preconfigured. +Kleo Connect is a React frontend for creating and managing a user-owned Kleo profile. The app guides a user through signup, wallet/social account connection, profile setup, data-card creation, rewards, privacy controls, and dashboard views. -## About +The project is built with Vite, React 18, TypeScript, Tailwind CSS, React Router, Web3 wallet libraries, map/chart UI packages, and Vitest. -Template for vite, React + tailwindcss + TypeScript projects with some tools preconfigured. +## Tech stack -![Screenshot](assets/screenshot.png) +- React 18 + React DOM +- TypeScript 4.9 +- Vite 4 +- Tailwind CSS 3 +- React Router 6 +- Vitest for tests +- ESLint + Prettier + Husky + commitlint +- Web3 integrations: Web3.js, MetaMask provider detection, Irys SDK, Helia/IPFS-related packages +- UI/data libraries: D3, Chart.js, Recharts, Leaflet, React Google Maps, dnd-kit -### Libraries +## Repository structure -- [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/) +```text +. +├── assets/ # Static documentation/demo assets +├── src/ +│ ├── App.tsx # Route definitions and top-level auth/profile flow +│ ├── main.tsx # React app entrypoint +│ ├── App.css # Global app styles +│ ├── assets/ # Images, fonts, SVGs, animation files used by UI +│ ├── common/ # Shared config, constants, hooks, interfaces, utilities +│ └── pages/ # Route-level pages: signup, profile, privacy policy +├── __tests__/ # Vitest tests +├── index.html # Vite HTML shell +├── package.json # Scripts and dependencies +├── tailwind.config.js # Tailwind theme and plugin config +├── vite.config.ts # Vite build/test configuration and polyfills +└── tsconfig.json # TypeScript configuration +``` + +## Prerequisites + +- Node.js 18.x or newer +- npm 9.x or newer +- A browser wallet such as MetaMask for wallet-dependent flows + +## Environment variables + +Copy the example file before running locally: + +```bash +cp .env.example .env +``` + +Fill in the values required for the backend/API and third-party integrations used by your environment. Keep secrets out of git. + +## Local setup + +Install dependencies: + +```bash +npm install +``` + +Start the Vite dev server: + +```bash +npm run dev +``` + +Vite prints the local URL in the terminal. The default is usually `http://localhost:5173`. + +## Available scripts + +```bash +npm run dev # Start local development server +npm run build # Create a production build in dist/ +npm run serve # Preview the production build on port 3000 +npm run lint # Run ESLint over TS/TSX/JS files +npm run test # Run Vitest +``` + +## Build and preview -### Tools +```bash +npm run build +npm run serve +``` + +The preview server runs the compiled Vite output and is useful for checking routing, static assets, and production-only build issues before deployment. + +## Testing + +Run the test suite with: + +```bash +npm run test +``` + +Tests live in `__tests__/` and use Vitest. Add tests for shared utilities, hooks, and route-level behavior when changing core flows. + +## Linting and formatting + +Run linting before opening a pull request: + +```bash +npm run lint +``` + +Formatting is handled by Prettier. Commit messages are expected to follow Conventional Commits because the repo includes commitlint and Husky hooks. + +Examples: + +```text +feat: add profile reward card +fix: handle missing wallet address +docs: document local setup +``` -- [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/) +## Key application flows -## Usage +- `/` checks the local auth/profile state and redirects to signup or profile. +- `/signup/:step` renders the multi-step signup flow. +- `/profile/:address` renders a public/user profile. +- `/my-data/:address` is available when the user is logged in. +- `/privacy` renders the privacy policy. -Create a new project from this template by clicking the "Use this template" button: +`src/App.tsx` owns the top-level route wiring and initial user state. Shared request/config logic lives under `src/common/`. -![](assets/template-usage.png) +## Contribution guidelines + +1. Create a focused branch for each change. +2. Run `npm install` after pulling dependency changes. +3. Keep route-level code in `src/pages/` and reusable logic in `src/common/`. +4. Prefer typed interfaces for data passed between components and API hooks. +5. Do not commit `.env`, API keys, wallet private keys, or generated build output. +6. Run `npm run lint` and `npm run test` before opening a pull request. +7. Use Conventional Commits for commit messages. + +## Deployment notes + +This is a Vite single-page app. A typical deployment runs: ```bash -yarn -yarn dev -yarn test +npm install +npm run build ``` + +Then serve the generated `dist/` directory with static hosting. Configure the host to route unknown paths back to `index.html` so React Router pages work on refresh. + +## License + +This project is licensed under the terms in [LICENSE](LICENSE).