onnxruntime-web JSEP deprecation announcement for developers - #31683
Merged
Edward Chen (edgchen1) merged 3 commits intoAug 6, 2026
Conversation
Adds docs/JSEP_Deprecation.md as the authoritative developer-facing statement that the JS execution provider (JSEP) is deprecated in favor of the native WebGPU EP, and that JSEP is in maintenance mode: bug fixes and security fixes only. It also documents how to tell the two implementations apart, since both register under the 'webgpu' backend key and the choice between them is made at build time. Adds short README pointers in onnxruntime/core/providers/js/ and js/web/lib/wasm/jsep/ so contributors landing in either half of JSEP are redirected. The jsep README notes that WebNN is not deprecated and will be relocated rather than removed. No removal timeline is committed yet; it will be set once real-world JSEP usage is understood, and announced before anything is removed. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Folds in the gaps found while auditing the plan against the code: build configuration parity as an explicit open question that gates the flip, int64 handling, and the full removal scope including the ~130 native C++/CMake files under onnxruntime/core/providers/js/ and onnxruntime/contrib_ops/js/. Restructures the pre-flip work as Phase 0, which starts by publishing the deprecation notice so JSEP contributions can be redirected immediately, then closes the parity and CI gaps: proxy worker, IO binding, WebNN, global env.webgpu settings, and profiling. Phase timing is no longer tied to specific releases. Only Phase 0 is scheduled. Phase 1 begins when its release gate is met, and Phase 2 once a review of reported parity gaps and JSEP usage concludes the temporary /jsep escape hatch can be withdrawn. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…n doc Two gaps in the env.webgpu.* wiring item (8.4). Power preference: JSEP passes undefined to requestAdapter() when unset and lets the browser choose, while the native WebGpuContextConfig default is WGPUPowerPreference_HighPerformance, so forwarding only explicitly-set values would move users who never expressed a preference onto a discrete GPU. The wiring needs a behavior-preserving default. Custom devices: env.webgpu.device is named as the replacement for the deprecated adapter and forceFallbackAdapter settings, but it is output-only -- both paths write it after init and neither reads it. Custom devices go through the per-session device option, which session-options.ts already registers via webgpuRegisterDevice. The env.ts doc comment needs fixing too. Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Edward Chen (edgchen1)
requested review from
Hariharan Seshadri (hariharans29) and
Jiajia Qin (qjia7)
August 5, 2026 23:59
Hariharan Seshadri (hariharans29)
approved these changes
Aug 6, 2026
Hariharan Seshadri (hariharans29)
left a comment
Hariharan Seshadri (hariharans29)
left a comment
Member
There was a problem hiding this comment.
LGTM
Copilot started reviewing on behalf of
Hariharan Seshadri (hariharans29)
August 6, 2026 02:31
View session
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a contributor-facing deprecation announcement for JSEP (the JS/TS WebGPU execution path used by onnxruntime-web) and updates the existing migration design doc to incorporate that announcement as Phase 0 plus additional clarifications around scope, gating, and removal prerequisites.
Changes:
- Add a new authoritative deprecation policy document at
docs/JSEP_Deprecation.md. - Add in-tree README pointers in the native (C++) and TypeScript halves of JSEP to redirect future work to the native WebGPU EP.
- Expand and re-phase the JSEP→native WebGPU EP migration design doc (Phase 0/1/2), including build-parity considerations and clarified gating/prereqs.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| onnxruntime/core/providers/js/README.md | Adds an in-directory deprecation notice for the native JS EP side and points contributors to the replacement WebGPU EP and the main deprecation doc. |
| js/web/lib/wasm/jsep/README.md | Adds a deprecation notice for the TS/WebGPU JSEP implementation and clarifies WebNN is not being deprecated. |
| docs/JSEP_Deprecation.md | Introduces the main deprecation announcement, contribution policy, and a quick “how to tell which WebGPU path you’re on” guide. |
| docs/design/onnxruntime_web_jsep_to_webgpu_ep_migration.md | Updates the migration design to include Phase 0 announcement + additional clarifications on scope, gating, CI coverage, and removal prerequisites. |
Jiajia Qin (qjia7)
approved these changes
Aug 6, 2026
Edward Chen (edgchen1)
deleted the
edgchen1/jsep_deprecation_dev_announcement
branch
August 6, 2026 16:16
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Announce JSEP deprecation to developers via docs in the repo. The main doc is
docs/JSEP_Deprecation.md.Also update the JSEP to WebGPU EP migration design doc to include this initial step as well as some other clarifications.
Motivation and Context
JSEP deprecation.