### Usage Example for UXP Configuration

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/types.md

Example of how to import and use the UXP configuration in your project setup. This demonstrates the typical integration pattern for UXP plugins.

```typescript
import { config } from "./uxp.config";
export default defineConfig({
  plugins: [uxp(config, process.env.MODE)],
});
```

--------------------------------

### Run create-bolt-uxp CLI

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Execute the create-bolt-uxp CLI to start a new project. Can be run directly from the local dist or globally after installation.

```bash
node create-bolt-uxp/dist/index.js
```

```bash
npm install -g create-bolt-uxp
create-bolt-uxp
```

--------------------------------

### Install UXP Plugin via Command Line (Windows)

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Use the Unified Plugin Installer Agent (UPIA) to install a UXP plugin from the command line on Windows. Ensure you navigate to the correct directory before running the command.

```bash
cd "C:\Program Files\Common Files\Adobe\Adobe Desktop Common\RemoteComponents\UPI\UnifiedPluginInstallerAgent"

UnifiedPluginInstallerAgent.exe /install /path/to/plugin.ccx
```

--------------------------------

### Install Webview Dependencies

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

If webview support is enabled, navigate to the webview-ui directory and install its dependencies. Remember to return to the root directory afterward.

```bash
cd webview-ui
npm install
cd ..
```

--------------------------------

### Install Webview UI Dependencies

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Navigate to the webview-ui directory and install its specific dependencies. Ensure you return to the project root afterwards.

```bash
cd webview-ui && yarn && cd ..
```

```bash
cd webview-ui && npm i && cd ..
```

```bash
cd webview-ui && pnpm i && cd ..
```

--------------------------------

### Setup bolt-uxp-utils for non-bundler projects

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/bolt-uxp-utils/README.md

Run the setup command to copy CommonJS files into your plugin directory. This makes the utilities accessible via relative paths.

```sh
npx bolt-uxp-utils setup
```

--------------------------------

### Installing Webview Modules

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Troubleshoot 'WEBVIEW MODULES NOT INSTALLED!' errors by navigating to the webview-ui directory, installing dependencies with npm, and then running the development server.

```bash
cd webview-ui
npm install
cd ..
npm run dev
```

--------------------------------

### Install Plugin Command

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/configuration.md

Uses UPIA to install all CCX files in `ccx/` to the specified host application(s).

```bash
yarn ccx-install
# BOLT_ACTION=ccx-install vite
```

--------------------------------

### Install create-bolt-uxp CLI

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Install the create-bolt-uxp CLI using npm, yarn, or pnpm. This command initializes a new bolt-uxp project.

```bash
npm init bolt-uxp
# or
yarn create bolt-uxp
# or
pnpm create bolt-uxp
```

--------------------------------

### Install UXP Plugin via Command Line (macOS)

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Use the Unified Plugin Installer Agent (UPIA) to install a UXP plugin from the command line on macOS. Ensure you navigate to the correct directory before running the command.

```bash
cd "/Library/Application Support/Adobe/Adobe Desktop Common/RemoteComponents/UPI/UnifiedPluginInstallerAgent/UnifiedPluginInstallerAgent.app/Contents/MacOS"

./UnifiedPluginInstallerAgent --install /path/to/plugin.ccx
```

--------------------------------

### Install bolt-uxp-utils with npm

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/bolt-uxp-utils/README.md

Install the library using npm. If your project uses Bolt UXP, UXP type packages are pre-included. Otherwise, install them separately.

```sh
npm install bolt-uxp-utils
```

```sh
npm install --save-dev @adobe/cc-ext-uxp-types @adobe/premierepro @types/photoshop
```

--------------------------------

### Start Development Server

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Execute the dev command to start the development server, which includes a file watcher and enables hot reload for rapid development.

```bash
npm run dev
```

--------------------------------

### Run Development Build

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Starts the development server with hot reloading and file watching.

