Development Guide

​

Getting Started

​

Prerequisites

• Node.js (version 18.x or later recommended)
• pnpm (or npm/yarn, though pnpm is used for this project)
• A Chromium-based browser (e.g., Google Chrome, Brave, Microsoft Edge)

​

Setup

1. Clone the Repository:
   Copy

   git clone https://github.com/claritybytes/chronotab-extension.git
   cd chronotab-extension
   

2. Install Dependencies: If you have pnpm installed:
   Copy

   pnpm install
   

   Alternatively, using npm:
   Copy

   npm install
   

3. Start the Development Server: This command will build the extension and watch for changes.
   Copy

   pnpm run dev
   # or
   npm run dev
   

   This will create a dist folder with the unpacked extension files.

​

Loading the Unpacked Extension in Chrome

1. Open Chrome and navigate to chrome://extensions.
2. Enable “Developer mode” using the toggle switch in the top-right corner.
3. Click the “Load unpacked” button.
4. Select the dist folder from your project directory.

​

Project Structure

• docs/: Mintlify documentation files.
  • reference/: Auto-generated JSDoc for background.js and scheduler.js.
  • Other .mdx files for general documentation.
• public/: Static assets like icons. manifest.json refers to these.
• scripts/: Build-related scripts, like postprocess-mdx.cjs for fixing JSDoc output.
• src/: Contains the core source code for the extension.
  • assets/: Static assets used within the React application (e.g., react.svg).
  • components/: Reusable React components.
    • ui/: UI primitive components from ShadCN/ui (e.g., button.tsx, tooltip.tsx).
    • Footer.jsx: Application footer.
    • SettingsMenu.jsx: Component for application settings.
  • lib/: Utility functions and libraries, often TypeScript (e.g., utils.ts).
  • pages/: React components representing different views/pages of the extension.
    • Dashboard.jsx: Main view for displaying and managing schedules.
    • ScheduleEditor.jsx: Form for creating and editing schedules.
    • MissedAlarmsPage.jsx: View for managing missed schedules.
  • utils/: Core utility scripts.
    • scheduler.js: Handles alarm creation, schedule logic, import/export.
  • App.jsx: Main React application component, handles routing.
  • App.css: Global styles for App.jsx.
  • background.js: The extension’s service worker. Manages alarms, notifications, context menus, and message passing.
  • index.css: Global styles, including Tailwind CSS setup.
  • main.jsx: Entry point for the React application, renders App into the DOM.
  • manifest.json: The Chrome extension manifest file. Defines permissions, background scripts, UI pages, icons, etc.
• package.json: Project metadata, dependencies, and scripts.
• vite.config.js: Configuration for the Vite build tool.
• tailwind.config.js: Configuration for Tailwind CSS.
• tsconfig.json (and variants): TypeScript configuration files.
• eslint.config.js: ESLint configuration for code linting.
• Other configuration files (e.g., postcss.config.js, jsdoc.conf.json).

​

Development Workflow

1. Make changes to the React components in src/, the background script (src/background.js), or other relevant files.
2. Vite will automatically rebuild the extension into the dist folder.
3. Reload the extension in chrome://extensions if necessary. For UI changes in the popup, often just re-opening the popup is enough.
4. Test your changes.

​

Key Technologies

• React: For building the user interface of the extension popup.
• Vite: As the build tool for fast development and optimized production builds.
• JavaScript (with JSDoc for type hints where applicable) / TypeScript: For application logic.
• Tailwind CSS: For styling (if fully integrated).
• Chrome Extension APIs: chrome.alarms, chrome.storage, chrome.notifications, chrome.contextMenus, chrome.tabs.

​

Building for Production

pnpm run build
# or
npm run build

​

Contributing

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes.
4. Ensure your code lints and builds correctly.
5. Submit a pull request with a clear description of your changes.