Seed Project

Use the /apps folder to customize system apps or include your own apps in the platform distribution. The CLI installs dependencies, runs development or build scripts, and copies app configuration and assets into the project modifications.

The CLI provides templates for customizing the Workspaces App, the Web Group App, the splash screen, and the Launchpad. You can also add your own apps.

Select templates during project creation, or list the available templates and add one later:

npx @interopio/iocd-cli@latest apps list
npx @interopio/iocd-cli@latest apps add workspaces

Customize the generated app in its folder under /apps. The test template uses the separate test directory configured for the project.

Updating a Template

Available since @interopio/iocd-cli 1.1.0

To replace an app with the template supplied by the CLI, use the apps update command:

npx @interopio/iocd-cli@latest apps update workspaces

⚠️ Note that updating a template deletes its existing app folder and replaces it with the template. This removes all customizations and other files in that folder. Commit or back up the files you want to retain before updating.

The CLI asks for confirmation before replacing the folder. For an intentional update without interaction, use --yes after saving your changes:

npx @interopio/iocd-cli@latest apps update workspaces --yes

Create a folder under /apps and add an iocd.app.json file describing how to prepare the app:

apps/
└── my-custom-app/
    ├── config/
    │   └── my-app-dev.json
    ├── iocd.app.json
    ├── package.json
    └── src/

The following example demonstrates how to run a development server and copy its app definition in development mode, then build and copy static assets for production:

{
    "dev": {
        "script": "start",
        "modifications": [
            {
                "source": "/config/my-app-dev.json",
                "destination": "/modifications/dev/iocd/config/apps/my-app.json"
            }
        ]
    },
    "build": {
        "script": "build",
        "modifications": [
            {
                "source": "/dist/",
                "destination": "/modifications/build/iocd/assets/my-app"
            }
        ]
    }
}

The development app definition must point to the development server. Add a production app definition pointing to the packaged assets under /modifications/build/iocd/config/apps.

The iocd.app.json file has the following properties:

The "dev" and "build" objects have the following properties:

Each modification has a "source" path in the app and a "destination" path in the seed project. The leading / in these configuration values identifies the corresponding app or project root.

To install app dependencies, execute:

npx @interopio/iocd-cli@latest apps install

To start app development scripts, execute the following in a separate terminal from the platform:

npm run apps-dev

This command is the only one that copies the "dev" modifications of the apps, such as app definitions pointing to the development servers. Start it before npm run dev so that the platform loads these definitions. The copied files remain in /modifications/dev, so later npm run dev and npm test runs also load the apps from the development servers, which must be running.

To build the apps and copy their output to the modifications folder, execute:

npx @interopio/iocd-cli@latest apps build

The platform build also builds the apps before applying modifications. Install their dependencies first with npm run setup or apps install.