```bash
npm run dev
# MODE=dev vite build --watch
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Navigate to your plugin directory and install project dependencies using npm, yarn, or pnpm. This is a required step after the CLI completes.

```bash
cd my-plugin
npm install
```

```bash
yarn install
```

```bash
pnpm install
```

--------------------------------

### Build Pipeline: Pre-build Setup (buildStart)

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/vite-config-deep-dive.md

Initializes the hot reload server, copies hybrid binaries in dev mode, and builds/copies the webview UI.

```typescript
buildStart() {
  // Initialize hot reload server in dev
  uxpSetup(config, mode);
  
  // Copy changed hybrid binaries in dev
  if (mode === "dev" && config.manifest.addon) {
    copyHybridBinaries(config, true);  // onlyChanged: true
  }
  
  // Build and copy webview in all modes
  if (config.webviewUi) {
    validateWebviewModules();
    buildWebviewUI(mode);
    copyWebviewOutput(mode);
  }
}
```

--------------------------------

### Develop bolt-uxp-utils

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/bolt-uxp-utils/README.md

Install dependencies and build the project. This is for contributors to the library.

```sh
npm install
npm run build
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Install project dependencies using your preferred package manager. This step may be automatically handled by the create command.

```bash
yarn
```

```bash
npm i
```

```bash
pnpm i
```

--------------------------------

### Host-Specific Files (Photoshop Example)

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Defines files that are included based on the selected host application. This example shows the configuration for Photoshop, including its specific API entry point.

```typescript
// Photoshop
{ value: "phxs", label: "Photoshop", files: ["src/api/photoshop.ts"] }
```

--------------------------------

### Install All Possible CCX Files

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Installs all CCX files found in the CCX folder. Ensure `yarn ccx` (or equivalent) has been run prior to using this command.

```bash
yarn ccx-install
```

```bash
npm run ccx-install
```

```bash
pnpm ccx-install
```

--------------------------------

### Webview Development Server Command

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Starts the development server for the webview UI on a specified port. This command should be run from within the `webview-ui` directory.

```bash
cd webview-ui && vite --port 8082
```

--------------------------------

### UXP Context Entry Point Structure

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Illustrates the structure of the entry point for the UXP context, including the HTML file and the main script that imports framework setup, mounts the app, and establishes the UXP API context.

```plaintext
index.html
    	├── <script src="src/index-[framework].ts/tsx"></script>
    	│   ├── Imports framework setup
    	│   ├── Mounts app to #root element
    	│   └── Establishes UXP API context
    	│
    	└── <div id="root"></div>
        	└── UI rendered by framework component src/main.[jsx|vue|svelte]
```

--------------------------------

### Framework-Specific Files (Svelte Example)

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Defines files that are included based on the chosen framework. This example shows the configuration for Svelte, including its entry points, package configurations, and tsconfig files.

```typescript
// Svelte
{
  value: "svelte",
  label: "Svelte",
  files: [
    "src/index-svelte.ts",
    "src/main.svelte",
    "package.svelte.jsonc",
    "tsconfig.svelte.json",
    "webview-ui/src/index-webview-svelte.ts",
    "webview-ui/src/main-webview.svelte",
    "webview-ui/package.svelte.jsonc",
    "webview-ui/tsconfig.svelte.json",
  ],
}
```

--------------------------------

### Install Dependencies Manually

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

If the package manager is not detected, manually install dependencies using npm, yarn, or pnpm.

```bash
npm install    # or yarn/pnpm
```

--------------------------------

### Webview Context Entry Setup

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/vite-config-deep-dive.md

Configuration for a separate Vite server when `webviewUi` is enabled, defining the structure and entry points for the webview UI.

```plaintext
webview-ui/
  ├─ vite.config.ts
  ├─ src/
  │  ├─ main-webview.tsx / .vue / .svelte  (entry)
  │  ├─ index-webview-*.tsx/.ts            (setup code)
  │  └─ webview-api.ts                     (API exposed to UXP)
  └─ index.html
```

--------------------------------

### Install bolt-uxp-utils for non-bundler projects

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/bolt-uxp-utils/README.md

Install the package via npm. This step is required for both bundler and non-bundler workflows.

```sh
npm install bolt-uxp-utils
```

--------------------------------

