SwaggerUI build artifacts proposal

This is current state of our build artifacts

This document describe state after https://github.com/swagger-api/swagger-ui/pull/7826 is merged.

swagger-ui.js

This is UMD build that doesn't include production dependencies and exports SwaggerUICore symbol on global object.

swagger-ui-bundle.js

This is UMD build that does include production dependencies and exports SwaggerUIBundle symbol on global object.

swagger-ui-standalone-preset.js

This is UMD build that does include production dependencies and exports SwaggerUIStandalonePreset symbol on global object.

swagger-ui-es-bundle.js

This is commonjs2 build that does include production dependencies.

swagger-ui-es-bundle-core.js

This is true ESM bundle that doesn't include production dependencies.

The difference between commonjs and commonjs2:

commonjs mean pure CommonJs (less flexibility)
commonjs2 also includes the module.exports stuff.

Proposal

I propose to simplify our build system and build fragments following backwards compatible way:

swagger-ui.js

This is UMD build that does include production dependencies and exports SwaggerUI symbol on global object. For backward compatibility we should also make sure that this bundle exports SwaggerUICore as well on global object.

swagger-ui-standalone.js

This is UMD build that does include production dependencies and exports SwaggerUIStandalonePreset symbol on global object. No change here.

swagger-ui.mjs

This is true ESM build that doesn't include production dependencies. This can be achieved by using following webpack config.

swagger-ui.cjs

This is commonjs2 build that doesn't include production dependencies. This will be deprecated, exists mostly for backward compatible reasons and will be removed in next major release following the next major release (two major releases) of swagger-ui.

package.json mappings

To achieve backward compatibility I propose following mappings:

  "main": "./dist/swagger-ui.cjs",
  "module": "./dist/swagger-ui.mjs",
  "exports": {
    ".": {
      "browser": "./dist/swagger-ui.mjs",
      "node": "./dist/swagger-ui.cjs"
      "import": "./dist/swagger-ui.mjs",
      "require": "./dist/swagger-ui.js",
    }
  }

Proposal phase 2

In this phase we should consider using forked CRA for our build system as demonstrated here so that we don't need to maintain a lot of webpack/babel/eslint configuration our selves and benefit from work of Facebook team which work hard of embedding current industry standards into the CRA build system. The only drawback is that we're now be able to easily update build deps like webpack/eslint/babel unless CRA does so. But there is still en option for ejecting if it comes to that.

This is suitable doing in next breaking change release of swagger-ui. First step is converting swagger-ui to pure ESM module first. This will allow to comsume other ESM modules which entire npm ecosystem is now converging to.

Build fragments will change to following:

swagger-ui.js

This is UMD build that does include production dependencies and exports SwaggerUI symbol on global object. For backward compatibility we should also make sure that this bundle exports SwaggerUICore as well on global object. This fragments is used mostly via unpkg.com.

swagger-ui-standalone.js

This is UMD build that does include production dependencies and exports SwaggerUIStandalonePreset symbol on global object. No change here.

swagger-ui.mjs

This is true ESM build that doesn't include production dependencies. This can be achieved by using following webpack config.

swagger-ui.cjs

This is commonjs2 build that doesn't include production dependencies. This will be deprecated, exists mostly for backward compatible reasons and will be removed in next major release following the next major release (two major releases) of swagger-ui.

Following mappings should be introduced:

  "exports": {
   "./react": {
      "browser": "./flavors/swagger-ui-react/index.mjs",
      "node": "./flavors/swagger-ui-react/commonjs.cjs"
      "import": "./flavors/swagger-ui-react/index.mjs",
      "require": "./flavors/swagger-ui-react/commonjs.cjs",    
   },
    ".": {
      "browser": "./dist/swagger-ui.mjs",
      "node": "./dist/swagger-ui.cjs"
      "import": "./dist/swagger-ui.mjs",
      "require": "./dist/swagger-ui.cjs",
    }
  }

We're dropping old mappings and using new exports field exclusively. Our support for particular Node.js versions should reflect that. exports fields allows to maps submodules so we can directly map the swagger-ui react component as well.

import SwaggerUIReact from 'swagger-ui/react';

swagger-ui-react and swagger-ui-dist can be discontinued. This also requires chanding react and react-dom to be peer dependencies. Versions of Node.js that supports exports field also support installing peer deps implicitly.

From

"depenencies": {
    "react": "=17.0.2",
    "react-dom": "=17.0.2"
}

To

"peerDepenencies": {
    "react": "=17.0.2",
    "react-dom": "=17.0.2"
}