FlowState is an elite, privacy-focused browser extension for digital wellness. It tracks time spent on websites and provides gentle, customizable nudges to encourage mindful browsing and maintain focus. Built with Manifest V3 and Zero-Telemetry principles.
mermaid graph TD A[Browser Extension Core (Manifest V3)] --> B{Content Scripts} A --> C{Background Service Worker} B --> D[UI Components (React/Preact)] C --> E[Time Tracking Logic] C --> F[Nudge Engine] C --> G[Storage (Local/Sync)] E --> G F --> G A --> H[Popup UI] H --> C
- Privacy-First Design: Zero telemetry. All data is stored locally or synced via browser sync storage. No external data exfiltration.
- Manifest V3 Compliant: Built for the future of browser extensions.
- Intelligent Time Tracking: Accurately monitors time spent on individual websites.
- Customizable Nudges: Set personalized prompts and timers to encourage breaks or refocusing.
- Focus Modes: Configure specific times or website lists for enhanced concentration.
- Elegant UI: Clean and intuitive interface accessible via a browser popup.
- Performance Optimized: Built with Vite for fast development builds and optimized production output.
- Node.js (v18+ recommended)
- npm or Yarn
-
Clone the repository: bash git clone https://github.com/chirag127/FlowState-Digital-Wellness-Time-Tracker-Browser-Extension.git cd FlowState-Digital-Wellness-Time-Tracker-Browser-Extension
-
Install dependencies: bash npm install
yarn install
-
Run in development mode: bash npm run dev
yarn dev
This will build the extension and watch for changes. You can then load the
distfolder as an unpacked extension in your browser (e.g., Chrome, Edge).
bash npm run build
yarn build
This command generates the optimized production build in the dist folder.
This project adheres to the following core principles:
- SOLID: Enhancing maintainability and scalability.
- DRY (Don't Repeat Yourself): Minimizing code duplication.
- YAGNI (You Ain't Gonna Need It): Focusing on essential features.
- Performance: Prioritizing efficient code and resource usage.
- Security: Implementing best practices for browser extensions, especially regarding Manifest V3 and data privacy.
- Repository Name:
FlowState-Digital-Wellness-Time-Tracker-Browser-Extension - Primary Function: Digital Wellness & Time Tracking Browser Extension
- Platform: Browser Extension (Manifest V3)
- Technology Stack: TypeScript, Vite, TailwindCSS, Biome, Playwright, React/Preact.
- Adhere to Manifest V3 specifications: Employ service workers, secure content scripts, and appropriate storage mechanisms.
- Feature-Sliced Design (FSD) principles: Organize code into features, layers, and segments for maintainability and scalability.
- Component-Based Architecture: Utilize React/Preact for declarative UI development.
- State Management: Employ Signals or similar efficient state management patterns.
- Tool: Biome (v1.7.0+)
- Configuration:
.biome.jsonfile in the root directory. - Verification Command:
npm run lintoryarn lint - Formatting Command:
npm run formatoryarn format
- Unit Testing: Vitest (v2.x+)
- E2E Testing: Playwright (v1.x+)
- Test Runner:
npm testoryarn test
- Development Server:
npm run dev/yarn dev - Production Build:
npm run build/yarn build - Linting:
npm run lint/yarn lint - Formatting:
npm run format/yarn format - Unit Tests:
npm test:unit/yarn test:unit - E2E Tests:
npm test:e2e/yarn test:e2e
- Manifest V3 Compliance: Strict adherence to security best practices, including leveraging the service worker model and content security policies.
- Data Privacy: No unnecessary data collection. User data remains local or uses browser sync storage only.
- Dependency Auditing: Regularly audit dependencies for vulnerabilities.
This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).
See the LICENSE file for more details.