### Example .env File Configuration

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/configuration.md

Configure runtime settings for hybrid plugins using a .env file at the project root. This includes Apple ID, Team ID, password, signing identity, and Azure certificate details.

```dotenv
APPLE_ID=developer@apple.com
APPLE_TEAM_ID=ABCD12345
APPLE_PASSWORD=abcd-efgh-ijkl-mnop
APPLE_SIGNING_IDENTITY="Developer ID Application: Company Name (ABCD12345)"
```

--------------------------------

### Development Build Command

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/configuration.md

Starts a file watcher with hot reload enabled for development. The WebSocket server listens on `hotReloadPort`.

```bash
yarn dev
# MODE=dev vite build --watch
```

--------------------------------

### Development Mode Build

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Starts the development server in watch mode. This process involves Vite and a UXP plugin to enable hot reloading, polyfill injection, and efficient development builds.

```bash
npm run dev
    ↓ (MODE=dev vite build --watch)
```

--------------------------------

### bolt-uxp-utils Premiere Pro Utilities

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Example imports for Premiere Pro-specific utility functions provided by the bolt-uxp-utils package.

```typescript
// Premiere Pro utilities
import { forEachVideoTrack, cloneSequence, getItemById } from "bolt-uxp-utils/ppro";
```

--------------------------------

### bolt-uxp-utils Photoshop Utilities

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Example imports for Photoshop-specific utility functions provided by the bolt-uxp-utils package.

```typescript
// Photoshop utilities
import { asModal, bpModal, deselectAllLayers } from "bolt-uxp-utils/ps";
```

--------------------------------

### Create a New Bolt UXP Plugin

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Use this command to scaffold a new UXP plugin project. Follow the prompts to configure your project's name, framework, and target Adobe hosts. After creation, install dependencies and build/develop the plugin.

```bash
npm create bolt-uxp
# Answer prompts:
# - Folder: ./my-plugin
# - Display Name: My Plugin
# - Framework: react (or svelte, vue)
# - Hosts: Photoshop, InDesign
# - Webview: no
# - Hybrid: no

cd my-plugin
npm install
npm run build
npm run dev
```

--------------------------------

### Development and Build Commands for Bolt UXP

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/INDEX.md

Use these npm scripts for development, production builds, packaging, and installation of your UXP plugin.

```bash
npm run dev      # Development with hot reload
npm run build    # Production build
npm run ccx      # Package for distribution
npm run zip      # Create distribution archive
npm run ccx-install    # Install plugin to Adobe app
npm run ccx-uninstall  # Uninstall plugin
```

--------------------------------

### runAction

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-vite-plugin.md

Executes CLI actions like CCX install/uninstall via UPIA (Unified Plugin Installer Agent). It takes a configuration object and an action string.

```APIDOC
## runAction

### Description
Executes CLI actions like CCX install/uninstall via UPIA (Unified Plugin Installer Agent).

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **config** (UXP_Config) - Required - Configuration object containing manifest
- **action** (string) - Required - Action to run: `"ccx-install"`, `"ccx-uninstall"`, or `"dependencyCheck"`

### Actions
- `"ccx-install"` — Installs all CCX files in the `ccx/` directory using UPIA
- `"ccx-uninstall"` — Uninstalls all plugins matching the manifest name
- `"dependencyCheck"` — Validates project dependencies

### Returns
void (process exits after execution)

### Example
```typescript
runAction(config, "ccx-install");
// Installs all .ccx files found in ./ccx/
```

### Error Handling
If UPIA is not installed at the expected system path, the action logs an error and exits:
```
UPIA does not exist at "...". Ensure UPIA is correctly installed.
```
```

--------------------------------

### Import Core UXP and Utility Functions

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/types.md

Imports core UXP functionalities and setup utilities from 'vite-uxp-plugin'. Use these for general UXP integration and action execution.

```typescript
import { uxp, uxpSetup, runAction } from "vite-uxp-plugin";
import type { UXP_Config, UXP_Manifest, UXP_Config_Extra } from "vite-uxp-plugin";
```

--------------------------------

