https://github.com/halo-dev/create-halo-plugin

Quickly create Halo plugin development templates
https://github.com/halo-dev/create-halo-plugin

Last synced: 5 months ago
JSON representation

Quickly create Halo plugin development templates

Host: GitHub
URL: https://github.com/halo-dev/create-halo-plugin
Owner: halo-dev
License: gpl-3.0
Created: 2025-06-21T04:13:41.000Z (12 months ago)
Default Branch: main
Last Pushed: 2025-12-24T15:27:10.000Z (5 months ago)
Last Synced: 2025-12-26T06:30:45.074Z (5 months ago)
Language: JavaScript
Size: 277 KB
Stars: 12
Watchers: 0
Forks: 5
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# 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

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

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

## 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** >= 18.0.0
- **Java** >= 21
- **Halo** >= 2.21.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 ` - Plugin name
- `-d, --domain ` - Domain for group and package name
- `-a, --author ` - Author name
- `-i, --includeUI` - Include UI project
- `-u, --uiTool ` - UI build tool (rsbuild or vite, required when includeUI is true)
- `-h, --help` - Show help message
- `-v, --version` - Show version number

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

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

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/halo-dev/create-halo-plugin

Awesome Lists containing this project

README