> ## Documentation Index
> Fetch the complete documentation index at: https://chronotab.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Guide

> Information for developing and contributing to Chronotab.

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:**
   ```bash theme={null}
   git clone https://github.com/claritybytes/chronotab-extension.git
   cd chronotab-extension
   ```

2. **Install Dependencies:**
   If you have `pnpm` installed:
   ```bash theme={null}
   pnpm install
   ```
   Alternatively, using `npm`:
   ```bash theme={null}
   npm install
   ```

3. **Start the Development Server:**
   This command will build the extension and watch for changes.
   ```bash theme={null}
   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:

```bash theme={null}
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](https://github.com/claritybytes/chronotab-extension/issues) on GitHub.