@majkapp/create-majk-plugin

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

🚀 Quick Start

# 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

# 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
│   └── src/
│       ├── main.jsx      # React entry point
│       ├── App.tsx       # Main application
│       ├── 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

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:

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'"

cd my-plugin
npm install

"dist/ directory not found"

npm run build  # Build plugin first

NPX not finding package

# Clear npm cache
npm cache clean --force

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

🧪 Testing the Generator

# 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:

# 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.1 (Current)

• ✅ 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

# 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