bolt-uxp

A lightning-fast boilerplate for building Adobe UXP Plugins in Svelte, React, or Vue built on Vite + TypeScript + Sass

• Lightning Fast Hot Reloading on changes
• Setup with TypeScript Definitions for UXP and Photoshop APIs
• Easily configure in uxp.config.ts
• Comes with multi-host-app configuration
• Optimized Build Size
• Template for UXP Hybrid C++ Plugins
• Easy Publish to CCX for Distribution
• Easy Package to ZIP archive with sidecar assets
• GitHub Actions ready-to-go for CCX Releases

Huge thanks to our backers who have made this project possible!

If you're interested in supporting this open-source project, please contact the Hyper Brew team.

If you have questions with getting started using Bolt UXP, feel free to ask and discuss in our free Discord community Discord Community.

If your team is interested in paid consulting or development with Bolt UXP, please contact the Hyper Brew team. More info on our Adobe Plugin Development & Consulting Services

Yes! Bolt UXP is 100% free and open source, being released under the MIT license with no attribution required. This means you are free to use it in your free or commercial projects.

We would greatly appreciate it if you could provide a link back to this tool's info page in your product's site or about page:

Bolt UXP Info Page Link: https://hyperbrew.co/resources/bolt-uxp

Built with Bolt UXP button graphics:

PNG Files

SVG Files

• Node.js 18 or later
• Adobe UXP Developer Tool (aka UDT)
• Package manager either
  • NPM (comes with Node.js)
  • Yarn ( ensure by running yarn set version classic )
  • PNPM ( ensure by running pnpm --version )

Create your new Bolt UXP project (follow CLI prompts)

• yarn - yarn create bolt-uxp
• npm - npx create-bolt-uxp
• pnpm - pnpm create-bolt-uxp

Change directory to the new project

• cd project

Install Dependencies (if not already done by create command)

• yarn - yarn
• npm - npm i
• pnpm - pnpm i

Build the plugin (must run before dev, can also run after for panel to work statically without the process)

• yarn yarn build
• npm npm run build
• pnpm pnpm build

Run the plugin in hot reload mode for development with UDT (see below)

• yarn yarn dev
• npm npm run dev
• pnpm pnpm dev

Build & Package the plugin as a CCX for delivery (separate CCX files for each host are generated due to current UXP requirements)

• yarn yarn ccx
• npm npm run ccx
• pnpm pnpm ccx

Bundles your packaged ccx file(s) and specified assets from copyZipAssets to a zip archive in the ./zip folder

• yarn yarn zip
• npm npm run zip
• pnpm pnpm zip

Install Note: The Adobe UXP Developer Tools (UDT) can be downloaded from the Adobe CC app

1. Open the Adobe UXP Developer Tool (2.0 or later)
2. Click the Add Plugin button in the top right corner
3. Select the manifest.json file in the dist folder

1. Click Load button on your plugin item
2. Click Debug button on your plugin item

Note: You only need to "Load" a plugin, do not use the "Load and Watch" feature. The bulit-in UDT file watcher aka "Load and Watch" does not reliably update on changes so we recommend avoiding it. Instead, Bolt UXP comes with it's own built-in WebSocket system to trigger a reload on each update which is more consistent and less error-prone.

You can install your UXP plugin from CCX file in a number of ways:

Download here: https://aescripts.com/learn/zxp-installer/ Simply drag and drop the CCX file onto the installer and follow the prompts.

As long as file associations are set up correctly, you can simply double click the CCX file to install it and you can follow the prompts in the Adobe CC app to complete the install

You can install via the command line directly with the UPIA tool.

Windows:

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

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

Mac:

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

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

The resulting directory can end up in any number of places depending on UPIA version and settings. This location is subject to change and managed by UPIA and the UXP database. In general do not modify or try to manipulate these locations or you will likely break the plugin.

Windows:

• C:\Program Files\Common Files\Adobe\UXP\Plugins\<username>\External\
• C:\Users\<username>\AppData\Roaming\Adobe\UXP\Plugins\External\

Mac:

• /Users/<username>/Library/Application Support/Adobe/UXP/Plugins

Special Note You cannot write UXP plugins directly into the directories above like you could with CEP panels. UXP plugins must be installed via either double-click or UPIA in order to correctly update a database file.

Currently the following Adobe apps support UXP plugins:

• Photoshop
• InDesign

If you have UXP Beta access to any of the other Adobe apps, you can add them as well, including:

• Premiere Pro (beta)
• Illustrator (beta)

Note: Bolt UXP will not work out of-the-box for apps in UXP beta, you will need beta access from Adobe app teams as they become available. Hyper Brew cannot assist you in this, you will need to contact Adobe app teams directly for access.

To add additional windows to a UXP Plugin, you'll need to do 2 things:

1. Add an additional panel in the uxp.config.ts (see the settings example commented out)
2. Add a <uxp-panel panelid="bolt.uxp.plugin.settings"> tag to your main entrypoint file (.tsx, .vue, or .svelte). Note that the panelid must match the panelid in the uxp.config.ts file.

Note: Unlike CEP Extensions which multi-panel extensions behave as separate isolated panels/websites, a multi-panel UXP plugin is all in 1 space with certain sections of the markup rendered in different panels (identified by the <uxp-panel /> tag)

UXP Hybrid Plugins allow you to write C++ functions and call them from UXP. This is useful for performance critical operations and accessing system methods not yet part of the UXP APIs.

If you enabled the Hybrid Plugin option during the yarn create bolt-uxp process, your project will come with already compiled binaries, and project files if you want to make your own customizations to the Hybrid Plugin.

