FRPLM Frontend Build Helper

Build, scaffold, diagnose, and verify FRPLM frontend extension panels.

This package provides the standard tooling for FRPLM extensions with Vue frontend panels. It generates the frontend scaffold, optionally creates Maven and Java integration, checks build prerequisites, and verifies that the generated panel.js bundle can be loaded by the FRPLM host.

Requirements

• Node.js >=20.19.0
• npm
• Maven, for full Java extension modules
• @frplm/host-sdk

Generated Maven projects use plugin-managed Node:

<nodeVersion>v22.13.0</nodeVersion>

Quick start

Create a complete FRPLM extension project:

npm exec --yes --package @frplm/frontend-build-helper@latest -- create-frplm-extension <extension-id>

Build it:

mvn package

A successful build produces:

frontend/dist/<extension-id>/panel.js
target/classes/extensions/<extension-id>/panel.js

Generated structure

pom.xml
src/main/java/.../<ClassName>.java
frontend/
  package.json
  tsconfig.json
  vite.config.mts
  index.html
  src/
    main.ts
    panel.ce.vue
    vue.d.ts

Scaffold examples

Create an extension with metadata:

npm exec --yes --package @frplm/frontend-build-helper@latest -- create-frplm-extension intentclassifier \
  --artifact-id frplm-ext-intentClassifier \
  --class-name IntentClassifier \
  --display-name "Intent classifier" \
  --description "Automatically picks up movements from chat history"

Generate inside an existing Maven module without replacing pom.xml:

npm exec --yes --package @frplm/frontend-build-helper@latest -- create-frplm-extension context-injector --no-maven

Generate only frontend files:

npm exec --yes --package @frplm/frontend-build-helper@latest -- create-frplm-extension context-injector --frontend-only

Frontend commands

Inside the generated frontend/ directory:

npm run doctor
npm run build
npm run verify

The build pipeline is:

frplm-extension-doctor
  ↓
vite build
  ↓
verify-extension-panel

CLI commands

create-frplm-extension

create-frplm-extension <extension-id> [options]

Common options:

--dir <path>                  Frontend directory. Default: frontend
--force                       Overwrite generated files
--no-install                  Do not run npm install after generation
--frontend-only               Generate only frontend files
--no-maven                    Do not generate pom.xml
--no-java                     Do not generate Java extension class
--helper-version <version>    @frplm/frontend-build-helper version
--host-sdk-version <version>  @frplm/host-sdk version

Maven and Java options:

--artifact-id <id>            Maven artifactId. Default: frplm-ext-<extension-id>
--group-id <id>               Maven groupId
--version <version>           Maven project version
--api-group-id <id>           FRPLM API dependency groupId
--api-artifact-id <id>        FRPLM API dependency artifactId
--api-version <version>       FRPLM API dependency version
--java-version <version>      Java compiler version. Default: 21
--node-version <version>      Maven-managed Node version. Default: v22.13.0
--package <name>              Java package name
--class-name <name>           Java class name
--display-name <name>         Extension display name
--description <text>          Extension description

frplm-extension-doctor

Checks whether the frontend can build.

frplm-extension-doctor [extension-id]

Useful options:

--project-dir <dir>   Check another frontend directory
--strict              Treat warnings as failures
--skip-maven          Skip Maven pom.xml checks

verify-extension-panel

Checks the built bundle:

verify-extension-panel [extension-id]

Default expected output:

dist/<extension-id>/panel.js

Useful option:

--project-dir <dir>   Check another frontend directory

The verifier fails when panel.js is missing, is HTML instead of JavaScript, contains top-level ESM imports, imports Vue at runtime, contains unresolved process.env, or does not appear to register the FRPLM custom element.

Extension id rules

Valid extension ids use lowercase letters, numbers, and optional internal hyphens.

valid:   intentclassifier
valid:   intent-classifier
invalid: IntentClassifier
invalid: intent_classifier
invalid: intent classifier
invalid: -intentclassifier
invalid: intentclassifier-

The extension id is used in:

frontend/dist/<extension-id>/panel.js
frplm-<extension-id>-panel
target/classes/extensions/<extension-id>/panel.js

Changing it later is a breaking change.

Manual Vite configuration

Generated extensions use:

import { defineFrplmExtensionPanelConfig } from "@frplm/frontend-build-helper/frplm-extension-vite";

export default defineFrplmExtensionPanelConfig({
    id: "context-injector"
});

This emits an IIFE bundle at:

dist/context-injector/panel.js

Manual panel registration

Generated frontends use:

import Panel from "./panel.ce.vue";
import { registerFrplmPanel } from "@frplm/frontend-build-helper/registerFrplmPanel";

registerFrplmPanel("context-injector", Panel);

This registers:

<frplm-context-injector-panel></frplm-context-injector-panel>

The FRPLM host loads panel.js and mounts that custom element.

Troubleshooting

frplm-extension-doctor: command not found

Install frontend dependencies:

cd frontend
npm install

vite.config.ts causes ESM errors

Use:

vite.config.mts

The initializer generates this file by default.

crypto.hash is not a function

Maven is using an old plugin-managed Node runtime.

Use:

<nodeVersion>v22.13.0</nodeVersion>

Then clean generated Node files:

rm -rf frontend/node frontend/node_modules

panel.js is missing

Build the frontend:

cd frontend
npm run build

Expected output:

dist/<extension-id>/panel.js

process.env remains in the bundle

Use defineFrplmExtensionPanelConfig instead of a custom Vite config, or add equivalent define replacements.

Publishing checklist

chmod +x bin/*.mjs
npm test
npm pack --dry-run
npm publish --access public

The packed package should include:

bin/create-frplm-extension.mjs
bin/extension-doctor.mjs
bin/verify-extension-panel.mjs
src/frplm-extension-vite.js
src/registerFrplmPanel.ts
package.json
README.md