Seed Project

Available since io.Connect Desktop 10.0

The io.Connect seed project provides the files and commands for configuring, customizing, testing, and packaging io.Connect Desktop. Use it to download platform components, apply your license and branding, customize system apps, and create installers or ZIP archives for distribution.

The @interopio/iocd-cli library provides the io.Connect CLI used to create and manage the project. Generated projects include NPM scripts for setup, development, testing, and building. You can also invoke the CLI via npx without installing it globally.

Keep your configuration, apps, and assets in the seed project so that you can apply them again when updating the platform components. The project also provides code signing, publishing, auto update settings, and a GitHub Actions workflow for building and testing on Windows and macOS.

Creating and testing a seed project requires:

• Node.js v22.13.0 or later.
• NPM v9 or later.
• Windows 10 or later, or macOS 11 or later.
• A valid license key for io.Connect Desktop.
• signtool.exe from the Windows SDK if you will sign Windows binaries.

As of @interopio/iocd-cli 2.0, packaging requires Electron Forge ^8.0.1. The @electron-forge/core package and installed @electron-forge/maker-*, @electron-forge/publisher-*, and @electron-forge/plugin-* packages must use compatible versions. New seed projects include the required dependencies.

ℹ️ For details on updating an existing project, see the CLI > Upgrading section.

1. Create a seed project:

npx @interopio/iocd-cli@latest create

2. Follow the prompts to specify a product name, select platform components and app templates, and provide a valid license key. Open the generated project folder in your terminal before executing the remaining commands.

3. Install the project dependencies:

npm install

4. Install the selected components and dependencies for the customizable apps:

npm run setup

5. If your project includes apps with development servers, start them in a separate terminal. This also copies their development app definitions to /modifications/dev, so start them before the platform:

npm run apps-dev

6. Start the platform with your development configuration:

npm run dev

7. Customize the configuration, modifications, and apps. Close the development platform, then run the generated tests:

npm test

8. Build the distribution for the operating system on which you are building:

npm run build

Configure code signing and publishing before distributing your build. The generated workflow can build on both Windows and macOS.

ℹ️ For details on output files and installation locations, see the Building for Production section.

The following example demonstrates the main folders and configuration files of a seed project:

.
├── .agents/                    # Guidance for compatible coding agents.
├── .github/
│   ├── actions/                # Actions used by the workflow (e.g., code signing setup).
│   └── workflows/              # GitHub Actions build and test workflow.
├── apps/                       # Customizable system apps and your own apps.
├── assets/
│   └── install.gif             # Animation displayed by the Windows installer.
├── components/                 # Downloaded platform components.
│   ├── iocd/                   # Required platform runtime.
│   └── <other-components>/     # Additional licensed components.
├── config/
│   ├── forge.config.js         # Packaging and publishing settings.
│   ├── iocd.cli.config.json    # CLI settings.
│   └── iocd.license.key        # Platform license key.
├── modifications/
│   ├── base/                   # Changes applied in development and builds.
│   ├── dev/                    # Additional changes for development.
│   └── build/                  # Additional changes for production builds.
├── tests/                      # Separate package for automated tests.
│   ├── wdio.config.ts
│   └── tests/                  # Specifications, helpers, and fixture apps.
├── LICENSE                     # Empty license file for your product.
└── package.json

The /components folder contains downloaded files. Store changes in /modifications or /apps so that reinstalling a component won't remove your customizations.