Skip to content

feat(pack): add target: node support for library builds#2683

Merged
xusd320 merged 2 commits into
nextfrom
feat/pack-library-node-target
Mar 12, 2026
Merged

feat(pack): add target: node support for library builds#2683
xusd320 merged 2 commits into
nextfrom
feat/pack-library-node-target

Conversation

@xusd320

@xusd320 xusd320 commented Mar 12, 2026

Copy link
Copy Markdown
Contributor

Add target: node support for library builds with platform-aware runtime backend selection (DOM vs Node.js).

@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces comprehensive support for targeting Node.js environments when building libraries. It enables the build system to generate platform-specific output, ensuring that libraries intended for Node.js utilize a tailored runtime backend that avoids browser-specific APIs. This enhancement significantly expands the utility of library builds by allowing them to seamlessly integrate into Node.js applications while maintaining the benefits of single-file bundling.

Highlights

  • Node.js Target Support: Added comprehensive support for targeting Node.js environments when building libraries, allowing for platform-specific optimizations and runtime behavior.
  • Platform-Aware Runtime Selection: Implemented dynamic selection of runtime backends (DOM for web, Node.js for server) based on the configured target platform, ensuring appropriate APIs are used.
  • New Node.js Runtime Backend: Introduced a dedicated runtime-backend-node.ts for library builds, which is optimized for single-chunk Node.js environments and avoids browser-specific DOM APIs.
  • Context and Chunking Logic Updates: Modified internal module, resolve, and chunking contexts to propagate platform information, enabling the build system to apply correct configurations for Node.js targets.
  • Snapshot Test Refactoring: Refactored existing snapshot tests and added new ones to validate the Node.js library build functionality and ensure correct output for different target platforms.
Changelog
  • crates/pack-api/src/library.rs
    • Imported Platform and server-side context functions.
    • Modified library context functions to dynamically select configurations based on the target platform (Web or Node.js).
    • Passed platform information to the library chunking context.
  • crates/pack-core/js/src/umd/runtime-backend-node.ts
    • Added a new Node.js-specific runtime backend for library builds.
  • crates/pack-core/src/library/chunking_context.rs
    • Added is_node_platform field and methods to LibraryChunkingContext to track the target platform.
  • crates/pack-core/src/library/contexts.rs
    • Updated LibraryChunkingContextOptions to include the target Platform.
    • Modified get_library_chunking_context to pass the platform information to the chunking context builder.
    • Clarified comments regarding the use of EdgeWorker environment for single-file bundling.
  • crates/pack-core/src/library/ecmascript/chunk.rs
    • Updated EcmascriptLibraryEvaluateChunk to pass the is_node_platform flag to the runtime code generation.
  • crates/pack-core/src/library/runtime/runtime_code.rs
    • Modified get_library_runtime_code to select the appropriate runtime backend (runtime-backend-node.ts or runtime-backend-dom.ts) based on the is_node_platform flag.
  • crates/pack-tests/tests/snapshot/basic/target_node/config.json
    • Renamed a snapshot test configuration file.
  • crates/pack-tests/tests/snapshot/basic/target_node/input/index.ts
    • Renamed a snapshot test input file.
  • crates/pack-tests/tests/snapshot/basic/target_node/input/utils.ts
    • Renamed a snapshot test input file.
  • crates/pack-tests/tests/snapshot/basic/target_node/output/_root-of-the-server___1e3d7703.js
    • Renamed and updated a snapshot test output file.
  • crates/pack-tests/tests/snapshot/basic/target_node/output/_root-of-the-server___1e3d7703.js.map
    • Removed a snapshot test output file.
  • crates/pack-tests/tests/snapshot/basic/target_node/output/_turbopack__runtime.js
    • Renamed a snapshot test runtime file.
  • crates/pack-tests/tests/snapshot/basic/target_node/output/_turbopack__runtime.js.map
    • Renamed a snapshot test runtime source map file.
  • crates/pack-tests/tests/snapshot/basic/target_node/output/main.js
    • Removed a snapshot test output file.
  • crates/pack-tests/tests/snapshot/basic/target_node/output/main.js.map
    • Renamed a snapshot test output source map file.
  • crates/pack-tests/tests/snapshot/target_node/basic_node/output/_root-of-the-server___7979544d.js.map
    • Added a new snapshot test source map file.
  • crates/pack-tests/tests/snapshot/target_node/basic_node/output/main.js
    • Added a new snapshot test output file.
  • crates/pack-tests/tests/snapshot/target_node/library_build_node_target/config.json
    • Added a new snapshot test configuration for Node.js library builds.
  • crates/pack-tests/tests/snapshot/target_node/library_build_node_target/input/helper.js
    • Added a new snapshot test helper file.
  • crates/pack-tests/tests/snapshot/target_node/library_build_node_target/input/index.js
    • Added a new snapshot test entry file.
  • crates/pack-tests/tests/snapshot/target_node/library_build_node_target/output/main.js
    • Added the expected output JavaScript file for Node.js library snapshot tests.
  • crates/pack-tests/tests/snapshot/target_node/library_build_node_target/output/main.js.map
    • Added the expected source map file for Node.js library snapshot tests.
Activity
  • No specific activity has been recorded for this pull request yet.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds support for target: node in library builds, enabling platform-aware runtime backend selection. The changes are well-structured and include new test cases for the Node.js target. I've identified a few areas in crates/pack-api/src/library.rs where code duplication can be reduced to improve maintainability. My review includes specific suggestions for refactoring.

