vercel / vercel/next.js

Docs: Turbopack - Web Platform feature compatiblity and plugin system

Open
#78,784 4 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Turbopack
Dominant language
JavaScript
Stars
142k
Forks
32.4k
Avg merge
2d 14h
Merged PRs (30d)
351

Description

What is the documentation issue?

A problem with every new bundler in the market is their lack of proper Web Worker and Audio Worklet support. Unfortunately Turbopack also has no (not yet) a plugin system package authors could use to bridge this gap.

The documentation around supported/unsupported features is very sparse regarding supported web platform features like Web Workers, Worklets.

https://nextjs.org/docs/app/api-reference/turbopack#unsupported-and-unplanned-features

Next.js should mention better what level of support exists and how they are activated.

Also there is no mention about the plans to have a plugin system (e.g. rspack tries to ship a compatible plugin system).

Is there any context that might help us understand?

Web Workers and (Audio) Worklets are always a problematic feature with bundlers and I'm fighting with the expanding jungle of bundlers to provide an easy integration of my library for users.

Web Workers and Audio Worklets are tricky because they are like additional entry points which are dynamically referenced.

For Web Workers most bundlers try to rely on the new Worker(new URL('./relative.js', import.meta.url)) syntax to detect which files are worker entry points that need special treatment. Bundlers typically emit a separate bootstrap/entrypoint file for the worker which is then referenced.

For Audio Worklets the support is often fully neglected or buggy. They are expected to be ESM modules using imports and there is no importScripts function like for Workers making it harder to support in situations where bundlers rewrite the classical imports with a custom module runtime loading mechanism.

For WebPack and Vite I created custom plugins to support what my library needs. But with Turbopack added to the market I face new problems where devs come along and report bugs that my library doesn't work with Vite 15.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/api-reference/turbopack

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked Turbopack API documentation page and review its “Unsupported and unplanned features” section. Determine what the docs currently say about Web Workers and Worklets, how support is activated, and whether plugin-system plans are documented. Done means the page clearly describes the relevant support level and stated plugin plans.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, nextjs
Domain
build-system, documentation, web-dev
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.