### Use Premiere Pro Utilities for Sequence Manipulation

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Import and utilize utility functions from `bolt-uxp-utils/ppro` to interact with Premiere Pro sequences. This example demonstrates iterating through video tracks.

```typescript
import {
  forEachVideoTrack,
  cloneSequence,
  getItemById,
} from "bolt-uxp-utils/ppro";

const project = await premierepro.Project.getActiveProject();
await forEachVideoTrack(sequence, async (track, index) => {
  console.log(`Track ${index}:`, track.name);
});
```

--------------------------------

### Create Plugin Zip Archive

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Execute the `npm run zip` command to create a zip archive of your plugin, typically used for distribution alongside CCX files or as an alternative installation method.

```bash
npm run zip
```

--------------------------------

### Get Descendant Item by ID

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Recursively searches the project structure starting from a given parent to find a descendant item by its unique ID.

```typescript
export const getDescendantById = async (
  id: string,
  parent: ProjectItem | FolderItem | Project,
): Promise<ProjectItem | undefined>
```

--------------------------------

### UXP Backend Project Structure

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Defines the directory structure for the UXP backend, highlighting key files like entry points, API modules, and setup scripts. Functions exported from `src/api/*.ts` are accessible to the webview via Comlink.

```tree
src/
├── index-react.tsx            # React entry (imports React)
├── main.tsx                   # React UI component
├── main.svelte / main.vue    # Vue/Svelte alternatives
├── api/
│   ├── uxp.ts                # Exported to webview
│   ├── photoshop.ts          # App-specific APIs
│   └── errors.ts             # Error handling
├── webview-setup-host.ts     # Initialize webview connection
└── globals.ts                # Global type defs
```

--------------------------------

### Opt-out of Unique IDs for UXP Plugins

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

In `uxp.config.ts`, set `uniqueIds: false` to maintain your existing UXP plugin ID across builds. This prevents duplicate installs for users who started using your plugin before version 1.2.5.

```javascript
uniqueIds: false
```

--------------------------------

### Build the Plugin

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Build the plugin. This command must be run before `dev` and can also be used for static panel functionality.

```bash
yarn build
```

```bash
npm run build
```

```bash
pnpm build
```

--------------------------------

### Start Hot Reload WebSocket Server

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-vite-plugin.md

Starts a WebSocket server to broadcast file change signals. It uses Node.js http and ws libraries. The server manages client connections and persists in memory.

```typescript
export const hotReloadServer = (hotReloadPort: number) => void
```

```typescript
hotReloadServer(8080);
// WebSocket server starts on ws://localhost:8080
```

--------------------------------

### Initialize Webview Host in UXP

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Initializes the connection to one or more webviews from the UXP context. Use `multi: true` for multiple panels.

```typescript
// src/webview-setup-host.ts
import { wrap } from 'comlink';

// Initialize connection to webview(s)
const webviewAPIs = await webviewInitHost({ multi: true });

// For single panel
const [mainWebviewAPI] = webviewAPIs;

// For multi-panel
const [mainWebviewAPI, settingsWebviewAPI] = webviewAPIs;

// Call webview functions with type safety
await mainWebviewAPI.pingWebview();
```

--------------------------------

### Build and Sign macOS Binary

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Run this command to build your Mac binary and sign it. This process also includes notarization with Apple's servers, which may take several minutes.

```bash
yarn-build-sign
```

--------------------------------

### getActiveRoot

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Gets the root bin of the currently active project. This function does not require any parameters.

```APIDOC
## getActiveRoot

### Description
Gets the root bin of the currently active project.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method Signature
```typescript
export const getActiveRoot = async (): Promise<FolderItem | undefined>
```

### Parameters
None

### Returns
Promise resolving to active project's root FolderItem or undefined

### Example
```typescript
const root = await getActiveRoot();
if (root) {
  const items = await root.getItems();
}
```
```

--------------------------------

### Production Build Command

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/configuration.md

Creates an optimized build for testing or local deployment.

```bash
yarn build
# MODE=build vite build
```

--------------------------------

### Uninstall UXP Plugins

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Uninstalls all installed UXP plugins that match the specified manifest name.

