feat(kit): support async constructor for adding plugins #33619

antfu · 2025-10-31T06:50:19Z

I think it's a common use case to install plugins lazily, imagine:

addVitePlugin(() => import('my-cool-plugin').then(r => r.default()))

The current workaround is:

const plugin = await import('my-cool-plugin').then(r => r.default)
addVitePlugin(() => plugin())

But this would defeat the point of the factory function to lazy load, as

const pluginVite = await import('my-cool-plugin/vite').then(r => r.default)
const pluginWebpack = await import('my-cool-plugin/webpack').then(r => r.default)
addVitePlugin(() => pluginVite())
addWebpackPlugin(() => pluginWebpack())

would result in loading unnecessary code.

This PR makes those utility support async usages.

Not sure if there are any performance concerns on this tho.

bolt-new-by-stackblitz · 2025-10-31T06:50:23Z

Run & review this pull request in StackBlitz Codeflow.

coderabbitai · 2025-10-31T06:53:57Z

Walkthrough

This PR converts several build-plugin APIs in packages/kit/src/build.ts to support asynchronous resolution. It adds local utility types Arrayable and Thenable, and changes signatures and internal flows to accept/return Thenable values. Updated members include extendViteConfig, extendWebpackCompatibleConfig, addVitePlugin, addWebpackPlugin, addRspackPlugin, AddBuildPluginFactory, and the internal wiring that awaits plugin getters and config mutation hooks.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–30 minutes

Review focus:
- Correct placement of await/async in hook registrations (vite:extend, vite:extendConfig, webpack/rspack extend hooks)
- Verification of updated function signatures and propagated Thenable<Arrayable<...>> types
- addBuildPlugin usage sites and propagation of new factory return types
- Handling of arrayable plugin inputs and functions returning promises
- Potential impacts on callers that relied on synchronous behaviour (ensure compatibility or documented change)

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "feat(kit): support async constructor for adding plugins" directly and clearly describes the main objective of the changeset. The modifications introduce support for Thenable-based (async-compatible) callback functions across all plugin-adding utilities (addVitePlugin, addWebpackPlugin, addRspackPlugin) and configuration extension functions. The title is concise, specific, and uses clear language that accurately conveys the primary change without vague terms or noise.
Description Check	✅ Passed	The pull request description is clearly related to the changeset and provides meaningful context for the changes. It explains the practical use case (lazy-loading plugins via dynamic imports), demonstrates the desired code pattern that motivates these modifications, and contrasts it with the current workaround that defeats lazy-loading benefits. The description directly addresses why async support in plugin factories is valuable, making it entirely relevant to the implementation of Thenable-based signatures across the plugin-adding functions.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/async-add-plugin

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c39fa64 and 8bcdbdc.

📒 Files selected for processing (1)

packages/kit/src/build.ts (10 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Follow standard TypeScript conventions and best practices

Files:

packages/kit/src/build.ts

🧠 Learnings (4)

📓 Common learnings

Learnt from: GalacticHypernova
Repo: nuxt/nuxt PR: 26468
File: packages/nuxt/src/components/plugins/loader.ts:24-24
Timestamp: 2024-11-05T15:22:54.759Z
Learning: In `packages/nuxt/src/components/plugins/loader.ts`, the references to `resolve` and `distDir` are legacy code from before Nuxt used the new unplugin VFS and will be removed.

📚 Learning: 2024-11-28T21:22:40.496Z

Learnt from: GalacticHypernova
Repo: nuxt/nuxt PR: 29661
File: packages/kit/src/template.ts:227-229
Timestamp: 2024-11-28T21:22:40.496Z
Learning: In `packages/kit/src/template.ts`, when updating the `EXTENSION_RE` regular expression for TypeScript configuration, avoid using patterns like `(\.\w+)+$` as they can result in catastrophic backtracking.

Applied to files:

packages/kit/src/build.ts

📚 Learning: 2024-11-11T12:34:22.648Z

Learnt from: Tofandel
Repo: nuxt/nuxt PR: 0
File: :0-0
Timestamp: 2024-11-11T12:34:22.648Z
Learning: Ensure that AI-generated summaries accurately reflect the key changes in the PR, focusing on notable changes such as the removal of unused imports and variables starting with underscores.

Applied to files:

packages/kit/src/build.ts

📚 Learning: 2024-11-05T15:22:54.759Z

Learnt from: GalacticHypernova
Repo: nuxt/nuxt PR: 26468
File: packages/nuxt/src/components/plugins/loader.ts:24-24
Timestamp: 2024-11-05T15:22:54.759Z
Learning: In `packages/nuxt/src/components/plugins/loader.ts`, the references to `resolve` and `distDir` are legacy code from before Nuxt used the new unplugin VFS and will be removed.

Applied to files:

packages/kit/src/build.ts

🧬 Code graph analysis (1)

packages/kit/src/build.ts (1)

packages/kit/src/utils.ts (1)

toArray (2-4)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)

