lucy-xp

Command line tool for building, managing, and configuring iviva UXP v5 widgets.

Installation

npm install -g lucy-xp

Commands

lucy-xp init <project>

Scaffold a new UXP v5 widget project.

lucy-xp init my-widget --env v5

Options:

• --env <env> — environment/version (use v5 for UXP v5 projects)

Creates a ready-to-build project with TypeScript, webpack, SCSS support, and CSS scoping pre-configured.

lucy-xp setup

Full project setup in one command. Runs all three setup steps below in sequence:

1. Install the uxp-lint VSCode extension
2. Configure uxp-lint for your app
3. Wire scoped CSS into your widget

cd /path/to/MyApp/5.0
lucy-xp setup

lucy-xp install-lint-vscode

Download and install the uxp-lint VSCode extension.

lucy-xp install-lint-vscode

Requires the code command to be available in your PATH (VSCode → Cmd+Shift+P → Shell Command: Install 'code' command in PATH).

lucy-xp setup-lint

Configure uxp-lint for an existing iviva v5 app. Prompts for the app folder and views folder paths, then:

• Runs uxp-lint setup interactively to create .uxplint/config.json
• Adds lint and prebuild scripts to views/package.json
• Adds @iviva/uxp-lint as a devDependency
• Creates an app-level .gitignore for generated lint output

lucy-xp setup-lint

lucy-xp setup-scoped-css

Install and configure @dinesh-gamage/react-scoped-css in an existing v5 widget project. Run from the widget's Resources/views folder (where webpack.config.js and bundle.json live).

cd /path/to/MyApp/5.0/Resources/views
lucy-xp setup-scoped-css

• Installs @dinesh-gamage/react-scoped-css, @babel/core, babel-loader, postcss-loader
• Patches webpack.config.js to hash CSS class names at build time (scoped per widget)
• Safe to re-run — prints "Already set up" if already configured

lucy-xp upload [dist.js] [bundle.json]

Upload a built widget bundle to a Lucy server.

lucy-xp upload --lucy-url https://myserver.com --lucy-apikey <key>

Options:

• --lucy-url <url> — server URL
• --lucy-apikey <apikey> — API key
• --lucy-env <envfile> — path to .lucyxp.config or .spaceworx.config file

lucy-xp upload-models [model-or-folder]

Upload model definition files to a Lucy server.

lucy-xp upload-models ./models --lucy-url https://myserver.com --lucy-apikey <key>

lucy-xp download-models [model-or-folder]

Download model definitions from a Lucy server into local JSON files.

lucy-xp download-models ./models --lucy-url https://myserver.com --lucy-apikey <key>
lucy-xp download-models --models MyModel,AnotherModel --lucy-url https://myserver.com --lucy-apikey <key>

Options:

• --models <names> — comma-separated model names to download

lucy-xp create-common-component <folder>

Scaffold a shared component template.

lucy-xp create-common-component my-component

CSS Scoping

New v5 projects created with lucy-xp init --env v5 have CSS scoping enabled out of the box. Class names are hashed at build time using the widget's bundle ID as a salt, so styles from different widgets never collide in a shared dashboard.

For existing projects, run lucy-xp setup-scoped-css to add scoping.

Linting

UXP v5 apps are validated with uxp-lint, which checks for:

• Inline styles (no-inline-styles)
• Incorrect icon format (no-fa-prefix)
• Form state in URL params (url-params-form-state)
• Missing React.memo (require-memo)
• Service config shape and defaults
• Bundle size, duplicate code, and more

Run lucy-xp setup-lint to configure it for your app, or lucy-xp install-lint-vscode to get inline hints in VSCode.