```bash
yarn ccx-uninstall
```

```bash
npm run ccx-uninstall
```

```bash
pnpm ccx-uninstall
```

--------------------------------

### hotReloadServer

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-vite-plugin.md

Starts a WebSocket server that listens for file changes and broadcasts reload signals to connected clients.

```APIDOC
## hotReloadServer

### Description
Starts a WebSocket server that listens for file changes and broadcasts reload signals to connected clients.

### Method Signature
```typescript
export const hotReloadServer = (hotReloadPort: number) => void
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **hotReloadPort** (number) - Required - Port number for WebSocket server (typically 8080)

### Returns
- void

### Details
- Uses Node.js `http` module and `ws` (WebSocket) library
- Listens for client connections and adds them to a Set
- Removes clients on disconnect
- Server persists in memory; calling multiple times is safe (returns early)

### Example
```typescript
hotReloadServer(8080);
// WebSocket server starts on ws://localhost:8080
```
```

--------------------------------

### getItemByNameChain

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Finds an item by traversing a chain of names down the project tree, starting from a specified parent or the active project.

```APIDOC
## getItemByNameChain

### Description
Finds an item by traversing a chain of bin names down the project tree.

### Parameters
#### Path Parameters
- **names** (string[]) - Required - Array of names from root to target
- **parent** (ProjectItem | FolderItem | Project) - Optional - Root scope (defaults to active project)

### Returns
Promise resolving to item at end of chain or undefined

### Example
```typescript
const item = await getItemByNameChain(["Assets", "Graphics", "logo.png"]);
// Finds: Assets bin → Graphics bin → logo.png file

await getItemByNameChain(["Sequences", "main"], project);
// Searches from specific project root
```
```

--------------------------------

### Enable Webview UI during Project Creation

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Use this command to create a new bolt-uxp project with Webview UI enabled. You will be prompted to confirm.

```bash
npm create bolt-uxp
# When prompted: "Enable Webview UI?" → Answer "y"
```

--------------------------------

### Get Child Item by ID

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Finds a direct child item within a parent container using its unique ID.

```typescript
export const getChildById = async (
  id: string,
  parent: ProjectItem | FolderItem | Project,
): Promise<ProjectItem | undefined>
```

--------------------------------

### Webview Production Build Command

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Builds the webview UI for production. This command should be executed from within the `webview-ui` directory.

```bash
cd webview-ui && vite build
```

--------------------------------

### Securely Managing Environment Variables

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Demonstrates the recommended practice for secret management by copying a .env.example template to .env, editing it with sensitive values, and ensuring the .env file is added to .gitignore to prevent committing secrets.

```bash
cp .env.example .env
# Edit .env with your values
# .env added to .gitignore

```

--------------------------------

### Get Active Project Root

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Retrieves the root FolderItem of the currently active project. Returns undefined if no project is active.

```typescript
export const getActiveRoot = async (): Promise<FolderItem | undefined>
```

```typescript
const root = await getActiveRoot();
if (root) {
  const items = await root.getItems();
}
```

--------------------------------

### Initialize Webview Context

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Sets up the webview context to communicate with the UXP host. The `page` variable indicates the specific panel if multiple are used.

```typescript
// webview-ui/src/main-webview.tsx
import { initWebview } from "./webview-setup";

const { api, page } = initWebview(webviewAPI);
// page = "main" | "settings" (if multi-panel)
```

--------------------------------

### UPIA Not Found Error Message

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-vite-plugin.md

This message is logged when UPIA is not installed at the expected system path, indicating an error during action execution.

```text
UPIA does not exist at "...". Ensure UPIA is correctly installed.
```

--------------------------------

### Create Bolt UXP Plugin CLI

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Demonstrates how to invoke the create-bolt-uxp CLI tool using different package managers to scaffold a new UXP plugin project.

```bash
npm create bolt-uxp
yarn create bolt-uxp
pnpm create bolt-uxp
```

--------------------------------

### Build and Package CCX Files

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Use npm scripts to generate distribution-ready .ccx files for each host application and package them into a zip archive. This process ensures unique plugin IDs and manifests per host.

```bash
npm run ccx  # Generates ccx/*.ccx files