GitHub Check: test-fixtures (ubuntu-latest, built, webpack, default, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, built, rspack, async, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, built, rspack, default, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, built, vite, default, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, built, vite, async, manifest-off, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, dev, vite-env-api, default, manifest-on, json, lts/-1)
GitHub Check: test-fixtures (ubuntu-latest, dev, vite-env-api, async, manifest-on, json, lts/-1)
GitHub Check: release-pkg-pr-new
GitHub Check: test-benchmark
GitHub Check: typecheck (ubuntu-latest, bundler)
GitHub Check: test-size
GitHub Check: code

🔇 Additional comments (5)

packages/kit/src/build.ts (5)

9-10: LGTM: Clean utility types for async support.

The Arrayable and Thenable utility types provide a clear, concise way to handle both synchronous and asynchronous plugin values, improving the API ergonomics for the async plugin support feature.

61-85: LGTM: Proper async handling in webpack/rspack config extension.

The implementation correctly handles both synchronous and asynchronous config callbacks by making the hook handler async and awaiting the user-provided function. This maintains backwards compatibility whilst enabling lazy plugin loading.

130-150: LGTM: Correct async plugin resolution for webpack and rspack.

Both functions properly handle asynchronous plugin factories by making the config callback async and awaiting the factory result. The implementation is consistent and maintains backwards compatibility with synchronous plugin values.

209-213: LGTM: Interface updated to support async plugin factories.

The AddBuildPluginFactory interface correctly reflects the new async-capable signatures, maintaining consistency across all three bundler options (vite, webpack, rspack).

215-227: LGTM: Correctly delegates to async-capable plugin functions.

The addBuildPlugin function requires no changes as it properly delegates to the updated addVitePlugin, addWebpackPlugin, and addRspackPlugin functions, which now handle asynchronous factory resolution.

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

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

pkg-pr-new · 2025-10-31T06:56:48Z

Open in StackBlitz

@nuxt/kit

npm i https://pkg.pr.new/@nuxt/kit@33619

nuxt

npm i https://pkg.pr.new/nuxt@33619

@nuxt/rspack-builder

npm i https://pkg.pr.new/@nuxt/rspack-builder@33619

@nuxt/schema

npm i https://pkg.pr.new/@nuxt/schema@33619

@nuxt/vite-builder

npm i https://pkg.pr.new/@nuxt/vite-builder@33619

@nuxt/webpack-builder

npm i https://pkg.pr.new/@nuxt/webpack-builder@33619

commit: 8bcdbdc

codspeed-hq · 2025-10-31T07:12:18Z

CodSpeed Performance Report

Merging #33619 will not alter performance

_{Comparing feat/async-add-plugin (8bcdbdc) with main (456cc36)}

Summary

✅ 10 untouched

danielroe

👌

(need to investigate lint failure)

feat(kit): support async constractor for adding plugins

cb54995

antfu requested a review from danielroe as a code owner October 31, 2025 06:50

github-actions bot added 4.x enhancement labels Oct 31, 2025

chore: fix missing change

c39fa64

danielroe approved these changes Oct 31, 2025

View reviewed changes

danielroe added 3 commits October 31, 2025 09:54

chore: add eslint disables

f55497d

Merge remote-tracking branch 'origin/main' into feat/async-add-plugin

b9ef708

fix: use correct options interface

8bcdbdc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(kit): support async constructor for adding plugins #33619

feat(kit): support async constructor for adding plugins #33619

antfu commented Oct 31, 2025 •

edited

Loading

Uh oh!

bolt-new-by-stackblitz bot commented Oct 31, 2025

Uh oh!

coderabbitai bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

codspeed-hq bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

danielroe left a comment •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

feat(kit): support async constructor for adding plugins #33619

Are you sure you want to change the base?

feat(kit): support async constructor for adding plugins #33619

Conversation

antfu commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bolt-new-by-stackblitz bot commented Oct 31, 2025

Uh oh!

coderabbitai bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Pre-merge checks and finishing touches

Uh oh!

pkg-pr-new bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #33619 will not alter performance

Summary

Uh oh!

danielroe left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

antfu commented Oct 31, 2025 •

edited

Loading

coderabbitai bot commented Oct 31, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 31, 2025 •

edited

Loading

codspeed-hq bot commented Oct 31, 2025 •

edited

Loading

danielroe left a comment •

edited

Loading