|
| 1 | +# Gitify Development Instructions |
| 2 | + |
| 3 | +Gitify is a Node.js/Electron desktop application that displays GitHub notifications in the system tray. It's built with React, TypeScript, and uses pnpm for package management. |
| 4 | + |
| 5 | +**ALWAYS follow these instructions first and only fallback to additional search and context gathering if the information in the instructions is incomplete or found to be in error.** |
| 6 | + |
| 7 | +## Working Effectively |
| 8 | + |
| 9 | +### Prerequisites and Setup |
| 10 | +- **Install pnpm globally first**: `npm install -g pnpm` |
| 11 | +- **Node.js requirement**: This project requires Node.js >=22 (check .nvmrc), though it works with Node 20+ with warnings |
| 12 | +- **Bootstrap the repository**: |
| 13 | + - `pnpm install` -- takes 2.5 minutes. NEVER CANCEL. Set timeout to 5+ minutes. |
| 14 | + |
| 15 | +### Development Workflow |
| 16 | +- **Build the application**: |
| 17 | + - `pnpm build` -- takes 32 seconds. NEVER CANCEL. Set timeout to 60+ minutes. |
| 18 | + - Builds both main (Electron process) and renderer (React UI) bundles |
| 19 | + - Output goes to `build/` directory |
| 20 | +- **Development mode with hot reload**: |
| 21 | + - `pnpm watch` -- starts webpack in watch mode for both main and renderer |
| 22 | + - Takes ~15 seconds for initial compilation |
| 23 | + - Leave running while developing |
| 24 | +- **Run the Electron app**: |
| 25 | + - `pnpm start` -- launches the desktop application |
| 26 | + - NOTE: Will fail in headless/container environments due to Electron sandbox restrictions (expected) |
| 27 | + - Use `CmdOrCtrl+R` to reload when watch mode detects changes |
| 28 | + |
| 29 | +### Linting and Code Quality |
| 30 | +- **Check linting and formatting**: |
| 31 | + - `pnpm lint:check` -- takes <1 second using Biome |
| 32 | + - **ALWAYS run before committing** or CI will fail |
| 33 | +- **Auto-fix issues**: |
| 34 | + - `pnpm lint` -- automatically fixes linting and formatting issues |
| 35 | + |
| 36 | +### Testing |
| 37 | +- **Run TypeScript compilation check**: |
| 38 | + - `pnpm tsc --noEmit` -- takes 5 seconds. NEVER CANCEL. Set timeout to 10+ minutes. |
| 39 | +- **Run unit tests**: |
| 40 | + - `pnpm test` -- takes 67 seconds. NEVER CANCEL. Set timeout to 30+ minutes. |
| 41 | + - Uses Jest with jsdom environment |
| 42 | + - NOTE: Some existing snapshot tests may fail but still return success - this is normal |
| 43 | + - Update snapshots after legitimate UI changes with `pnpm test -u` |
| 44 | +- **Run tests with coverage** (CI format): |
| 45 | + - `pnpm test --coverage --runInBand --verbose` |
| 46 | + |
| 47 | +## Validation Scenarios |
| 48 | + |
| 49 | +**CRITICAL**: After making changes, ALWAYS validate your work by running these scenarios: |
| 50 | + |
| 51 | +### Build Validation |
| 52 | +1. **Clean build test**: `rm -rf build && pnpm build` |
| 53 | +2. **Verify build outputs**: Check that `build/main.js`, `build/renderer.js`, and `build/styles.css` are created |
| 54 | +3. **File sizes should be reasonable**: main.js ~300KB, renderer.js ~2MB, styles.css ~1MB |
| 55 | +4. **Success indicators**: Look for "webpack compiled successfully" messages for both main and renderer |
| 56 | + |
| 57 | +### Code Quality Validation |
| 58 | +1. **Linting passes**: `pnpm lint:check` should show warnings but complete successfully (exit code 0) |
| 59 | +2. **TypeScript compiles**: `pnpm tsc --noEmit` should complete without errors |
| 60 | +3. **Tests pass**: Run `pnpm test` and ensure no new test failures (some existing ones may fail - focus on your changes) |
| 61 | + |
| 62 | +### Development Environment Testing |
| 63 | +1. **Watch mode works**: Start `pnpm watch`, make a small change to a file in `src/`, verify webpack recompiles (look for compilation success messages) |
| 64 | +2. **Development build**: The watch mode creates development builds with source maps in `build/` directory |
| 65 | + |
| 66 | +## Expected Command Outputs |
| 67 | + |
| 68 | +### Successful Build |
| 69 | +``` |
| 70 | +webpack 5.101.2 compiled successfully in [time] |
| 71 | +``` |
| 72 | + |
| 73 | +### Successful Tests (with some expected failures) |
| 74 | +``` |
| 75 | +Test Suites: X failed, Y passed, Z total |
| 76 | +Tests: A failed, B passed, C total |
| 77 | +``` |
| 78 | +Note: Focus on ensuring no NEW test failures from your changes. |
| 79 | + |
| 80 | +### Successful Linting |
| 81 | +``` |
| 82 | +Checked X files in Yms. No fixes applied. |
| 83 | +Found Z warnings. |
| 84 | +``` |
| 85 | +Warnings are acceptable - the important part is that it completes successfully. |
| 86 | + |
| 87 | +## Common Tasks and File Locations |
| 88 | + |
| 89 | +### Key Files and Directories |
| 90 | +- **Main Electron process**: `src/main/` - Node.js backend code |
| 91 | +- **Renderer process**: `src/renderer/` - React frontend code |
| 92 | +- **Shared code**: `src/shared/` - Common utilities and types |
| 93 | +- **Build configuration**: `config/` - Webpack configs and electron-builder settings |
| 94 | +- **Assets**: `assets/` - Icons, sounds, and static resources |
| 95 | + |
| 96 | +### Configuration Files |
| 97 | +- **package.json**: Main project configuration and scripts |
| 98 | +- **biome.json**: Linting and formatting rules |
| 99 | +- **jest.config.ts**: Test configuration |
| 100 | +- **tsconfig.json**: TypeScript configuration |
| 101 | +- **tailwind.config.ts**: CSS framework configuration |
| 102 | + |
| 103 | +### Frequently Modified Areas |
| 104 | +- **Notification logic**: `src/renderer/hooks/useNotifications.ts` |
| 105 | +- **GitHub API client**: `src/renderer/utils/api/` |
| 106 | +- **UI components**: `src/renderer/components/` |
| 107 | +- **Authentication**: `src/renderer/utils/auth/` |
| 108 | +- **Settings**: `src/renderer/routes/Settings.tsx` |
| 109 | + |
| 110 | +## Build and Release Process |
| 111 | + |
| 112 | +### Local Packaging (for testing) |
| 113 | +- **macOS**: `pnpm package:macos --publish=never` |
| 114 | +- **Windows**: `pnpm package:win --publish=never` |
| 115 | +- **Linux**: `pnpm package:linux --publish=never` |
| 116 | +- **NOTE**: These require the full build first and additional platform-specific dependencies |
| 117 | + |
| 118 | +### Pre-commit Checks |
| 119 | +- **Automatic via Husky**: Git hooks run `pnpx lint-staged` on commit |
| 120 | +- **Manual validation**: Run `pnpm lint:check && pnpm tsc --noEmit && pnpm test` |
| 121 | + |
| 122 | +## Important Constraints and Limitations |
| 123 | + |
| 124 | +### Timing Expectations |
| 125 | +- **Dependency installation**: 2-3 minutes (normal for Electron projects) |
| 126 | +- **Full build (clean)**: 30-35 seconds |
| 127 | +- **Watch mode initial compilation**: 10-15 seconds |
| 128 | +- **Watch mode recompilation**: 5-8 seconds for incremental changes |
| 129 | +- **Test suite**: 60-70 seconds |
| 130 | +- **TypeScript compilation**: 5 seconds |
| 131 | +- **Linting**: <1 second |
| 132 | + |
| 133 | +### Environment Issues |
| 134 | +- **Electron in containers**: Will fail to start due to sandbox restrictions (expected behavior in headless environments) |
| 135 | +- **Node version warnings**: Project requires Node >=22, works with 20+ but shows warnings in `pnpm` commands |
| 136 | +- **Build warnings**: Some PostCSS/Tailwind warnings in renderer build are normal and expected |
| 137 | +- **Linting warnings**: Existing codebase has some linting warnings - focus only on your changes |
| 138 | + |
| 139 | +### Common Troubleshooting |
| 140 | +- **Build failures**: Check Node version, ensure `pnpm install` completed successfully |
| 141 | +- **Test snapshot failures**: Run `pnpm test -u` to update snapshots after legitimate UI changes |
| 142 | +- **Linting errors**: Run `pnpm lint` to auto-fix most issues |
| 143 | +- **Watch mode not updating**: Restart watch mode, check file permissions |
| 144 | + |
| 145 | +## Development Philosophy |
| 146 | + |
| 147 | +This project focuses on GitHub notification monitoring, not being a full GitHub client. Keep changes: |
| 148 | +- **Simple and focused** on core notification functionality |
| 149 | +- **Consistent** with existing UI patterns and design language |
| 150 | +- **Minimal** - avoid adding complexity for edge cases |
| 151 | +- **Cross-platform** compatible (macOS, Windows, Linux) |
| 152 | + |
| 153 | +## Technology Stack Reference |
| 154 | + |
| 155 | +**Core Technologies:** |
| 156 | +- **Electron 37+**: Desktop app framework |
| 157 | +- **React 19+**: UI library |
| 158 | +- **TypeScript 5+**: Language |
| 159 | +- **pnpm 10+**: Package manager |
| 160 | +- **Biome**: Linting and formatting |
| 161 | +- **Jest**: Testing framework |
| 162 | +- **Webpack 5**: Build system |
| 163 | +- **Tailwind CSS**: Styling framework |
| 164 | + |
| 165 | +**Key Dependencies:** |
| 166 | +- **menubar**: System tray integration |
| 167 | +- **electron-updater**: Auto-update functionality |
| 168 | +- **@primer/react**: GitHub's React component library |
| 169 | +- **date-fns**: Date utilities |
| 170 | +- **axios**: HTTP client for GitHub API |
| 171 | + |
| 172 | +ALWAYS reference this information first before exploring the codebase or running commands to save time and avoid common pitfalls. |
0 commit comments