npm run zip  # Packages ccx files + assets into zip archive
```

--------------------------------

### Create Bolt UXP Project

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Initiates the creation of a new UXP project using npm. This command prompts for project details and scaffolds the necessary files based on the selected template and configurations.

```bash
npm create bolt-uxp
```

--------------------------------

### UXP Build Watch Command

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Builds the UXP application and watches for changes, outputting the build to the `dist/` directory.

```bash
vite build --watch
```

--------------------------------

### resolveToFolderItem

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Safely casts an item to a FolderItem if it's a bin, or gets the project root if a Project is passed. This is useful for ensuring you have a FolderItem to work with.

```APIDOC
## resolveToFolderItem

### Description
Safely casts an item to a FolderItem if it's a bin, or gets project root if passed a Project.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method Signature
```typescript
export const resolveToFolderItem = async (
  item: ProjectItem | FolderItem | Project,
): Promise<FolderItem | undefined>
```

### Parameters
- **item** (ProjectItem | FolderItem | Project) - Required - Item to resolve

### Returns
Promise resolving to FolderItem or undefined if not a bin

### Example
```typescript
const folder = await resolveToFolderItem(item);
if (folder) {
  const children = await folder.getItems();
}
```
```

--------------------------------

### Non-Serializable Data Structure Example

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Illustrates data structures that cannot be serialized due to class instances or functions. These will result in a 'Failed to serialize arguments' error.

```typescript
export async function process(data: MyClass): Promise<MyClass> {
  // ❌ Class instances don't serialize
}
```

```typescript
export async function getCallback(): Promise<() => void> {
  // ❌ Functions can't cross postMessage bridge
}
```

--------------------------------

### Build Commands

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/INDEX.md

Command-line interface commands for building, packaging, and managing UXP plugins.

```APIDOC
## Build Commands

### Description
Command-line interface commands for building, packaging, and managing UXP plugins.

### Commands
- `npm run dev`: Starts the development server with hot reloading.
- `npm run build`: Creates a production build of the plugin.
- `npm run ccx`: Packages the plugin into the CCX distribution format.
- `npm run zip`: Creates a distribution archive of the plugin.
- `npm run ccx-install`: Installs the plugin to an Adobe application using CCX format.
- `npm run ccx-uninstall`: Uninstalls the plugin from an Adobe application.
```

--------------------------------

### Enable Webview UI

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/configuration.md

Enable a separate Webview UI context. This requires a separate dev server and build pipeline for `webview-ui/`. This setting must be configured at project creation.

```typescript
webviewUi: true, // Enable webview
```

--------------------------------

### Build Plugin Once

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Run the build command to compile your plugin. This step is necessary for hot reload functionality to work correctly.

```bash
npm run build
```

--------------------------------

### Set Environment Variables for CLI

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Configure the CLI non-interactively by setting environment variables before executing the script. This allows for automated setup of plugin properties.

```bash
BOLT_FOLDER=./my-plugin \
BOLT_DISPLAYNAME="My Plugin" \
BOLT_FRAMEWORK=react \
BOLT_APPS=phxs,ppro \
BOLT_WEBVIEW=false \
BOLT_HYBRID=false \
node create-bolt-uxp/dist/index.js
```

--------------------------------

### uxpSetup

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-vite-plugin.md

Initializes the hot reload WebSocket server in dev mode. It takes a configuration object and an optional mode string.

```APIDOC
## uxpSetup

### Description
Initializes the hot reload WebSocket server in dev mode.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **config** (UXP_Config) - Required - Configuration object with hotReloadPort
- **mode** (string) - Optional - Build mode to check if dev

### Returns
void

