---
# System prepended metadata

title: PatchKit Launcher SDK Documentation

---

Welcome to PatchKit Launcher SDK Documentation!

We will explain here how you can create your own launcher with PatchKit Launcher SDK, customize it and deploy on PatchKit Panel.

## Requirements

To start working with SDK you need a few things installed on your development machine:
- NodeJS (we recommend [nvs](https://github.com/jasongin/nvs) and NodeJS v16.16.0)
- package manager of your choice (we recommend [yarn](https://classic.yarnpkg.com/lang/en/docs/install) although both npm and pnpm should work as well)
- an App Catalog on PatchKit Panel (you can create it [here](https://panel.patchkit.net/app_catalogs))

## Example project

To help you with bootstraping your launcher, we recommend to download the example project. Simply download the archive and unpackage the contents to a directory where you will be working on your launcher.

## Basic concepts

PatchKit Launcher SDK structures the project in two separate components:
- **Runtime** - application built on top of Electron framework that supplies the core functionality like installing and updating the apps as well as window managment, shortcuts creation, or deeplinks.
- **Theme** - user interface built with frontend technologies, allowing you to completely customize your launcher. You can think of it as front-end application with additional API exposed from launcher runtime.

Those two components are deployed individually to allow quick updates of the theme without a need for rebuilding the runtime. Deploying instructions are detailed in [this](#building-and-deployment) section.

## Runtime

The runtime consists of:
- package.json that depends on two SDK packages: `patchkit-generic-launcher2-dev-tools` and `patchkit-generic-launcher2-base-presets`.
- presets

### Presets

The concept of presets, allows you to have different variants of your launcher. The common use cases of having multiple presets are:
- to target multiple platforms (Windows, macOS or Linux)
- to separate development/internal and production versions of the launcher

Each preset is a JavaScript file placed in `src` directory, that exports the configuration object. Thanks to that, you can store shared configuration in separate JavaScript files and compose it with libraries like `deepmerge` (please take a look at the example project).

List configurable preset fields:
- `id` - *Example*: `patchkit-demo-launcher`. **Required**. **Please note that it cannot be changed once the launcher is deployed!**.
- `name` - *Example*: `PatchKit Demo Launcher`. **Required**. Used in places visible to user.
- `description` - *Example*: `PatchKit Demo Launcher`. **Required**. Most often it simply equals to the `name`, but you can use it to describe the specifics of your launcher.
- `companyId` - *Example*: `upsoft`. **Required**. **Please note that it cannot be changed once the launcher is deployed!**.
- `companyName` - *Example*: `Upsoft`. **Required**. Used in places visible to user.
- `iconFilePath` - *Example*: `require.resolve("./icons/windows.ico")`.
- `secret` - *Example*: `aabbccddeeffgghhiijjkkll11223344`. **Required**.
- `appsCatalogId` - *Example*: `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`. **Required**. You can find it in [the list of your App Catalogs on PatchKit Panel](https://panel.patchkit.net/app_catalogs).
- `isAppsBranchesNotDefaultRootDirAllowed` - *Default*: `false`. Whether to allow installing apps in any directory (not only the default ones).
- `window`
  - `defaultSize` - *Default*: `{ width: 1024, height: 768 }`.
  - `defaultMinSize` - *Default*: `{ width: 1024, height: 768 }`.
  - `defaultMaxSize` - *Default*: `{ width: 1024, height: 768 }`.
  - `defaultIsResizable` - *Default*: `false`.
  - `isBorderless` - *Default*: `false`.
  - `isTransparent` - *Default*: `false`.
  - `areCornersRounded` - *Default*: `true`.
- `protocol` - *Default*: `undefined`. *Example*: `{ "id": "patchkit-demo-launcher" }`. Allows you to configure deeplinks functionality for your launcher so it can be opened from web links like `patchkit-demo-launcher://action`.

### `patchkit-generic-launcher2-dev-tools` 

This package provides the scripts required to start the launcher in development mode as well as to build it:
- `run-patchkit-generic-dev-launcher2`:
  - **required** `-p or --presetFileName`
  - **required** `-t or --overrideThemeUrl`
- `build-patchkit-generic-prod-launcher2`:
  - **required** `-p or --presetFileName`
  - **required** `-v or --version`
  - *optional* `--appleId`
  - *optional* `--appleIdPassword`

You can use those scripts:
- directly with `yarn`, for example `yarn run-patchkit-generic-dev-launcher2`
- directly with `npx`, for example `npx run-patchkit-generic-dev-launcher2`
- by aliasing them in `scripts` field of package.json (please take a look at the example project)

### `patchkit-generic-launcher2-base-presets`

This package provides the presets with default values, commonly used across launchers built with SDK.

## Theme

As stated above, theme is simply an user interface application built with web technologies, just like front-end. Please take a look at the example project to learn how to utilize API exposed from the launcher runtime to create the launcher user interface.

### Possible routing issues

To make your launcher theme compatible with deployment option on PatchKit Panel, you need to adjust the routing method in your application. Since the theme is going to be deployed in the subdirectory, you can't assume the absolute path to your application at a build time. Due to that we recommend using solutions like `HashRouter` from `react-router` to avoid any issues after the deployment.

## Theme Development

To start developing your launcher theme, you need to run both components (preferrably in development mode).

First, start the theme (the method could be different in various frameworks) so it's served on your localhost.

In example project you can do this with:
```sh
cd theme
yarn
yarn start
```

As soon as your theme is started, you can start the launcher.

In example project you can do this with:
```sh
cd runtime
yarn
# Windows
yarn run-dev -p windows-preset.js -t http://localhost:3000
# macOS
yarn run-dev -p macos-preset.js -t http://localhost:3000
```

And now you should be able to work on your launcher theme (in case of example project, you are able to see live changes as it's levearing CRA hot reload funcionality).

## Building and Deployment

### Runtime

Before you proceed, make sure that you've created a new Electron App on PatchKit Panel and filled the secret in particular preset file.

You can build your launcher runtime with `build-patchkit-generic-prod-launcher2` script. 

In example project you can do this with:
```sh
cd runtime
yarn
# Windows
yarn build-prod -p windows-preset.js -v 1.0.0
# macOS
yarn build-prod -p macos-preset.js -v 1.0.0
```

**Please remember to increment the version number everytime you deploy a new launcher runtime**. The versioning is based on semver, and is used to determine theme compatibility (majors must match, the theme target version minor must be less or equal to your launcher version).

After building is done, you need to upload the launcher runtime on PatchKit Panel (**version label must match the launcher version**):
- in case of Windows, upload the zip that contains the setup executable
- in case of macOS, upload the zip that contains both `.dmg` and `.zip` files

### Theme

Before you proceed, make sure that you've created a new Launcher Theme on PatchKit Panel and assigned it to your launcher.

Building your launcher theme with approperiate command from the framework you're using.

In example project you can do this with:
```sh
cd theme
yarn
yarn build
```

Once your launcher theme is built, collect the resulting files in a zip (in example project they're located in `theme/build` directory) and upload them in a new launcher theme version. **Remember to specify correct target version, most often the version of latest runtime deployed, so the new version doesn't break launchers that are yet to be updated.**.
