feat(rslib): handle hashbang / react directives natively

[fi3ework]

Summary

related Rslib PR web-infra-dev/rslib#1331.

Overview

This PR adds native support for handling hashbang (#!/usr/bin/env node) and React directives ("use client", "use server" and whatever the very first comment that starts with "use ") in both RslibPlugin and EsmLibraryPlugin.

Key Features

1. Hashbang Support

• Automatically extracts hashbang from module source and places it at the first line of output
• Sets executable file permissions (0o755) for files with hashbang
• Works across all output formats (CJS, ESM)

2. React Directives Support

• Extracts and preserves React directives like "use client" and "use server"
• Ensures directives are placed at the beginning of the output (after hashbang if present, after "use strict" if present)
• Always outputs directives with double quotes

Implementation Details

Parser Plugins:

implementated in RslibPlugin, so RslibPlugin is required, which means it won't work with EsmLibraryPlugin alone.

• HashbangParserPlugin: Extracts hashbang from source code
• ReactDirectivesParserPlugin: Extracts React directives from source code
• Both store extracted data in module's build_info.extras

Render Integration:

• RslibPlugin: Direct source manipulation during render phase for non-ESM formats
• EsmLibraryPlugin: Uses InitFragment mechanism for ESM format
• Both plugins have similar logic intentionally (documented with comments) as they handle different output formats with different rendering mechanisms

File Permissions:

• Implemented in CompilerAssetEmitted hook
• Uses rspack_fs::FilePermissions for cross-platform compatibility

Utility Functions:

• Added get_module_hashbang() and get_module_directives() in rspack_core
• Support for both regular modules and concatenated modules

Related links

Checklist

• Tests updated (or not required).
• Documentation updated (or not required).

[netlify]

✅ Deploy Preview for rspack canceled.

Name	Link
🔨 Latest commit	520b2e7
🔍 Latest deploy log	https://app.netlify.com/projects/rspack/deploys/6916bd5795f6030008ea575c

[github-actions]

📦 Binary Size-limit

Comparing 520b2e7 to test: rename test script from 'test:rstest' to 'test:base' (#12194) by neverland

❌ Size increased by 18.00KB from 47.45MB to 47.47MB (⬆️0.04%)

[codspeed-hq]

CodSpeed Performance Report

Merging #12168 will not alter performance

_{Comparing hashbang (520b2e7) with main (d2ae8f2)}

Summary

✅ 17 untouched

[Copilot]

Pull Request Overview

This PR adds native support for handling hashbang (#!/usr/bin/env node) and React directives ("use client", "use server") in rslib by implementing parser plugins that extract these elements from source code and re-insert them at the correct positions in the output, along with automatic file permission setting for hashbang files.

Key Changes:

• Added HashbangParserPlugin and ReactDirectivesParserPlugin to extract hashbang and directives during parsing
• Implemented render hooks in both RslibPlugin and EsmLibraryPlugin to re-inject extracted content at the beginning of output files
• Added automatic chmod 0o755 for files with hashbang via the CompilerAssetEmitted hook

Reviewed Changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/rspack-test/configCases/rslib/react-directives/test.js	Test suite for React directives handling across CJS and ESM formats
tests/rspack-test/configCases/rslib/react-directives/test.config.js	Test configuration specifying bundle selection
tests/rspack-test/configCases/rslib/react-directives/rspack.config.js	Build configurations for testing directives in CJS, ESM, and ESM with EsmLibraryPlugin
tests/rspack-test/configCases/rslib/react-directives/index.js	Source file with "use client" directive for testing
tests/rspack-test/configCases/rslib/hashbang-and-chmod/test.js	Test suite for hashbang extraction and executable permissions
tests/rspack-test/configCases/rslib/hashbang-and-chmod/test.config.js	Test configuration for hashbang tests
tests/rspack-test/configCases/rslib/hashbang-and-chmod/rspack.config.js	Build configurations for testing hashbang across formats
tests/rspack-test/configCases/rslib/hashbang-and-chmod/index.js	Source file with hashbang for testing
crates/rspack_plugin_rslib/src/react_directives_parser_plugin.rs	Parser plugin that extracts directives starting with "use " from source code
crates/rspack_plugin_rslib/src/plugin.rs	Integration of parser plugins and render hooks, plus asset_emitted hook for chmod
crates/rspack_plugin_rslib/src/lib.rs	Module exports for new parser plugins
crates/rspack_plugin_rslib/src/hashbang_parser_plugin.rs	Parser plugin that extracts hashbang from source code
crates/rspack_plugin_rslib/Cargo.toml	Added rspack_fs dependency for file permissions
crates/rspack_plugin_esm_library/src/render.rs	Added hashbang and directives handling via InitFragments for ESM output
crates/rspack_core/src/utils/mod.rs	Added utility functions to retrieve hashbang and directives from module build_info
crates/rspack_binding_api/src/fs_node/write.rs	Updated chmod call to properly wrap arguments with FnArgs
crates/rspack_binding_api/src/fs_node/node.rs	Added type alias for chmod function signature
Cargo.lock	Updated dependencies for rspack_plugin_rslib

---

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