feat: opt-in the web platform's new binary output format

[PupilTong]

Summary by CodeRabbit

• New Features

  • Added an opt-in feature flag for the web platform's new binary output format (internal-use-only; may be removed later). Enable by setting the environment variable to the string "true".

• Behavior Changes

  • The flag activates the binary format only when set exactly to "true"; leaving it unset returns the regular JSON payload.

• Bug Fixes

  • Improved user-facing error message for invalid flag values.

Checklist

• Tests updated (or not required).
• Documentation updated (or not required).
• Changeset added, and when a BREAKING CHANGE occurs, it needs to be clearly marked (or not required).

[changeset-bot]

🦋 Changeset detected

Latest commit: 9b9e4d4

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

This PR includes changesets to release 6 packages

Name	Type
@lynx-js/rspeedy	Patch
@lynx-js/template-webpack-plugin	Patch
create-rspeedy	Patch
@lynx-js/react-rsbuild-plugin	Patch
upgrade-rspeedy	Patch
@lynx-js/react-alias-rsbuild-plugin	Patch

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

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 110a027 and 9b9e4d4.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (3)

• .changeset/moody-snakes-study.md
• packages/webpack/template-webpack-plugin/package.json
• packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• .changeset/moody-snakes-study.md

---

📝 Walkthrough

Walkthrough

Adds a changeset for an opt-in web binary output flag, moves @lynx-js/web-core-wasm to runtime dependencies in the webpack plugin, and tightens EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE handling and error messages in WebEncodePlugin.

Changes

Cohort / File(s)	Summary
Changeset Documentation \.changeset/moody-snakes-study.md	Adds a new changeset documenting an opt-in feature flag (EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE) for the web binary output format and patch bumps for affected packages.
Dependency Management packages/webpack/template-webpack-plugin/package.json	Moves @lynx-js/web-core-wasm from devDependencies to dependencies (runtime dependency).
Binary Output Logic packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts	Changes flag handling to accept only the string 'true' for binary output (dynamic import of @lynx-js/web-core-wasm/encode), return JSON when unset, and throw on any other value; removes previous catch-based import handling and updates error text.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: add initial project files including LICENSE, README, and ESLint… #2089 — Introduces the @lynx-js/web-core-wasm package files that are now a runtime dependency.
• feat(template-webpack-plugin): add appType field for web bundle #1738 — Alters encoding behavior in WebEncodePlugin.ts, overlapping with the feature-flag and encoding changes.
• feat: improve web-core-wasm #2148 — Refactors or expands wasm encode APIs and TemplateManager exports referenced by the plugin.

Suggested reviewers

• upupming
• luhc228
• Sherry-hue

Poem

🐇 I nibble flags beneath the glowing screen,
A tiny opt-in path where binary dreams preen,
Wasm hops to runtime on a careful cue,
Only "true" may lead the tunnel through,
Templates hum softly — a rabbit's tidy scene.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing an opt-in feature for the web platform's new binary output format, which is directly reflected in the changeset, package.json dependency reorganization, and WebEncodePlugin modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 4 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...ack/template-webpack-plugin/src/WebEncodePlugin.ts	50.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Adds an opt-in path for generating the web platform’s new binary template output by gating a WASM-based encoder behind an environment flag, and updates packaging/release metadata to ship the capability.

Changes:

• Gate WebEncodePlugin output format selection behind EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE === 'true' and encode via @lynx-js/web-core-wasm/encode when enabled.
• Move @lynx-js/web-core-wasm from devDependencies to dependencies for runtime/type availability.
• Add a Changesets entry describing the feature flag.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts	Adds env-flag-controlled binary encoding path using WASM encoder and updates error text.
packages/webpack/template-webpack-plugin/package.json	Promotes @lynx-js/web-core-wasm to a runtime dependency.
.changeset/moody-snakes-study.md	Adds release note describing the new opt-in binary output flag.

Comments suppressed due to low confidence (1)

packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts:120