### Example
```typescript
uxpSetup(config, "dev");
// Starts WebSocket server on port 8080
```
```

--------------------------------

### Find Item by Media Path

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Recursively searches for a clip item using the absolute media file path. Requires a parent container to start the search from.

```typescript
export const findItemByPath = async (
  parent: ProjectItem | FolderItem,
  path: string,
): Promise<ClipProjectItem | undefined>
```

```typescript
const clip = await findItemByPath(project, "/media/video.mp4");
```

--------------------------------

### Webview Frontend to UXP Communication

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Demonstrates how the Webview context (frontend) communicates with the UXP context (backend). It initializes the webview and allows calling UXP functions.

```typescript
// webview-ui/src/webview-setup.ts (Webview context)
import { initWebview } from "./webview-setup";

const { api, page } = initWebview(webviewAPI);
// page = "main" | "settings" (if multi-panel)

// Call UXP functions
await api.getProjectInfo();
await api.getUXPInfo();
```

--------------------------------

### Serializable Data Structure Example

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Defines a data structure that can be serialized and passed across the postMessage bridge. Ensure all properties are primitives, arrays, or plain objects.

```typescript
export async function process(data: {
  name: string;
  items: string[];
  count: number;
}): Promise<{ success: boolean; message: string }> {
  // ...
}
```

--------------------------------

### Run Production Build

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Creates a single production build without watching or hot reloading.

```bash
npm run build
# MODE=build vite build
```

--------------------------------

### Get Item by Name Chain

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Finds an item by traversing a sequence of bin names down the project hierarchy. The parent scope can be specified or defaults to the active project.

```typescript
export const getItemByNameChain = async (
  names: string[],
  parent?: ProjectItem | FolderItem | Project,
): Promise<ProjectItem | undefined>
```

```typescript
const item = await getItemByNameChain(["Assets", "Graphics", "logo.png"]);
// Finds: Assets bin → Graphics bin → logo.png file

await getItemByNameChain(["Sequences", "main"], project);
// Searches from specific project root
```

--------------------------------

### Build and Package Plugin for Delivery

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Build and package the plugin as a CCX file for delivery. Separate CCX files are generated for each host due to current UXP requirements.

```bash
yarn ccx
```

```bash
npm run ccx
```

```bash
pnpm ccx
```

--------------------------------

### Get Item by ID with Root Resolution

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

A convenience function to find an item by its ID. It automatically resolves the root scope if no parent is provided, defaulting to the active project.

```typescript
export const getItemById = async (
  id: string,
  parent?: ProjectItem | FolderItem | Project,
): Promise<ProjectItem | undefined>
```

```typescript
await getItemById("abc123");
// Searches active project

await getItemById("abc123", someBin);
// Searches inside that bin

await getItemById("abc123", someClip);
// Searches clip's project root
```

--------------------------------

### Execute CLI Actions with runAction

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-vite-plugin.md

The `runAction` function executes CLI actions such as CCX installation or uninstallation via UPIA. It requires a configuration object and the specific action string.

```typescript
export const runAction = (config: UXP_Config, action: string) => void
```

```typescript
runAction(config, "ccx-install");
// Installs all .ccx files found in ./ccx/
```

--------------------------------

### Package for Distribution (CCX)

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Generates .ccx files for each host application, suitable for packaging.

```bash
npm run ccx
# MODE=package vite build
```

--------------------------------

### Initialize Webview with Multi Flag

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

When initializing the host webview, set the 'multi' flag to true to enable multi-panel support and receive an array of APIs.

```typescript
// src/webview-setup-host.ts
const webviewAPIs = await webviewInitHost({ multi: true });
const [mainAPI, settingsAPI] = webviewAPIs;
```

--------------------------------

### Get Child Item by Name

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Finds a direct child item within a parent container by its name. Supports optional case and space insensitivity, and filtering by item type.

```typescript
export const getChildByName = async (
  name: string,
  parent: ProjectItem | FolderItem | Project,
  caseInsensitive?: boolean,
  spaceInsensitive?: boolean,
  projectItemType?: "CLIP" | "BIN" | "COMPOUND" | "FILE" | "STYLE",
): Promise<ProjectItem | undefined>
```

```typescript
const clip = await getChildByName("intro.mp4", project, true);
// Matches "Intro.MP4" with case insensitivity

