feat(nx-plugin): add NX Plugin with OpenAPI client generator and executor #1947

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

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 to fit into 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 24, 2025 6:20pm

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

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

⚠️ No Changeset found

Latest commit: a5eb2fa

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

Attention: Patch coverage is 66.66667% with 1 line in your changes missing coverage. Please review.

Project coverage is 22.52%. Comparing base (9ccd969) to head (a5eb2fa).

Files with missing lines	Patch %	Lines
...s/openapi-ts/src/openApi/shared/utils/operation.ts	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1947      +/-   ##
==========================================
- Coverage   22.52%   22.52%   -0.01%     
==========================================
  Files         324      324              
  Lines       31857    31858       +1     
  Branches     1232     1232              
==========================================
  Hits         7177     7177              
- Misses      24671    24672       +1     
  Partials        9        9

Flag	Coverage Δ
unittests	`22.52% <66.66%> (-0.01%)`	⬇️

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

examples/openapi-ts-nuxt/turbo.json

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


Added this file to cache builds

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

examples/openapi-ts-sample/src/App.tsx


 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

examples/openapi-ts-sample/src/client/client.gen.ts

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


Ran the code gen

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

packages/config-vite-base/package.json

@@ -10,6 +10,19 @@
  "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

packages/config-vite-base/package.json

+        "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

packages/config-vite-base/src/setup.ts

@@ -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

packages/config-vite-base/src/vitest.base.config.ts

@@ -25,6 +25,7 @@ export function createVitestConfig(
        },
      },
      root,
+      setupFiles: ['@config/vite-base/setup'],


Adding our new vitest setup file with the new export path

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

turbo.json

@@ -2,7 +2,7 @@
  "$schema": "./node_modules/turbo/schema.json",
  "tasks": {
    "build": {
-      "cache": false,
+      "cache": true,


Enabled caching for quicker local dev

packages/nx-plugin/src/executors/update-api/updateApi.spec.ts

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


packages/nx-plugin/src/executors/update-api/updateApi.ts

…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.

github-advanced-security

CodeQL found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

…tests

… object type before accessing 'case' property

… for directory creation

seriouslag · 2025-07-24T18:34:57Z

@seriouslag what's the latest on this plugin?

Rebased the PR.
I will test out the latest changes.

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

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

View reviewed changes

packages/nx-plugin/src/executors/update-api/index.ts Fixed Show fixed Hide 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 bot 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 11 commits July 24, 2025 07:53

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

57dda7f

…e module path

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

ad16a4e

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

c8c2236

- 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…

2526549

…verrides in package.json files to support node 18

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

733ff69

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

94a79a0

refactor(nx-plugin): improve file formatting utilities

e3e4b7d

seriouslag force-pushed the feat/add-nx-plugin-2 branch from aab87bc to 0dedaa8 Compare July 24, 2025 12:11

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

52a1e75

seriouslag force-pushed the feat/add-nx-plugin-2 branch from 0dedaa8 to 52a1e75 Compare July 24, 2025 12:12

vercel bot deployed to Preview July 24, 2025 12:14 View deployment

github-advanced-security bot found potential problems Jul 24, 2025

View reviewed changes

vercel bot deployed to Preview July 24, 2025 12:21 View deployment

seriouslag force-pushed the feat/add-nx-plugin-2 branch from f0259ea to f4b65ed Compare July 24, 2025 12:21

patch(nx-plugin): removed generated tests

92f6777

seriouslag force-pushed the feat/add-nx-plugin-2 branch from f4b65ed to 92f6777 Compare July 24, 2025 12:22

vercel bot deployed to Preview July 24, 2025 12:24 View deployment

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

4810908

…tests

vercel bot deployed to Preview July 24, 2025 12:32 View deployment

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

a2fb1da

vercel bot deployed to Preview July 24, 2025 17:35 View deployment

seriouslag added 2 commits July 24, 2025 14:18

fix(operation): ensure output case handling is robust by checking for…

1314d5d

… object type before accessing 'case' property

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

a5eb2fa

… for directory creation

vercel bot deployed to Preview July 24, 2025 18:20 View deployment

seriouslag mentioned this pull request Jul 24, 2025

fix(operation): ensure output case handling is robust by checking for object type #2356

Merged

		@@ -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!

feat(nx-plugin): add NX Plugin with OpenAPI client generator and executor #1947

Are you sure you want to change the base?

feat(nx-plugin): add NX Plugin with OpenAPI client generator and executor #1947

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!

github-advanced-security bot left a comment

Choose a reason for hiding this comment

Uh oh!

seriouslag commented Jul 24, 2025

Uh oh!

Uh oh!

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