@callstack/nativepack
Advanced tools
A Webpack-based toolkit to build your React Native application with full support of Webpack ecosystem.
A Webpack-based toolkit to build your React Native application with full support of Webpack ecosystem.
@callstack/nativepack is a next generation of Haul — a Webpack-based bundler for React Native applications.
@callstack/nativepack uses Webpack 5 and React Native CLI's plugin system to allow you to bundle your application using Webpack and allow to easily switch from Metro.
Check the base webpack.config.js template, if you're curious how it all looks like.
r keyimport() support with and without React.lazy().entry option.ChunksToHermesBytecodePlugin plugin to automatically transform async chunks to bytecode format.webpack-init commandThe main feature of @callstack/nativepack is Webpack and its ecosystem of loaders, plugins and support for various features like symlinks, aliases etc. However, because @callstack/nativepack is based on Webpack, it is targeted towards advanced users who already know how to use Webpack and want to leverage Webpack ecosystem.
If you're just starting with React Native, it's better to stick with the default solution — Metro, since you probably won't benefit much from switching to Webpack.
@callstack/nativepack was design for the advanced users, as such it exposes low-level API in form of Webpack plugins and utilities, meaning we only give you the tools you need to build React Native application, but the actual configuration and maintenance of said config is on your shoulders.@callstack/nativepack is written to allow you to bundle and run development server directly from Webpack CLI as well by using React Native CLI. You can pick one you want to go with.@callstack/nativepack should be used by seasoned React Native developers with at least basic experience with Webpack.@callstack/nativepack as a foundation for bringing multi-bundle support to React Native, by allowing you to use asynchronous chunks and finally Webpack 5 latest feature — Module Federation.@callstack/nativepack vs MetroBoth Metro and @callstack/nativepack have different approaches for the similar problem — bundling JavaScript code for your React Native application, where Metro is custom-built solution and @callstack/nativepack uses Webpack. As a result there few differences that you should consider when deciding the solution to use:
@callstack/nativepack, but they are supported with Metro See: Known issues.@callstack/nativepack vs Haul@callstack/nativepack is a direct successor to Haul. Therefore we took the experience we gained with Haul while making rather major changes in the approach:
@callstack/nativepack has smaller footprint and allows for greater level of customization, since you have access to the Webpack config.@callstack/nativepack supports Hot Module Replacement + React Refresh, whereas Haul does not.@callstack/nativepack doesn't support any kind of multi-bundling yet, whereas Haul supports legacy implementation of multi-bundling (though it requires to alter React Native source code, so we don't recommend that).@callstack/nativepack delivers better Developer Experience by providing you with more meaningful logs, easier usage and more customizability.On paper, @callstack/nativepack should work with any version of Webpack 5, but we recommend to consult with the compatibility table below.
The table represents versions of webpack for which @callstack/nativepack is confirmed to work correctly.
If you don't see your version, give it a go. If it doesn't work, please open an issue.
webpack | @callstack/nativepack |
|---|---|
5.22.0 | 1.0.x, 1.1.x, 1.2.x |
>=5.29.0 | 1.2.x, |
npm i -D webpack terser-webpack-plugin babel-loader @callstack/nativepack
# or
yarn add -D webpack terser-webpack-plugin babel-loader @callstack/nativepack
react-native.config.js (if it doesn't exists) and paste the following content:
module.exports = {
commands: require('@callstack/nativepack/commands')
};
webpack.config.js based on the template.webpack-bundle/webpack-start commands:
export BUNDLE_COMMAND=webpack-bundle to Bundle React Native code and images phase inside Build Phases in your project XCode config. The final phase should look similar to:
export NODE_BINARY=node
export BUNDLE_COMMAND=webpack-bundle
../node_modules/react-native/scripts/react-native-xcode.sh
bundleCommand: "webpack-bundle" setting to project.ext.react inside android/app/build.gradle file, so it looks similar to:
project.ext.react = [
enableHermes: false, // clean and rebuild if changing
bundleCommand: "webpack-bundle",
bundleInDebug: false
]
npx react-native webpack-start and develop your app.Once you've completed Installation & setup you can:
npx react-native webpack-start.npx react-native webpack-bundle.npx webpack-cli -c webpack.config.js.The API documentation is available at https://callstack-nativepack.netlify.app/.
Asynchronous chunks allows you to split your code into separate files using dynamic import() or by
manually declaring them in Webpack configuration using entry option.
Each chunk's code will get saved separately from the main bundle inside its own .chunk.bundle file and included in the
final application file (ipa/apk). Chunks can help you improve startup time by deferring parts of the application
from being both parsed and evaluated at the start of the app. The chunks code will still be included in the file,
so the total download size the user will have to download from App Store/Google Play will not shrink.
Asynchronous chunks support requires @callstack/nativepack native module to be included in the app
to download/read and evaluate JavaScript code from chunks. By default, the native module should be auto-linked
so there's no additional steps for you to perform. The template webpack.config.js
is configured to support asynchronous chunks as well.
Chunks are fully supported when using Hermes, with one caveat: only the main bundle will be automatically transformed into bytecode bundle by Hermes. By default, all chunks will be left as regular JavaScript files.
If you want all files, including chunks, to be transformed into bytecode ones, you will need to add additional build task/step to XCode/Gradle configuration to transform chunks with Hermes CLI or create a Webpack plugin to transform chunks with Hermes CLI after compilation is finished, but before the process exits.
In the future you will be able to use ChunksToHermesBytecodePlugin for that.
AppRegistry.registerComponent will always require full reload.With Webpack's Hot Module Replacement, the modules don't refresh themselves, but their parents refresh them, meaning for components A -> B (A renders B),
if you edit B, the component A will refresh B, but if you edit component A there's no one to refresh A.
The easiest workaround it create additional component that will simply render your previous root component, eg:
// --- index.js -------------------------------------------
import React from 'react';
import { App } from './App';
// Your new root component, make sure it's exported!
// Editing `Root` will result in full page reload`
export function Root() {
return <App />;
}
AppRegistry.registerComponent('AppName', () => Root);
// --- App.js ---------------------------------------------
import React from 'react';
// -- snip --
// `Root` will refresh `App` so HMR wll work as expected.
export function App() {
// -- snip --
}
After applying Hot Module replacement update, if the error is throw or console.log/console.error is called,
the stack trace that React Native prints will be different — less precise — compared to running the same code after a full reload.
It's because HMR updates (which can consist of multiple files and runtime logic) created by Webpack
have to evaluated at once, so it's impossible for the JavaScript engine to identify from which file each pice of code from HMR update is.
Instead it will fallback to the name of the file that evaluated the update — WebpackHMRClient.ts.
This expected and there's little we can do about it. The stack trace is still correct, but it's less precise.
If you encounter such situation, and you need to get the precise stack trace, you can do a full reload
and reproduce the error or console.log/console.error call.
@callstack/nativepack is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Callstack is a group of React and React Native geeks, contact us at hello@callstack.com if you need any help with these or just want to say hi!
FAQs
A Webpack-based toolkit to build your React Native application with full support of Webpack ecosystem.
We found that @callstack/nativepack demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.