feat(nx-plugin): add NX Plugin with OpenAPI client generator and executor by seriouslag · Pull Request #1947 · hey-api/hey-api

seriouslag · 2025-04-14T01:10:08Z

Update June 2026
I am keeping this up to date at seriouslag/openapi-ts-nx-plugin and plan to do so for the foreseeable future.
Any feature requests or notes post there.

This NX plugin will generate an NX package from an OpenAPI spec file and run the openapi-ts on the spec.

This is useful for NX projects.
Also very useful to let AI agents know how to use the plugin to automate setting up client code for an NX project.

TODO:

Stretch in this PR:

Find or build an OpenAPI diff package that supports OpenAPI 2 through 3.1. We are using api-smart-diff. There haven't been many updates, and there's no Swagger 2 support. We are getting around this by upgrading the Swagger files to OpenAPI v3 files before diffing.
Support different test frameworks (missing jest)
Generate linting support (eslint, etc)

Questions:
Q: How to handle updates to the OpenAPI spec file?
A: We have added an executor and a call to each generated project. Each project can run the executor to update the spec file and regenerate the client code.

Q: How do we list the plugin in the NX plugin repository
A: https://nx.dev/extending-nx/recipes/publish-plugin#list-your-nx-plugin

Fixes: #1910

Related PRs:

bolt-new-by-stackblitz · 2025-04-14T01:10:11Z

Run & review this pull request in StackBlitz Codeflow.

vercel · 2025-04-14T01:10:13Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
hey-api-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 31, 2025 5:46am

changeset-bot · 2025-04-14T01:13:45Z

⚠️ No Changeset found

Latest commit: 13a3c9c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

codecov · 2025-04-14T01:26:08Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 22.53%. Comparing base (b9dc166) to head (13a3c9c).
⚠️ Report is 2989 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1947   +/-   ##
=======================================
  Coverage   22.53%   22.53%           
=======================================
  Files         324      324           
  Lines       31840    31840           
  Branches     1232     1232           
=======================================
  Hits         7174     7174           
  Misses      24657    24657           
  Partials        9        9

Flag	Coverage Δ
unittests	`22.53% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pkg-pr-new · 2025-04-14T01:37:06Z

Open in StackBlitz

@hey-api/client-axios

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-axios@1947

@hey-api/client-fetch

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-fetch@1947

@hey-api/client-next

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-next@1947

@hey-api/client-nuxt

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/client-nuxt@1947

@hey-api/nuxt

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/nuxt@1947

@hey-api/nx-plugin

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/nx-plugin@1947

@hey-api/openapi-ts

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/openapi-ts@1947

@hey-api/vite-plugin

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/vite-plugin@1947

commit: cbd9614

seriouslag · 2025-04-14T22:42:49Z

@@ -0,0 +1,11 @@
+{


Added this file to cache builds

seriouslag · 2025-04-14T22:43:18Z

 function App() {
  const onClick = async () => {
-    postFoo({
+    addPet({


Changed this file to use actual generated code, I was getting type errors how it was

Sample is meant to be a playground for local development and testing. I thought I ignored it in ESLint?

Maybe was an issue with my IDE, why not use actual code instead of adding broken imports and ignoring it with comments?

I don't remember, I was probably testing something and didn't clean it up. It's similar to the sample snapshot script except it contains a whole app with UI. The idea is to be able to test drive the output since snapshots are never actually executed. Obviously should be way more polished!

seriouslag · 2025-04-14T22:43:33Z

@@ -1,7 +1,32 @@
 // This file is auto-generated by @hey-api/openapi-ts


Ran the code gen

seriouslag · 2025-04-14T22:44:19Z

  "scripts": {
    "build": "tsup"
  },
+  "exports": {


Was facing issues with our new configs, adding the exports and adding cjs fixed the issues,

seriouslag · 2025-04-14T22:44:44Z

+        "default": "./dist/index.cjs"
+      }
+    },
+    "./setup": "./src/setup.ts"


Exporting the setup file as a direct source file for other vitests to use as a setup file.

seriouslag · 2025-04-14T22:45:22Z

@@ -0,0 +1,5 @@
+// FAIL LOUDLY on unhandled promise rejections / errors


Adding this file because vitest fails if an error is uncaught, but no trace is given to the logs. This change adds the trace. This will help future debugging.

seriouslag · 2025-04-14T22:45:45Z

        },
      },
      root,
+      setupFiles: ['@config/vite-base/setup'],


Adding our new vitest setup file with the new export path

seriouslag · 2025-04-14T22:46:16Z

  "tasks": {
    "build": {
-      "cache": false,
+      "cache": true,


Enabled caching for quicker local dev

+    });
+    if (existsSync(v2SpecPath)) {
+      logger.debug(`Spec file already exists: ${v2SpecPath}`);
+      await writeFile(v2SpecPath, v2Spec);


…d type error

…e module path

- fix typo in vitest.config output - change vitest.config to mts for better type support - list vite and vitest as a dep if enabled - change vitest to single fork runner - change build to only output cjs to support nx plugins - add caching and nx linking if spec file is in another project

- Replace direct mkdir calls with makeDir utility for consistent directory creation. - Update plugin handling in client generation to support additional plugins. - Modify tests and schemas to reflect changes in plugin structure and options. - Improve error handling and logging in updateApi executor. - Add formatting functionality for generated files and update README for clarity.

- Replace the existing openapi-diff dependency with api-smart-diff for improved comparison accuracy. - Add comprehensive test cases to validate spec comparison logic across various scenarios.

…verrides in package.json files to support node 18

… management - Introduce `baseTsConfigName` and `baseTsConfigPath` options in the OpenAPI client generator and update executor schemas. - Enhance README documentation to reflect new options and their usage. - Implement `getBaseTsConfigPath` utility to resolve tsconfig paths based on provided options. - Update tests to cover new tsconfig path handling logic.

- Introduce functions to standardize OpenAPI and Swagger specs, including version detection and conversion. - Implement `removeExamples` function to clean up specs before comparison, ensuring accurate diff results. - Add comprehensive tests for new functionality, covering various scenarios for OpenAPI 3.1 and Swagger 2.0 specs. - Update existing comparison logic to utilize standardized specs for improved accuracy.

…tests

… for directory creation

…flags

…t for generated files

seriouslag · 2025-12-29T20:18:22Z

Not dead, been using this for quite a few months, need to update with latest openapi-ts.

I have an idea to infer these tasks from an openapi.config.* file in the NX project (this is how other executors work like vitest, rspack, vite, webpack, eslint, etc.)

This will improve the DX and config.

mrlubos · 2025-12-29T20:25:48Z

@seriouslag would you be interested in publishing this plugin as a part of ecosystem? We could feature it in the docs as such, so there'd be no pressure to merge it into main, and people who are interested could use it. I think we'd just need to figure out how to test it so people know which version it's compatible with

jinder · 2026-01-16T23:36:19Z

This is exactly the plugin I've been looking for. Would love to see the inferred task support as it would make setting this up and maintaining it on a monorepo super easy.

seriouslag · 2026-01-19T22:28:20Z

This is exactly the plugin I've been looking for. Would love to see the inferred task support as it would make setting this up and maintaining it on a monorepo super easy.

Hey @jinder i will look at releasing this in the coming weeks

jinder · 2026-01-20T22:06:05Z

@seriouslag I've actually been playing with the plugin from your repository with inferred tasks and it works really well! My only suggestion (and change I made) was to remove the npx calls to prevent it downloading the npm packages for openapi-ts rather than using the pre-installed one.

seriouslag · 2026-01-20T23:28:02Z

@jinder feel free to open a PR and we can start tracking issues on that repo.

vercel Bot deployed to Preview April 14, 2025 01:11 View deployment

github-advanced-security AI found potential problems Apr 14, 2025

View reviewed changes

Comment thread packages/nx-plugin/src/executors/update-api/index.ts Fixed

seriouslag force-pushed the feat/add-nx-plugin-2 branch from 37ec549 to d84ba4c Compare April 14, 2025 01:13

vercel Bot deployed to Preview April 14, 2025 01:14 View deployment

seriouslag force-pushed the feat/add-nx-plugin-2 branch from d84ba4c to fb901bc Compare April 14, 2025 01:20

vercel Bot deployed to Preview April 14, 2025 01:21 View deployment

seriouslag force-pushed the feat/add-nx-plugin-2 branch from fb901bc to 438dac9 Compare April 14, 2025 01:21

seriouslag changed the title ~~feat(nx-plugin): add nx plugin to generate and update client code~~ feat(nx-plugin): add NX Plugin with OpenAPI client generator and executor Apr 14, 2025

vercel Bot deployed to Preview April 14, 2025 01:22 View deployment

vercel Bot deployed to Preview April 14, 2025 01:29 View deployment

vercel Bot deployed to Preview April 14, 2025 01:34 View deployment

vercel Bot deployed to Preview April 14, 2025 21:07 View deployment

seriouslag force-pushed the feat/add-nx-plugin-2 branch from 0a60e87 to d4711ce Compare April 14, 2025 21:11

vercel Bot deployed to Preview April 14, 2025 21:12 View deployment

vercel Bot deployed to Preview April 14, 2025 21:35 View deployment

seriouslag force-pushed the feat/add-nx-plugin-2 branch from acb3de8 to c889844 Compare April 14, 2025 21:35

vercel Bot deployed to Preview April 14, 2025 21:36 View deployment

vercel Bot deployed to Preview April 14, 2025 21:52 View deployment

vercel Bot deployed to Preview April 14, 2025 22:26 View deployment

vercel Bot deployed to Preview April 14, 2025 22:36 View deployment

seriouslag commented Apr 14, 2025

View reviewed changes

vercel Bot deployed to Preview April 17, 2025 00:18 View deployment

github-advanced-security AI found potential problems Apr 17, 2025

View reviewed changes

vercel Bot deployed to Preview April 17, 2025 00:39 View deployment

seriouslag force-pushed the feat/add-nx-plugin-2 branch from df83798 to c527716 Compare April 17, 2025 00:42

seriouslag added 19 commits July 29, 2025 12:25

feat(client): update example to use actual code from the spec to avoi…

9095673

…d type error

feat(config): update setup file reference in Vitest base config to us…

13d9cf2

…e module path

feat(turbo.json): add build task configuration for Nuxt project

9881ed1

feat(nx-plugin): enhance OpenAPI spec comparison functionality

fc91491

- Replace the existing openapi-diff dependency with api-smart-diff for improved comparison accuracy. - Add comprehensive test cases to validate spec comparison logic across various scenarios.

chore(dependencies): downgrade find-my-way to version 9.2.0 and add o…

b2a99c5

…verrides in package.json files to support node 18

feat(nx-plugin): update to support NX 21 continuous pipelines

5c826aa

major: add node 24 in CI, remove node 18 as a supported target

a4e0c78

refactor(nx-plugin): improve file formatting utilities

1156b91

refactor(nx-plugin): handle configs from builtin client packages

5c1ab93

patch(nx-plugin): removed generated tests

1e9a937

test(nx-plugin): add experimental parser validation to configuration …

7ce9e42

…tests

test(nx-plugin): add parser configuration for tests

54ba264

fix(openapi-client): update temp folder handling to use absolute path…

c2059ae

… for directory creation

fix(nx-plugin): update command generation to correctly format plugin …

a3f5d25

…flags

fix(openapi-client): update output path generation to use project roo…

0613b46

…t for generated files

seriouslag force-pushed the feat/add-nx-plugin-2 branch from a5eb2fa to 0613b46 Compare July 29, 2025 16:37

vercel Bot deployed to Preview July 29, 2025 16:38 View deployment

seriouslag added 2 commits July 31, 2025 01:42

feat(nx-plugin): add projectReferences option

f5b1e7d

feat(nx-plugin): copy generator templates to dist

13a3c9c

vercel Bot deployed to Preview July 31, 2025 05:46 View deployment

		@@ -1,7 +1,32 @@
		// This file is auto-generated by @hey-api/openapi-ts

		@@ -0,0 +1,5 @@
		// FAIL LOUDLY on unhandled promise rejections / errors

Uh oh!

Uh oh!

Conversation

seriouslag commented Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bolt-new-by-stackblitz Bot commented Apr 14, 2025

Uh oh!

vercel Bot commented Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

changeset-bot Bot commented Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

codecov Bot commented Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pkg-pr-new Bot commented Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seriouslag Apr 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Check failure

Uh oh!

Uh oh!

seriouslag commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrlubos commented Dec 29, 2025

Uh oh!

jinder commented Jan 16, 2026

Uh oh!

seriouslag commented Jan 19, 2026

Uh oh!

jinder commented Jan 20, 2026

Uh oh!

seriouslag commented Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

seriouslag commented Apr 14, 2025 •

edited

Loading

vercel Bot commented Apr 14, 2025 •

edited

Loading

changeset-bot Bot commented Apr 14, 2025 •

edited

Loading

codecov Bot commented Apr 14, 2025 •

edited

Loading

pkg-pr-new Bot commented Apr 14, 2025 •

edited

Loading

seriouslag Apr 14, 2025 •

edited

Loading

seriouslag commented Dec 29, 2025 •

edited

Loading