Comment thread crates/pack-api/src/library.rs
Comment thread crates/pack-api/src/library.rs
Comment thread crates/pack-api/src/library.rs
@xusd320 xusd320 force-pushed the feat/pack-library-node-target branch 8 times, most recently from 6477a94 to 18e1551 Compare March 12, 2026 08:13
- Make library endpoint platform-aware: dispatch compile-time info,
  module options, and resolve options based on Platform (Web/Node)
- Create Node.js-compatible runtime backend (runtime-backend-node.ts)
  without DOM APIs (no document.createElement, importScripts, etc.)
- Conditionally select runtime backend in runtime_code.rs based on
  is_node_platform flag on LibraryChunkingContext
- Always use EdgeWorker environment for library chunking context
  (ChunkLoading::Edge prevents async chunk splitting for single-file output)
- Move and organize target_node snapshot tests under target_node/
- Add library_build_node_target test with dynamic import() to verify
  single-chunk enforcement and correct Node.js built-in externals
@xusd320 xusd320 force-pushed the feat/pack-library-node-target branch from 18e1551 to 915e4c1 Compare March 12, 2026 08:14
@xusd320 xusd320 enabled auto-merge (squash) March 12, 2026 09:27
@xusd320 xusd320 merged commit 9d1a371 into next Mar 12, 2026
19 checks passed
@xusd320 xusd320 deleted the feat/pack-library-node-target branch March 12, 2026 09:42
@github-actions

Copy link
Copy Markdown

📊 Performance Benchmark Report (with-antd)

Utoopack Performance Report (Intelligent)

Report ID: utoopack_performance_report_20260312_094651
Generated: 2026-03-12 09:46:51
Trace File: trace_antd.json (0.6GB, 3.32M events)
Test Project: examples/with-antd


Executive Summary

Key Findings

Metric Value Assessment
Total Wall Time 8,571.0 ms Baseline
Total Thread Work (de-duped) 27,975.4 ms Non-overlapping busy time
Effective Parallelism 3.3x thread_work / wall_time
Working Threads 5 Threads with actual spans
Thread Utilization 65.3% 🆗 Average
Total Spans 1,658,050 All B/E + X events
Meaningful Spans (>= 10us) 573,672 (34.6% of total)
Tracing Noise (< 10us) 1,084,378 (65.4% of total)

Workload Distribution by Tier

Category Tasks Total Time (ms) % of Thread Work
P0: Runtime/Resolution 0 0.0 0.0%
P1: I/O & Heavy Tasks 39,789 3,789.5 13.5%
P3: Asset Pipeline 36,841 3,478.5 12.4%
P4: Bridge/Interop 0 0.0 0.0%
Other 497,042 23,136.7 82.7%

🤖 AI Intelligent Attributions

New section mapping granular tasks to bottlenecks.

Top 10 Batching Candidates

These highly-called tasks are dominated by a single parent. If the parent can batch them into one call, it drastically reduces scheduler overhead.

Task Name Count Top Caller (Attribution) Avg P95 Total Time
analyze ecmascript module 36,894 process module (76%) 100.5 us 0.29 ms 3,706.6 ms

Top 20 Tasks by Total Duration

Total (ms) Count Avg (us) P95 (ms) Max (ms) % Work Task Name Top Caller
8,373.3 211,036 39.7 0.1 12.5 29.9% module write all entrypoints to disk (1%)
4,157.4 71,473 58.2 0.1 243.6 14.9% process module module (15%)
3,706.6 36,894 100.5 0.3 243.5 13.2% analyze ecmascript module process module (76%)
2,832.0 25,063 113.0 0.4 89.4 10.1% code generation chunking (7%)
1,877.0 68,395 27.4 0.0 6.1 6.7% resolving module (31%)
1,676.5 61,530 27.2 0.0 7.7 6.0% internal resolving resolving (30%)
1,417.3 33,725 42.0 0.1 10.4 5.1% precompute code generation code generation (31%)
1,414.3 15,016 94.2 0.3 47.9 5.1% chunking write all entrypoints to disk (0%)
1,312.3 8,569 153.1 0.1 313.2 4.7% write all entrypoints to disk None (0%)
1,139.2 13,740 82.9 0.3 128.4 4.1% compute async module info chunking (0%)
1,058.7 8,091 130.9 0.5 31.8 3.8% parse ecmascript analyze ecmascript module (26%)
635.4 11,595 54.8 0.1 43.5 2.3% compute async chunks compute async chunks (0%)
295.0 1,936 152.4 0.4 17.9 1.1% generate source map code generation (96%)
106.7 848 125.8 0.0 22.0 0.4% compute binding usage info write all entrypoints to disk (0%)
71.7 2,168 33.1 0.0 3.1 0.3% read file parse ecmascript (91%)
58.4 197 296.7 0.4 17.9 0.2% make production chunks chunking (3%)
54.9 1,877 29.2 0.0 8.1 0.2% collect mergeable modules compute merged modules (0%)
41.0 14 2929.3 10.1 12.1 0.1% apply effects write all entrypoints to disk (7%)
40.1 13 3087.1 10.2 11.9 0.1% write file apply effects (100%)
31.1 10 3110.1 14.5 17.9 0.1% compute merged modules make production chunks (100%)

Duration Distribution

Range Count Percentage
< 10us (noise) 1,084,378 65.4%
10us - 100us 546,611 33.0%
100us - 1ms 22,603 1.4%
1ms - 10ms 4,355 0.3%
10ms - 100ms 96 0.0%
> 100ms 7 0.0%

Action Items

  1. [P0] Use Batching Candidates to pinpoint specific files needing try_join or reduced #[turbo_tasks::function] limits.
  2. [P1] Inspect P95 (ms) for heavy monolith tasks. Focus on long-tail outliers rather than averages.

Report generated by Intelligent Utoopack Performance Analysis Agent

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants