This guide provides instructions for setting up the development environment, understanding the project structure, and contributing to the Chronotab Chrome extension.

​
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:

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

  2. Install Dependencies: If you have pnpm installed:

    pnpm install

    Alternatively, using npm:

    npm install

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

    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.

The Chronotab extension icon should now appear in your browser’s toolbar. As you make changes to the source code, Vite will automatically rebuild the extension. You may need to click the “reload” button for the extension in chrome://extensions to see changes in the background script or manifest, or sometimes for UI changes if hot-reloading doesn’t catch everything.

​
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

To create an optimized production build:

pnpm run build
# or
npm run build

This will generate the production-ready files in the dist folder, which can then be packaged (e.g., zipped) for submission to the Chrome Web Store.

​
Contributing

Contributions are welcome! If you’d like to contribute:

  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.

If you find a bug or have a feature request, please open an issue on GitHub.