# Apps

Source: https://docs.interop.io/desktop/developers/seed-project/apps/index.html

## Overview

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.

## Using Template Apps

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

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

| Template | Description |
|----------|-------------|
| `groups` | Web Group App for window grouping. |
| `launchpad` | Launchpad for starting apps. |
| `splash` | Splash screen displayed during platform startup. |
| `workspaces` | Workspaces App for managing Workspaces. |
| `tests` | Automated test package, included in new projects. |

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:

```cmd
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:

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

## Creating Custom Apps

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

```text
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:

```json
{
    "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:

| Property | Type | Description |
|----------|------|-------------|
| `"base"` | `object[]` | File modifications applied in both modes. |
| `"build"` | `object` | Script and file modifications used when building the app. |
| `"dev"` | `object` | Script and file modifications used during development. |

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

| Property | Type | Description |
|----------|------|-------------|
| `"modifications"` | `object[]` | Files or folders to copy into the project modifications. |
| `"script"` | `string` | Optional NPM script name from the app `package.json`. |

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.

## Managing Apps

To install app dependencies, execute:

```cmd
npx @interopio/iocd-cli@latest apps install
```

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

```cmd
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:

```cmd
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`.