[OKAN-SOFTWARE]

Description

Fix DataCloneError when the HTML generator uses a custom bundler with parallel worker threads.

The bundler is needed on the main thread but contains functions that cannot be cloned into worker messages.

Changes

• Add workerConfigOmit support to generator metadata.
• Exclude the HTML bundler from worker-thread configuration.
• Preserve the original configuration and existing custom-bundler API.
• Add a regression test demonstrating the failure before the fix and successful worker cloning afterward.
• Add patch changesets for @doc-kit/core and @doc-kit/generator-react.

Validation

• Regression test: failed before the fix, passed afterward.
• Full test suite after rebase: 781 passed, 0 failed (Node.js 24).
• Formatting passed.
• Lint: 0 errors, 1 existing unrelated warning.
• Git diff validation passed.
• Browser E2E tests not run locally; GitHub Actions E2E tests passed.

GitHub Actions

• Unit tests and coverage: Passed.
• E2E tests: Passed.
• Lint and formatting: Passed.
• Documentation generation: Passed.
• CodeQL JavaScript: Passed.
• CodeQL TypeScript: Failed during repository checkout due to a runner network connectivity issue (git exit code 128). Analysis did not start; maintainer rerun needed.

Related Issues

Fixes #1201

Check List

• Read the contribution guidelines and followed the commit conventions.
• Ran the full unit test suite successfully.
• Checked formatting and linting.
• Added regression test coverage.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
api-docs-tooling	Ready	Preview	Oct 30, 2026 7:53pm UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.78%. Comparing base (b8d7b77) to head (4b122c7).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1204      +/-   ##
==========================================
+ Coverage   93.77%   93.78%   +0.01%     
==========================================
  Files         289      289              
  Lines       28813    28875      +62     
  Branches     2913     2916       +3     
==========================================
+ Hits        27018    27081      +63     
+ Misses       1773     1772       -1     
  Partials       22       22              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

api-links Generator

Performance estimate _{(single CI run)}

• Generation time: 7.4% faster (1.08 s → 1.00 s)
• Peak memory: 3.7% lower (295.14 MB → 284.25 MB)

json Generator

Performance estimate _{(single CI run)}

• Generation time: 3.0% faster (9.94 s → 9.64 s)
• Peak memory: 1.0% lower (982.46 MB → 972.36 MB)

legacy-html Generator

Performance estimate _{(single CI run)}

• Generation time: 1.3% faster (16.62 s → 16.40 s)
• Peak memory: 3.3% lower (1.53 GB → 1.48 GB)

legacy-json Generator

Performance estimate _{(single CI run)}

• Generation time: 3.6% slower (9.18 s → 9.51 s)
• Peak memory: 4.0% lower (959.50 MB → 921.56 MB)

llms-txt Generator

Performance estimate _{(single CI run)}

• Generation time: 32.7% faster (9.09 s → 6.12 s)
• Peak memory: 7.7% higher (903.61 MB → 972.86 MB)

orama-db Generator

Performance estimate _{(single CI run)}

• Generation time: 6.0% slower (5.46 s → 5.79 s)
• Peak memory: 11.3% higher (1.02 GB → 1.14 GB)

web Generator

Performance estimate _{(single CI run)}

• Generation time: 63.6% slower (15.42 s → 25.23 s)
• Peak memory: 3.3% lower (1.55 GB → 1.50 GB)

[avivkeller]

This is smart, but would it be smarter to just omit keys containing unclone-ables?

[OKAN-SOFTWARE]

Good point.
I considered automatic filtering, but my concern is that it could silently remove configuration values that workers actually need, particularly with nested objects.

I went with workerConfigOmit to make those exclusions explicit and predictable.
Each generator declares which options belong only on the main thread, while the remaining configuration stays intact.

Thanks

[avivkeller]

it could silently remove configuration values that workers actually need

How? Workers can't need uncloneables, since they would fail to clone

[OKAN-SOFTWARE]

You're right — my wording was imprecise. Workers cannot receive uncloneable values through structured cloning.

My concern is that automatically dropping those values could hide configuration mistakes. A future option containing a function might require a different design, and silently removing it could produce unexpected behavior.

With workerConfigOmit, we explicitly exclude only bundler, which we've verified runs on the main thread. Unexpected uncloneable values still produce an error instead of being silently discarded.

I think that makes the behavior easier to maintain and debug.

[ovflowd]

SGTM but left a review comment

[ovflowd]

Apologies @OKAN-SOFTWARE, can you rebase?

[OKAN-SOFTWARE]

Apologies @OKAN-SOFTWARE, can you rebase?

Rebased onto the latest main and pushed the updated branch. The merge conflict is resolved.
Validation completed on Node.js 24:
Tests: 781 passed, 0 failed
Formatting: passed (463 files)
Lint: 0 errors, 1 unrelated warning

Thanks for the feedback and review! Stay Safe

[OKAN-SOFTWARE]

The latest CI results look good overall. Unit tests, E2E tests, linting, formatting, and documentation generation passed.

The CodeQL TypeScript job failed during repository checkout (git exit code 128) because the runner couldn't connect to github.com:443. CodeQL analysis never started.

I don't have permission to rerun the workflow. Could a maintainer please rerun the failed CodeQL job?

Thank you!

[kgeminicdev]

Checked the bundler's call sites to answer the auto-omit question: it's only read in html/generate.mjs on the main thread (buildServer, buildClient, and compile per page). Nothing under processChunk touches config.bundler, and it's the only html option typed to hold functions (virtualImports etc. are Record<string, string>), so ['bundler'] is the complete list today.

I'd keep it explicit. Auto-dropping uncloneable values would also drop a function from an option a worker does read, and turn today's loud DataCloneError into silently wrong output.