berger-engineering-io · michaelbe812 · Apr 2, 2026
diff --git a/README.md b/README.md
@@ -1,62 +1,37 @@
 # Nx Plugin OpenAPI
 
-A powerful Nx plugin ecosystem for generating API client code from OpenAPI specifications. This monorepo provides a flexible, plugin-based architecture that supports multiple code generators.
+Generate API clients from OpenAPI specs in your Nx workspace. Pluggable architecture -- choose the generator that fits your stack.
 
 ## Packages
 
-| Package | Description | npm |
-|---------|-------------|-----|
-| [`@nx-plugin-openapi/core`](./packages/core/README.md) | Core plugin system with executor and generators | [![npm](https://img.shields.io/npm/v/@nx-plugin-openapi/core.svg)](https://www.npmjs.com/package/@nx-plugin-openapi/core) |
-| [`@nx-plugin-openapi/plugin-openapi`](./packages/plugin-openapi/README.md) | Plugin for [OpenAPI Generator](https://openapi-generator.tech) | [![npm](https://img.shields.io/npm/v/@nx-plugin-openapi/plugin-openapi.svg)](https://www.npmjs.com/package/@nx-plugin-openapi/plugin-openapi) |
-| [`@nx-plugin-openapi/plugin-hey-api`](./packages/plugin-hey-api/README.md) | Plugin for [hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) | [![npm](https://img.shields.io/npm/v/@nx-plugin-openapi/plugin-hey-api.svg)](https://www.npmjs.com/package/@nx-plugin-openapi/plugin-hey-api) |
-| [`@lambda-solutions/nx-plugin-openapi`](./packages/nx-plugin-openapi/README.md) | Legacy package (OpenAPI Generator only) | [![npm](https://img.shields.io/npm/v/@lambda-solutions/nx-plugin-openapi.svg)](https://www.npmjs.com/package/@lambda-solutions/nx-plugin-openapi) |
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                   @nx-plugin-openapi/core                    │
-│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
-│  │  generate-api   │  │  Plugin Loader  │  │ Auto Install │ │
-│  │   executor      │  │                 │  │              │ │
-│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
-└─────────────────────────────────────────────────────────────┘
-                              │
-          ┌───────────────────┴───────────────────┐
-          ▼                                       ▼
-┌────────────────────────┐           ┌────────────────────────┐
-│ @nx-plugin-openapi/    │           │ @nx-plugin-openapi/    │
-│   plugin-openapi       │           │   plugin-hey-api       │
-│                        │           │                        │
-│ Uses @openapitools/    │           │ Uses @hey-api/         │
-│ openapi-generator-cli  │           │ openapi-ts             │
-└────────────────────────┘           └────────────────────────┘
-```
+| Package | Description |
+|---------|-------------|
+| [`@nx-plugin-openapi/core`](./packages/core/README.md) | Core executor and plugin system |
+| [`@nx-plugin-openapi/plugin-openapi`](./packages/plugin-openapi/README.md) | [OpenAPI Generator](https://openapi-generator.tech) -- 50+ languages, Angular services |
+| [`@nx-plugin-openapi/plugin-hey-api`](./packages/plugin-hey-api/README.md) | [hey-api](https://heyapi.dev/) -- modern TypeScript, fetch/axios, tree-shakeable |
 
 ## Quick Start
 
-### Installation
+**1. Install core + a generator plugin**
 
 ```bash
-# Install the core package
 nx add @nx-plugin-openapi/core
 
-# Install a generator plugin (choose one or both)
-npm install --save-dev @nx-plugin-openapi/plugin-openapi  # For OpenAPI Generator
-npm install --save-dev @nx-plugin-openapi/plugin-hey-api  # For hey-api
+# Pick one (or both):
+npm install -D @nx-plugin-openapi/plugin-openapi @openapitools/openapi-generator-cli
+npm install -D @nx-plugin-openapi/plugin-hey-api @hey-api/openapi-ts
 ```
 
-### Basic Usage
-
-Execute the following command:
+**2. Add a target** (interactive)
 
 ```bash
 nx g @nx-plugin-openapi/core:add-generate-api-target
 ```
 
-This will add a `generate-api` target to your `project.json`:
+Or add it manually to `project.json`:
 
-```json
+```jsonc
+// OpenAPI Generator
 {
   "targets": {
     "generate-api": {
@@ -71,9 +46,8 @@ This will add a `generate-api` target to your `project.json`:
 }
 ```
 
-Or use the `hey-api` generator:
-
-```json
+```jsonc
+// hey-api
 {
   "targets": {
     "generate-api": {
@@ -88,48 +62,26 @@ Or use the `hey-api` generator:
 }
 ```
 
-### Run the generator
+**3. Generate**
 
 ```bash
 nx run my-app:generate-api
 ```
 
-## Documentation
-
-For comprehensive documentation, visit our [documentation site](https://nx-plugin-openapi.lambda-solutions.io/).
+## Why this plugin?
 
-- [Getting Started](https://berger-engineering-io.github.io/nx-plugin-openapi/getting-started/overview/)
-- [Installation Guide](https://berger-engineering-io.github.io/nx-plugin-openapi/getting-started/installation/)
-- [Plugins Overview](https://berger-engineering-io.github.io/nx-plugin-openapi/plugins/overview/)
-- [Configuration Reference](https://berger-engineering-io.github.io/nx-plugin-openapi/usage/configuration/)
-- [Creating Custom Plugins](https://berger-engineering-io.github.io/nx-plugin-openapi/guides/creating-plugins/)
-- [Examples](https://berger-engineering-io.github.io/nx-plugin-openapi/usage/examples/)
+- **Nx-native** -- caching, affected commands, dependency graph, Nx Cloud
+- **Pluggable** -- swap generators without changing your workflow
+- **Multiple specs** -- generate from several OpenAPI files in one target
+- **Auto-install** -- missing plugins are installed on first run
 
-## Features
-
-- **Plugin Architecture**: Choose between multiple code generators
-- **Auto-Installation**: Plugins are automatically installed when needed
-- **Nx Integration**: Full support for Nx caching, affected commands, and dependency graph
-- **Multiple Specs**: Generate code from multiple OpenAPI specifications in a single target
-- **Flexible Configuration**: Pass generator-specific options via `generatorOptions`
-
-## Available Generators
-
-### `openapi-tools` (via `@nx-plugin-openapi/plugin-openapi`)
-
-Uses the battle-tested [OpenAPI Generator](https://openapi-generator.tech) to generate TypeScript Angular clients and more.
-
-**Peer dependency**: `@openapitools/openapi-generator-cli`
-
-### `hey-api` (via `@nx-plugin-openapi/plugin-hey-api`)
-
-Uses [hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) for modern TypeScript client generation with excellent type safety.
+## Documentation
 
-**Peer dependency**: `@hey-api/openapi-ts`
+Full docs: [berger-engineering-io.github.io/nx-plugin-openapi](https://berger-engineering-io.github.io/nx-plugin-openapi/)
 
-## Contributing
+## Legacy package
 
-Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+The original `@lambda-solutions/nx-plugin-openapi` is still maintained for backward compatibility. See [migration guide](./packages/nx-plugin-openapi/README.md).
 
 ## License
 

diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
@@ -9,7 +9,7 @@ export default defineConfig({
     starlight({
       title: 'Nx Plugin OpenAPI',
       description:
-        'Nx Plugin for seamless integration of OpenAPI Generator Angular client',
+        'Generate type-safe API clients from OpenAPI specs in your Nx workspace',
       social: [
         {
           icon: 'github',
@@ -18,44 +18,31 @@ export default defineConfig({
         },
       ],
       sidebar: [
-        {
-          label: 'Getting Started',
-          items: [
-            { label: 'Overview', slug: 'getting-started/overview' },
-            { label: 'Installation', slug: 'getting-started/installation' },
-            { label: 'Quick Start', slug: 'getting-started/quick-start' },
-          ],
-        },
+        { label: 'Getting Started', slug: 'getting-started' },
         {
           label: 'Plugins',
           items: [
-            { label: 'Overview', slug: 'plugins/overview' },
             { label: 'OpenAPI Generator', slug: 'plugins/plugin-openapi' },
             { label: 'hey-api', slug: 'plugins/plugin-hey-api' },
           ],
         },
         {
-          label: 'Usage',
-          items: [
-            { label: 'Configuration', slug: 'usage/configuration' },
-            { label: 'Examples', slug: 'usage/examples' },
-            { label: 'Nx Integration', slug: 'usage/nx-integration' },
-          ],
-        },
-        {
-          label: 'API Reference',
+          label: 'Reference',
           items: [
-            { label: 'generate-api executor', slug: 'reference/generate-api' },
+            { label: 'Configuration', slug: 'reference/configuration' },
           ],
         },
         {
           label: 'Guides',
           items: [
-            { label: 'Creating Custom Plugins', slug: 'guides/creating-plugins' },
+            {
+              label: 'Creating Custom Plugins',
+              slug: 'guides/creating-plugins',
+            },
           ],
         },
         {
-          label: 'Legacy Nx Plugin',
+          label: 'Legacy Plugin',
           items: [
             { label: 'Overview', slug: 'legacy-nx-plugin/overview' },
           ],

diff --git a/apps/docs/src/content/docs/getting-started.md b/apps/docs/src/content/docs/getting-started.md
@@ -0,0 +1,116 @@
+---
+title: Getting Started
+description: Install and generate your first API client in under 5 minutes
+---
+
+## Install
+
+Requires an Nx workspace (v19+) and Node.js.
+
+```bash
+# Core package
+nx add @nx-plugin-openapi/core
+```
+
+Then pick a generator plugin:
+
+```bash
+# Option A: OpenAPI Generator -- 50+ languages, Angular injectable services, Java required
+npm install -D @nx-plugin-openapi/plugin-openapi @openapitools/openapi-generator-cli
+
+# Option B: hey-api -- modern TypeScript, fetch/axios, tree-shakeable, no Java
+npm install -D @nx-plugin-openapi/plugin-hey-api @hey-api/openapi-ts
+```
+
+:::tip[Auto-install]
+If you skip installing a plugin, the core package will attempt to install it automatically on first use.
+:::
+
+## Add a generate-api target
+
+The quickest way:
+
+```bash
+nx g @nx-plugin-openapi/core:add-generate-api-target
+```
+
+This walks you through the options and adds a `generate-api` target to your `project.json`.
+
+### Manual setup
+
+Add the target yourself:
+
+```json title="project.json"
+{
+  "targets": {
+    "generate-api": {
+      "executor": "@nx-plugin-openapi/core:generate-api",
+      "options": {
+        "generator": "hey-api",
+        "inputSpec": "apps/my-app/openapi.yaml",
+        "outputPath": "libs/api-client/src"
+      },
+      "outputs": ["{options.outputPath}"]
+    }
+  }
+}
+```
+
+Set `"generator"` to `"openapi-tools"` for OpenAPI Generator or `"hey-api"` for hey-api.
+
+## Generate
+
+```bash
+nx run my-app:generate-api
+```
+
+The executor cleans the output directory, runs the chosen generator, and produces the client code.
+
+## Recommended Nx setup
+
+Add these defaults to `nx.json` so caching and build dependencies work automatically:
+
+```json title="nx.json"
+{
+  "targetDefaults": {
+    "generate-api": {
+      "cache": true,
+      "inputs": [
+        "{projectRoot}/swagger.json",
+        "{projectRoot}/openapi.yaml",
+        "{projectRoot}/openapi-config.json"
+      ],
+      "outputs": ["{options.outputPath}"]
+    },
+    "build": {
+      "dependsOn": ["generate-api"]
+    }
+  }
+}
+```
+
+## Multiple specs
+
+For microservice architectures, pass an object instead of a string:
+
+```json
+{
+  "options": {
+    "generator": "hey-api",
+    "inputSpec": {
+      "users-api": "apis/users.yaml",
+      "products-api": "apis/products.yaml"
+    },
+    "outputPath": "libs/api-clients/src"
+  }
+}
+```
+
+Each key becomes a subdirectory under `outputPath`.
+
+## Next steps
+
+- [OpenAPI Generator plugin](/plugins/plugin-openapi/) -- all options for `openapi-tools`
+- [hey-api plugin](/plugins/plugin-hey-api/) -- all options for `hey-api`
+- [Configuration reference](/reference/configuration/) -- executor options
+- [Creating custom plugins](/guides/creating-plugins/) -- build your own generator