# create-halo-plugin
English | [简体中文](README.zh-CN.md)
🚀 Quickly create Halo plugin development templates
A scaffolding tool for creating [Halo](https://www.halo.run) plugin projects with modern development setup.
## Features
- 🎯 **Interactive CLI** - Guided project setup with prompts
- 🏗️ **Modern Build Tools** - Choose between Vite or Rsbuild for UI development
- 📦 **Complete Project Structure** - Pre-configured Gradle build, UI setup, and plugin manifest
- 📝 **TypeScript Support** - Full TypeScript configuration for UI development
- ➕ **Incremental Setup** - Add UI or a publishable Java module to an existing plugin
## Quick Start
Create a new Halo plugin project using any of the following commands:
```bash
# npm
npm create halo-plugin
npm create halo-plugin my-plugin
# pnpm (recommended)
pnpm create halo-plugin
pnpm create halo-plugin my-plugin
# yarn
yarn create halo-plugin
yarn create halo-plugin my-plugin
# npx
npx create-halo-plugin
npx create-halo-plugin my-plugin
```
## Usage Examples
### Create with auto-generated directory name
```bash
pnpm create halo-plugin
# Creates a directory named "plugin-{your-plugin-name}"
```
### Create in a specific directory
```bash
pnpm create halo-plugin my-awesome-plugin
# Creates the project in "./my-awesome-plugin" directory
```
### Interactive Setup
The CLI will guide you through the setup process:
```bash
🚀 Welcome to Halo Plugin Creator!
✔ Plugin name: › my-awesome-plugin
✔ Domain (for group and package name): › com.example
✔ Author name: › John Doe
✔ Include UI project? › yes
✔ Choose UI build tool: › Vite
📋 Project Configuration:
Name: my-awesome-plugin
Domain: com.example
Package: com.example.myawesomeplugin
Author: John Doe
Include UI: Yes
UI Tool: vite
Output Directory: /path/to/my-awesome-plugin
✔ Create project? › yes
```
### Creating Backend-Only Plugins
If your plugin doesn't need a user interface, you can skip UI project creation via command line:
```bash
pnpm create halo-plugin my-backend-plugin --name=my-backend-plugin --domain=com.example --author="John Doe" --includeUI=false
```
Or select "no" when prompted to include a UI project during interactive setup.
### Add UI Later
Run the command from an existing Halo plugin root:
```bash
npx create-halo-plugin add ui --tool vite
# or
npx create-halo-plugin add ui --tool rsbuild
```
The command shows the files it will create or update before applying the
change. Repeating the same command is a no-op. Existing `ui/` directories and
unrecognized Gradle layouts are left untouched.
### Add a Publishable Java Module
```bash
npx create-halo-plugin add module api
```
This creates the Java source and test structure, Maven Central publishing
configuration, module README, and `.github/workflows/publish.yml`. It also
includes the module in `settings.gradle` and adds it as an implementation
dependency of the root plugin.
The publishing workflow publishes snapshots from `main` and releases from
`v*` tags. Configure these repository secrets before publishing:
`MAVEN_CENTRAL_USERNAME`, `MAVEN_CENTRAL_PASSWORD`, `SIGNING_KEY`,
`SIGNING_KEY_ID`, and `SIGNING_PASSWORD`.
## Project Structure
### Full Project with UI
```bash
my-plugin/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/example/myplugin/
│ │ │ └── MyPluginPlugin.java
│ │ └── resources/
│ │ ├── plugin.yaml
│ │ └── logo.png
│ └── test/
│ └── java/
│ └── com/example/myplugin/
│ └── MyPluginPluginTest.java
├── ui/
│ ├── src/
│ │ ├── index.ts
│ │ ├── views/
│ │ └── assets/
│ ├── package.json
│ ├── vite.config.ts (or rsbuild.config.ts)
│ └── tsconfig.json
├── build.gradle
├── settings.gradle
├── gradlew
└── README.md
```
### Backend-Only Project (without UI)
```bash
my-plugin/
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/example/myplugin/
│ │ │ └── MyPluginPlugin.java
│ │ └── resources/
│ │ ├── plugin.yaml
│ │ └── logo.png
│ └── test/
│ └── java/
│ └── com/example/myplugin/
│ └── MyPluginPluginTest.java
├── build.gradle
├── settings.gradle
├── gradlew
└── README.md
```
## Development
### Projects with UI
After creating your project:
```bash
# Navigate to your project
cd my-plugin
# Start Halo development server
./gradlew haloServer
# In another terminal, start UI development
cd ui
pnpm dev
```
### Backend-Only Projects
For projects without UI:
```bash
# Navigate to your project
cd my-plugin
# Start Halo development server
./gradlew haloServer
```
## Requirements
- **Node.js** >= 22.0.0 for the CLI; >=22.12.0 for generated UI projects
- **Java** >= 21
- **Halo** >= 2.27.0
## Plugin Name Rules
Plugin names must follow this pattern:
- Start and end with alphanumeric characters (a-z, 0-9)
- Can contain hyphens (-) and dots (.) in the middle
- Only lowercase letters allowed
- Examples: `my-plugin`, `blog.comment`, `user-management`
## UI Build Tools
Choose between two modern build tools:
### Vite
- 🔧 Simple configuration
- 📦 Optimized builds
### Rsbuild
- 🚀 Rspack-based for speed
- 🛠️ Rich plugin ecosystem
- 📊 Better build performance
- 📦 Code splitting, suitable for larger plugin projects
## Command Line Options
```bash
# Show help
npx create-halo-plugin --help
# Show version
npx create-halo-plugin --version
# Create project with command line arguments
npx create-halo-plugin my-plugin \
--name=my-plugin \
--domain=com.example \
--author="John Doe" \
--includeUI \
--uiTool=rsbuild
# Create backend-only project
npx create-halo-plugin my-backend-plugin \
--name=my-backend-plugin \
--domain=com.example \
--author="John Doe" \
--includeUI=false
```
Available options:
- `-n, --name <name>` - Plugin name
- `-d, --domain <domain>` - Domain for group and package name
- `-a, --author <author>` - Author name
- `-i, --includeUI` - Include UI project
- `-u, --uiTool <tool>` - UI build tool (rsbuild or vite, required when includeUI is true)
- `-h, --help` - Show help message
- `-v, --version` - Show version number
Incremental commands inspect the actual Groovy Gradle configuration and do not
depend on generator comments. Kotlin DSL is not supported. A Java module
requires an identifiable top-level `dependencies` block; ambiguous structures
are rejected instead of overwritten.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
[GPL-3.0](LICENSE) © [Halo](https://github.com/halo-dev)
## Related
- [Halo](https://www.halo.run) - Powerful and easy-to-use open source website builder
- [Halo Documentation](https://docs.halo.run) - Official documentation
- [Plugin Development Guide](https://docs.halo.run/developer-guide/plugin/introduction)