const bin = await getChildByName("assets", project, false, false, "BIN");
// Finds bin named exactly "assets"
```

--------------------------------

### Signing and Notarizing macOS and Windows Binaries

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Provides commands for building, signing, and notarizing macOS binaries using 'yarn mac-build-sign', and signing Windows binaries with an EV certificate using 'yarn win-sign'.

```bash
yarn mac-build-sign  # Builds, signs, and notarizes for macOS

```

```bash
yarn win-sign        # Signs Windows binary with EV certificate

```

--------------------------------

### Target Additional Adobe Apps in UXP Config

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/README.md

Modify the `host` array in `uxp.config.ts` to specify which Adobe applications and minimum versions your plugin should support. This example adds support for Illustrator.

```typescript
host: [
  { app: "PS", minVersion: "24.2.0" },
  { app: "ID", minVersion: "18.5" },
  { app: "premierepro", minVersion: "22.3" },
  { app: "AI", minVersion: "18.5" },  // Add Illustrator
]
```

--------------------------------

### Call Webview Function from UXP

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/webview-system.md

Demonstrates calling a function defined in the webview from the UXP host context. Ensure the webview API is properly initialized.

```typescript
// UXP context: src/components/Main.tsx
import { wrap } from 'comlink';

async function processData() {
  const result = await mainWebviewAPI.processData({
    name: "John",
    age: 30,
  });
  console.log("Result from webview:", result);
}
```

--------------------------------

### Enable Unique Plugin IDs

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/configuration.md

When true, appends the host app code to the plugin ID to prevent conflicts when installing for multiple applications. Set to false to use a single ID for all hosts.

```typescript
uniqueIds: true, // Generate unique IDs per host
```

--------------------------------

### Resolve or Get Project Root

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/api-reference-bolt-uxp-utils.md

Normalizes an optional item parameter for search functions, falling back to the active project's root if no item is provided. Handles Project, FolderItem, and ProjectItem inputs.

```typescript
export const resolveOrGetRoot = async (
  item?: ProjectItem | FolderItem | Project,
): Promise<FolderItem | undefined>
```

--------------------------------

### Call Webview Functions from UXP

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Shows how to call functions defined in the webview context from the UXP context. The 'webviewInitHost' function is used to initialize communication, and only primitive types should be returned.

```javascript
webviewAPIs = await webviewInitHost({ multi: true });
[mainWebviewAPI] = webviewAPIs;

await mainWebviewAPI.pingWebview();
```

--------------------------------

### Create Distribution Archive

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Bundles the project into a zip archive for final distribution. This includes generating CCX packages and combining them with other assets into a single zip file.

```bash
npm run zip
    ↓ (MODE=zip vite build)
```

--------------------------------

### UXP Plugin Vite Transformer Hooks

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/project-architecture.md

Illustrates the modular lifecycle hooks available in a Vite plugin for transforming and managing the build process. These hooks allow for pre-build setup, HTML transformation, code manipulation, bundle finalization, and post-build actions.

```typescript
// Modular lifecycle hooks
plugin.buildStart()     // Pre-build setup
plugin.transformIndexHtml()  // HTML transformation
plugin.renderChunk()    // Code transformation
plugin.generateBundle() // Bundle finalization
plugin.closeBundle()    // Post-build actions
```

--------------------------------

### Project Folder Prompt

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Specifies the directory where project files will be generated. This prompt accepts relative or absolute paths.

```text
Where do you want to create your project?
Initial Value: ./
Required: Yes
```

--------------------------------

### Framework Selection Prompt

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/_autodocs/create-bolt-uxp-cli.md

Determines the UI framework for the project, affecting entry point files, tsconfig, build dependencies, and component syntax.

```text
Pick a Framework
● Svelte
○ React
○ Vue
```

--------------------------------

### Build Hybrid Plugin for macOS Debug

Source: https://github.com/hyperbrew/bolt-uxp/blob/master/README.md

Scripts to build, sign, and package the hybrid plugin for macOS debugging. Ensure Apple Signing Credentials are configured in the .env file.

```bash
yarn mac-build-debug
```

```bash
yarn mac-sign
```

```bash
yarn build
```