Bolt UXP

Bolt UXP is composed of three primary packages that work together to facilitate UXP plugin development:

• bolt-uxp: The core package and template source used by the CLI tool.
• create-bolt-uxp: A CLI tool used to scaffold new projects based on the bolt-uxp templates.
• vite-uxp-plugin: A Vite plugin that provides the necessary build features and environment for developing UXP plugins.

The Webview UI option allows you to build your user interface using full CSS/HTML/JS DOM support (Edge on Windows, Safari on MacOS).

Important Requirements:

• The Webview UI option must be enabled during the create bolt-uxp project setup.
• Enabling this creates two separate contexts:
  • UI Context: Located in webview-ui/*
  • UXP Backend Context: Located in src/*

Communication Rules:

• Because the contexts are separate, you can only return primitive types (strings, numbers, booleans, arrays, static objects) across the bridge. Returning object instances or references will fail.
• All exported functions in your uxp and app files are automatically exposed to the Webview.

Debugging:

• UXP Context: Use Adobe UXP Developer Tools.
• Webview UI Context: Use webview devtools (Right-click > "Inspect" on the UI).

You can build a UXP panel where the entire UI is contained within a Webview. This approach creates two separate contexts:

1. Webview Frontend: Uses standard CSS/HTML/JS features available in the host OS browser (Edge on Windows, Safari on MacOS).
2. UXP Backend: The standard UXP environment.

Requirements:

• Requires a separate build system for the frontend.
• If you are not hosting the backend with a Hybrid Plugin, you must build the frontend to a single HTML file.

Bolt UXP does not come with a pre-configured Spectrum integration, but you can add it manually.

Spectrum UXP (Native Widgets)

You can use native Spectrum UXP widgets directly. To avoid TypeScript errors when using custom elements, add declarations to your globals.d.ts file.

Example for React:

declare global {
  namespace JSX {
    interface IntrinsicElements {
      "sp-heading": React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement>,
        HTMLElement
      >;
    }
  }
}

Spectrum Web Components

To use Spectrum Web Components, install the package from npm and import the components as needed: npm install @spectrum-web-components/bundle

When using Webview mode with multiple panels:

1. Follow the standard multi-window setup in uxp.config.ts and add <uxp-panel /> elements.
2. Ensure webviewInitHost({ multi: true }) is enabled in your UXP code.
3. Accessing specific panel APIs: Deconstruct the webviewAPIs array in the order the panels are listed in uxp.config.ts.
4. Conditional Rendering: In your Webview UI code, use the page variable from initWebview() to determine which panel is currently rendering (e.g., 'main' or 'settings').

// Accessing specific APIs in UXP
const [mainWebviewAPI, settingsWebviewAPI] = webviewAPIs;
mainWebviewAPI.doThisFunction();
settingsWebviewAPI.doThatFunction();

// Conditional rendering in Webview UI
import { initWebview } from "./webview-setup";
const { api, page } = initWebview(webviewAPI);
// page will be e.g. 'main' | 'settings'

Bolt UXP is designed to work with the Adobe UXP Developer Tool (UDT).

1. Setup UDT

• Ensure Developer Mode is enabled in your host app (e.g., Photoshop) via Preferences > Plugins > Enable Developer Mode.
• Open UDT (version 2.0 or later).
• Click Add Plugin and select the manifest.json file located in your project's dist folder.

2. Load and Debug

• Do not use the 'Load and Watch' feature in UDT. Bolt UXP uses its own built-in WebSocket system for more reliable hot reloading.
• Click the Load button on your plugin item in UDT.
• Click the Debug button to open the Dev Tools.

3. Troubleshooting

If you switch debuggers (e.g., from UDT to VS Code), you must unload the plugin from UDT and re-run your build command before starting the new debugger.

If your project uses a bundler like Bolt UXP, Vite, Webpack, or esbuild, install the package via npm.

If you are starting a project from scratch (not using Bolt UXP), you must also manually install the required Adobe UXP type packages to ensure proper type checking and autocomplete.

Note: If you encounter installation issues with yarn due to the @adobe/premierepro engine constraints, use yarn install --ignore-engines. npm handles this automatically.

# For projects with a bundler
npm install bolt-uxp-utils

# For projects starting from scratch
npm install --save-dev @adobe/cc-ext-uxp-types @adobe/premierepro @types/photoshop

If you are contributing to the core templates of Bolt UXP, follow these steps to set up your local development environment:

1. Clone the repository.
2. Install dependencies using yarn:

   yarn

3. Start the development server:
   ```bash
yarn dev

To test support for different frameworks (React, Vue, Svelte), modify index.html by enabling the corresponding <script /> tag and disabling the others.