Skip to content

Commit 70590a8

Browse files
michael-borckclaude
michael-borck
and
claude
committed
Add CLAUDE.md documentation for future Claude Code instances
- Created comprehensive development guide covering project architecture - Documented modular template system and CLI tool structure - Added all essential commands for workspace, core package, and CLI development - Explained Electron multi-process build system and TypeScript configuration - Included module integration patterns and publishing workflows - Focused on big-picture architecture requiring multi-file understanding 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 3bc04e3 commit 70590a8

File tree

9 files changed

+1594
-4
lines changed

9 files changed

+1594
-4
lines changed

‎CLAUDE.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is a modular Electron application template system that provides reusable packages for building desktop applications. The system includes a published npm CLI tool (`@michaelborck/create-electron-kit`) that generates new Electron projects from predefined template combinations.
8+
9+
## Architecture
10+
11+
### Workspace Structure
12+
- **packages/**: Independent modules that can be combined into applications
13+
- **tools/create-app/**: Published npm CLI package for project generation
14+
- **test-output/**: Generated test projects (not part of the main codebase)
15+
16+
### Core Architecture Pattern
17+
The system uses a modular architecture where each package in `packages/` is self-contained:
18+
- Each module exports its functionality through an `index.ts` file
19+
- Modules follow a consistent structure: managers/services, components, stores, types
20+
- The `core` package provides the base Electron + React setup that other modules extend
21+
- Template combinations are defined in `tools/create-app/src/templates.ts`
22+
23+
### Key Technologies
24+
- **Electron**: Desktop app framework
25+
- **React 18**: UI framework with TypeScript
26+
- **Vite**: Build tool for renderer process
27+
- **Tailwind CSS**: Styling system
28+
- **Zustand**: State management
29+
- **TypeScript**: Throughout the entire stack
30+
31+
## Development Commands
32+
33+
### Root Level (Workspace)
34+
```bash
35+
# Core development
36+
npm run dev # Start core package development
37+
npm run build # Build core package only
38+
npm run build:all # Build all packages in workspace
39+
40+
# Quality assurance
41+
npm run test # Run tests across all packages
42+
npm run lint # Lint all packages
43+
npm run format # Format code with Prettier
44+
45+
# Utilities
46+
npm run clean # Clean all dist folders and node_modules
47+
```
48+
49+
### Core Package (packages/core)
50+
```bash
51+
# Development
52+
npm run dev # Start both main and renderer in watch mode
53+
npm run dev:main # Watch main + preload processes only
54+
npm run dev:renderer # Start Vite dev server for renderer
55+
56+
# Building
57+
npm run build # Build all processes (main, preload, renderer)
58+
npm run build:main # Build Electron main process
59+
npm run build:preload # Build preload script
60+
npm run build:renderer # Build React renderer with Vite
61+
62+
# Distribution
63+
npm run start # Start built Electron app
64+
npm run dist # Create distributable with electron-builder
65+
66+
# Quality
67+
npm run lint # ESLint for TypeScript/React
68+
npm run typecheck # TypeScript compilation check
69+
```
70+
71+
### CLI Tool (tools/create-app)
72+
```bash
73+
# Development
74+
npm run build # Compile TypeScript to dist/
75+
npm run dev # Watch mode compilation
76+
77+
# Publishing
78+
npm publish --access=public # Publish to npm (already published as @michaelborck/create-electron-kit)
79+
```
80+
81+
## Module System
82+
83+
### Adding New Modules
84+
When creating new packages, follow this structure:
85+
```
86+
packages/new-module/
87+
├── src/
88+
│ ├── index.ts # Main export file
89+
│ ├── ManagerClass.ts # Core functionality
90+
│ ├── types.ts # TypeScript definitions
91+
│ ├── components/ # React components (if applicable)
92+
│ └── stores/ # State management (if applicable)
93+
├── package.json
94+
└── tsconfig.json
95+
```
96+
97+
### Template Configuration
98+
Template combinations are defined in `tools/create-app/src/templates.ts`. Each template specifies:
99+
- `modules`: Array of package names to include
100+
- `name` and `description`: Metadata for CLI display
101+
102+
The CLI automatically handles:
103+
- Copying module source code to generated projects
104+
- Adding appropriate dependencies to package.json
105+
- Merging module-specific configurations
106+
107+
### Dependency Management
108+
The CLI tool in `tools/create-app/src/createApp.ts` contains a `getModuleDependencies()` function that maps each module to its required npm dependencies. Update this when adding new modules that require external packages.
109+
110+
## Build System Details
111+
112+
### Electron Multi-Process Architecture
113+
- **Main process** (`src/main/`): Node.js environment, window management
114+
- **Preload script** (`src/preload/`): Secure bridge between main and renderer
115+
- **Renderer process** (`src/renderer/`): React application in Chromium
116+
117+
### TypeScript Configuration
118+
- Root `tsconfig.json`: Base configuration
119+
- Process-specific configs: `tsconfig.main.json`, `tsconfig.renderer.json`
120+
- Each package has its own `tsconfig.json` for independent compilation
121+
122+
### State Management Pattern
123+
Uses Zustand for state management with this pattern:
124+
- Stores in `src/stores/` or `src/renderer/stores/`
125+
- Manager classes handle business logic
126+
- Components consume stores via hooks
127+
128+
## Testing Generated Projects
129+
130+
When testing CLI-generated projects:
131+
```bash
132+
# Generate test project
133+
npx @michaelborck/create-electron-kit test-project --template=ai-app --skip-install --skip-git
134+
135+
# Manual testing in generated project
136+
cd test-project
137+
npm install
138+
npm run dev
139+
```
140+
141+
## Publishing Updates
142+
143+
The CLI tool is published as `@michaelborck/create-electron-kit`. To update:
144+
1. Increment version in `tools/create-app/package.json`
145+
2. Build: `cd tools/create-app && npm run build`
146+
3. Publish: `npm publish --access=public`
147+
148+
## Module Integration Pattern
149+
150+
When modules are combined in generated projects, they follow this provider pattern:
151+
```tsx
152+
<SettingsProvider>
153+
<DatabaseProvider>
154+
<AIProvider>
155+
<NotificationProvider>
156+
<App />
157+
</NotificationProvider>
158+
</AIProvider>
159+
</DatabaseProvider>
160+
</SettingsProvider>
161+
```
162+
163+
Each module exports its provider and related hooks for consumption by the application.

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -65,16 +65,16 @@ electron-template/
6565

6666
```bash
6767
# Create a new AI-powered application
68-
npx @template/create-app my-ai-app --template=ai-app
68+
npx @michaelborck/create-electron-kit my-ai-app --template=ai-app
6969

7070
# Create a data analysis application
71-
npx @template/create-app my-data-app --template=data-app
71+
npx @michaelborck/create-electron-kit my-data-app --template=data-app
7272

7373
# Create with all modules
74-
npx @template/create-app my-full-app --template=full
74+
npx @michaelborck/create-electron-kit my-full-app --template=full
7575

7676
# Start with minimal setup
77-
npx @template/create-app my-basic-app --template=basic
77+
npx @michaelborck/create-electron-kit my-basic-app --template=basic
7878
```
7979

8080
### Manual Setup

0 commit comments

Comments
 (0)