1
0
mirror of https://github.com/lancedikson/bowser synced 2026-09-25 21:44:23 +00:00

fix: make dual packaging non-breaking for existing consumers

Keeps the published surface of bowser@2.14.1 intact while adding a real
ESM build, and rewrites CI so it can actually run the new toolchain.

Packaging

- Restore the flat artifact layout. es5.js and bundled.js stay at the
  tarball root next to src/, so unpkg.com/bowser/es5.js and
  require('bowser/bundled') keep working. bowser.mjs is added alongside.
- Build the UMD bundles from dedicated single-default-export entries in
  build/entries/. src/bowser.js gained named exports (parse, getParser)
  to fix #511, but a UMD bundle with named exports makes require('bowser')
  a namespace object instead of the class: typeof flips from 'function' to
  'object' and BROWSER_MAP / ENGINE_MAP / OS_MAP / PLATFORMS_MAP disappear,
  since they are static getters rather than exports.
- globalName back to lowercase 'bowser', matching the shipped es5.js.
  Renaming it to 'Bowser' would break every script-tag consumer.
- Enumerate every legacy subpath in the exports map. Conditional exports
  are honoured from Node 12.16.0 onward, so a "."-only map turns paths
  that resolve today into ERR_PACKAGE_PATH_NOT_EXPORTED. Subpath patterns
  ("./src/*") need Node 12.20.0+ and the trailing-slash folder form was
  removed in Node 17, so explicit per-file keys are the only spelling that
  works across the whole supported range. Extension-less aliases included:
  the README documents require('bowser/bundled').
- main, browser and module keep their existing values. No engines field
  (npm warns EBADENGINE, pnpm fails under engine-strict) and no type
  field (it would reclassify es5.js as ESM).

Build

- Minify the UMD bundles with terser instead of rolldown's built-in oxc
  minifier. oxc prints every string literal as a template literal and
  rejects any compress.target below es2015, so it cannot emit ES5 and was
  silently undoing babel's lowering. terser is what webpack 4 used.
- Wire up the copyright banner, which was declared but never passed to a
  config, and restore bundled.js as the polyfilled build via core-js/stable.
- Add index.d.mts so the import condition has ESM types. Reusing the
  export = declarations for both conditions describes an ES module with
  CommonJS types.

CI

- Replace npm ci with pnpm across all workflows. This is what was failing:
  the lockfile was swapped for pnpm-lock.yaml but the workflows still ran
  npm ci, pinned to Node 12.16.3 and 16. Build now runs on Node 24, which
  tsdown requires.
- Add a pack-smoke job that installs the packed tarball on Node 12.16.3,
  14, 18, 20 and 24 and exercises every documented entry point, plus
  publint and attw on the tarball. This is what makes "non-breaking" a
  tested claim rather than an argument; it catches all of the above.
- Restore test-list-of-ua.js to asserting src against the built es5.js.
  It had been collapsed to comparing Bowser.parse with itself.
This commit is contained in:
naorpeled
2026-08-01 14:40:56 +03:00
parent 1944c3d05c
commit a78d9d35a2
16 changed files with 1467 additions and 586 deletions

View File

@@ -27,7 +27,9 @@ _For legacy code, check out the [1.x](https://github.com/bowser-js/bowser/tree/v
# Use cases
First of all, require the library. This is a UMD Module, so it will work for AMD, TypeScript, ES6, and CommonJS module systems.
First of all, require the library. Bowser is a dual package: `require` resolves
to a UMD build (which also works for AMD and as a plain `<script>` tag), and
`import` resolves to a real ES module.
```javascript
const Bowser = require("bowser"); // CommonJS
@@ -37,11 +39,30 @@ import * as Bowser from "bowser"; // TypeScript
import Bowser from "bowser"; // ES6 (and TypeScript with --esModuleInterop enabled)
```
The ES module build also exposes `parse` and `getParser` as named exports, so
you can import just the part you use and let your bundler drop the rest:
```javascript
import { getParser, parse } from "bowser";
const browser = getParser(window.navigator.userAgent);
```
Loaded from a CDN or a `<script>` tag, Bowser attaches itself to the global as
`bowser` (lowercase):
```html
<script src="https://unpkg.com/bowser@2/es5.js"></script>
<script>
console.log(bowser.parse(window.navigator.userAgent));
</script>
```
By default, the exported version is the *ES5 transpiled version*, which **do not** include any polyfills.
In case you don't use your own `babel-polyfill` you may need to have pre-built bundle with all needed polyfills.
In case you don't use your own polyfills you may need to have pre-built bundle with all needed polyfills.
So, for you it's suitable to require bowser like this: `require('bowser/bundled')`.
As the result, you get a ES5 version of bowser with `babel-polyfill` bundled together.
As the result, you get a ES5 version of bowser with `core-js` polyfills bundled together.
You may need to use the source files, so they will be available in the package as well.