• This introduces/changes behavior behind EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE, but there is no test exercising the binary-encode path. Add a test case that sets the env var and asserts the emitted template payload is binary (and/or that wasm encode is invoked).

          const isExperimentalWebBinary = process
            .env['EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE'];
          if (isExperimentalWebBinary === 'true') {
            const { encode } = await import('@lynx-js/web-core-wasm/encode')
              .catch(
                () => {
                  throw new Error(
                    `cannot enable the flat EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE, please contact developers`,
                  );
                },
              );
            return {
              buffer: Buffer.from(encode(tasmJSONInfo as TasmJSONInfo)),
              debugInfo: '',
            };
          } else {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.changeset/moody-snakes-study.md:
- Line 9: Replace the incorrect phrase "a internal use only flag" with the
corrected, hyphenated form "an internal-use-only flag" in the
.changeset/moody-snakes-study.md content (search for the exact string "a
internal use only flag" to locate the sentence), ensuring the surrounding
sentence remains grammatically correct and unchanged otherwise.

In `@packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts`:
- Line 112: The error message string in WebEncodePlugin referencing
"EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE" contains a typo: replace the word "flat"
with "flag" in the message string (the literal that currently reads `cannot
enable the flat EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE, please contact
developers`) inside the WebEncodePlugin implementation so the message reads
`cannot enable the flag EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE, please contact
developers`.

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6caf9e0 and 7f57ac9.

📒 Files selected for processing (3)

• .changeset/moody-snakes-study.md
• packages/webpack/template-webpack-plugin/package.json
• packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts

[codspeed-hq]

Merging this PR will degrade performance by 8.46%

❌ 1 regressed benchmark
✅ 71 untouched benchmarks
⏩ 3 skipped benchmarks¹

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	basic-performance-div-100	6.8 ms	7.4 ms	-8.46%

---

_{Comparing PupilTong:p/hw/opt-in-wasm (9b9e4d4) with main (d32c4c6)}

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[relativeci]

Web Explorer

#7918 Bundle Size — 383.53KiB (0%).

9b9e4d4(current) vs d32c4c6 main#7915(baseline)

Bundle metrics   1 change

	Current #7918	Baseline #7915
Initial JS	154.63KiB	154.63KiB
Initial CSS	35.1KiB	35.1KiB
Cache Invalidation	0%	49.49%
Chunks	8	8
Assets	8	8
Modules	238(-0.42%)	239
Duplicate Modules	16	16
Duplicate Code	2.99%	2.99%
Packages	4	4
Duplicate Packages	0	0

Bundle size by type  no changes

	Current #7918	Baseline #7915
JS	252.58KiB	252.58KiB
Other	95.85KiB	95.85KiB
CSS	35.1KiB	35.1KiB

Bundle analysis report Branch PupilTong:p/hw/opt-in-wasm Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts (1)

113-133: ⚠️ Potential issue | 🟡 Minor

Align accepted-value wording with the actual condition.

Line 113 treats both null and undefined as fallback, but Line 132 says only undefined is accepted. Please make the condition/comment/error text consistent to avoid config confusion.

Suggested consistency patch

-          } else if (isExperimentalWebBinary == null /*undefined or null */) {
+          } else if (isExperimentalWebBinary == null /* undefined or null */) {
@@
-            // only allow 'true' or undefined/null
+            // only allow 'true' or undefined/null
             throw new Error(
-              `Unknown value of EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE: ${isExperimentalWebBinary}. Expecting "true" or undefined.`,
+              `Unknown value of EXPERIMENTAL_USE_WEB_BINARY_TEMPLATE: ${isExperimentalWebBinary}. Expecting "true", undefined, or null.`,
             );

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts` around lines
113 - 133, The code treats both null and undefined as the fallback
(isExperimentalWebBinary == null) but the thrown error only mentions undefined;
update the messaging to match the condition: in the block that throws the Error
referencing isExperimentalWebBinary (and related comment above the branch), make
the wording consistently state that only 'true' or null/undefined are allowed
(e.g., "Expecting 'true' or undefined/null"), or alternatively change the
condition to only accept undefined if you prefer that policy; update the comment
and the Error text so both reflect the same allowed values for
isExperimentalWebBinary (refer to isExperimentalWebBinary, genStyleInfo, and
tasmJSONInfo in WebEncodePlugin.ts).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts`:
- Around line 113-133: The code treats both null and undefined as the fallback
(isExperimentalWebBinary == null) but the thrown error only mentions undefined;
update the messaging to match the condition: in the block that throws the Error
referencing isExperimentalWebBinary (and related comment above the branch), make
the wording consistently state that only 'true' or null/undefined are allowed
(e.g., "Expecting 'true' or undefined/null"), or alternatively change the
condition to only accept undefined if you prefer that policy; update the comment
and the Error text so both reflect the same allowed values for
isExperimentalWebBinary (refer to isExperimentalWebBinary, genStyleInfo, and
tasmJSONInfo in WebEncodePlugin.ts).

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e79fd99 and 110a027.

📒 Files selected for processing (1)

• packages/webpack/template-webpack-plugin/src/WebEncodePlugin.ts