Seed Project

Build the seed project to produce installers and ZIP archives containing your components, configuration, apps, and assets. Packaging uses Electron Forge, configured in config/forge.config.js.

A normal build performs the following operations:

1. Reinstalls the components included in the build, unless --skip-install is set.
2. Builds the apps and copies their output to the modifications folders.
3. Applies base and build modifications, copies the license, and collects additional components.
4. Signs the platform binaries according to your code signing settings.
5. Creates the configured installer and archive artifacts. On Windows, the CLI also signs the final setup executable when signing is enabled.
6. Publishes the artifacts if publishers are configured.

ℹ️ For details on preparing distributions, see the Code Signing, Install & Uninstall Tasks, and Publishing & Auto Updates sections.

To build the platform, execute:

npm run build

The following commands demonstrate how to copy packages to a custom output directory or reuse installed components:

npm run build -- --output custom/path
npm run build-skip-install

⚠️ Note that --skip-install requires the configured components to be installed already. Use it only when you intend to build from those local components.

The --publish-only option skips component installation, app building, modifications, and the initial signing stage:

npm run build -- --publish-only

⚠️ Note that --publish-only packages the current contents of /components/iocd without preparing them again, and it also invokes Forge make before publishing. Running npm run dev or npm test after a build applies the development modifications to that folder and, on Windows, replaces the main executable with an unsigned copy. Use --publish-only only directly after a full build (e.g., to retry a failed publish). To upload existing artifacts without packaging again, use your hosting upload tools.

Packages are written under /dist/make. The --output option copies them to another directory relative to the project root. Additional components are included in <installation_location>/components. If the project includes only iocd, the package won't contain an empty /components folder.

The <installation_location> placeholder represents the folder containing the platform executable on Windows and the app bundle Contents folder on macOS.

Windows

The supplied makers produce a Squirrel.Windows setup executable and a portable ZIP archive. Squirrel also produces the packages and metadata used for updates.

To change the animation displayed by the installer, replace assets/install.gif in the seed project or change the loadingGif value of the Squirrel maker in config/forge.config.js.

The setup executable is named <exe_name>-v<version>-setup.exe, where <exe_name> is the executable name without the extension (by default, the product slug) and <version> is the product version. To hide the installer UI, pass the --silent argument to the setup executable:

io-connect-desktop-v1.0.0-setup.exe --silent

Squirrel installs the app in %LocalAppData%/<product_slug>/app-<version>, where <product_slug> is the configured product slug and <version> is the product version.

By default, user data is stored in %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

The following example demonstrates how to use separate product folders for user data and cache on Windows. Save it as /modifications/base/iocd/config/system.json.merge-win32:

{
    "folders": {
        "userData": "%LocalAppData%/${PRODUCT_SLUG}/UserData/%IO_CD_ENV%-%IO_CD_REGION%",
        "cache": {
            "location": "%LocalAppData%/${PRODUCT_SLUG}/Cache/%IO_CD_ENV%-%IO_CD_REGION%",
            "copy": true
        }
    }
}

macOS

The supplied makers produce a DMG disk image and a ZIP archive. The app bundle can be installed in /Applications or another chosen location.

By default, user data is stored in ~/Library/Application Support/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

ℹ️ For details on other output formats, see the Electron Forge makers documentation.

Installation Paths

The platform can run from a different installation location. When distributing a ZIP archive or moving an installation, account for the path limits of the target operating system and the nested paths in your package. Additional components and custom assets can increase the longest path. Check the complete extracted package at the intended location.

ℹ️ For details on Windows path limits, see the Microsoft documentation.

The generated /.github/workflows/build.yml workflow builds on Windows and macOS. Configure the required license, signing credentials, notarization credentials, and publisher credentials via GitHub Actions secrets.

Available since @interopio/iocd-cli 2.1.0

The generated workflow runs npm test before building on both operating systems. Its run_tests input defaults to true. Existing projects retain their own workflow files, so review older or customized workflows and add a test step after setup if it is missing.

ℹ️ For details on test runner requirements and failure output, see the Testing > CI/CD section.