chore!: bundle CLI with esbuild by AlbinaBlazhko17 · Pull Request #2866 · Redocly/redocly-cli

AlbinaBlazhko17 · 2026-06-11T10:55:57Z

What/Why/How?

Switched @redocly/cli to bundle with esbuild and produce one dependency-free file.

Added scripts/build.mjs - esbuild config that bundles src/index.ts → lib/index.js
Added scripts/prepare-publish-dir.mjs - creates a .publish staging directory with a minimal package.json (no dependencies) and only the files that need to be published
Changed scripts/local-pack.sh - pack:prepare now builds and packs from .publish
Removed packages/cli from tsconfig.build.json references - tsc no longer compiles the CLI
Inlined template.hbs as a string constant in build-docs/utils.ts as a fallback - esbuild does not copy assets, so resolveTemplateSource tries to read the file first and falls back to the embedded template
Simplified package.ts - replaced createRequire with a static JSON import, which esbuild handles natively
Removed pin-intersecting-deps.sh and all yarn cache workarounds from smoke tests - no transitive deps means no version conflicts to pin

Reference

Testing

Locally, in CI, in other products.

Screenshots (optional)

Check yourself

This PR follows the contributing guide
All new/updated code is covered by tests
Core code changed? - Tested with other Redocly products (internal contributions only)
New package installed? - Tested in different environments (browser/node)
Documentation update has been considered

Security

The security impact of the change has been considered
Code follows company security practices and guidelines

Note

High Risk
Major packaging and distribution change: published CLI has no node_modules dependencies, which can break plugins and integrators that relied on hoisting; esbuild bundling also changes how commands and assets load at runtime.

Overview
@redocly/cli is now built with esbuild and published without runtime dependencies, so installs are faster and the tarball only contains bin/, bundled lib/, README, LICENSE, and generated THIRD_PARTY_NOTICES.

The build pipeline adds packages/cli/scripts/build.mjs (ESM bundle + code splitting, redoc leak guard on the main entry) and prepare-publish-dir.mjs (stages .publish with a minimal package.json). Root compile runs the CLI bundle instead of tsc for the CLI; packages/cli is removed from tsconfig.build.json. Release and snapshot flows publish from .publish via scripts/release-publish.mjs and updated local-pack.sh.

Breaking for plugin authors: packages hoisted from the CLI (e.g. @redocly/openapi-core) are no longer available unless declared in the plugin’s own dependencies (documented in the changeset).

build-docs is dynamically imported so heavy redoc/React code stays out of the main bundle; the default Handlebars template is inlined in utils.ts (file-based templates still work). Scorecard plugin evaluation sets __redocly_dirname from an optional config directory via pathToFileURL. Smoke CI drops yarn cache/pin workarounds; Docker build no longer copies template.hbs manually.

^{Reviewed by Cursor Bugbot for commit c525d5e. Bugbot is set up for automated code reviews on this repo. Configure here.}

changeset-bot · 2026-06-11T10:56:07Z

🦋 Changeset detected

Latest commit: c525d5e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@redocly/cli	Minor
@redocly/openapi-core	Minor
@redocly/respect-core	Minor

Not sure what this means? Click here to learn what changesets are.

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

github-actions · 2026-06-11T10:58:03Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	81.37% (🎯 81%)	7394 / 9086
🔵	Statements	80.73% (🎯 80%)	7687 / 9521
🔵	Functions	84.5% (🎯 84%)	1473 / 1743
🔵	Branches	73.05% (🎯 72%)	5002 / 6847

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/cli/src/commands/build-docs/index.ts	93.33%	50%	100%	93.33%	53
packages/cli/src/commands/build-docs/utils.ts	56.66%	35.48%	83.33%	58.62%	46-67, 133
packages/cli/src/commands/scorecard-classic/validation/plugin-evaluator.ts	83.33%	76.19%	100%	82.75%	17, 59-62
packages/cli/src/commands/scorecard-classic/validation/validate-scorecard.ts	80%	73.68%	100%	79.16%	52-54, 72-92
packages/cli/src/utils/package.ts	100%	100%	100%	100%

Generated in workflow #10315 for commit c525d5e by the Vitest Coverage Report Action

