# Unisphere Workspace NX Plugin

Official Nx plugin for Unisphere workspace development. This plugin provides generators and executors for creating and managing Unisphere runtimes, visuals, applications, and packages.

## Features

- Create and manage Unisphere runtimes
- Add visuals to existing runtimes
- Generate development applications
- Create shared packages
- Documentation site generation
- Package management utilities

## Installation

This plugin is typically installed as part of a Unisphere workspace. If you need to install it manually:

```bash
npm install @unisphere/nx --save-dev
```

## Generators

All generators are non-interactive and require explicit flags. Run any generator without flags to see available options and examples.

### add-runtime

Creates a new Unisphere runtime package.

**Required flags:**
- `--name`: The name of the runtime to create
- `--consumer`: Runtime consumer type (`external` or `internal`)

**Optional flags:**
- `--dependencies`: Packages to install (comma-separated: `react`, `ds`, `mui`)

**Example:**
```bash
nx g @unisphere/nx:add-runtime \
  --name=my-runtime \
  --consumer=external \
  --dependencies=react,ds
```

### add-visual

Adds a visual component to an existing runtime.

**Required flags:**
- `--runtimeName`: The name of the runtime to add the visual to
- `--visualName`: The name of the visual to create

**Optional flags:**
- `--isSingleOccurrence`: Whether this visual is limited to single occurrence (default: `false`)

**Example:**
```bash
nx g @unisphere/nx:add-visual \
  --runtimeName=my-runtime \
  --visualName=my-visual
```

### add-application

Creates a development application for testing runtimes.

**Required flags:**
- `--name`: The name of the application to create
- `--servingType`: How the app should be served
  - `local-dev-playground`: Local development playground (default)
  - `self-hosted`: Self-hosted application
  - `iframe-with-post-messages`: iframe with post messages
  - `assets-only`: Assets only

**Optional flags:**
- `--runtimeName`: Which runtime should the playground load
- `--htmlPageTitle`: The HTML page title for your app
- `--dependencies`: Packages to install (comma-separated: `ds`, `mui`, `react-hook-form`)

**Example:**
```bash
nx g @unisphere/nx:add-application \
  --name=my-dev-app \
  --servingType=local-dev-playground \
  --runtimeName=my-runtime
```

### add-package

Creates a new shared package in the workspace.

**Required flags:**
- `--name`: The name of the package to create
- `--type`: Package type
  - `library`: Shared library
  - `types`: TypeScript types package
  - `configuration`: Configuration package

**Optional flags:**
- `--dependencies`: Packages to install (comma-separated: `react`, `ds`, `mui`)

**Example:**
```bash
nx g @unisphere/nx:add-package \
  --name=shared-utils \
  --type=library \
  --dependencies=react
```

### add-documentation

Generates a documentation site for your workspace.

**Required flags:**
- `--title`: The title for the documentation site

**Example:**
```bash
nx g @unisphere/nx:add-documentation \
  --title="My Project Documentation"
```

### remove

Removes a package from the workspace and cleans up all references.

**Required flags:**
- `--name`: The name of the package to remove

**Example:**
```bash
nx g @unisphere/nx:remove --name=my-package
```

### rename-package

Renames an existing package and updates all references.

**Required flags:**
- `--currentName`: Current package name
- `--newName`: New package name

**Example:**
```bash
nx g @unisphere/nx:rename-package \
  --currentName=old-name \
  --newName=new-name
```

### change-package-scope

Changes the scope of a package (e.g., from `@company` to `@newcompany`).

**Required flags:**
- `--name`: Package name to update
- `--newScope`: New scope (without `@` prefix)

**Example:**
```bash
nx g @unisphere/nx:change-package-scope \
  --name=my-package \
  --newScope=newcompany
```

## Getting Help

Forgot what flags are required? Just run any generator without flags and you'll get a helpful error message with examples:

```bash
$ nx g @unisphere/nx:add-runtime

Error: Missing required option: 'name'
  Description: The name of the runtime to create
  Example: nx g @unisphere/nx:add-runtime --name=my-runtime --consumer=external
```

## Migration from Interactive Generators

If you're upgrading from an older version that had interactive prompts, see the [Migration Guide](../../docs/migration/non-interactive-generators.md) for details on the changes and how to update your workflows.

## Development

### Testing Generators

Run all generator tests:
```bash
npm test -- packages/nx/src/generators/
```

### Building the Plugin

```bash
nx build @unisphere/nx
```

## License

See the root [LICENSE](../../LICENSE) file for details.
