diff --git a/README.md b/README.md index 462e31e..68f8980 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,142 @@ -# 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 onboarding users into the Kleo profile experience, connecting social accounts, collecting profile metadata, and showing profile progress, referrals, milestones, privacy controls, and data-quality views. -## About +The app is built with Vite, React 18, TypeScript, Tailwind CSS, React Router, Web3 integrations, social OAuth helpers, and visualization libraries such as D3, Chart.js, and Recharts. -Template for vite, React + tailwindcss + TypeScript projects with some tools preconfigured. +## Tech Stack -![Screenshot](assets/screenshot.png) +- React 18 with TypeScript +- Vite 4 for local development and production builds +- Tailwind CSS 3 for styling +- React Router 6 for route management +- Vitest for tests +- Web3, Irys, Helia, and wallet/social provider integrations -### Libraries +## Local Setup -- [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/) +1. Install dependencies: -### Tools + ```bash + npm install + ``` -- [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/) +2. Create a local environment file: -## Usage + ```bash + cp .env.example .env.local + ``` -Create a new project from this template by clicking the "Use this template" button: + If `.env.example` is not present in your checkout, create `.env.local` and add only the provider keys you need for the workflow you are testing. -![](assets/template-usage.png) +3. Start the development server: + + ```bash + npm run dev + ``` + +Vite prints the local URL after startup. The app redirects unauthenticated users into the signup flow. + +## Environment Variables + +The app reads provider configuration through `import.meta.env` in `src/common/config.ts`. + +Common variables include: + +```text +VITE_GOOGLE_OAUTH_CLIENT_ID= +VITE_GOOGLE_OAUTH_CLIENT_SECRET= +VITE_CALENDLY_INTEGRATION_API_KEY= +VITE_CALENDLY_CLIENT_SECRET= +VITE_CALENDLY_WEBHOOK_SIGNING_KEY= +VITE_INSTAGRAM_APPLICATION_ID= +VITE_INSTAGRAM_APP_SECRET= +VITE_LINKEDIN_APPLICATION_ID= +VITE_LINKEDIN_APPLICATION_SECRET= +VITE_TWITTER_APPLICATION_ID= +VITE_TWITTER_KEY= +VITE_TWITTER_SECRET= +VITE_TWITTER_CLIENT_ID= +VITE_GITHUB_CLIENTID= +VITE_GOOGLE_MAP_KEY= +VITE_RPC_URL= +VITE_REDIRECTED_URL= +VITE_KLEO_THIRDWEB_CLIENT_KEY= +VITE_KLEO_THIRDWEB_SECRET= +VITE_UPLOAD_API_DOMAIN= +``` + +Only expose values with the `VITE_` prefix when they are safe to ship to the browser. Do not commit `.env.local` or production secrets. + +## Project Structure + +```text +src/ + App.tsx # top-level route definitions and auth redirect logic + main.tsx # React app entrypoint + common/ + config.ts # environment-backed provider config + hooks/ # shared hooks such as useFetch + constants/ # shared app constants and seed data + pages/ + signup/ # onboarding and account-connection flow + profile/ # profile dashboard, referrals, milestones, privacy, data views + PrivacyPolicy/ # privacy policy page + assets/ # images, fonts, SVGs, dashboard assets + index.css # global Tailwind entry +__tests__/ # Vitest tests +assets/ # README/demo screenshots and design assets +``` + +## App Routes + +- `/` redirects users based on whether a token-backed profile exists. +- `/signup/:step` renders the signup/onboarding flow. +- `/profile/:address` renders the profile dashboard. +- `/my-data/:address` renders data details for logged-in users. +- `/privacy` renders the privacy policy. + +## Development Commands + +```bash +npm run dev # start Vite dev server +npm run build # create production build +npm run serve # preview production build on port 3000 +npm run lint # run ESLint +npm run test # run Vitest +``` + +## Testing + +Run the test suite with: ```bash -yarn -yarn dev -yarn test +npm run test -- --run ``` + +Use `-- --run` in CI or one-off verification so Vitest exits instead of entering watch mode. + +## Build And Deployment + +Create a production build: + +```bash +npm run build +``` + +The compiled app is written to `dist/` and can be deployed to any static hosting platform that supports single-page apps. Configure your host to route unknown paths back to `index.html` so React Router can handle client-side routes. + +## Contribution Guidelines + +1. Keep feature code close to its route or profile/signup component group. +2. Add shared utilities under `src/common/` only when they are reused by more than one feature area. +3. Keep provider keys and OAuth credentials in environment variables. +4. Run `npm run test -- --run` and `npm run build` before opening a PR. +5. For UI changes, include a short before/after note or screenshot in the PR description. + +## Troubleshooting + +- If provider login fails, confirm the matching `VITE_*` value is present and allowed for the current redirect URL. +- If routes 404 after deployment, configure static hosting fallback to `index.html`. +- If tests hang locally, run `npm run test -- --run` instead of plain `npm run test`. +- If wallet or upload flows fail, verify `VITE_RPC_URL`, `VITE_KLEO_THIRDWEB_CLIENT_KEY`, and `VITE_UPLOAD_API_DOMAIN`.