halo-plugin-dev

name	halo-plugin-dev
description	Create or modify Halo CMS plugins, including Java backend code, plugin.yaml and extension resources, Gradle and DevTools configuration, plugin APIs and lifecycle, and Vue-based Console or User Center UI. Use for Halo plugin implementation, migration, debugging, or integration work; do not use for theme-only changes.

Halo Plugin Development

Halo is built on Spring Boot + Spring WebFlux + Vue 3. A plugin consists of:

• Backend (Java): runs inside Halo's JVM, uses Spring DI, reactive WebFlux, custom extensions (CRD-like), and custom APIs
• Frontend (Vue/TypeScript): built as an IIFE or ESM UI provider for Console and UC (User Center)
• Manifest (plugin.yaml): plugin metadata, dependencies, settings, and config map names

Version first: inspect the target project's Halo platform dependency and plugin.yaml spec.requires before choosing an API or build format. Use the references below for Halo-specific invariants and workflow guidance. For version-sensitive field names, signatures, and UI contracts, follow the official documentation routes linked from the relevant reference instead of guessing or silently raising spec.requires.

Quick Start

Create a new plugin project using the official scaffolding tool:

pnpm create halo-plugin

Follow the prompts (plugin name, domain, author, UI build tool: Rsbuild or Vite).

Then run with DevTools (requires Docker):

./gradlew haloServer

Visit http://localhost:8090/console — username/password defaults to admin/admin.

After code changes:

./gradlew reload

Or use watch for auto-reload:

./gradlew watch

Development Workflow

1. Scaffold: pnpm create halo-plugin
2. Backend: write Java code under src/main/java/
3. Frontend: write Vue/TS code under the project's existing UI source directory, normally ui/src/
4. Manifest: configure src/main/resources/plugin.yaml
5. Extensions: declare YAML resources under src/main/resources/extensions/
6. Run: ./gradlew haloServer (with Docker)
7. Test: visit Console at http://localhost:8090/console
8. Build: ./gradlew build produces a JAR for distribution

References Index

File	Content	When to read
references/api-changelog.md	High-impact plugin API changes by Halo version, with docs routes	Before using version-sensitive APIs, upgrading Halo dependencies, or raising spec.requires
references/plugin-structure.md	Directory structure, backend/frontend layout, build.gradle basics	Creating a new plugin from scratch or understanding the directory layout
references/plugin-manifest.md	plugin.yaml fields, version requirements, dependencies, settings/configMap	Writing or editing plugin.yaml
references/plugin-interaction.md	pluginDependencies, API modules, shared events, defining and consuming plugin extension points	Depending on another plugin, exposing an API module, sharing events, or making a plugin extensible
references/devtools.md	haloServer, reload, watch, generateApiClient, generateRoleTasks, debug config	Running ./gradlew haloServer, hot reload, or debugging a plugin
references/server-extension.md	Custom Extension (GVK), AbstractExtension, CRUD APIs, indexes, field/label selectors	Defining a custom data model, storage, or query indexes
references/server-api.md	CustomEndpoint, @Controller with @ApiVersion, query params, validation, OpenAPI docs	Writing a new backend API endpoint or controller
references/server-lifecycle.md	BasePlugin lifecycle (start/stop/delete), Scheme registration/cleanup	Handling plugin start, stop, delete, or scheme registration
references/server-shared-beans.md	ReactiveExtensionClient, SchemeManager, UserService, AttachmentService, ExtensionGetter, etc.	Injecting or calling Halo core services from plugin Java code
references/server-security.md	Role templates, RBAC rules, verbs, aggregation, UI permissions	Adding RBAC roles, API permissions, or UI permission checks