npm package: @impartner/nx-angular
Description: Nx plugin for building Angular-based applications for Impartner.
Author: Impartner
Latest version: 3.0.1

# `@impartner/nx-angular`

This package is an [Nx](https://nx.dev/) plugin that offers a collection of [code generators](https://nx.dev/core-features/plugin-features/use-code-generators) and [task executors](https://nx.dev/core-features/plugin-features/use-task-executors) to help facilitate development of [Angular](https://angular.dev/)-based applications for Impartner, Inc. and its platforms. This plugin may be used to help create new [Nx](https://nx.dev/) monorepos and projects or be added to existing ones.

This plugin's code generators create and extend projects using the Impartner library packages listed below. For additional information, please consult their documentation.

- [`@impartner/angular-sdk`](https://www.npmjs.com/package/@impartner/angular-sdk/)
- [`@impartner/angular-apps`](https://www.npmjs.com/package/@impartner/angular-apps/)
- [`@impartner/design`](https://www.npmjs.com/package/@impartner/design/)
- [`@impartner/design-components`](https://www.npmjs.com/package/@impartner/design-components/)

## Dependencies

Each release of this plugin package targets a specific minimum version of Nx, and only guarantees support for the specified major version (ex. `21.x.x`) range. Please refer to the below table to see which versions are supported or targeted for a given release.

| @impartner/nx-angular | Nx      |
| --------------------- | ------- |
| 1.0.0                 | ~17.1.3 |
| 2.0.0                 | ^19.6.1 |
| 3.0.0                 | ^21.5.1 |

## Getting Started

- If working with an existing [Nx](https://nx.dev/) monorepo workspace:
  1. Install `@impartner/nx-angular` from npm.
  2. Run the `@impartner/nx-angular:install` generator to set up some recommended workspace defaults for building Impartner applications.
- If creating a new [Nx](https://nx.dev/) workspace from scratch:
  1. Invoke the `create-impartner-workspace` create package via `npx`, which will generate a new Nx workspace using the `@impartner/nx-angular:preset` preset generator:  
     `npx create-impartner-workspace`
     - If an alternative package manager would be used in the workspace, include the `--packageManager` argument followed by the name of the desired package manager (eg. `npm`, `yarn`, `pnpm`)
     - Alternatively to `create-impartner-workspace`, you may specify this package as a preset when using the main Nx workspace builder, `create-nx-workspace`:  
       `npx create-nx-workspace <workspace-name> --preset=@impartner/nx-angular`  
       If you encounter difficulties are errors with `create-impartner-workspace`, consider trying this alternative and see if the issue persists.
  2. Answer the prompts presented in the command line to finish initializing the workspace, including whether to create an initial Angular project and what kind.

## Updating

When working in an existing [Nx](https://nx.dev/) monorepo workspace, the plugin can be updated using the `nx migrate` command; updating the plugin in this way will also update all related Impartner packages and their dependencies in the workspace.

```
> nx migrate @impartner/nx-angular
```

## Generators

### `@impartner/nx-angular:install`

Installs core Impartner Angular SDK packages in the workspace, and optionally allows for configuration of default Prettier settings.

### `@impartner/nx-angular:preset`

Installs core Impartner Angular SDK packages in the workspace, sets recommended default Prettier formatter settings, and offers a guided experience for creating an initial Impartner MicroFrontEnd (MFE) or Widget application using the other generators in the plugin.

### `@impartner/nx-angular:impartner-mfe-app`

Creates a new Angular application in the workspace configured for build and deployment as an MFE on Impartner application hosts, including options for automatic configuration of `i18next`-based internationalization and custom application support for upload to Impartner's extensibility suite.

### `@impartner/nx-angular:impartner-widget-app`

Creates a new Angular application in the workspace configured for build and deployment of widget web components to Impartner application hosts, including options for automatic configuration of `i18next`-based internationalization and and custom application support for upload to Impartner's extensibility suite.

### `@impartner/nx-angular:add-widget`

Creates Angular components, interfaces, and constant definition values for a new Impartner widget in an existing project created with the `@impartner/nx-angular:impartner-widget-app` generator.

**Note:** Projects for **custom** Impartner widgets may only implement and expose one widget each.

## Executors

### `@impartner/nx-angular:build-package`

Does any additional processing (if required) of build artifacts for an Angular application or library project, and produces a new artifact ready for upload to package repositories or to Impartner's extensibility suite.

**Note:** This executor only officially supports Angular application builds using the Webpack-based builder process, with no tested or unofficial support for alternative build processes (eg. esbuild, rspack).