npm package: @majkapp/create-majk-plugin
Description: CLI tool to bootstrap Majk plugins from quickstart template
Author: Jules White
Latest version: 2.0.8

# @majkapp/create-majk-plugin

CLI tool to quickly bootstrap Majk plugins from the quickstart template.

---

## 🚀 Quick Start

```bash
# Create a plugin with default directory
npx @majkapp/create-majk-plugin myorg my-plugin

# Create plugin without UI (backend-only)
npx @majkapp/create-majk-plugin myorg my-plugin --no-ui

# Create in custom directory
npx @majkapp/create-majk-plugin myorg my-plugin ./custom-dir

# Create in current directory
npx @majkapp/create-majk-plugin myorg my-plugin .
```

---

## 📋 Usage

```
create-majk-plugin <organization> <plugin-name> [directory]
```

### Arguments

- **organization** (required) - NPM organization name (e.g., "mycompany")
- **plugin-name** (required) - Plugin name in kebab-case (e.g., "my-plugin")
- **directory** (optional) - Target directory (default: plugin-name)

### Options

- `--no-ui` - Generate plugin without UI (backend functions only)
- `--help`, `-h` - Show help message

### Examples

```bash
# Create plugin @myorg/my-plugin in ./my-plugin directory
npx @majkapp/create-majk-plugin myorg my-plugin

# Create backend-only plugin (no React UI)
npx @majkapp/create-majk-plugin myorg my-plugin --no-ui

# Create plugin @acme/weather in ./weather-plugin directory
npx @majkapp/create-majk-plugin acme weather ./weather-plugin

# Create plugin in current directory
npx @majkapp/create-majk-plugin mycompany dashboard .
```

---

## 📦 What You Get

The tool copies the complete quickstart sample and configures it with your organization and plugin name.

### Two Templates Available

**Full Quickstart** (default):
- Complete plugin with React dashboard UI
- Sample screens and components
- Vite + Tailwind CSS setup
- UI contract tests

**No-UI Quickstart** (`--no-ui` flag):
- Backend-only plugin (functions and services)
- No React dependencies
- Smaller and simpler for API/automation plugins
- Function tests only

### Generated Structure

```
my-plugin/
├── ARCHITECTURE.md       # Plugin architecture documentation
├── CLAUDE.md             # Instructions for Claude AI assistant
├── README.md             # Plugin README
├── START_HERE.md         # Comprehensive developer guide
├── TESTING_START_HERE.md # Testing documentation
├── package.json          # Configured with @organization/plugin-name
├── tsconfig.json         # TypeScript configuration
├── vite.config.js        # Vite build configuration
├── tailwind.config.js    # Tailwind CSS configuration
├── postcss.config.js     # PostCSS configuration
├── src/
│   ├── index.ts          # Plugin definition
│   ├── adapters/         # Adapter layer (data access)
│   ├── domain/           # Domain entities
│   └── services/         # Business logic
├── ui/
│   ├── index.html        # HTML entry
│   ├── hero.ts           # Hero configuration
│   ├── postcss.config.js # PostCSS config for UI
│   ├── tailwind.config.js # Tailwind config for UI
│   ├── public/
│   │   └── mcp-dom-agent.js  # File picker bridge script
│   └── src/
│       ├── main.jsx      # React entry point
│       ├── App.tsx       # Main application (starter with file picker demo)
│       ├── App.showcase.tsx  # Full showcase for reference
│       ├── index.css     # Global styles
│       └── contracts/    # UI contracts
├── tests/
│   ├── README.md         # Testing documentation
│   ├── domain/           # Domain tests
│   ├── plugin/           # Plugin tests
│   │   ├── functions/    # Function unit tests
│   │   └── ui/           # UI E2E tests
│   └── helpers/          # Test helpers
└── dist/                 # Built output (after npm run build)
```

### Key Features Included

**Backend:**
- ✅ Complete plugin architecture with adapters, services, and domain layers
- ✅ Sample MAJK adapter showing how to integrate with MAJK APIs
- ✅ Null adapter for testing
- ✅ Sample service with comprehensive business logic
- ✅ Plugin definition with functions, screens, and UI configuration

**Frontend:**
- ✅ React 18 with TypeScript
- ✅ Beautiful dashboard UI with sample items
- ✅ Hash-based routing (required for MAJK plugins)
- ✅ Theme integration (@majkapp/plugin-theme)
- ✅ UI components (@majkapp/plugin-ui, @heroui/react)
- ✅ Tailwind CSS with MAJK preset
- ✅ Auto-generated API client and hooks
- ✅ File/Directory picker demo with mcp-dom-agent.js bridge
- ✅ Topbar menu pattern (one per left-nav item)

