@c8y/apps/README.md

# @c8y/apps

The application package (`@c8y/apps`) provides example applications for the Web SDK.

## Getting started

To use the @c8y/apps you need to install the [@c8y/cli](https://www.npmjs.com/package/@c8y/cli). Refer to its documentation for installation instructions. 
Once installed you can run:

```
$ c8ycli new [your-app-name] [example-name]
```

For example, to generate the tutorial application with the name `my-app` you need to run:

```
$ c8ycli new my-app tutorial
```

The `c8ycli new` command can also be provided on its own without the `[name]` and `[template]` options. In this case a few steps will have to be completed via the interface before the app is scaffolded:

**Step 1:**
```
? Enter the name of the project: (my-application)
```

The first step will ask for the project name. If no project name is entered, the default value `my-application` will be used.

> **Info:** This step can also be skipped if the name is provided in the initial command: `c8ycli new my-application`.

**Step 2:**
```
? Which base version do you want to scaffold from? (Use arrow keys)
> 1010.0.X (latest)
> 1011.X.0 (next)
> 1011.0.X
> 1009.0.X
> 1007.0.X
> 1006.0.X
> other
```

In the second step, the base scaffolding version must be selected. The interface will provide the last GA release (latest), the latest available release (next) and four older GA releases. Additionally a version can be manually entered by selecting the `other` option.

**Step 2 (other):**
```
? Enter the desired version:
```

In this step, the desired version must be entered manually e.g. `1010.0.0`.

> **Info:** This question will appear only if `other` was selected in the previous step. 

**Step 3:**

```
? Which base project do you want to scaffold from?
  administration
  application
  cockpit
  devicemanagement
  hybrid
  tutorial
  widget-plugin
```

In the final step, the base project to scaffold from must be selected.

> **Info:** This step will only show projects which are available for the selected version in Step 2.

## Included applications

The following table provides an overview on the currently supported applications:

| Name | Description |
| ---- | --- |
|`application`| An empty application to quickly bootstrap new applications. It is the default application and used if you don't specify an `[example-name]`.|
|`hybrid`| Also an empty application but running in hybrid mode. That means it can import angularjs plugins and therefore can be used for migration purpose. |
|`tutorial`| An application that already assembles most of the concepts of the [@c8y/ngx-components](https://www.npmjs.com/package/@c8y/ngx-components). Use this to get real code examples. |
|`widget-plugin`| An Module Federation plugin that can be used to create your own custom widgets. |
|`cockpit`| The [Cockpit](http://www.cumulocity.com/guides/users-guide/cockpit/) default application. Use this to extend the existing Cockpit application. |
|`devicemanagement`| The [Devicemanagement](http://www.cumulocity.com/guides/users-guide/devicemanagement/) default application. Use this to extend the existing Device Management application. |
|`administration`| The [Administration](http://www.cumulocity.com/guides/users-guide/administration/) default application. Use this to extend the existing Administration application. |