github-actions · 2026-06-11T10:59:13Z

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓▓▓▓▓▓▓▓▓ 1.27x ± 0.01	▓▓▓▓▓▓▓▓▓▓▓▓▓ 1.41x ± 0.01	▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 1.82x ± 0.02
cli-next	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)

AlbinaBlazhko17 · 2026-06-11T13:05:31Z

  "types": "lib/index.d.ts",
  "exports": {
    ".": {
+      "types": "./lib/index.d.ts",


Changed order of the exports to avoid warnings. Made the same changes for respect-core.

AlbinaBlazhko17 · 2026-06-11T13:13:36Z

 WORKDIR /build
 COPY . .
 RUN apk add --no-cache jq git && \
-    npm ci --no-optional --ignore-scripts && \


We don't need to skip deps under optionalDependencies, because we don't have deps at all.

AlbinaBlazhko17 · 2026-06-11T13:14:54Z

+    "release": "node ./scripts/release-publish.mjs",
    "pack:prepare": "./scripts/local-pack.sh",
    "respect:parser:generate": "pegjs --format es --output packages/respect-core/lib/modules/runtime-expressions/abnf-parser.js packages/respect-core/src/modules/runtime-expressions/abnf-parser.pegjs && cp packages/respect-core/lib/modules/runtime-expressions/abnf-parser.js packages/respect-core/src/modules/runtime-expressions/abnf-parser.js",
-    "build-docs:copy-assets": "cp packages/cli/src/commands/build-docs/template.hbs packages/cli/lib/commands/build-docs/template.hbs ",


We don't need any templates inside lib folder. We only have lib/index.js.

github-actions · 2026-06-11T13:24:18Z

📦 A new experimental 🧪 version v0.0.0-snapshot.1781184257 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1781184257

⚠️ Note: This is a development build and may contain unstable features.

This reverts commit 8334e58.

…ic for build-docs

… add warning

AlbinaBlazhko17 · 2026-06-16T08:44:00Z

+);
+
+const seenPkgRoots = new Set();
+const licenseGroups = new Map(); // spdx -> { text, packages: ['name@version — Copyright ...'] }


We cannot just point to our public repo, so i picked different approach to show license and packages to what it belongs. The current THIRD_PARTY_NOTICES has 772 rows.

AlbinaBlazhko17 · 2026-06-16T08:45:31Z

+  metafile: true,
+  // Avoid errors when external dependencies use CJS syntax.
+  banner: {
+    js: "import { createRequire as __createRequire } from 'node:module';\nconst require = __createRequire(import.meta.url);",


If i remove this it will not throw an error, but i will leave this as a guard. @tatomyr WDYT?

Let's try without it first.

I did more deep testing and received an error, so we leave this banner prop.

AlbinaBlazhko17 · 2026-06-16T08:48:49Z

 !tsconfig.json
 !package-lock.json
+!README.md
+!LICENSE.md


We have root LICENSE.md file with this extension.

tatomyr · 2026-06-16T09:33:58Z

+  const templateSource = customTemplate
+    ? readFileSync(customTemplate, 'utf-8')
+    : DEFAULT_TEMPLATE_SOURCE;
+  const template = handlebars.compile(templateSource);


Do we still need to convert it to string?

No, because we use 'utf-8'.

tatomyr · 2026-06-16T09:36:53Z

    "Roman Hotsiy <roman@redocly.com> (https://redocly.com/)"
  ],
-  "dependencies": {
+  "devDependencies": {


Please check if npx changeset version will still correctly bump the CLI version when bumping its dev dependencies.

I gave it a shot and looks like it updated CLI.

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c525d5e. Configure here.}

cursor · 2026-06-16T12:38:03Z

+
+for (const relInput of allInputs) {
+  const absInput = path.resolve(packageDir, relInput);
+  const pkgRootMatch = absInput.match(/^(.*\/node_modules\/(?:@[^/]+\/)?[^/]+)/);


Windows path breaks license scan

Low Severity

Third-party notice generation matches node_modules using a regex that only allows forward slashes, while path.resolve on Windows produces backslash paths. Bundled dependency discovery can be skipped on Windows, yielding incomplete or misleading THIRD_PARTY_NOTICES output.

^{Reviewed by Cursor Bugbot for commit c525d5e. Configure here.}

chore: use esbuild to bundle cli

24a6fdb

AlbinaBlazhko17 and others added 6 commits June 11, 2026 14:47

refactor: comments, naming and script

23c1b35

chore: change comments

64c8287

fix: failed smoke tests

13097cb

fix: add missing binTargetPath

e284f86

chore: remove unused enableCrossOsArchive

79ae229

Merge branch 'main' into feat/esbuild-bundle-cli

5d77530

AlbinaBlazhko17 commented Jun 11, 2026

View reviewed changes

chore: try to remove compile from the smoke test

f130d53

AlbinaBlazhko17 commented Jun 11, 2026

View reviewed changes

AlbinaBlazhko17 self-assigned this Jun 11, 2026

AlbinaBlazhko17 added the snapshot Create experimental release PR label Jun 11, 2026

AlbinaBlazhko17 and others added 7 commits June 11, 2026 17:51

Merge branch 'main' into feat/esbuild-bundle-cli

3c0b344

chore: retrigger CI

dd3993a

chore: trigger workflow

2d61a33

fix: failing smoke tests

8334e58

Revert "fix: failing smoke tests"

f7f2194

This reverts commit 8334e58.

chore: trigger CI

9bf261a

chore: add dot

b91c75e

AlbinaBlazhko17 marked this pull request as ready for review June 12, 2026 07:36

AlbinaBlazhko17 requested review from a team as code owners June 12, 2026 07:36

feat: add code splitting into chuncs by dynamic imports and add dynam…

e14b327

…ic for build-docs

JLekawa approved these changes Jun 12, 2026

View reviewed changes

chore: remove unused deps due to bundle

b37d33f

feat: move all deps to the devDep

400e935

cursor Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread packages/cli/scripts/build.mjs

AlbinaBlazhko17 added 2 commits June 12, 2026 12:34

fix: resolving path to plugin

53b1f55

fix: failed test

79e4768

cursor Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread packages/cli/scripts/build.mjs

chore: clean lib folder before build

dd57cea

cursor Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread .github/workflows/release.yaml

AlbinaBlazhko17 added 6 commits June 12, 2026 13:30

fix: bumping versions

dc2437d

fix: pipeline, scripts, plugin-evaluator and add THIRD_PARTY_NOTICES

fdb23b6

chore: deslope

9ad62f7

chore: run format

6e280d0

fix: e2e script, build third party license, remove template, test and…

f70d6e8

… add warning

chore: run formatter

7a6e98b

AlbinaBlazhko17 commented Jun 16, 2026

View reviewed changes

chore: update e2e script

51376ca

cursor Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread packages/cli/scripts/build.mjs Outdated

chore: change target in esbuild

4cde987

tatomyr changed the title ~~chore: bundle CLI with esbuild~~ chore!: bundle CLI with esbuild Jun 16, 2026

tatomyr reviewed Jun 16, 2026

View reviewed changes

Comment thread packages/cli/src/commands/build-docs/index.ts Outdated

tatomyr reviewed Jun 16, 2026

View reviewed changes

AlbinaBlazhko17 added 4 commits June 16, 2026 14:36

fix: change target and refactor import of redoc version

dae6bf5

Merge branch 'main' into feat/esbuild-bundle-cli

bb5965a

chore: uncomment smokes

bfad5ac

chore: comment smoke due to failing

4b7d5bd

cursor Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread packages/cli/scripts/prepare-publish-dir.mjs

chore: remove comments

c525d5e

cursor Bot reviewed Jun 16, 2026

View reviewed changes

Conversation

AlbinaBlazhko17 commented Jun 11, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

github-actions Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Benchmark (Lower is Faster)

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!

github-actions Bot commented Jun 11, 2026

Uh oh!

Uh oh!

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!

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!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 16, 2026

Choose a reason for hiding this comment

Windows path breaks license scan

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AlbinaBlazhko17 commented Jun 11, 2026 •

edited by cursor Bot

Loading

changeset-bot Bot commented Jun 11, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading

github-actions Bot commented Jun 11, 2026 •

edited

Loading