**Testing:**
- ✅ Comprehensive test suite with unit and E2E tests
- ✅ Domain service tests
- ✅ Plugin function tests
- ✅ UI contract tests
- ✅ Test helpers and utilities

**Documentation:**
- ✅ START_HERE.md - Step-by-step developer guide
- ✅ ARCHITECTURE.md - Complete architecture documentation
- ✅ TESTING_START_HERE.md - Testing guide
- ✅ CLAUDE.md - Instructions for AI assistants

---

## 🛠️ Development Workflow

After generating your plugin:

```bash
cd my-plugin

# Install dependencies
npm install

# Build plugin (compiles TypeScript + builds UI)
npm run build

# Development mode (UI hot-reload)
npm run dev

# Run tests
npm test                    # Run function tests
npm run test:contract       # Run UI contract tests

# Build for production
npm run build
```

**Build Process:**
1. `tsc` - Compiles `src/` → `dist/`
2. `npm run generate` - Creates TypeScript client from backend functions
3. `vite build` - Builds React app to `dist/`

---

## 🎯 What Gets Customized

The tool makes **minimal changes** to the quickstart template:

1. **package.json** - Updates the `name` field to `@organization/plugin-name`

Everything else is copied as-is from the quickstart sample, giving you a fully working plugin to start from.

---

## 🔧 Requirements

- **Node.js**: 18.0.0 or higher
- **npm**: 7.0.0 or higher (comes with Node.js 18+)
- **Network**: Access to npm registry for dependencies

---

## 📚 After Generation

1. **Read START_HERE.md** - Complete developer guide
2. **Run `npm install`** - Install dependencies
3. **Run `npm run build`** - Build the plugin
4. **Load in MAJK** - Use MAJK to load your plugin directory

---

## 🐛 Troubleshooting

### "Directory already exists"

The tool won't overwrite existing directories. Choose a different name or remove the existing directory.

### "Cannot find module '@majkapp/plugin-kit'"

```bash
cd my-plugin
npm install
```

### "dist/ directory not found"

```bash
npm run build  # Build plugin first
```

### NPX not finding package

```bash
# Clear npm cache
npm cache clean --force

# Try with latest
npx @majkapp/create-majk-plugin@latest myorg my-plugin
```

---

## 🧪 Testing the Generator

```bash
# Basic test
node bin/create-majk-plugin.js testorg test-plugin

# With custom directory
node bin/create-majk-plugin.js testorg test-plugin ./custom-test

# Help
node bin/create-majk-plugin.js --help
```

---

## 🔄 Maintaining Templates

**For developers of create-majk-plugin:**

The templates are synced from the canonical samples in the monorepo:

```bash
# Update templates from samples/quickstart and samples/quickstart-no-ui
npm run update-templates
```

This ensures the generator always uses the latest sample code.

---

## 📝 Version History

### v2.0.6 (Current)
- ✅ Added `mcp-dom-agent.js` file picker bridge for native file/directory selection
- ✅ Added working File/Directory Picker Demo on dashboard
- ✅ Updated index.html to load mcp-dom-agent.js
- ✅ Topbar menu per left-nav item pattern in starter template

### v2.0.5
- ✅ Comprehensive comments in App.tsx starter template
- ✅ Documentation for query/mutation hooks usage
- ✅ Showcase components separated into `_showcase/` directory

### v2.0.1
- ✅ Added `--no-ui` flag for backend-only plugins
- ✅ Two templates: quickstart and quickstart-no-ui
- ✅ Template update script for maintainers
- ✅ Generated no-ui plugins include sync script (works within monorepo)

### v2.0.0
- ✅ Complete rewrite for simplicity
- ✅ Now based on quickstart sample template
- ✅ Accepts organization and plugin-name as arguments
- ✅ Only customizes package.json name field
- ✅ No complex features or prompts
- ✅ Copies complete quickstart with all documentation

### v1.x
- Previous version with feature-based generation

---

## 📄 License

MIT

---

## 🎯 Quick Reference

```bash
# Basic usage
npx @majkapp/create-majk-plugin myorg my-plugin

# Backend-only (no UI)
npx @majkapp/create-majk-plugin myorg my-plugin --no-ui

# Custom directory
npx @majkapp/create-majk-plugin myorg my-plugin ./path/to/dir

# Current directory
npx @majkapp/create-majk-plugin myorg my-plugin .

# Help
npx @majkapp/create-majk-plugin --help
```