Certain packages cause OpenAPI generation failures due to esbuild configuration

austinkelleher commented 4 months ago

Problem

We ran into an issue using jsdom with next-rest-framework. When generating the OpenAPI schema via the CLI, we are seeing the warnings that look like this:

Compiling endpoints...
▲ [WARNING] "./xhr-sync-worker.js" should be marked as external for use with "require.resolve" [require-resolve-not-external]

    ../../node_modules/.pnpm/jsdom@24.0.0/node_modules/jsdom/lib/jsdom/living/xhr/XMLHttpRequest-impl.js:31:57:
      31 │ const syncWorkerFile = require.resolve ? require.resolve("./xhr-sync-worker.js") : null;

The result is that APIs whose bundles indirectly import the jsdom package are actually not being generated properly. The generate schema will not include these APIs. Certain packages should be excluded from the esbuild process (for example, jsdom and esbuild).

Proposal

A method of overriding the default configuration options being passed to esbuild inside of next-rest-framework. Even better, a JavaScript API for interfacing with next-rest-framework's build tooling for maximum flexibility.

Consider the following JS API:

import {
  compileEndpoints,
  syncOpenApiSpecFromBuild,
  clearTmpFolder
} from 'next-rest-framework/generate';

blomqma commented 4 months ago

Yeah I think those functions could be exposed from the package, but obviously it would be better to have an easy-to-use CLI tooling working with any set of dependencies for all projects using this framework and no need to write your own CLI. Given how many reports I have received recently about people having issues with ESBuild, I'm starting to think that an alternative way might be a better option here. I made an attempt here to drop the ESBuild process all together from the CLI commands and parse the OpenAPI definitions instead directly from the TS/JS source code using tsx: https://github.com/blomqma/next-rest-framework/pull/161

blomqma commented 4 months ago

v6.0.0-beta.4 is now published with the mentioned changes in #161, please let me know if this won't address your issue.

austinkelleher commented 2 months ago

@blomqma So sorry for the late response on this. Really appreciate your quick turnaround. We upgraded to 6.x and everything seems to be working great! 🚀

blomqma / next-rest-framework

Certain packages cause OpenAPI generation failures due to esbuild configuration #159

Problem

Proposal