1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is `create-addon`, a CLI tool for generating Node.js native addon projects. It provides scaffolding for C++, Objective-C, and Swift addons with platform-specific templates. The CLI features an interactive UI built with React and Ink.
## Architecture
### Core Components
- **CLI Entry Point**: `src/bin/index.ts` - Main CLI implementation using yargs and Ink
- **Interactive UI**: `src/components/` - React components for the CLI interface
- **Template System**: `templates/` - Contains boilerplate code for different addon types
- **Build System**: Uses bunchee for TypeScript compilation to `dist/`
### Templates Structure
Each template in `templates/` follows this pattern:
- `binding.gyp` - node-gyp build configuration
- `package.json` - Template package configuration
- `src/` - Native code (C++, Objective-C, Swift)
- `include/` - Header files
- `js/index.js` - JavaScript wrapper using EventEmitter pattern
### Template Types
- **cpp-linux**: C++ addon with GTK+ integration for Linux
- **cpp-win32**: C++ addon for Windows platforms
- **objective-c**: Objective-C addon for macOS with Todo functionality
- **swift**: Swift addon for macOS with bridge to JavaScript
## Commands
### Development
```bash
# Build the CLI (builds to dist/ using bunchee)
pnpm run build
# Build with watch mode for development
pnpm run dev
# Test the CLI locally (after building)
node dist/bin.js
# Install dependencies
pnpm install
```
### Generated Project Commands
Each generated addon project includes:
```bash
# Build the native addon
npm run build
# Clean build artifacts
npm run clean
```
## Working with Templates
- All templates use `node-addon-api` for modern N-API bindings
- Templates include EventEmitter-based JavaScript wrappers
- Platform detection prevents loading incompatible addons
- Templates demonstrate Todo functionality as example implementation
## Template Architecture Patterns
### JavaScript Wrapper Pattern
All templates use a consistent pattern:
1. Platform check before loading native module
2. EventEmitter inheritance for event handling
3. Private `#parse` method for payload processing
4. Conditional module.exports based on platform
### Native Module Structure
- Main addon class extends EventEmitter capabilities
- Consistent method naming (`helloWorld`, `helloGui`)
- Event-driven architecture for todo operations
- JSON payload communication between native and JavaScript
## Interactive UI Components
The CLI uses React components with Ink for a modern interactive experience:
- **CreateAddonApp**: Main application component managing the flow with state machine pattern (project-name → template-selection → creating → success/error)
- **ProjectNameInput**: Interactive project name input with validation
- **TemplateSelector**: Visual template selection with icons and descriptions
- **ProgressIndicator**: Real-time progress feedback with spinners
- **Summary**: Success screen with next steps
### UI Flow States
The interactive flow follows these states:
1. `project-name` - Collect project name if not provided
2. `template-selection` - Select template if not provided via CLI args
3. `creating` - Show progress while copying files and updating configuration
4. `success` - Display completion with next steps (auto-exits after 3s)
5. `error` - Show error message (auto-exits after 3s)
## Build Configuration
- Uses `bunchee` for bundling TypeScript with ESM support
- Workspace configuration in `pnpm-workspace.yaml` includes templates as packages
- Templates are excluded from main build but included in CLI distribution
- Project configured as ESM module with React JSX support
- TypeScript config targets ES2022 with bundler module resolution
- Built files go to `dist/` directory, with `dist/bin.js` as the main entry point
## CLI Arguments and Usage
The CLI supports both interactive and non-interactive modes:
```bash
# Interactive mode (prompts for missing options)
create-addon
# Semi-interactive (prompt for template)
create-addon my-project
# Non-interactive (all options provided)
create-addon my-project --template cpp-linux
# With additional options
create-addon my-project -t swift --skip-install
```
Available templates: `cpp-linux`, `cpp-win32`, `objective-c`, `swift`
## Template File Structure
Templates are located in `templates/` and follow this structure:
- `binding.gyp` - node-gyp configuration for native compilation
- `package.json` - Template package with build scripts and dependencies
- `src/` - Native source code (C++, Objective-C, Swift)
- `include/` - Header files
- `js/index.js` - JavaScript wrapper with platform detection and EventEmitter pattern
Template package.json gets updated with the user's project name during creation.