Since Hybrid Plugins are application specific, you will need to compile the macOS binary with XCode on macOS and the Windows binary with Visual Studio 2019 on Windows. The hybrid plugin project files are located in ./src/hybrid, and they compile to ./public-hybrid, which ends up in ./dist/mac and ./dist/pc after build. The structure required is as follows:

root
 ├─ mac
 │   ├─ arm64
 |      └─ bolt-uxp-hybrid.uxpaddon
 |   └─ x64
 |      └─ bolt-uxp-hybrid.uxpaddon
 └─ win
     └─ x64
        └─ bolt-uxp-hybrid.uxpaddon

Supported platforms include:

• MacOS x64
• MacOS arm64
• Windows x64

(note that Windows arm64 for Hybrid Plugins is not currently supported by Adobe UXP applications)

The main exported function inside the current Hybrid Plugin is execSync() which works like Node.js's execSync() function. It takes a string and returns the output of the command. This is useful for running system commands and getting the output back to your UXP plugin, which is currently not possible via the UXP APIs.

The Xcode project is designed to build a universal binary from an arm64 (M1, M2, M3) machine that works for both arm machines and x64 machines. If you are not on an arm machine, you will need to change the copy build settings to only build for x64, and note that your hybrid plugin will not work on arm machines.

The project is set up for Visual Studio 2019. A post-build action will copy the resulting .uxpaddon binary to the ./public-hybrid folder. If you are using a different version of Visual Studio, you may need to update settings for this to work, but Adobe recommends 2019 currently.

You can easily rebuild a binary from the command line without opening XCode or Visual Studio with yarn mac-build and yarn win-build. You'll need to ensure msbuild for Windows and xcodebuild for MacOS are in your system's environment variables.

Alternatively, you can build debug builds with yarn win-build-debug in order to attach to the process and debug your C++ code with breakpoints, however make sure to build a release version for distribution, otherwise your users will experience a Failed to load Addon: The specified module could not be found error when your users without a dev environment try to load your plugin.

The current UXP Hybrid binaries (.uxpaddon files) come signed and notorized for MacOS and signed for Windows, however if you make modifications to the C++ source code and compile again, you will need to sign and notorize with your own certs for MacOS and Windows. Instructions for signing and notorizing are below:

MacOS requires your hybrid plugins to be signed and notorized when shipped to users.

Requirements:

• Apple Developer Account
• Developer ID Certificate
• Latest Xcode installed
• Xcode Command Line Tools installed

Once these are set up, duplicate the .env.example file to a .env file and fill out all fields with your Apple credentials.

Install your cert locally, and ensure your signing settings in XCode are set to that certificate for both arm64 and x64.

Ensure you are logged into your correct Apple account in XCode.

Finally run yarn-build-sign to both build your mac binary and sign it. This will also notorize the binary with Apple's servers which can take several minutes.

More details on how the signing and notorization process works can be found in the scripts/mac-sign.js file.

Windows does not require signing, however it's generally a good idea to avoid any warning popups or Windows silently blocking your plugin. A script is provided to sign your Windows binary with an EV cert hosted via Azure. Once you have a cert purchased and hosted with Azure, you'll need to fill out the .env file with your Azure credentials.

Once your cert hosting is set up and your .env file is filled out, you can run yarn win-sign to sign your Windows binary.

While Bolt UXP supports hot reloading, this does not extend to the C++ Hybrid plugin portion of the project. If you only make changes to the frontend code, hot reloading will work as expected, however if you make changes to the MacOS or Windows binaries, you will see a warning in the console that you need to unload and load the plugin since the binaries are locked during debug. You can do this in UDT by selecting "Unload", building the binary, then selecting "Load" again.

Currently there is no way to automate this process in UDT, but we have requested that the Adobe UXP team add this feature.

More info on Hybrid Plugins can be found here: https://developer.adobe.com/photoshop/uxp/2022/guides/hybrid-plugins/

Currently, hybrid plugins are only supported in Photoshop.

There are several flavors of Adobe Spectrum:

• Spectrum CSS
• React Spectrum
• Spectrum Web Components
• Spectrum UXP

Recently the Adobe UXP team is moving away from the built-in Spectrum UXP to Spectrum Web Components.

Since this move is recent, and compatibility is pending, Bolt UXP doesn't come set up for any Spectrum integration, however if you'd like you can add it yourself.

Spectrum UXP

You can use native Spectrum UXP widgets without any extra dependencies, however you will recieve TypeScript errors. To remove these errors you'll need to add defs for spectrum in your globals.d.ts file per your framework (React example below)

React Example for <sp-heading />

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

More info on Spectrum UXP: https://developer.adobe.com/xd/uxp/uxp/reference-spectrum/

Spectrum Web Components

For Spectrum Web Components, you'll need to add the dependency from npm and import the components into your project as needed. Follow the guide here:

https://www.npmjs.com/package/@spectrum-web-components/bundle

• Update a Bolt UXP Project To update an existing Bolt UXP project to the the latest version, create a new Bolt UXP project with the same framework (React, Vue, Svelte) and host apps, then compare and update the following files:
  1. package.json - Update all dependencies and scripts ( vite-uxp-plugin - usually contains the most frequent updates )
  2. vite.config.ts - Unless you've modified the vite config yourself, you can just copy the contents of the latest into yours.
  3. uxp.config.ts - Check if any new properties have been added that don't exist in your config.
  4. src/api - Update this entire folder.
  5. src/hybrid - Update this entire folder unless you've made modifications to the C++ code.

If you're interested in updating bolt-uxp core, please see the ./readme_dev.md