---
url: /docs/features/code-splitting.md
---

# Code splitting

Code Splitting is a technique that splits the code into multiple files, which can be loaded on
demand and in parallel.

It can be used to:

- Optimize the initial size of the application and to improve the startup performance by deferring
  the parsing (only with JSC) and execution (JSC and Hermes) of the non-critical code.
- Dynamically deliver content and features to the users based on runtime factors: user's role,
  subscription plan, preferences etc.
- **For developers and companies**: split and isolate pieces of the product to improve scalability
  and reduce coupling.

Code Splitting is one of the most important features in Re.Pack, and it's based on Webpack's
infrastructure as well as the native module
that allows to execute the additional code on the same JavaScript context (same React Native
instance).

:::info

For dynamic feature delivery, Code Splitting should be used as a mean to optimize the user
experience by deferring the features or deliver existing features only to a subset of users.

:::

Code Splitting with Re.Pack is not designed to add new features dynamically without doing the
regular App Store or Play store release. It can be used to deliver fixes or tweaks to additional
(split) code, similarly to Code Push, but you should not add new features with it.

:::caution

Using Code Splitting to deliver new features without a regular App Store release is likely
going to violate Apple's App Store Terms and your application might be rejected or banned.

:::

:::tip

You should provide access to all the features for the App Store review process.

Also, it might be beneficial to highlight that all split features are closely integrated with
application and cannot work in isolation - you don't want to introduce confusion that your
application might compete with Apple's App Store.

On that note, you might want to avoid using terms like _mini-app_ or _mini-app store_ in favour of
_modules_, _components_, _plugins_ or simply _features_.

:::

## Usage

The specific implementation of Code Splitting in your application can be different and should account for your project's specific needs, requirements and limitations.

In general, we can identify 3 main categories of implementation. All of those approaches are based on the same underlying mechanism: Re.Pack's [`ScriptManager`](/api/runtime/script-manager.md) and the native module for it.

:::tip

Use [Glossary of terms](/docs/resources/glossary.md) to better understand the content of this documentation.

:::

### Generic usage

On a high-level, all functionalities that enable usage of Webpack's Code Splitting, are powered by
Re.Pack's [`ScriptManager`](/api/runtime/script-manager.md), which consists of the JavaScript part and the native part.

The [`ScriptManager`](/api/runtime/script-manager.md) has methods which allows to:

1. Download and execute script - [`loadScript`](/api/runtime/script-manager.md#loadscript)
2. Prefetch script (without executing immediately) - [`prefetchScript`](/api/runtime/script-manager.md#prefetchscript)
3. Resolve script location - [`resolveScript`](/api/runtime/script-manager.md#resolvescript)
4. Invalidate cache - [`invalidateScripts`](/api/runtime/script-manager.md#invalidatescripts)

In order to provide this functionalities, a resolver has to be added using [`ScriptManager.shared.addResolver`](/api/runtime/script-manager.md#addresolver):

```ts
import { ScriptManager, Script } from "@callstack/repack/client";

ScriptManager.shared.addResolver(async (scriptId, caller) => {
  // In dev mode, resolve script location to dev server.
  if (__DEV__) {
    return {
      url: Script.getDevServerURL(scriptId),
      cache: false,
    };
  }

  return {
    url: Script.getRemoteURL(
      `http://somewhere-on-the-internet.com/${scriptId}`
    ),
  };
});
```

If the `storage` is provided, the returned `url` from `resolve` will be used for cache management.
You can read more about it in [Caching and Versioning](#caching-and-versioning).

:::info

Do not instantiate `ScriptManager` yourself - use `ScriptManager.shared` to get access to an instance.

:::

Under the hood, the way a script gets loaded can be summarized as follows:

1. `ScriptManager.shared.loadScript(...)` gets called, either:
   - Automatically by the dynamic `import(...)` function handled by Webpack, when using [Async chunks approach](#async-chunks)
   - Manually when using [Scripts approach](#scripts) or [Module Federation](#module-federation)
2. `ScriptManager.shared.loadScript(...)` is called `scriptId` and `caller` arguments, which are either provided by:
   - Webpack, based on it's internal naming logic or a [magic comment: `webpackChunkName`](https://webpack.js.org/migrate/5/#using--webpackchunkname--)
   - Manually
3. `ScriptManager.shared.loadScript(...)` resolves the chunk location using `ScriptManager.shared.resolveScript(...)`.
4. The resolved location is compared against previous location of that script, if and only if, `storage` was provided and the script was resolved before.
5. The resolved location is passed to the native module, which downloads if necessary and executes the script.
6. Once the code has been executed the `Promise` returned by `ScriptManager.shared.loadScript(...)` gets resolved.

:::info

[`ScriptManager.shared.prefetchScript(...)`](/api/runtime/script-manager.md#prefetchscript) follows
the same behavior except for #6, where it only downloads the file and doesn't execute it.

:::

### Approaches

There are generally 3 approaches to Code Splitting with Webpack and Re.Pack. Keep in mind that the
actual code you will have to create might be slightly different, depending on your project's
requirements, needs and limitations.

Those approaches should be used as a base for your Code Splitting implementation.

:::tip

It's recommended to read [Generic usage](#generic-usage) first, to understand it on a high-level and
get the necessary context.

:::

#### Async chunks

Async chunks (or asynchronous chunks) are the easiest Code Splitting approach. They are usually
created by using dynamic `import(...)` function, which makes them extremely easy to introduce it
into the codebase.

The async chunks are created alongside the main bundle as part of a single
Webpack compilation, making it a great choice for a modular applications where all the code is
developed in-house.

The usage of async chunks essentially boils down to calling `import(...)` in your code, for example:

```js
const myChunk = await import("./myChunk.js");
```

Async chunks created by dynamic `import(...)` function can be nicely integrated using `React.lazy`
and `React.Suspense`:

```jsx
// MyChunk.js
export default function MyChunk(props) {
  return /* ... */;
}

// App.js
const MyChunk = React.lazy(() => import("./MyChunk.js"));

function App() {
  return (
    <React.Suspense fallback={<Text>Loading...</Text>}>
      <MyChunk /* someProp="someValue" */ />
    </React.Suspense>
  );
}
```

For each file in the dynamic `import(...)` function a new chunk will be created - those chunks will
be remote chunks by default.

:::tip

You can learn more about local and remote chunks in the dedicated [Local vs Remote chunks guide](#local-vs-remote-chunks).

:::

:::tip

To learn more or use async chunks in your project, check out our [dedicated Async chunks guide](#guide-async-chunks).

:::

:::tip

To see `import(...)`, `React.lazy` and `React.Suspense` in action, check out
[Re.Pack's `TesterApp`](https://github.com/callstack/repack/blob/main/apps/tester-app/src/asyncChunks/AsyncContainer.tsx).

:::

:::caution

Don't forget to add resolver using [`ScriptManager.shared.addResolver`](/api/runtime/script-manager.md#addresolver)!

:::

#### Scripts

This approach allows to execute arbitrary code in your React Native application.
It's a similar concept as adding a new `<script>` element to a Web page.

Those scripts can be written in-house or externally, bundled using Webpack or a different bundler.
This also means that scripts can be created as part of separate Webpack compilations, or separate
build pipelines, from separate codebases and repositories.

:::warning

Scripts should only be used by advanced users with deep Webpack knowledge and experience.

Scripts give a lot of flexibility but it also means the support for them is limited. It's not possible for Re.Pack's
contributors to support all potential setups using this approach.

:::

:::caution

Beware, with dynamic scripts **there's no dependency sharing by default**. If you want your scripts
to reuse existing dependencies from the main bundle, it's up to you to figure out how to do it.
A good starting point would be:

- [https://webpack.js.org/configuration/externals/](https://webpack.js.org/configuration/externals/)
- [https://webpack.js.org/plugins/dll-plugin/](https://webpack.js.org/plugins/dll-plugin/)

:::

Loading a script is as simple as running a single function:

```js
await ScriptManager.shared.loadScript("my-script");
console.log("Script loaded");
```

And adding a resolver to the [`ScriptManager`](/api/runtime/script-manager.md#addResolver) to resolve your
scripts:

```js
import { ScriptManager, Script } from "@callstack/repack/client";

ScriptManager.shared.addResolver(async (scriptId) => {
  if (scriptId === "my-script") {
    return {
      url: Script.getRemoteURL("https://my-domain.dev/my-script.js", {
        excludeExtension: true,
      }),
    };
  }
});
```

#### Module Federation

Use [Module Federation](/docs/features/module-federation.md) document for information on adoption of Module Federation in React Native projects with Re.Pack.

## Guide: Async chunks

Let's assume, we are building an E-Learning application with specific functionalities for a student
and for a teacher. Both student and a teacher will get different UIs and different features, so it
would make sense to isolate the student's specific code from the teacher's. That's were Code
Splitting comes into play - we can use dynamic `import(...)` function together with `React.lazy` and
`React.Suspense` to conditionally render the student and the teacher sides based on the user's role.
The code for the student and the teacher will be put into a remote async chunk, so that the initial
download size will be smaller.

:::tip

It's recommended to read:

- [Concept](#concept)
- [Generic usage](#generic-usage)
- [Async chunks usage](#async-chunks)

first, to understand Code Splitting, usage on a high-level and get the necessary context.

:::

:::tip

Before you begin, make sure the Re.Pack's native module is linked into your application:

- [https://reactnative.dev/docs/linking-libraries-ios](https://reactnative.dev/docs/linking-libraries-ios)
- [https://github.com/react-native-community/cli/blob/master/docs/autolinking.md](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md)

:::

### Source code

Let's use the following code for the student's side:

```jsx
// StudentSide.js
import * as React from "react";
import { View, Text } from "react-native";

export default function StudentSide({ user }) {
  return (
    <View style={{ flex: 1 }}>
      <Text>Hello {user.name}!</Text>
      <Text>You are a student.</Text>
      {/* ...more student related code */}
    </View>
  );
}
```

And a code for the teacher's side:

```jsx
// TeacherSide.js
import * as React from "react";
import { View, Text } from "react-native";

export default function TeacherSide({ user }) {
  return (
    <View style={{ flex: 1 }}>
      <Text>Hello {user.name}!</Text>
      <Text>You are a teacher.</Text>
      {/* ...more teacher related code */}
    </View>
  );
}
```

Now in our parent component, which will be common for both the student and the teacher:

```jsx
// Home.js
import * as React from "react";
import { Text } from "react-native";

const StudentSide = React.lazy(() =>
  import(/* webpackChunkName: "student" */ "./StudentSide.js")
);

const TeacherSide = React.lazy(() =>
  import(/* webpackChunkName: "teacher" */ "./TeacherSide.js")
);

export function Home({ user }) {
  const Side = React.useMemo(
    () =>
      user.role === "student" ? (
        <StudentSide user={user} />
      ) : (
        <TeacherSide user={user} />
      ),
    [user]
  );

  return (
    <React.Suspense fallback={<Text>Loading...</Text>}>
      <Side />
    </React.Suspense>
  );
}
```

Since we are using Webpack's magic comments, we need to make sure Babel is not removing those.
Add `comments: true` to your Babel config, for example:

```js
module.exports = {
  presets: ["module:metro-react-native-babel-preset"],
  comments: true,
};
```

At this point all the code used by `StudentSide.js` will be put into `student.chunk.bundle` and
`TeacherSide.js` into `teacher.chunk.bundle`.

Before we can actually render out application, we need to add resolver using [`ScriptManager.shared.addResolver(...)`](/api/runtime/script-manager.md#addresolver),
so it can resolve the chunks:

```js
// index.js
import { AppRegistry } from "react-native";
import { ScriptManager, Script } from "@callstack/repack/client";
import AsyncStorage from "@react-native-async-storage/async-storage";
import App from "./src/App"; // Your application's root component
import { name as appName } from "./app.json";

ScriptManager.shared.setStorage(AsyncStorage);
ScriptManager.shared.addResolver(async (scriptId) => {
  // `scriptId` will be either 'student' or 'teacher'

  // In dev mode, resolve script location to dev server.
  if (__DEV__) {
    return {
      url: Script.getDevServerURL(scriptId),
      cache: false,
    };
  }

  return {
    url: Script.getRemoteURL(
      `http://somewhere-on-the-internet.com/${scriptId}`
    ),
  };
});

AppRegistry.registerComponent(appName, () => App);
```

This code will allow Re.Pack's [`ScriptManager`](/api/runtime/script-manager.md) to
actually locate your chunks for the student and the teacher, and download them.

When bundling for production/release, all remote chunks, including `student.chunk.bundle` and
`teacher.chunk.bundle` will be copied to `<projectRoot>/build/output/<platform>/remote` by default,
for example: `<projectRoot>/build/output/ios/student.chunk.bundle`.

You should upload files from this directory to a remote server or a CDN from where `ScriptManager`
will download them.

:::tip

You can change this directory and/or mark chunks as local. Refer to dedicated [Local vs Remote chunks guide](#local-vs-remote-chunks)
for more information.

:::

## Local vs Remote chunks

Each chunk created by using dynamic `import(...)` function can be either remote or a local chunk.

**By default all chunks are remote.**

### Chunk naming

Regardless of the chunk's type, it's important to understand how chunks are named.

:::info

Chunk naming is handled solely by Webpack. Re.Pack does not alter or customize chunk names in any way.

:::

By default, chunk name is inferred by Webpack based on the source filename. For example if you have a file
`./src/Button.js`, the inferred name would be `src_Button_js`. This human-readable chunk name will only be used
in development though. By default, Webpack in production, minimizes chunk names to numbers to save space,
meaning `src_Button_js` chunk in production might look like `137`.

This behavior is fine for Web, but in React Native with `ScriptManager`, it's not ideal, because we don't know what
this number will be in production.

There are 2 options to address this problem:

1. Set [`optimization.chunkIds`](https://webpack.js.org/configuration/optimization/#optimizationchunkids) option to `named` in Webpack config.
2. Use `/* webpackChunkName: "<name>" */` magic comment in `import(...)`.

:::tip

You can use both `optimization.chunkIds` and `webpackChunkName` comment at the same time. They are not mutually exclusive.

:::

:::tip

Chunk extension can be configured in [`output.chunkFilename`](https://webpack.js.org/configuration/output/#outputchunkfilename), which is set to `.chunk.bundle` by default.
It's usually **not** necessary to modify it.

:::

#### Named `chunkIds` config option

Setting [`optimization.chunkIds`](https://webpack.js.org/configuration/optimization/#optimizationchunkids) option to `named` in your Webpack config will
force Webpack to always use the human-readable form for the name of the chunks.

:::info

In version `3.x`, Re.Pack's templates for Webpack config have `chunkIds` is set to `named` by default.

:::

```js
/* ... */

export default (env) => {
  /* ... */

  return {
    /* ... */

    optimization: {
      /* ... */

      chunkIds: "named",
    },

    /* ... */
  };
};
```

:::tip

Keep in mind that, `webpackChunkName` magic comment will always take precedence, so even if you have `chunkIds: 'named'`, Webpack will use name in `webpackChunkName`
comment for that chunk instead of the inferred one.

:::

#### `webpackChunkName` magic comment

`webpackChunkName` magic comment allows you to provide your own custom name that should be used for the chunk when calling `import(...)` function:

```js
import(/* webpackChunkName: "button" */ "./Button");
```

This example will result in chunk being named `button`, so the filename with extension will be `button.chunk.bundle`.

:::tip

You can use `webpackChunkName` magic comment to provide your custom name, regardless of the `optimization.chunkIds` option.
`webpackChunkName` will always take precedence.

:::

### Remote chunks

By default all chunks are remote chunks, meaning they are not bundled into the application and will be downloaded from the remote location (usually the Internet) on demand.
This helps with reducing the initial application size, especially if you have logic or features that only a subset of users will use - it doesn't make sense for everyone else
to always have to download the code (together with the application) they won't need.

All remote chunks are stored under `<projectRoot>/build/output/<platform>/remotes` by default. For example if `button.chunk.bundle` is a remote chunk, it will be stored under:
`<projectRoot>/build/output/ios/remotes/button.chunk.bundle` for iOS.

You can customize this by providing [`extraChunks`](/api/plugins/repack.md#extrachunks) to [`RepackPlugin`](/api/plugins/repack.md):

```js
/* ... */

export default (env) => {
  /* ... */

  return {
    /* ... */

    plugins: [
      new Repack.RepackPlugin({
        /* ... */

        extraChunks: [
          {
            test: /.*/,
            type: "remote",
            outputPath: path.join("my/custom/path"),
          },
        ],
      }),
    ],
  };
};
```

This example, will mark all chunks as remote ones and store them under `<projectRoot>/my/custom/path`.

If `outputPath` in `extraChunks` is a relative path, it will be joined with the value of `context` property, which is set to root directory of your project by default.
You can also provide an absolute path, in which case, it won't be modified in any way and used as is.

:::tip

You can provide multiple `type: 'remote'` specs - see [Advanced example](#advanced-example) for more info.

:::

### Local chunks

In some situations, having chunks as remote ones is not ideal. For example, if you know that majority of the users will need a specific chunk you can mark it as local.

Local chunks will always be included in the final application (`.ipa` or `.apk`) file alongside main bundle. This can save mobile data usage and make your application feel
faster (in cases where network connection is degraded), but you will still benefit from improved startup, because the JavaScript engine will defer parsing and evaluation of
local chunks until they are actually needed.

:::tip

If you're using Hermes and you compile your code into bytecode bundles, it's better **not** to use local chunks and instead make the code a part of the main bundle.

Using **local** chunks with Hermes and bytecode bundles, will likely result **in worse performance**.

:::

You can customize which chunk should be local by providing [`extraChunks`](/api/plugins/repack.md#extrachunks) option in [`RepackPlugin`](/api/plugins/repack.md) configuration:

```js
/* ... */

export default (env) => {
  /* ... */

  return {
    /* ... */

    plugins: [
      new Repack.RepackPlugin({
        /* ... */

        extraChunks: [
          {
            include: /^.+\.local$/,
            type: "local",
          },
          {
            // IMPORTANT!
            exclude: /^.+\.local$/,
            type: "remote",
            outputPath: path.join("build/output", platform, "remote"), // Default path
          },
        ],
      }),
    ],
  };
};
```

The example above will make all chunks matching the RegExp `/^.+\.local$/` a local chunks, for example `student.local` (`student.local.chunk.bundle`) will be a local chunk, whereas everything else will become a remote.

:::warning

Specifying `extraChunks` will override any defaults - you must configure `remote` chunks yourself as well, otherwise they won't be stored anywhere!

:::

Once you have some chunks as local, you need to alter the resolver in [`ScriptManager.shared.addResolver`](/api/runtime/script-manager.md#addresolver):

```js
import { ScriptManager, Script } from "@callstack/repack/client";

ScriptManager.shared.addResolver(async (scriptId) => {
  // In development, get all the chunks from dev server.
  if (__DEV__) {
    return {
      url: Script.getDevServerURL(scriptId),
      cache: false,
    };
  }

  // In production, get chunks matching the regex from filesystem.
  if (/^.+\.local$/.test(scriptId)) {
    return {
      url: Script.getFileSystemURL(scriptId),
    };
  } else {
    return {
      url: Script.getRemoteURL(`https://my-domain.dev/${scriptId}`),
    };
  }
});
```

:::tip

To avoid having to repeat the RegExp, you can create a new `.js` or `.json` file, export the RegExp and use the file both in the source code as well as in the Webpack config.

Check out the [`local-chunks` example](https://github.com/callstack/repack-examples) for concrete implementation.

:::

### Advanced example

You can mix multiple `type: 'local'` and `type: 'remote'` specs using `test`, `include` and `exclude` to match different chunks:

```js
/* ... */

export default (env) => {
  /* ... */

  return {
    /* ... */

    plugins: [
      new Repack.RepackPlugin({
        /* ... */

        extraChunks: [
          {
            // Make all student related chunks local.
            include: ["student", /^student-.+$/],
            type: "local",
          },
          {
            // Anything not student related should be remote and stored under
            // `<projectRoot>/build/output/<platform>/remotes/core`.
            exclude: /^student-.+$/,
            type: "remote",
            outputPath: path.join("build/output", platform, "remotes/core"),
          },
          {
            // All teacher related chunks should be remote and stored under
            // `<projectRoot>/build/output/<platform>/remotes/teacher`.
            test: /^teacher.*$/,
            type: "remote",
            outputPath: path.join("build/output", platform, "remotes/teacher"),
          },
        ],
      }),
    ],
  };
};
```

Use the table below for examples, how the config above would treat different chunks:

| Name                   | `type`   | `outputPath`                                            |
| ---------------------- | -------- | ------------------------------------------------------- |
| `student`              | `local`  | -                                                       |
| `student-extensions`   | `local`  | -                                                       |
| `components`           | `remote` | `<projectRoot>/build/output/<platform>/remotes/core`    |
| `utils`                | `remote` | `<projectRoot>/build/output/<platform>/remotes/core`    |
| `teacher`              | `remote` | `<projectRoot>/build/output/<platform>/remotes/teacher` |
| `teacher-affiliations` | `remote` | `<projectRoot>/build/output/<platform>/remotes/teacher` |

:::tip

`test`, `include` and `exclude` properties behave in the same way as those in [Webpack's loader rules](https://webpack.js.org/configuration/module/#rule-conditions):

- `test: string | RegExp | Array<string | RegExp>` must match if specified
- `include: string | RegExp | Array<string | RegExp>` must match if specified
- `exclude: string | RegExp | Array<string | RegExp>` must **not** match if specified

:::

## Caching and versioning

The caching mechanism in Re.Pack prevents scripts over-fetching, which helps reducing
bandwidth usage, specially since they can easily take up multiple MBs od data.

Providing `storage` options to
[`ScriptManager.shared.setStorage`](/api/runtime/script-manager.md#setstorage) will enable
caching of downloaded script. The `storage` option accepts anything with similar
API to `AsyncStorage`'s `getItem`, `setItem` and `removeItem` functions.

By default, [`ScriptManager`](/api/runtime/script-manager.md) will compare the `method`/`url`/`query`/`header` or `body`
returned by `resolve` with the values stored in `storage` to determine if downloading is
necessary. Skipping the download will only happen, if the values are equal, meaning you can introduce
versioning by changing the `url`, for example:

```js
import { ScriptManager, Script } from "@callstack/repack/client";

ScriptManager.shared.setStorage(AsyncStorage);
ScriptManager.shared.addResolver(async (scriptId) => {
  const { version } = await getRemoteConfig();

  return {
    url: Script.getRemoteURL(`http://my-domain.dev/v${version}/${scriptId}`),
  };
});
```

Or by keeping the base URL inside remote config:

```js
import { ScriptManager, Script } from "@callstack/repack/client";

ScriptManager.shared.setStorage(AsyncStorage);
ScriptManager.shared.addResolver(async (scriptId) => {
  const { baseURL } = await getRemoteConfig();

  return {
    url: Script.getRemoteURL(`${baseURL}/${scriptId}`),
  };
});
```

:::caution

Versioning should be use with caution. If you upload a new version of a script and it happens that old main bundle is not compatible with new files, you
might end up with broken application or crashes.

:::

Usually cache invalidation happens automatically, but it's possible to invalidate chunk manually as
well using [`ScriptManager.shared.invalidateScripts(...)`](/api/runtime/script-manager.md#invalidatescripts),
which removes the scripts from filesystem and from the `storage`.

:::warning

Be careful what scripts are you manually invalidating - it's possible to remove local scripts from
filesystem using this API.

:::



---
url: /docs/features/dev-server.md
---

# DevServer

Re.Pack 5 has it's own dev server that contain all features as Metro packager does, or even more in some cases.

## Features

Re.Pack's dev server supports both Rspack and webpack and provides essential development features:

- **Hot Module Reloading**: Instantly reflects code changes in the app
- **Source Maps**: Enables proper debugging with source code mapping
- **Multiple Platforms**: Supports both iOS and Android development
- **Development Tools**: Integrated with React Native DevTools

:::tip Looking for DevServer configuration?

For complete DevServer configuration options and API reference, check out the [DevServer API documentation](/api/dev-server.md).

:::

## Usage

To start the dev server, you can use the following command:


```sh [npm]
npm run react-native start
```

```sh [yarn]
yarn react-native start
```

```sh [pnpm]
pnpm react-native start
```

```sh [bun]
bun react-native start
```

To get the full list of options available, check out the [`start`](/api/cli/start.md)'s command documentation.

:::info

The command is started through the React Native Community CLI's `start` command, which is overridden [inside `react-native.config.js`](/docs/getting-started/quick-start.md#2-commands) to spawn Re.Pack's dev server.

:::

### Automatic ADB reverse

Re.Pack automatically handles ADB reverse port forwarding for Android development. When starting the dev server, it will wait for devices to be connected (`adb wait-for-device`) and then automatically run `adb reverse` on all connected Android devices.

### Keyboard shortcuts

You can use various keyboard shortcuts inside a terminal to interact with the dev server.

| Key | Description                                                                               |
| --- | ----------------------------------------------------------------------------------------- |
| `r` | Reloads the app on connected device/simulator                                             |
| `d` | Opens the developer menu (same as shaking device)                                         |
| `j` | Opens the [React Native DevTools](/docs/features/devtools.md) for debugging and profiling |
| `a` | Runs `adb reverse` to enable communication between Android device and dev server          |



---
url: /docs/features/devtools.md
---

# React Native Devtools

React Native Devtools are currently recommended way of debugging your React Native application. Re.Pack comes with built-in support for React Native Devtools.

## Features

All the features of React Native Devtools are available in Re.Pack:

- [Console](https://reactnative.dev/docs/react-native-devtools#console)
- [Source & breakpoints](https://reactnative.dev/docs/react-native-devtools#sources--breakpoints)
- [Memory](https://reactnative.dev/docs/react-native-devtools#memory)
- [Built-in support for React DevTools](https://reactnative.dev/docs/react-native-devtools#react-devtools-features)

## Usage

To start debugging your application, you can either:

- Press `j` in the terminal where Re.Pack dev server is running (remember to have at least one device connected)

- Open the Developer Menu by:

  - iOS Simulator: `Cmd (⌘) + D`

  - Android Emulator: `Cmd (⌘) + M`

  Then select "Open DevTools".

![React Native Devtools](/img/devtools.png)

## Usage with Module Federation

When using [Module Federation](/docs/features/module-federation.md), each remote will appear as a separate entry in the Sources panel. This makes it easier to debug federated modules by allowing you to:

- View and debug the source code of each remote independently
- Set breakpoints in federated modules

For example, if you have a host application with two remotes named "shop" and "checkout" each one will appear as a separate entry in the Sources panel.

![React Native Devtools with Module Federation](/img/devtools-mf.png)

This separation helps maintain clear boundaries between different parts of your federated application during debugging sessions.

:::tip

To learn more about React Native Devtools, check out the [official documentation](https://reactnative.dev/docs/react-native-devtools).

:::



---
url: /docs/features/flow-support.md
---

# Flow support

:::note Rspack users
Since SWC doesn't currently support Flow, we use a dedicated loader to strip Flow types in Rspack. With webpack, Flow support is implemented using the same set of Babel plugins as Metro.
:::

Re.Pack 5 includes support for Flow language via dedicated loaders that remove Flow type annotations from the code.

## Usage with codebase

To use Flow language in your project, you need to setup [`flow-loader`](/api/loaders/flow-loader.md) in your Rspack configuration.

```js title=rspack.config.cjs
module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/
        use: {
          loader: "@callstack/repack/flow-loader",
          options: { all: true },
        },
        type: "javascript/auto",
      },
    ],
  },
};
```

To see the full list of options available, please refer to the [flow-loader documentation](/api/loaders/flow-loader.md#options).

## Usage with libraries

Re.Pack also includes list of popular React Native libraries that ships with Flow type annotations and automatically strips annotations from them.
Here's the list of libraries that are [supported](https://github.com/callstack/repack/blob/07b2e2059487f0b6962b05016e7f1453ba35c379/packages/repack/src/rules/flowTypedModulesLoadingRules.ts#L12).

:::info Contributing
If you're using a Flow-typed library that's not on our list, please consider opening an issue or submitting a PR!
:::

However if you are using a library that is not in the list, you can add it to the list by using the following configuration:

```js title=rspack.config.cjs
import { getModulePaths } from '@callstack/repack/utils';

module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        include: getModulePaths([
          'library-name',
        ]),
        use: {
          loader: '@callstack/repack/flow-loader',
          options: { all: true },
        },
        type: 'javascript/auto',
      },
    ],
  },
};
```

:::note TypeScript vs Flow
Flow is not a commonly used solution in the React Native ecosystem, with TypeScript being the default and recommended choice for type checking. We maintain Flow support primarily for legacy codebases, libraries, and specific use cases where Flow is still required.
:::



---
url: /docs/features/module-federation.md
---

# Module Federation

:::warning Notice:
The documentation for Re.Pack 5 is currently under development and is not ready yet.

Please refer to [Re.Pack 4.x Module Federation documentation](https://v4.re-pack.dev/docs/module-federation) for now, but please keep in mind that it's not up to date with the latest changes in Re.Pack 5.
:::



---
url: /docs/features/module-resolution.md
---

# Module resolution

Module resolution is the process by which a bundler determines which file to load when you import a module. In React Native, this process has unique requirements—platform-specific files, scaled assets, and the `react-native` condition in package exports all need special handling.

Re.Pack is designed to match [Metro's resolution behavior](https://metrobundler.dev/docs/resolution) as closely as possible, ensuring that projects migrating from Metro or using libraries designed for Metro work correctly.

Getting module resolution right ensures that:

- Platform-specific files (`.ios.js`, `.android.js`) load correctly for each target
- Libraries with React Native-specific entry points work as expected
- Scaled assets (`@2x`, `@3x` images) resolve properly

## How Re.Pack resolves modules

Re.Pack configures the underlying bundler's resolver to match Metro's behavior. When using Rspack, resolution is handled by [rspack-resolver](https://github.com/unrs/rspack-resolver)—a Rust port of [enhanced-resolve](https://github.com/webpack/enhanced-resolve) with the same interface. When using webpack, the original enhanced-resolve is used.

The [`getResolveOptions()`](/api/utils/get-resolve-options.md) utility returns the configuration needed to match Metro's resolution behavior:

```ts
import * as Repack from "@callstack/repack";

export default (env) => {
  return {
    resolve: {
      ...Repack.getResolveOptions(),
    },
  };
};
```

Resolution happens per-platform—each build (iOS, Android, etc.) runs as a separate bundler process with platform-specific resolution configured automatically based on the target platform.

## Platform-specific resolution

React Native allows you to create platform-specific versions of files using special extensions. Re.Pack resolves these extensions in the following order:

1. `.{platform}.{ext}` (e.g., `.ios.js`, `.android.js`)
2. `.native.{ext}` (when `preferNativePlatform: true`, which is the default)
3. `.{ext}` (base extension)

### Example

Given a request for `./component` on iOS, Re.Pack will look for files in this order:

```
component.ios.js    → Platform-specific (highest priority)
component.native.js → Native fallback
component.js        → Base file (lowest priority)
```

The same request on Android:

```
component.android.js → Platform-specific (highest priority)
component.native.js  → Native fallback
component.js         → Base file (lowest priority)
```

### Supported source extensions

Re.Pack supports these source file extensions by default:

- `.js`, `.jsx`
- `.ts`, `.tsx`
- `.json`

Each of these can be combined with platform and native extensions:

```
.ios.js, .ios.jsx, .ios.ts, .ios.tsx, .ios.json
.native.js, .native.jsx, .native.ts, .native.tsx, .native.json
.android.js, .android.jsx, .android.ts, .android.tsx, .android.json
```

### Disabling native extension fallback

If you don't want `.native.*` files to be resolved as fallbacks, set `preferNativePlatform` to `false`:

```ts
Repack.getResolveOptions({
  preferNativePlatform: false,
});
```

:::tip

This is useful when building for non-native platforms (like web) where `.native.*` files might contain React Native-specific code that won't work in a browser.

:::

With this setting, a request for `./component` on a `web` platform would only check:

```
component.web.js → Platform-specific
component.js     → Base file (no .native.js fallback)
```

## Package resolution (main fields)

:::info What are main fields?

Main fields are `package.json` properties that point to a package's entry file. Packages can specify different entry points for different environments—`main` for Node.js, `browser` for web, `react-native` for React Native.

:::

When resolving a package's entry point, Re.Pack checks these fields in `package.json` in order:

1. `react-native` — React Native-specific entry point
2. `browser` — Browser-compatible entry point
3. `main` — Standard Node.js entry point

This matches Metro's default configuration and ensures React Native-optimized code is preferred.

### Example

Given this `package.json`:

```json
{
  "name": "some-library",
  "main": "lib/index.js",
  "browser": "lib/browser.js",
  "react-native": "lib/native.js"
}
```

Re.Pack will resolve to `lib/native.js` because `react-native` has the highest priority.

:::tip

For more details on how main fields work, see the [resolve.mainFields](https://rspack.dev/config/resolve#resolvemainfields) documentation.

:::

## Package exports (conditional exports)

:::info What are package exports?

Package exports (`exports` field in `package.json`) are a modern replacement for main fields. They let packages define multiple entry points (e.g., `pkg/utils`), serve different code per environment, and hide internal files. See the [Node.js docs](https://nodejs.org/api/packages.html#package-entry-points) for details.

:::

Modern packages use the `exports` field in `package.json` to define entry points with conditions. Re.Pack supports this through the `enablePackageExports` option.

:::caution

Package exports support is **disabled by default** (`enablePackageExports: false`) to maintain backwards compatibility with existing React Native projects. Enable it explicitly if your dependencies require it.

:::

### Enabling package exports

```ts
Repack.getResolveOptions({
  enablePackageExports: true,
});
```

### How conditional exports work

When enabled, Re.Pack uses the `react-native` condition to resolve packages. The resolver also differentiates between ESM and CommonJS:

- **ESM imports**: Uses conditions `['react-native', 'import']`
- **CommonJS requires**: Uses conditions `['react-native', 'require']`

:::tip

These ESM/CJS conditions are always configured (via `byDependency`) to support [package imports](https://nodejs.org/api/packages.html#subpath-imports), even when `enablePackageExports` is `false`.

:::

### Example package with exports

```json
{
  "name": "modern-library",
  "exports": {
    ".": {
      "react-native": "./dist/native/index.js",
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js",
      "default": "./dist/index.js"
    },
    "./utils": {
      "react-native": "./dist/native/utils.js",
      "import": "./dist/esm/utils.js",
      "require": "./dist/cjs/utils.js"
    }
  }
}
```

With `enablePackageExports: true`, importing this package in React Native will resolve to the `react-native` condition entry points.

:::warning

Some packages may have `exports` configurations that work differently than their `main`/`react-native` field configurations. Test thoroughly when enabling this option in existing projects.

:::

## Asset resolution

Re.Pack handles scaled assets (images with `@1x`, `@2x`, `@3x` suffixes) automatically using `extensionAlias` configuration.

### Supported scalable assets

Images that support resolution scaling:

- `bmp`, `gif`, `jpg`, `jpeg`, `png`, `psd`, `svg`, `webp`, `tiff`

### How scaled resolution works

When you import an image like `./icon.png`, Re.Pack's `extensionAlias` configuration allows the resolver to find scaled variants:

```
icon@0.75x.png
icon@1x.png
icon@1.5x.png
icon@2x.png
icon@3x.png
icon@4x.png
icon.png
```

The actual asset selection (choosing the right scale for the device) happens at runtime through React Native's asset system.

```jsx
// Import resolves to the appropriate scaled variant
import icon from './assets/icon.png';

// React Native selects the correct scale at runtime
<Image source={icon} />
```

### Other supported asset types

Re.Pack also supports these non-scalable asset types:

- **Video**: `m4v`, `mov`, `mp4`, `mpeg`, `mpg`, `webm`
- **Audio**: `aac`, `aiff`, `caf`, `m4a`, `mp3`, `wav`
- **Documents**: `html`, `pdf`, `yaml`, `yml`
- **Fonts**: `otf`, `ttf`
- **Other**: `zip`, `obj`

## Troubleshooting

Most resolution issues can be solved with two configuration options:

- **`resolve.alias`** — Redirect imports to a different module or file
- **`module.rules`** — Control how specific modules are processed

```ts
export default (env) => {
  return {
    resolve: {
      alias: {
        // Redirect problematic package to a compatible version
        'legacy-package': 'legacy-package/dist/react-native',
      },
    },
    module: {
      rules: [
        {
          // Force specific files through a loader
          test: /problematic-module/,
          use: 'babel-loader',
        },
      ],
    },
  };
};
```

### Package not resolving correctly

1. **Check the package's `package.json`** — Look at `main`, `react-native`, `browser`, and `exports` fields
2. **Verify platform extensions** — Ensure platform-specific files use correct naming (`.ios.js`, not `.iOS.js`)
3. **Check `enablePackageExports`** — Some modern packages require this to be `true`

### Platform-specific files not being picked up

1. **Verify file naming** — Extensions must be lowercase (`.ios.js`, not `.IOS.js`)
2. **Check the platform value** — Ensure you're building for the correct target platform
3. **Inspect resolve configuration** — Log the output of `getResolveOptions()` to verify extensions order

### Package exports compatibility issues

When enabling `enablePackageExports`, some packages may resolve differently:

1. **Compare with Metro** — Test the same import in a Metro-bundled project
2. **Check condition order** — The `react-native` condition should take precedence
3. **Inspect the package** — Some packages have incorrect or incomplete `exports` configurations

## Related documentation

- [getResolveOptions](/api/utils/get-resolve-options.md) — API reference
- [Rspack resolve configuration](https://rspack.dev/config/resolve) — Rspack resolver options
- [webpack resolve configuration](https://webpack.js.org/configuration/resolve/) — webpack resolver options
- [Code Splitting](/docs/features/code-splitting.md) — For chunk resolution
- [Glossary](/docs/resources/glossary.md) — Terminology reference



---
url: /docs/features/nativewind.md
---

# NativeWind

[NativeWind](https://www.nativewind.dev/) brings Tailwind CSS utility classes to React Native, enabling rapid, consistent styling. With Re.Pack, you can seamlessly integrate NativeWind through a dedicated plugin.

[@callstack/repack-plugin-nativewind](https://github.com/callstack/repack/tree/main/packages/plugin-nativewind) is a plugin for Re.Pack that enables integrating NativeWind into your React Native projects.

## About

This plugin seamlessly integrates NativeWind with Re.Pack's build process by:

- Configuring PostCSS and Tailwind CSS processing for your stylesheets
- Handling conversion of CSS to React Native-compatible styles
- Setting up proper SWC transformations for NativeWind's JSX runtime

## Installation

First, follow these steps from the official [NativeWind installation guide](https://www.nativewind.dev/docs/getting-started/installation):

1. [Install NativeWind](https://www.nativewind.dev/docs/getting-started/installation/frameworkless) - follow everything except the metro setup.
2. [Setup Tailwind CSS](https://www.nativewind.dev/docs/getting-started/installation#2-setup-tailwind-css)
3. [Import your CSS file](https://www.nativewind.dev/docs/getting-started/installation#5-import-your-css-file)
4. (Optional) [Setup TypeScript support](https://www.nativewind.dev/docs/getting-started/installation#7-typescript-setup-optional)

Then install the Re.Pack NativeWind plugin and its dependencies:


```sh [npm]
npm install -D @callstack/repack-plugin-nativewind postcss postcss-loader autoprefixer
```

```sh [yarn]
yarn add -D @callstack/repack-plugin-nativewind postcss postcss-loader autoprefixer
```

```sh [pnpm]
pnpm add -D @callstack/repack-plugin-nativewind postcss postcss-loader autoprefixer
```

```sh [bun]
bun add -D @callstack/repack-plugin-nativewind postcss postcss-loader autoprefixer
```

```sh [deno]
deno add -D npm:@callstack/repack-plugin-nativewind npm:postcss npm:postcss-loader npm:autoprefixer
```

:::tip Version Alignment
The NativeWind plugin is versioned together with Re.Pack. For best compatibility, align the version of `@callstack/repack-plugin-nativewind` with your `@callstack/repack` version in the project.
:::

:::info{title="A note on dependencies:"}
These additional dependencies (`postcss`, `postcss-loader`, and `autoprefixer`) are required for processing Tailwind CSS with Webpack/Rspack, as specified in the [official Tailwind CSS Rspack guide](https://tailwindcss.com/docs/guides/rspack). They enable PostCSS processing and autoprefixing of CSS styles in your build pipeline.
:::

## Usage

To add the plugin to your Re.Pack configuration, update your `rspack.config.js` or `webpack.config.js` as follows:

```js title="rspack.config.js"
import { NativeWindPlugin } from "@callstack/repack-plugin-nativewind";

export default (env) => {
  // ...
  return {
    // ...
    plugins: [
      // ...
      new NativeWindPlugin(),
    ],
  };
};
```

## Troubleshooting

- **Styles not applying?**

  - Ensure your CSS import is present and the plugin is added to your rspack/webpack config.
  - Make sure you have the `nativewind/babel` preset applied in your babel config.

- **TypeScript issues?**

  Follow the [NativeWind TypeScript setup guide](https://www.nativewind.dev/docs/getting-started/installation/frameworkless#6-typescript-setup-optional).

## Further Resources

- [NativeWind Documentation](https://www.nativewind.dev/docs)
- [Tailwind CSS Documentation](https://tailwindcss.com/)
- [Re.Pack NativeWind Plugin Repo](https://github.com/callstack/repack/tree/main/packages/plugin-nativewind)



---
url: /docs/features/reanimated.md
---

# React Native Reanimated

Re.Pack provides first-class support for [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/) through a dedicated plugin that simplifies integration and in some cases, optimizes your build performance.

:::info This plugin is primarily used to disable console warnings that are not relevant when bundling a React Native app.

:::

## How it Works

The Worklets Babel Plugin transforms your code so that it can run on the Worklet Runtimes. It looks for functions marked with a `'worklet';` directive and converts them into serializable objects.

When using Rspack, the worklets babel plugin is executed via `babel-swc-loader`. The `ReanimatedPlugin` handles configuration and suppresses warnings that would otherwise appear during the build process.

## Installation

If you haven't already, install the `react-native-reanimated` package:


```sh [npm]
npm install react-native-reanimated
```

```sh [yarn]
yarn add react-native-reanimated
```

```sh [pnpm]
pnpm add react-native-reanimated
```

```sh [bun]
bun add react-native-reanimated
```

```sh [deno]
deno add npm:react-native-reanimated
```

To add Reanimated support to your Re.Pack project with Rspack, install the plugin:


```sh [npm]
npm install -D @callstack/repack-plugin-reanimated
```

```sh [yarn]
yarn add -D @callstack/repack-plugin-reanimated
```

```sh [pnpm]
pnpm add -D @callstack/repack-plugin-reanimated
```

```sh [bun]
bun add -D @callstack/repack-plugin-reanimated
```

```sh [deno]
deno add -D npm:@callstack/repack-plugin-reanimated
```

## Usage with Reanimated 4+

For Reanimated 4 and above, the worklet transformation is handled by the `react-native-worklets/plugin` babel plugin.

Install the worklets package:


```sh [npm]
npm install react-native-worklets
```

```sh [yarn]
yarn add react-native-worklets
```

```sh [pnpm]
pnpm add react-native-worklets
```

```sh [bun]
bun add react-native-worklets
```

```sh [deno]
deno add npm:react-native-worklets
```

### Babel Configuration

Add the worklets plugin to your `babel.config.js`:

```js title="babel.config.js"
module.exports = {
  presets: ["module:@react-native/babel-preset"],
  plugins: ["react-native-worklets/plugin"],
};
```

### Rspack Configuration

Add the plugin to your Rspack configuration with the `unstable_disableTransform` option set to `true`.

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");
const { ReanimatedPlugin } = require("@callstack/repack-plugin-reanimated");

module.exports = {
  plugins: [
    new Repack.RepackPlugin(),
    new ReanimatedPlugin({
      unstable_disableTransform: true,
    }),
  ],
};
```

This will disable adding now redundant `babel-loader` rules, and defer the transformation to Babel through `babel-swc-loader`.

## Usage with Reanimated 3

First add the `react-native-reanimated` babel plugin to your `babel.config.js`:

```js title="babel.config.js"
module.exports = {
  presets: ["module:@react-native/babel-preset"],
  plugins: [
    "react-native-reanimated/plugin",
  ],
};
```

Then apply the `ReanimatedPlugin` with the  unstable\_disableTransform option set to `true`.

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");
const { ReanimatedPlugin } = require("@callstack/repack-plugin-reanimated");

module.exports = {
  plugins: [
    new Repack.RepackPlugin(),
    new ReanimatedPlugin({
      unstable_disableTransform: true,
    }),
  ],
};
```



---
url: /docs/getting-started/bundlers.md
---

# Rspack & webpack



---
url: /docs/getting-started/introduction.md
---

# Introduction

Before diving deep into Re.Pack and introducing it into project, it's important to understand when and why to use Re.Pack and how does it compare with alternatives.

## About Re.Pack

Re.Pack is a modern toolkit that wraps Rspack and webpack to make them work seamlessly with React Native applications.

The toolkit includes:

- **React Native-specific plugins and loaders** that handle platform differences (platform specific files, assets, etc.)
- **Integrated development server** with Hot Module Replacement (HMR) + React Refresh, and debugging capabilities through React Native Devtools
- **Runtime modules** like ScriptManager for advanced features like code splitting and Module Federation

## Design goals

Re.Pack is designed to be a **drop-in replacement for Metro** with the primary goal of making migration as easy as possible. The toolkit aims to:

- Provide seamless integration with existing React Native projects
- Maintain compatibility with Metro's expected behavior while offering enhanced capabilities
- Minimize configuration changes needed during migration
- Offer a smooth transition path from Metro to advanced bundling features

This approach ensures teams can adopt Re.Pack incrementally, starting with basic Metro replacement and gradually leveraging advanced features like Module Federation and custom webpack configurations as needed.

## Why & when

Re.Pack is particularly valuable in these scenarios:

### 1. **Microfrontends with Module Federation**

Re.Pack provides first-class support for Module Federation, enabling you to build microfrontend architectures where different teams can develop and deploy parts of your mobile app independently.

### 2. **Advanced Tree Shaking**

Leverage state-of-the-art tree shaking capabilities that can significantly reduce bundle size by eliminating unused code more effectively than Metro, helping you save valuable bytes in your final application bundle.

### 3. **High Customizability**

Access to the full Rspack/webpack ecosystem means extensive customization options through loaders, plugins, and advanced configuration. You can implement complex build requirements that aren't possible with Metro.

### 4. **Build Performance**

Rspack's Rust-based architecture provides significant performance improvements for large codebases, especially when combined with advanced caching strategies.

Re.Pack is designed for teams that need these advanced capabilities and have developers willing to familiarize themselves with alternative bundling tools.

:::tip Don't drop Metro just yet!

If you're just starting with React Native, consider sticking with Metro - the default bundler for React Native applications. Re.Pack shines when you have specific requirements that Metro cannot address but is not compatible with tools that assume Metro as a bundler present in the project setup.

:::



---
url: /docs/getting-started/microfrontends.md
---

# Microfrontends

Microfrontends (MFEs) are an architectural approach that breaks down a web application’s frontend into smaller, independently deployable pieces that can be downloaded on demand. Think of them as the frontend equivalent of microservices: instead of one massive, tangled codebase, you get modular chunks that different teams can own, develop, and ship on their own timelines. It's important to note that we're not talking about producing a single JS bundle from multiple independent teams. It's about producing many JS bundles that can be later downloaded on demand by a mobile app.

While web MFEs and microservices are often about using independent tech stacks, it's different on mobile iOS and Android ecosystems due to platform constraints and app store rules that typically prevent loading any compiled code.

Re.Pack is largely designed to enable microfrontends on mobile. It's one of the key differences between other React Native bundlers, such as Metro, which don't support this architecture out of the box.

## Use Cases

Mobile microfrontends shine in scenarios where complexity and team size grow beyond what a monolith can handle. Here are some use cases we found compelling for this archiecture:

- **Strong Team Boundaries**: If you’ve got separate teams working on different parts of an app (say, one for product listing, another for user settings), and often at different geographical locations or even company divisions, MFEs let each team own their domain end-to-end without stepping on each other’s toes.
- **Independent Deployments**: While React Native allows for over-the-air updates, MFEs offer a more targeted deployments possibility, instead of replacing the whole JavaScript bundle like all OTA solutions out there.
- **Super Apps**: When building a mobile super app with features loaded on demand, MFEs let you ship lightweight containers that pull in functionality as users need it, without them to be available in the initial app bundle, reducing the overall app size.

It's crucial to be sure about what you want to achieve with microfrontends. Adopting this architecture, as with any other engineering design choice, comes with its own complexity. Make sure the trade-offs are worth it. And avoid using microforntends because it's some trend to follow.

## Module Federation

Re.Pack makes it possible to use Rspack, leveraging whole webpack ecosystem. Thanks to that you can use one of the key features built around this ecosystem, which was designed to solve common pains working with microfrontends: Module Federation. Module Federation is an architectural pattern for the decentralization of JavaScript applications. It allows you to share code and resources among multiple JavaScript applications (or microfrontends).

Re.Pack supports Module Federation since v3 in its own flavor, that was different from using it on the web. However, since then, the Module Federation 2 was released, which adds dynamic type hinting, Manifest, Federation Runtime, and Runtime Plugin System. These new features allowed us to better integrate this architecture into React Native runtime—which differs from the web—while retaining the same API that web developers are used to.

## Limitations

While Module Federation 2 enables Re.Pack to use the same conventions and APIs as on the web, mobile microfrontends are more limited due to native platform and app stores constraints:

- You must use the same React, React Native and native dependencies versions across all MFEs
- All native modules need to be available in the host application (the one that is released to app stores)
- You can only dynamically load JavaScript code from a microfrontend – this code can reference and use native modules that are bundled within the host app

## Challenges

One of the complexities of microfrontends is version management. It’s challenging to handle on your own and can be quite cumbersome based on our experience. If you’re open to third-party services, we recommend Zephyr Cloud, which simplifies this problem, allows for sub-second deploys, and officially [integrates with Re.Pack](https://docs.zephyr-cloud.io/recipes/repack-mf) in a form of a Rspack/webpack plugin.

## Examples

Below you can find open source examples of how you can set up Re.Pack with microfrontends:

- [Super App Showcase](https://github.com/callstack/super-app-showcase) – MFEs versioned using a custom script
- [Zephyr Re.Pack Example](https://github.com/ZephyrCloudIO/zephyr-repack-example) – MFEs versioned using Zephyr Cloud



---
url: /docs/getting-started/quick-start.md
---

# Quick start

## Pre-requisites

If you're already familiar with JavaScript, React Native and webpack, then you'll be able to get moving quickly! Otherwise, it's highly recommended to get yourself familiar with these topic and then come back here:

- [React Native documentation](https://reactnative.dev/)
- [Webpack concepts](https://webpack.js.org/concepts/)

## Minimum requirements

- Node >= 20
- React Native >= 0.77.0

:::note On React Native Version

The absolute minimum required version of React Native is 0.74.0, which contains fixes enabling proper SWC transpilation. While versions lower than 0.74 might work, they will most likely only function with Webpack.

:::

:::info Version Support Policy

Re.Pack is designed to work with the latest React Native version and maintains backward compatibility with the two previous versions.
While older versions might work, they are not officially supported.

If you're interested in fixing compatibility issues for older versions, feel free to open a PR!

:::

## Installation

To create a new React Native project with Re.Pack or adapt an existing one:


```sh [npx]
npx @callstack/repack-init
```

```sh [yarn]
yarn dlx @callstack/repack-init
```

```sh [pnpm]
pnpm dlx @callstack/repack-init
```

```sh [bunx]
bunx @callstack/repack-init
```

In case the command above didn't work for any reason, you can follow the manual migration guide [here](/docs/migration-guides/metro.md).

:::tip The defaults work well for most projects
If you need custom settings (like additional loaders or plugins), check out our [configuration guide](/docs/guides/configuration.md).
:::

## Usage

Now that you have Re.Pack configured, you should be able to use Re.Pack's development server and bundle your application.

### Running development server

When developing your application, you want to run Re.Pack's development server to compile your source code with Rspack/webpack.

To start the development server, you can use React Native Community CLI and run:


```sh [npm]
npm run react-native start
```

```sh [yarn]
yarn react-native start
```

```sh [pnpm]
pnpm react-native start
```

```sh [bun]
bun react-native start
```

To learn about `start` command, check out the [start command documentation](/api/cli/start.md).

### Bundling the app

When you are building the release version of your application, Re.Pack will be picked up automatically as the bundler. In case you want to create bundle manually, **the recommended way is to use React Native Community CLI** and run:


```sh [npm]
npm run react-native bundle
```

```sh [yarn]
yarn react-native bundle
```

```sh [pnpm]
pnpm react-native bundle
```

```sh [bun]
bun react-native bundle
```

To learn about `bundle` command, check out the [bundle command documentation](/api/cli/bundle.md).

:::tip 🎉 Congratulations!

You've successfully set up Re.Pack in your project. We highly recommend to check out the following:

- [Configuration Guide](/docs/guides/configuration.md) to learn how to configure Re.Pack to your project needs.
- [API Reference](/api/index.md) to learn more about Re.Pack's API.
- [Deployment of MiniApps](/docs/guides/deploy.md) to learn how to deploy your federated MiniApps with Zephyr Cloud.

:::



---
url: /docs/guides/bundle-analysis.md
---

# Bundle analysis

Bundle analysis is a crucial process that helps you understand your app's performance bottlenecks and identify opportunities for optimization. By analyzing your bundle, you can gain insights into bundle size and composition, module dependencies, duplicate modules, and compilation time. We recommend using [Rsdoctor](https://rsdoctor.dev/) for bundle analysis, though you can also check our [alternative tools section](#alternative-tools) for other options.

## Rsdoctor

**Rsdoctor** provides comprehensive visualization of the build process, offering detailed insights into compilation time, compilation transformations, module dependencies, duplicate modules, and bundle size analysis.

### Installation


**Rspack**


```sh [npm]
npm install @rsdoctor/rspack-plugin -D
```

```sh [yarn]
yarn add @rsdoctor/rspack-plugin -D
```

```sh [pnpm]
pnpm add @rsdoctor/rspack-plugin -D
```

```sh [bun]
bun add @rsdoctor/rspack-plugin -D
```


**webpack**


```sh [npm]
npm install @rsdoctor/webpack-plugin -D
```

```sh [yarn]
yarn add @rsdoctor/webpack-plugin -D
```

```sh [pnpm]
pnpm add @rsdoctor/webpack-plugin -D
```

```sh [bun]
bun add @rsdoctor/webpack-plugin -D
```


### Usage

:::danger Only for development
Please do not use Rsdoctor in production version.

The `process.env.RSDOCTOR` is used to conditionally enable the plugin just for the development environment.
:::

Initialize the plugin in your bundler configuration:


**Rspack**

```ts title=rspack.config.mjs
import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

export default {
  // ...
  plugins: [
    process.env.RSDOCTOR &&
      new RsdoctorRspackPlugin({
        // plugin options
      }),
  ],
};
```


**webpack**

```ts title=webpack.config.js
import { RsdoctorWebpackPlugin } from '@rsdoctor/webpack-plugin';

export default {
  // ...
  plugins: [
    process.env.RSDOCTOR &&
      new RsdoctorWebpackPlugin({
        // plugin options
      }),
  ],
};
```


Use the `RSDOCTOR` environment variable when running the build:

```bash
RSDOCTOR=true npx react-native bundle
```

:::tip Specific platform analysis
For better analysis results, it's recommended to run a single platform build using the `--platform` option:

```bash
RSDOCTOR=true npx react-native bundle --platform <platform>
```

This helps to get more focused and accurate bundle analysis for each platform.
:::

After running the above commands, when the build is completed, it will open the build analysis page. For complete features, please refer to [Rsdoctor documentation](https://rsdoctor.dev/).

### Options

The `RsdoctorPlugin` plugin provides several options to customize the build analysis. Read more about it [here](https://rsdoctor.dev/config/options/options).

## Alternative tools

- [Sonda](https://github.com/filipsobol/sonda) - Universal visualizer and analyzer for JavaScript and CSS. Compatible with Re.Pack.
- [Webpack Bundle Analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) - A tool for analyzing the bundle size of your React Native application.
- [react-native-bundle-discovery](https://github.com/retyui/react-native-bundle-discovery/blob/main/Re.Pack.md) - Simple tooling to inspect the JS bundle internals.
- [source-map-explorer](https://github.com/danvk/source-map-explorer) - A tool for analyzing the bundle size of your React Native application.



---
url: /docs/guides/configuration.md
---

# Configuration

Re.Pack uses the same configuration system as Rspack and webpack. This means you can leverage the extensive configuration options from either of the bundlers while working with React Native projects. Re.Pack comes with minimal, development & production-ready defaults that work out of the box, but as your project grows, you may need to customize various aspects of the bundling process.

## How to configure

Since Re.Pack is built on top of Rspack and webpack, you can refer to their respective documentation for available configuration options:

- [Rspack documentation](https://rspack.dev/config.html)
- [Webpack documentation](https://webpack.js.org/configuration/)

For example, if you want to configure output options for your bundles, you would look up these options in the [Rspack output documentation](https://rspack.dev/config/output.html) or [webpack output documentation](https://webpack.js.org/configuration/output/) and use them in the project config:

```js title="rspack.config.cjs"
module.exports = {
  output: {
    filename: "index.bundle",
    chunkFilename: "[name].chunk.bundle",
  },
};
```

You can find all available options in the respective bundler's documentation. Most configuration options work the same way as they do in Rspack/webpack, with some React Native specific extensions that we'll cover later in this guide.

## Template configurations

Re.Pack ships with template configurations to help you get started.
These templates provide sensible defaults and common configurations for both Rspack and webpack.


**Rspack ESM**


```js title=rspack.config.mjs
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import * as Repack from '@callstack/repack';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

/**
 * Rspack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about Rspack configuration: https://rspack.dev/config/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

export default Repack.defineRspackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          parallel: true,
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```


**Rspack CJS**


```js title=rspack.config.cjs
const Repack = require('@callstack/repack');

/**
 * Rspack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about Rspack configuration: https://rspack.dev/config/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

module.exports = Repack.defineRspackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          parallel: true,
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```


**webpack ESM**


```js title=webpack.config.mjs
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import * as Repack from '@callstack/repack';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

/**
 * Webpack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about webpack configuration: https://webpack.js.org/configuration/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

export default Repack.defineWebpackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```


**webpack CJS**


```js title=webpack.config.cjs
const Repack = require('@callstack/repack');

/**
 * Webpack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about webpack configuration: https://webpack.js.org/configuration/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

module.exports = Repack.defineWebpackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```


## TypeScript configuration

Re.Pack supports TypeScript configuration files for both Rspack and webpack, allowing you to write your configuration in TypeScript with full type safety.

:::tip About TypeScript support in Node
Node.js `v23.6.0` or higher supports stripping TypeScript types out of the box.
If you are stuck on older Node versions, refer to [Rspack TypeScript support documentation](https://rspack.rs/config/#typescript-configuration-file).
It details ways to use TypeScript configs outside of newest Node versions.
:::

### TypeScript configuration files

You can use TypeScript configuration files with the following naming conventions:

- `rspack.config.cts`, `rspack.config.mts` or `rspack.config.ts` for Rspack
- `webpack.config.cts`, `webpack.config.mts` or `webpack.config.ts` for webpack

### Using `defineRspackConfig` and `defineWebpackConfig`

Re.Pack provides helper functions for type-safe configuration:

- `defineRspackConfig` - for Rspack configurations
- `defineWebpackConfig` - for webpack configurations

Consider the following example for the default Rspack configuration:

```ts title="rspack.config.mts"
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import * as Repack from '@callstack/repack';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

/**
 * Rspack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about Rspack configuration: https://rspack.dev/config/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

export default Repack.defineRspackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      ...Repack.getJsTransformRules(),
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```

## Configuration variants

Configuration can be defined in two ways: as a static object or as a function that returns a configuration object.

### Static configuration

The simplest form is a static object that defines your configuration:

```js title="rspack.config.cjs"
const Repack = require("repack");

module.exports = {
  entry: "./index.js",
  output: {
    filename: "index.bundle",
  },
  plugins: [new Repack.RepackPlugin()],
};
```

### Dynamic configuration

For more flexibility, you can export a function that returns the configuration object. This is useful when you need to:

- Configure an option based on the platform (e.g. `ios` or `android`)
- Enable or disable configuration based on the `mode`

```js title="rspack.config.cjs"
const Repack = require("repack");

module.exports = function (env) {
  const { mode, platform } = env;

  return {
    mode,
    output: {
      path: path.resolve(__dirname, "build/generated", platform),
    },
    plugins: [new Repack.RepackPlugin()],
  };
};
```

The `env` argument is an object with the following properties:

| Property            | Type                    | Description                                                                     |
| ------------------- | ----------------------- | ------------------------------------------------------------------------------- |
| `mode`              | `string`                | Compilation mode (`'production'` or `'development'`)                            |
| `platform`          | `string`                | Target application platform                                                     |
| `context`           | `string`                | Context in which all resolution happens (usually project root directory)        |
| `entry`             | `string`                | Input filename - entry point of the bundle                                      |
| `bundleFilename`    | `string`                | Bundle output filename - name under which generated bundle will be saved        |
| `sourceMapFilename` | `string`                | Source map filename for the main bundle                                         |
| `assetsPath`        | `string`                | Directory where generated static assets will be saved                           |
| `minimize`          | `boolean`               | Whether to minimize the final bundle                                            |
| `reactNativePath`   | `string`                | Path to React Native dependency (usually points to `node_modules/react-native`) |
| `devServer`         | `object` \| `undefined` | Development server configuration options                                        |

## Configuration precedence

Re.Pack follows a specific order when resolving configuration values. When the same option is defined in multiple places, the value with higher precedence takes priority. Here's the precedence order from highest to lowest:

1. CLI flags (e.g. `--mode production`)
2. Project configuration (your `rspack.config.js` or `webpack.config.js`)
3. Command-specific configuration
4. Re.Pack defaults
5. Rspack/webpack defaults

For example, if you set the `mode` in your configuration file:

```js title="rspack.config.cjs"
module.exports = {
  mode: "development",
};
```

But run the CLI with a different mode:

```bash
npx react-native bundle --mode production
```

The CLI flag (`production`) will take precedence over the configuration file value (`development`).

### Command-specific defaults

Below you can find the defaults for each command.

:::tip
Remember that if you define the same options in your configuration file (e.g. `rspack.config.cjs` or `webpack.config.cjs`), they will take effect over the defaults listed below.
:::

#### `start` command

```js
{
  mode: "development",
  devServer: {
    host: "localhost",
    port: 8081,
    hot: true,
    server: "http",
  },
}
```

#### `bundle` command

```js
{
  mode: "production",
  devServer: false,
  optimization: {
    minimize: true,
  },
}
```

### Re.Pack defaults

These are the base defaults that Re.Pack provides regardless of the command being run:


**Rspack**


```js
{
  devtool: "source-map",
  experiments: {
    parallelLoader: true,
  },
  output: {
    clean: true,
    hashFunction: "xxhash64",
    filename: "index.bundle",
    chunkFilename: "[name].chunk.bundle",
    path: "[context]/build/generated/[platform]",
    publicPath: "noop:///",
  },
  optimization: {
    chunkIds: "named",
  },
}
```


**webpack**


```js
{
  devtool: "source-map",
  output: {
    clean: true,
    hashFunction: "xxhash64",
    filename: "index.bundle",
    chunkFilename: "[name].chunk.bundle",
    path: "[context]/build/generated/[platform]",
    publicPath: "noop:///",
  },
  optimization: {
    chunkIds: "named",
  },
}
```


## Configuration enhancements

Re.Pack extends the configuration system with few features to make things easier. These values will be resolved before passing the configuration to the bundler and starting the compilation.

### Output path

The `output.path` option supports the `[platform]` placeholder which gets replaced with the current platform value:

```js
// Your configuration
output: {
  path: "build/generated/[platform]";
}

// When building for iOS, will be resolved to
output: {
  path: "build/generated/ios";
}
```

### Resolve extensions

The `resolve.extensions` option supports the `[platform]` placeholder to enable platform-specific file resolution. This allows you to use platform-specific files like `MyComponent.ios.js` or `MyComponent.android.js`:

```js
// Your configuration
resolve: {
  extensions: [".[platform].ts", ".[platform].js", ".ts", ".js"];
}

// When building for iOS, will be resolved to
resolve: {
  extensions: [".ios.ts", ".ios.js", ".ts", ".js"];
}
```



---
url: /docs/guides/debugging.md
---

# Debugging

Debugging is an important part of development. To debug apps using Re.Pack, you can use the following methods:

## Debugging configuration & build

To debug build process and compilation time, compilation transformations, module dependencies, duplicate modules, and bundle size analysis, you can use the [Rsdoctor plugin](/docs/guides/bundle-analysis.md). This tool provides a visual interface to help you identify and fix potential build issues.

## Debugging runtime

Re.pack has first-class support for debugging runtime. You can use React Native DevTools to debug your app and inspect component state, props, and performance in real-time. Take a look at our detailed guide [here](/docs/features/devtools.md).

## Other

You can always pass `--verbose` flag or `REPACK_VERBOSE=1` environment variable to the `bundle` or `start` command to get more detailed logs:

```bash
npx react-native bundle --verbose
```

```bash
REPACK_VERBOSE=1 npx react-native bundle
```



---
url: /docs/guides/deploy.md
---

# Deployment

## Zephyr Cloud Integration

Re.Pack supports deploying your React Native Applications with MiniApps to [Zephyr Cloud](https://zephyr-cloud.io) with `zephyr-repack-plugin` by adding one line of code in your build configuration file - whether you're using [Rspack](https://rspack.dev) or [webpack](https://webpack.js.org) - you can seemlessly integrate deployment into your workflow.

## About Zephyr Cloud

Zephyr Cloud is an orchestration platform for instant deployment of Web and Cross-platform applications. You can bring your own cloud provider, or use Zephyr Cloud's hosted service. Read more about [supported cloud providers](https://docs.zephyr-cloud.io/cloud).

When you are using `zephyr-repack-plugin` with a React Native project with MiniApps, Zephyr automatically handles deploying and resolving to the correct remote application without modifying build configuration files (you can keep the `remoteEntry` as `MobileCart@https://localhost:8080/mf-manifest.json` without additional changes on each deployment).

## Prerequisites

1. We assume you have a React Native project with MiniApps ready. If not, you can follow the [Quick start guide](/docs/getting-started/quick-start.md) from Re.pack docs or use the bootstrap CLI provided by Zephyr Cloud by running `create-zephyr-apps` and select `React Native` as the framework.

```bash
npx create-zephyr-apps@latest
```

2. A Zephyr Cloud account: sign up at [Zephyr Cloud](https://app.zephyr-cloud.io?ref=repack) if you haven't already.

:::info Related docs

For more details related to `create-zephyr-apps` CLI, please refer to the [Zephyr Cloud's documentation for React Native, Re.Pack and Module Federation](https://docs.zephyr-cloud.io/recipes/repack-mf).

You can also read more about deployment, concepts and best practices about how to use Zephyr Cloud in their [documentation](https://docs.zephyr-cloud.io).

:::

## Configuration

Install plugin by running:


```sh [npm]
npm install zephyr-repack-plugin@latest
```

```sh [yarn]
yarn add zephyr-repack-plugin@latest
```

```sh [pnpm]
pnpm add zephyr-repack-plugin@latest
```

```sh [bun]
bun add zephyr-repack-plugin@latest
```

And wrapping your build configuration with the plugin:

```js
const { withZephyr } = require('zephyr-repack-plugin');

module.exports = withZephyr({
  // your build configuration
});
```

For more details about configuration, please refer to the [configuration guide](https://docs.zephyr-cloud.io/recipes/repack-mf#modify-thehostapp) on Zephyr Cloud's documentation.

## Deploy to Zephyr Cloud

When enabled, your MiniApps are deployed to Zephyr Cloud automatically whenever you build, or when the development server is running on your project. A deploy URL will be generated in your terminal as shown below:

![Zephyr Cloud React Native Deploy URL](/img/repack-deploy-url.png)

### Expected behavior

If you click on the deploy URL, you will see this image:

![Asset not found](/img/asset-not-found.png)

This is expected behavior as MiniApps on React Native doesn't have a default root `index.html` file.

However, you can inspect whether anything was deployed by adding the suffix `/mf-manifest.json` at the end of the URL to see if the manifest file exists (this behaviour will be improved soon).

| URL                             | Manifest file                                    |
| ------------------------------- | ------------------------------------------------ |
| `https://<your-deploy-url>.com` | `https://<your-deploy-url>.com/mf-manifest.json` |

The deploy URL is instantly sharable, available and able to be used, or auto-resolved by Zephyr Cloud when you  have a MiniApp in your Host App. [Read more about deploying, managing federated application with Zephyr Cloud](https://docs.zephyr-cloud.io/how-to/mf-guide).

:::tip Learn more about Zephyr Cloud

- [Website](https://zephyr-cloud.io)
- [Documentation](https://docs.zephyr-cloud.io)
- [Discord](https://zephyr-cloud.io/discord)
- [Twitter](https://zephyr-cloud.io/twitter)
- [YouTube](https://zephyr-cloud.io/youtube)

:::



---
url: /docs/guides/expo-modules.md
---

# Expo Modules

The [Expo Modules](https://docs.expo.dev/modules/overview/) is a popular solution for writing native modules and views in Swift and Kotlin for React Native apps. It provides a modern, consistent API across platforms with minimal boilerplate and full support for React Native's New Architecture, while maintaining backwards compatibility.

Using Expo Modules with Re.Pack requires some setup - this guide will show you how to get started with Expo Modules in your project.

## Installation

:::info
Skip the ["Configure Expo CLI for bundling"](https://docs.expo.dev/bare/installing-expo-modules/#configure-expo-cli-for-bundling-on-android-and-ios) section, as Re.Pack handles the bundling process.
:::

### 1. Install Expo package

Install the Expo package in your project:


```sh [npm]
npm install expo
```

```sh [yarn]
yarn add expo
```

```sh [pnpm]
pnpm add expo
```

```sh [bun]
bun add expo
```

```sh [deno]
deno add npm:expo
```

### 2. Modify Native Platform files

Follow these steps from the official Expo guide:

1. [Configuration for Android](https://docs.expo.dev/bare/installing-expo-modules/#configuration-for-android)
2. [Configuration for iOS](https://docs.expo.dev/bare/installing-expo-modules/#configuration-for-ios)

### 3. Add Re.Pack Integration

First, install the official Re.Pack Expo Modules plugin:


```sh [npm]
npm install -D @callstack/repack-plugin-expo-modules
```

```sh [yarn]
yarn add -D @callstack/repack-plugin-expo-modules
```

```sh [pnpm]
pnpm add -D @callstack/repack-plugin-expo-modules
```

```sh [bun]
bun add -D @callstack/repack-plugin-expo-modules
```

```sh [deno]
deno add -D npm:@callstack/repack-plugin-expo-modules
```

Then, add the plugin to your configuration file:

```js title=rspack.config.cjs
const { ExpoModulesPlugin } = require("@callstack/repack-plugin-expo-modules");

module.exports = {
  plugins: [
    new ExpoModulesPlugin(),
  ]
};
```

## Usage

After completing the setup, you can start using Expo modules in your application.

:::tip
For specific module installation and usage instructions, refer to the [Expo documentation](https://docs.expo.dev/versions/latest/).
:::

### Verifying installation

You can verify that the installation was successful by logging a value from `expo-constants`.

First, install the `expo-constants` package:


```sh [npm]
npm install expo-constants
```

```sh [yarn]
yarn add expo-constants
```

```sh [pnpm]
pnpm add expo-constants
```

```sh [bun]
bun add expo-constants
```

```sh [deno]
deno add npm:expo-constants
```

Then, add the following code to your `index.js` file:

```js title=index.js
import Constants from 'expo-constants';

console.log(Constants.expoConfig);
```

You should see the `expoConfig` object in the console (in React Native Dev Tools).



---
url: /docs/guides/inline-assets.md
---

# Inlining assets

There are some situations when you might want to inline assets into the JavaScript bundle, instead of extracting them into standalone files.

Common examples of such use cases are:

- Using assets inside of [Module Federation remotes](/docs/features/module-federation.md) where you can't have assets extracted and shipped with the host app bundle.
- Out-of-tree platforms that don't support static assets in a similar way as React Native on iOS/Android does or don't support static assets at all.

:::tip Use sparingly and only when necessary

Inlining assets into the bundle makes the **bundle size larger** and increases the **initial startup time** of an app. It's most noticable when you inline an asset which has 3 scales (e.g. `@1x`, `@2x` and `@3x`). In that scenario, all of the scales will be inlined into the bundle since it's not possible to determine which scale is needed at runtime.

:::

## Usage

To inline assets you have to pass `inline: true` option to the [Assets loader](/api/loaders/assets-loader.md):

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      {
        test: Repack.getAssetExtensionsRegExp(),
        use: {
          loader: "@callstack/repack/assets-loader",
          options: { inline: true },
        },
      },
    ],
  },
};
```

You can also use the `inline: true` option in the [getAssetsTransformRules](/api/utils/get-asset-transform-rules.md) helper function:

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [...Repack.getAssetsTransformRules({ inline: true })],
  },
};
```

This will cause all assets processed by Assets loader in the rule to be inlined into the JavaScript bundle.

Inlined assets are imported in the same way as extracted assets:

```jsx
import image from './image.png';

<Image source={image} />
// or
<Image source={require('./image.png')} />
```

The value of `image` in this example would be either an object with `uri`, `width`, `height` and `scale` or an array of such objects, in case there are multiple scales.

## Size-based inlining

You can combine `inline: true` with `maxInlineSize` to set a file size threshold in bytes. Assets whose **largest scale variant** is smaller than or equal to the threshold will be inlined; larger assets will be extracted as separate files.

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      {
        test: Repack.getAssetExtensionsRegExp(),
        use: {
          loader: "@callstack/repack/assets-loader",
          options: { inline: true, maxInlineSize: 20 * 1024 }, // inline assets up to 20 KB
        },
      },
    ],
  },
};
```

Or via the helper:

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [...Repack.getAssetTransformRules({ inline: true, maxInlineSize: 20 * 1024 })],
  },
};
```

:::info Scale variants and the size threshold

The threshold is compared against the **largest scale variant** of the asset (e.g. `@3x`), not the `@1x` file. This is intentional — when an asset is inlined, all scale variants are embedded into the bundle, so the largest one is what determines the worst-case size impact.

For example, a `@1x` PNG that is 10 KB may have a `@3x` variant of 80 KB. With `inline: true` and `maxInlineSize: 20 * 1024` the asset would be extracted, not inlined, because the `@3x` variant exceeds the threshold.

:::

## Selective inlining by path

You can provide multiple rules with Re.Pack's [Assets loader](/api/loaders/assets-loader.md) - one rule would extract the assets and another would inline them. There's no limit how many of these rules you could have.

Make sure you configure those rules not to overlap, so that any single asset is only processed by one rule (by one [Assets loader](/api/loaders/assets-loader.md)). Use combination of `include`, `exclude` and `test` (for extensions matching) to configure each rule.

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      // only assets in the inlineAssets folder should be inlined
      {
        test: Repack.getAssetExtensionsRegExp(),
        include: [path.join(context, "src/assetsTest/inlineAssets")],
        use: {
          loader: "@callstack/repack/assets-loader",
          options: { inline: true },
        },
      },
      // treat all other assets like native assets
      {
        test: Repack.getAssetExtensionsRegExp(),
        exclude: [path.join(context, "src/assetsTest/inlineAssets")],
        use: "@callstack/repack/assets-loader",
      },
    ],
  },
};
```

:::tip Learn more about loader rules

You can read more about loader rules and how to configure them in:

- [Rspack Module Rules documentation](https://rspack.dev/config/module.html#modulerules)
- [Webpack Module Rules documentation](https://webpack.js.org/configuration/module/#modulerules)

:::



---
url: /docs/guides/remote-assets.md
---

# Remote assets

Re.Pack provides you with a way to extract and serve your assets externally, such as on a CDN,
instead of bundling them directly into your application. When working with ModuleFederation
this is the recommended approach to handling the assets in federated modules, as inlining
the assets causes your bundle size to increase dramatically.

:::tip Use remote assets only in production
During development, it's best to disable remote assets and load them locally. When you're ready to move to production, you can use `enabled: true` and then upload the assets to the CDN of your choosing.
:::

## Usage

To convert assets to remote assets you have to configure `remote` option in the [Assets loader](/api/loaders/assets-loader.md):

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      {
        test: Repack.getAssetExtensionsRegExp(),
        use: {
          loader: "@callstack/repack/assets-loader",
          options: {
            remote: {
              enabled: true,
              publicPath: "http://localhost:9999",
            },
          },
        },
      },
    ],
  },
};
```

You can also use the remote assets configuration with [getAssetsTransformRules](/api/utils/get-asset-transform-rules.md) helper function:

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      ...Repack.getAssetsTransformRules({
        remote: {
          enabled: true,
          publicPath: "http://localhost:9999",
        },
      }),
    ],
  },
};
```

Remote assets are imported in the same way as local assets:

```jsx
import image from './image.png';
<Image source={image} />
// or
<Image source={require('./image.png')} />
```

In both cases shown above, the the value of `source` prop will resolve to an object of shape:

```ts
type Source = {
  uri: string;
  width: number;
  height: number;
  scale: number;
};
```

### Default behaviour

The `uri` prop will have a value of an URL that's constructed by joining `publicPath`, 'assets' and local path to the asset together. If `publicPath` is set to [https://example.com](https://example.com) and the local path to the asset is logo.png, then the resulting `uri` value would be: `https://example.com/assets/images/logo.png`.

:::info Scaled assets are fully supported

The asset will resolve to proper scale in runtime by constructing a relevant URL with scale suffix at the end of it.

:::

When you create a production bundle, a directory called `remote-assets` will be included in your project's build directory. This directory contains all of the remote assets that are needed for your application.

By default, the remote-assets directory will be located at `build/generated/<platform>/remote-assets`. However, if you want the remote assets to appear in the `OutputPlugin` directory, which is part of the `RepackPlugin`, you will need to configure an additional property called `auxiliaryAssetsPath`:

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = (env) => {
  const { platform } = env;

  return {
    plugins: [
      new Repack.RepackPlugin({
        output: {
        auxiliaryAssetsPath: path.join("build/output", platform, "remote"),
      },
    }),
  ],
};
```

The final step is to upload your remote assets to your CDN, which is located at `publicPath`, and then host them from that location, which will make them available to users of your app.

### Customizing Asset Path

The `assetPath` option offers finer control over how remote asset paths are constructed. This feature allows you to define a custom function for modifying paths, which can be helpful if you need to apply custom naming conventions or add extra directory layers.
Specified pattern will be applied to both the generated folder path and URL. If `assetPath` is not provided, the [default behaviour](#default-behaviour) will be used.

Consider the following example:

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

function getCustomAssetPath({
  resourceFilename,
  resourceDirname,
  resourceExtensionType,
}) {
  const customHash = getCustomHash();
  return `my-remote-assets/${resourceFilename}-${customHash}.${resourceExtensionType}`;
}

module.exports = {
  module: {
    rules: [
      {
        test: Repack.getAssetExtensionsRegExp(),
        use: {
          loader: "@callstack/repack/assets-loader",
          options: {
            remote: {
              enabled: true,
              publicPath: "http://localhost:9999",
              assetPath: getCustomAssetPath,
            },
          },
        },
      },
    ],
  },
};
```

The configuration above would generate the following paths:

| Property   | Value                                                                     |
| ---------- | ------------------------------------------------------------------------- |
| asset path | `<buildFolder>/remote-assets/assets/my-remote-assets/logo-customhash.png` |
| asset URL  | `http://localhost:9999/my-remote-assets/logo-customhash.png`              |



---
url: /docs/guides/svg.md
---

# SVG support

By default, Re.Pack's [Assets loader](/api/loaders/assets-loader.md) is configured to allow you to import SVGs in you code, but that doesn't mean you can render them immediately.

## Pre-requisites

To render SVGs in your application, you first need to add [`react-native-svg`](https://github.com/react-native-svg/react-native-svg) native module to your application.

Please follow this installation instructions [here](https://github.com/react-native-svg/react-native-svg#installation).

## Exclude SVG from Re.Pack's Assets loader

Now that you have [`react-native-svg`](https://github.com/react-native-svg/react-native-svg) installed and linked into the application, you need to tell Rspack (or webpack) **not to use** Re.Pack's [Assets loader](/api/loaders/assets-loader.md) from processing SVGs, since you will process them manually later.

Go to your Rspack/webpack configuration file and apply the following diff:

```diff
      {
        test: ReactNative.getAssetExtensionsRegExp(
-         ReactNative.ASSET_EXTENSIONS
+         ReactNative.ASSET_EXTENSIONS.filter((ext) => ext !== 'svg')
        ),
        use: {
          loader: '@callstack/repack/assets-loader',
```

:::tip

If you don't have Re.Pack's Assets loader rule in your Rspack/webpack config, read [this guide](/api/loaders/assets-loader.md#migrating-from-assetsplugin) first.

:::

Now you need to tell Rspack/webpack how to handle `.svg` files.

## Using `@svgr/webpack`

Using [SVGR](https://react-svgr.com/) is a good option, if you want to render imported SVGs in the
same way as you would render any other React component:

```js
import * as React from "react";
import DeveloperActivitySvg from "./undraw_Developer_activity_re_39tg.svg";

export function MyComponent() {
  return <DeveloperActivitySvg width="100%" height="400" />;
}
```

### Setup

To use SVGR, you need to add an additional rule to process SVGs with `@svgr/webpack` loader.

Go to your Rspack/webpack configuration and apply the following diff:

```diff title="rspack.config.js"
module.exports = {
  // ...
  module: {
    // ...
    rules: [
      // ...
+     {
+       test: /\.svg$/,
+       use: [
+         {
+           loader: '@svgr/webpack',
+           options: {
+             native: true,
+             // You might want to uncomment the following line.
+             // More info: https://react-svgr.com/docs/options/#dimensions
+             // dimensions: false,
+           },
+         },
+       ],
+     },
    ],
    // ...
  },
  // ...
};
```

Thanks to the rule above, your SVGs will be processed by `@svgr/webpack` and converted to components
from [`react-native-svg`](https://github.com/react-native-svg/react-native-svg) allowing you to simply
import the component and render it as a React component.

## Using asset modules

Using Rspack/webpack's asset modules is a simpler and faster way to render SVGs in your application.
It's a good option, if you don't need or care about using the imported SVG as React component,
and you're fine with using `SvgXml` or `SvgUri` component from [`react-native-svg`](https://github.com/react-native-svg/react-native-svg).

:::info

You can read more about Rspack/webpack's asset modules [here](https://rspack.dev/guide/features/asset-module).

:::

### `SvgXml` + `asset/source`

The SVG file will be included in a bundle as a raw source in a separate module.

```js
import * as React from "react";
import { SvgXml } from "react-native-svg";
import developerActivitySvgXml from "./undraw_Developer_activity_re_39tg.svg";

export function MyComponent() {
  return <SvgXml xml={developerActivitySvgXml} width="100%" height="400" />;
}
```

### `SvgUri` + `asset/inline`

The SVG file will be included in a bundle as a data URI in a separate module.

```js
import * as React from "react";
import { SvgUri } from "react-native-svg";
import developerActivitySvgUri from "./undraw_Developer_activity_re_39tg.svg";

export function MyComponent() {
  return <SvgUri uri={developerActivitySvgUri} width="100%" height="400" />;
}
```

### Setup

To use asset modules, you need to add additional rule to process SVGs as an asset module.

Go to your Rspack/webpack configuration and apply the following diff:

```diff title="rspack.config.js"
module.exports = {
  // ...
  module: {
    // ...
    rules: [
      // ...
+     {
+       test: /\.svg$/,
+       type: 'asset/source', // or `asset/inline`
+     },
    ],
    // ...
  },
  // ...
};
```

Now you can import the XML of your SVG in you code and render it using `SvgXml` from [`react-native-svg`](https://github.com/react-native-svg/react-native-svg) or `SvgUri` if you chose `asset/inline` type.

:::info

If you want to inline SVGs as data URI, use `asset/inline` in the rule:

```js
{
  test: /\.svg$/,
  type: 'asset/inline',
},
```

Remember to use `SvgUri` for inlined SVGs instead of `SvgXml`.

:::

You can also use both, `asset/source` and `asset/inline` in your application:

```diff title="rspack.config.cjs"
module.exports = {
  // ...
  module: {
    // ...
    rules: [
      // ...
+     {
+       test: /\.svg$/,
+       include: /assets\/source\//,
+       type: 'asset/source',
+     },
+     {
+       test: /\.svg$/,
+       include: /assets\/inline\//,
+       type: 'asset/inline',
+     },
    ],
    // ...
  },
  // ...
};
```

:::tip

When using both `assets/source` and `assets/inline`, you can specify different `test`, `include` and `exclude` values,
so that Rspack/webpack can figure out which mechanism to use for which SVG. You can read more about rule conditions here:

- [Condition](https://rspack.dev/config/module#condition)
- [Rule.include](https://rspack.dev/config/module#ruleinclude)
- [Rule.exclude](https://rspack.dev/config/module#ruleexclude)
- [Rule.test](https://rspack.dev/config/module#ruletest)

:::

:::warning

Do not use `asset/resource` type, as it won't work correctly in React Native and can potentially
crash your application.

:::



---
url: /docs/migration-guides/metro.md
---

# Migrating from Metro

If the automatic migration using `@callstack/repack-init` didn't work for any reason,
or if you have custom project structure, you can follow these manual migration steps:

### 1. Dependencies

Install required dependencies in your project:


**Rspack**


```sh [npm]
npm install -D @rspack/core @swc/helpers @callstack/repack
```

```sh [yarn]
yarn add -D @rspack/core @swc/helpers @callstack/repack
```

```sh [pnpm]
pnpm add -D @rspack/core @swc/helpers @callstack/repack
```

```sh [bun]
bun add -D @rspack/core @swc/helpers @callstack/repack
```

```sh [deno]
deno add -D npm:@rspack/core npm:@swc/helpers npm:@callstack/repack
```


**webpack**


```sh [npm]
npm install -D webpack terser-webpack-plugin @callstack/repack
```

```sh [yarn]
yarn add -D webpack terser-webpack-plugin @callstack/repack
```

```sh [pnpm]
pnpm add -D webpack terser-webpack-plugin @callstack/repack
```

```sh [bun]
bun add -D webpack terser-webpack-plugin @callstack/repack
```

```sh [deno]
deno add -D npm:webpack npm:terser-webpack-plugin npm:@callstack/repack
```


This will install the latest versions of your chosen bundler and necessary dependencies for code optimization and minification.

Once the dependencies are installed, you need to tell React Native Community CLI to add Re.Pack's commands.

### 2. Commands

Add the following content to `react-native.config.js` (or create it if it doesn't exist):


**Rspack**

```js title="react-native.config.js"
module.exports = {
  commands: require('@callstack/repack/commands/rspack'),
};
```


**webpack**

```js title="react-native.config.js"
module.exports = {
  commands: require('@callstack/repack/commands/webpack'),
};
```


This will allow you to use Re.Pack when running `react-native start` and `react-native bundle` commands.

### 3. Configuration

Pick one of the templates below and create configuration file in the root directory of your project. The name of the file should be identical to the one on top of the template e.g. `rspack.config.mjs`.


**Rspack ESM**


```js title=rspack.config.mjs
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import * as Repack from '@callstack/repack';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

/**
 * Rspack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about Rspack configuration: https://rspack.dev/config/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

export default Repack.defineRspackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          parallel: true,
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```
{RspackESMTemplate}


**Rspack CJS**


```js title=rspack.config.cjs
const Repack = require('@callstack/repack');

/**
 * Rspack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about Rspack configuration: https://rspack.dev/config/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

module.exports = Repack.defineRspackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          parallel: true,
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```


**webpack ESM**


```js title=webpack.config.mjs
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import * as Repack from '@callstack/repack';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

/**
 * Webpack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about webpack configuration: https://webpack.js.org/configuration/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

export default Repack.defineWebpackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```


**webpack CJS**


```js title=webpack.config.cjs
const Repack = require('@callstack/repack');

/**
 * Webpack configuration enhanced with Re.Pack defaults for React Native.
 *
 * Learn about webpack configuration: https://webpack.js.org/configuration/
 * Learn about Re.Pack configuration: https://re-pack.dev/docs/guides/configuration
 */

module.exports = Repack.defineWebpackConfig({
  context: __dirname,
  entry: './index.js',
  resolve: {
    ...Repack.getResolveOptions(),
  },
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: 'javascript/auto',
        use: {
          loader: '@callstack/repack/babel-swc-loader',
          options: {},
        },
      },
      ...Repack.getAssetTransformRules(),
    ],
  },
  plugins: [new Repack.RepackPlugin()],
});

```


:::info Go with ESM config by default

We recommend to use ESM version of Rspack/webpack config with the `.mjs` extension. However, Re.Pack also supports ESM under `.js` and CJS variant under `.js` and `.cjs` extensions. Check our [templates](https://github.com/callstack/repack/blob/main/templates/) for CJS and ESM variants as well as the documentation on [Configuration](/docs/guides/configuration.md) to see the list of all available Rspack/webpack config location and extensions.

:::

### 4. Configure XCode

When building release version of your application XCode project will still use Metro to bundle the application, so you need to adjust build settings to make XCode use Re.Pack instead.

Open your application's Xcode project/workspace and:

1. Click on the project in **_Project navigator_** panel on the left
2. Go to **_Build Phases_** tab
3. Expand **_Bundle React Native code and images_** phase
4. Add following content to the phase:

```bash
if [[ -f "$PODS_ROOT/../.xcode.env" ]]; then
source "$PODS_ROOT/../.xcode.env"
fi
if [[ -f "$PODS_ROOT/../.xcode.env.local" ]]; then
source "$PODS_ROOT/../.xcode.env.local"
fi

export CLI_PATH="$("$NODE_BINARY" --print "require('path').dirname(require.resolve('@react-native-community/cli/package.json')) + '/build/bin.js'")"
```

After the change, the content of this phase should look similar to:

```bash title="Bundle React Native code and images" {6-13}
set -e

WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"
REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"

if [[ -f "$PODS_ROOT/../.xcode.env" ]]; then
source "$PODS_ROOT/../.xcode.env"
fi
if [[ -f "$PODS_ROOT/../.xcode.env.local" ]]; then
source "$PODS_ROOT/../.xcode.env.local"
fi

export CLI_PATH="$("$NODE_BINARY" --print "require('path').dirname(require.resolve('@react-native-community/cli/package.json')) + '/build/bin.js'")"

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"
```

### 5. Install CocoaPods dependencies

For iOS development, you need to install CocoaPods dependencies. From the project root directory run:

```bash
npx pod-install
```

This will install all the necessary iOS dependencies for your project, including the Re.Pack native module.

:::tip 🎉 Congratulations!

You've successfully set up Re.Pack in your project. We highly recommend to check out the following:

- [Configuration Guide](/docs/guides/configuration.md) to learn how to configure Re.Pack to your project needs.
- [API Reference](/api/index.md) to learn more about Re.Pack's API.

:::



---
url: /docs/migration-guides/repack-v4.md
---

# Migrating from Re.Pack 4

:::info Re.Pack 5 now supports Rspack!
Re.Pack 5 introduces support for [Rspack](https://rspack.dev/),
a high-performance webpack alternative with a highly compatible API.
This migration guide focuses solely on migrating from **V4** to **V5** while continuing to use webpack.

If you're interested in using Rspack (which is encouraged), we recommend first completing the migration
to **V5** with webpack and then following our separate [webpack to Rspack migration guide](/docs/migration-guides/rspack.md).
:::

:::danger Changes to internal plugins are not covered
Plugins that are part of `RepackPlugin` are considered internal and are not covered by this migration guide.
:::

## Update dependencies in `package.json`

The first step is to update the Re.Pack in the `devDependencies` section of your `package.json`:

```diff
{
  "devDependencies": {
-    "@callstack/repack": "4.x.x"
+    "@callstack/repack": "~5.0.0"
  }
}
```

You can also remove `babel-loader` from your `devDependencies` as Re.Pack 5 now includes it by default:

```diff
{
  "devDependencies": {
-    "babel-loader": "^9.1.3"
  }
}
```

:::tip Good time to update webpack and terser-webpack-plugin

While not necessary, for the best experience with Re.Pack 5,
we recommend updating your `webpack` and `terser-webpack-plugin` dependencies to their latest versions:

```json
{
  "devDependencies": {
    "webpack": "^5.98.0",
    "terser-webpack-plugin": "^5.3.11"
  }
}
```

:::

After updating the project dependencies, run the install command of your package manager:


```sh [npm]
npm install
```

```sh [yarn]
yarn install
```

```sh [pnpm]
pnpm install
```

```sh [bun]
bun install
```

```sh [deno]
deno install
```

## Update `react-native.config.js`

Since Re.Pack 5 now supports multiple bundlers (webpack and Rspack),
you need to specify that you want to use webpack commands explicitly.
Update your `react-native.config.js` in a following way:

```diff
module.exports = {
-  commands: require('@callstack/repack/commands'),
+  commands: require('@callstack/repack/commands/webpack'),
};
```

## Update webpack configuration

Below are the changes that you need to be aware of when migrating to Re.Pack 5. Most of the changes revolve around reducing the amount of configuration needed.

:::info Re.Pack 5 makes webpack configuration much smaller
In **V5** we've significantly simplified webpack configuration templates.
Many defaults are now configured out of the box, reducing the need for explicit
configuration and making your configuration files much cleaner and easier to maintain.

For a comprehensive guide on configuring webpack using Re.Pack 5, including all available
options, defaults, and configuration variants, please refer to our
[Configuration guide](/docs/guides/configuration.md).
:::

### Breaking: New configuration cascade system

A strict configuration cascade system was introduced to provide clear and predictable configuration resolution:

1. CLI flags (highest precedence)
2. Config values
3. Command defaults
4. Re.Pack defaults
5. Webpack/Rspack defaults (lowest precedence)

:::warning CLI arguments now bypass config files!
CLI arguments now always take the highest precedence and cannot be overridden by config files. This change aligns Re.Pack behavior with other similar CLI tools. Make sure to update your configuration with this in mind.
:::

For more details about the configuration system and available options and their defaults, see our [Configuration guide](/docs/guides/configuration.md#configuration-precedence).

### Breaking: `devtool` option is now used to configure sourcemaps

We've changed how sourcemaps are configured to align better with webpack's native configuration. The `devtool` option is now used to control the behavior of generated sourcemaps, replacing the previous `RepackPlugin` configuration. Please make sure to remove any `devtool: false` from your configuration to keep sourcemaps enabled.

```diff
-  devtool: false,
-  plugins: [
-    new RepackPlugin({
-      sourceMaps: true,
-    }),
-  ],
+  // Use webpack's native devtool option to configure sourcemaps
+  devtool: 'source-map',
```

:::tip You can remove the devtool option altogether
`devtool: 'source-map'` is now the default value in **V5**.
:::

The sourcemap handling is now managed by a dedicated internal `SourceMapPlugin` that's included in the `RepackPlugin` by default - you don't need to add it separately.

### Breaking: `getInitializationEntries` was removed

The `getInitializationEntries` helper function was removed as initialization entries are now configured automatically.

You can now simplify your entry configuration:

```diff
-  entry: [
-    ...Repack.getInitializationEntries(reactNativePath, {
-      hmr: devServer && devServer.hmr,
-    }),
-    entry,
-  ],
+  entry: './index.js', // or just entry if you're using env.entry
```

### Breaking: react-refresh transformation is now handled by `reactRefreshLoader`

We've changed how the React Refresh transformation is handled to make it compatible with both Rspack and webpack. The transformation now relies on `@rspack/plugin-react-refresh` which is shipped with Re.Pack and is configured automatically in the `RepackPlugin`.

You can simplify your `babel-loader` rule by removing the `react-refresh/babel` plugin from options:

```diff
{
  test: /\.[jt]sx?$/,
  exclude: /node_modules/,
-  use: {
-    loader: 'babel-loader',
-    options: {
-      plugins:
-        devServer && devServer.hmr
-          ? ['module:react-refresh/babel']
-          : undefined,
-    },
-  },
+  use: 'babel-loader'
}
```

### Breaking: Simplified RepackPlugin configuration

We've significantly reduced the required `RepackPlugin` configuration. Several options have been removed as they were redundant, and others have become optional as they can be inferred from your webpack configuration.

The following options have been **removed**:

```diff
plugins: [
  new RepackPlugin({
-    context,      
-    mode,         
-    sourceMaps,   
-    entryName,    
-    devServer,   
     output: {
-      bundleFilename,
-      sourceMapFilename,
-      assetsPath, 
     } 
  }),
]
```

The following options are now **optional**:

```diff
plugins: [
  new RepackPlugin({
-    platform,
-    output: {},
  }),
]
```

:::tip Minimal configuration
The plugin configuration object is now entirely optional. In most cases, you can use the minimal setup:

```js
plugins: [new Repack.RepackPlugin()]
```

For available options and their defaults, see the [RepackPlugin API documentation](/api/plugins/repack.md).
:::

### Breaking: Output configuration moved to CLI flags

Since output-related configuration options have been removed from `RepackPlugin`, the following properties: `bundleFilename`, `sourceMapFilename`, `assetsPath` are now controlled exclusively through their respective CLI flags - [see bundle command documentation](/api/cli/bundle.md).

### Breaking: Simplified `assets-loader` configuration

The `assets-loader` configuration has been simplified:

1. `devServerEnabled` was removed, it's now inferred automatically from configuration
2. `platform` was made optional and by default is inferred from configuration
3. `scalableAssetExtensions` is now optional and defaults to `Repack.SCALABLE_ASSETS`

You can now simplify your assets loader configuration:

```diff
{
  test: Repack.getAssetExtensionsRegExp(Repack.ASSET_EXTENSIONS),
  use: {
    loader: '@callstack/repack/assets-loader',
-    options: {
-      platform,
-      devServerEnabled: Boolean(devServer),
-      scalableAssetExtensions: Repack.SCALABLE_ASSETS,
-    },
  },
}
```

### Breaking: `JavaScriptLooseModePlugin` was removed

The `JavascriptLooseMode` plugin has been removed as it was no longer relevant. `@react-native/babel-preset` is now the exclusive handler for loose mode configuration.

### `getPublicPath` utility function is now deprecated

The `getPublicPath` utility function has been deprecated and now acts as a functional no-op. The default values are now configured out of the box, removing need for this utility. You can safely remove any usage of this utility:

```diff
output: {
-    publicPath: Repack.getPublicPath({platform, devServer}),
},
```

## Other notable changes

### React Native DevTools is now the only supported debugger

Legacy remote debugging support has been removed in favor of the new React Native DevTools, which is now enabled by default. The new debugger provides a better debugging experience specifically tailored for React Native applications and will be the only supported debugger going forward.

### Removed `--silent` flag from start command

The `--silent` CLI flag has been removed from the start command. To silence the output, you can use shell redirection instead:

```bash
# Unix/macOS
npx react-native start > /dev/null 2>&1

# Windows
npx react-native start > nul 2>&1
```

### Changed `--reverse-port` to `--no-reverse-port` in start command

The `--reverse-port` CLI option has been replaced with `--no-reverse-port`. This change makes it clearer that port reversing is enabled by default and the flag is used to disable it.

### Deprecated `--webpackConfig` in favor of `--config`

The `--webpackConfig` CLI option has been deprecated in favor of the new `--config` option. This change aligns the option name with other bundler configurations. While `--webpackConfig` will continue to work for now, we recommend updating your scripts to use `--config` instead:

```diff
- react-native webpack-bundle --webpackConfig webpack.config.js
+ react-native webpack-bundle --config webpack.config.js
```



---
url: /docs/migration-guides/rspack.md
---

# Migrating to Rspack

This guide will help you migrate your React Native project from using webpack to Rspack with Re.Pack.

:::warning ⚠️ Migrate to Re.Pack 5 first!

If your project is using version 4 of Re.Pack, you need to migrate it to use Re.Pack 5 first.

See the [Migration from Re.Pack 4 guide](/docs/migration-guides/repack-v4.md) for more details.
:::

:::tip Why migrate to Rspack?

[Rspack](https://rspack.dev/) is a fast Rust-based bundler that's compatible with the webpack ecosystem, offering significantly faster build times for both development and production while maintaining webpack compatibility with minimal migration effort.
For more details on why Rspack was created and its advantages, see the [official rationale](https://rspack.dev/guide/start/introduction#why-rspack).
:::

## Update dependencies in `package.json`

To use Rspack, you'll need to update your dependencies by adding the following:


```sh [npm]
npm install -D @rspack/core @swc/helpers
```

```sh [yarn]
yarn add -D @rspack/core @swc/helpers
```

```sh [pnpm]
pnpm add -D @rspack/core @swc/helpers
```

```sh [bun]
bun add -D @rspack/core @swc/helpers
```

```sh [deno]
deno add -D npm:@rspack/core npm:@swc/helpers
```

## Update `react-native.config.js`

Since Re.Pack now supports multiple bundlers, you need to specify that you want to use Rspack commands explicitly.
Update your `react-native.config.js` file to use Rspack commands:

```diff title="react-native.config.js"
module.exports = {
-  commands: require('@callstack/repack/commands/webpack'),
+  commands: require('@callstack/repack/commands/rspack'),
};
```

## Updating configuration

### 1. Rename your configuration file

Rename your configuration file to match the Rspack convention:

- 📄 `webpack.config.js` → `rspack.config.js`
- 📄 `webpack.config.mjs` → `rspack.config.mjs`
- 📄 `webpack.config.cjs` → `rspack.config.cjs`

### 2. Update your configuration

When migrating from webpack to Rspack, you'll need to make several changes to your configuration file.

:::warning Additional steps may be required for complex configurations
The modifications outlined below cover the basic changes needed for most React Native projects. However, if you have a more complex webpack setup with custom loaders, plugins, or configurations, these changes might not be sufficient.

For more advanced migration scenarios, refer to the [official Rspack migration guide](https://rspack.dev/guide/migration/webpack), which provides detailed instructions for migrating various webpack features, plugins, and loaders to their Rspack equivalents.
:::

#### Remove `TerserPlugin` import and configuration

Rspack uses [SwcJsMinimizerRspackPlugin](https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin) for minification, which is much faster than `TerserPlugin` and comes configured by default. You can remove both the `TerserPlugin` import and its configuration.

```diff
- const TerserPlugin = require('terser-webpack-plugin');
  const Repack = require('@callstack/repack');

  module.exports = (env) => {
    return {
-     optimization: {
-       minimizer: [
-         new TerserPlugin({
-           test: /\.(js)?bundle(\?.*)?$/i,
-           extractComments: false,
-           terserOptions: {
-             format: {
-               comments: false,
-             },
-           },
-         }),
-       ],
-     },
    };
  };
```

#### Replace `babel-loader` with `getJsTransformRules`

Rspack uses SWC for transpilation instead of Babel. The `getJsTransformRules()` helper function configures all necessary JavaScript/TypeScript transformation rules.

```diff
module: {
  rules: [
-   {
-     test: /\.[cm]?[jt]sx?$/,
-     use: 'babel-loader',
-     type: 'javascript/auto',
-   },
+   ...Repack.getJsTransformRules(),
    ...Repack.getAssetTransformRules(),
  ],
},
```

:::info About getJsTransformRules
The `getJsTransformRules()` function returns the default rules for transforming JavaScript and TypeScript files using SWC. It handles both your application code and `node_modules`, and is functionally equivalent to the official `@react-native/babel-preset`. For more details, see the [API documentation for getJsTransformRules](/api/utils/get-js-transform-rules.md).
:::

#### Configure Flow support (if needed)

If your project uses [Flow](https://flow.org/) for type checking, you'll need to add a dedicated loader since SWC (used by Rspack) doesn't support Flow natively. Re.Pack provides a `@callstack/repack/flow-loader` to strip Flow type annotations from your code. Add the following rule to your module configuration:

```diff title="rspack.config.cjs"
module.exports = {
  module: {
    rules: [
      ...Repack.getJsTransformRules(),
      ...Repack.getAssetTransformRules(),
+     {
+       test: /\.jsx?$/,
+       type: 'javascript/auto',
+       exclude: /node_modules/,
+       use: {
+         loader: '@callstack/repack/flow-loader',
+         options: { all: true },
+       },
+     },
    ],
  },
};
```

:::tip Flow-typed libraries

There is no need to configure Flow support for libraries since `getJsTransformRules` handles them out of the box. In rare cases, you may need to configure Flow support for unhandled libraries.

For more details, see our [Flow support documentation](/docs/features/flow-support.md).
:::

#### Use `@callstack/repack-plugin-reanimated`

If your project uses `react-native-reanimated`, we provide an official plugin to ensure optimal performance when bundling with Rspack.

To add the Re.Pack Reanimated plugin to your project:


```sh [npm]
npm install -D @callstack/repack-plugin-reanimated
```

```sh [yarn]
yarn add -D @callstack/repack-plugin-reanimated
```

```sh [pnpm]
pnpm add -D @callstack/repack-plugin-reanimated
```

```sh [bun]
bun add -D @callstack/repack-plugin-reanimated
```

```sh [deno]
deno add -D npm:@callstack/repack-plugin-reanimated
```

Then update your Rspack configuration file to include the plugin:

```js title="rspack.config.js"
const Repack = require('@callstack/repack');
const { ReanimatedPlugin } = require('@callstack/repack-plugin-reanimated');

module.exports = (env) => {
  return {
    plugins: [
      new Repack.RepackPlugin(),
      new ReanimatedPlugin(),
    ],
  };
};
```

For more details on using Reanimated with Re.Pack & Rspack, see our [Reanimated support](/docs/features/reanimated.md) page.

## Running your app

After migration, you can run the development server using the same command as before:


```sh [npx]
npx react-native start
```

```sh [yarn]
yarn react-native start
```

```sh [pnpm]
pnpm react-native start
```

```sh [bun]
bun react-native start
```

Same goes for creating a production bundle:


```sh [npx]
npx react-native bundle
```

```sh [yarn]
yarn react-native bundle
```

```sh [pnpm]
pnpm react-native bundle
```

```sh [bun]
bun react-native bundle
```

:::tip Having trouble?

If you are having trouble migrating to Rspack reach out and open an issue on [GitHub](https://github.com/callstack/repack/issues/new/choose).
:::

## Cleanup

After successfully migrating to Rspack and confirming that your app runs correctly, you can remove webpack-related dependencies that are no longer needed:


```sh [npm]
npm uninstall webpack terser-webpack-plugin
```

```sh [yarn]
yarn remove webpack terser-webpack-plugin
```

```sh [pnpm]
pnpm remove webpack terser-webpack-plugin
```

```sh [bun]
bun remove webpack terser-webpack-plugin
```



---
url: /docs/resources/glossary.md
---

# Glossary of terms

## Bundle

A collection of processed (compiled, transformed) code, packed together into self-contained format
by a _bundler_ (e.g: webpack, Rollup, etc). It includes not only the processed source code, but all
the necessary dependencies and usually static assets.

## Main bundle

A special form of a [Bundle](#bundle), which is also self-executable (standalone).
Meaning executing the Main bundle inside a JavaScript Virtual Machine will run your application.

Also known as _Index bundle_.

## Chunk

A lighter version of a [Bundle](#bundle), designed to be pulled in and used together with the
[Main bundle](#main-bundle). A chunk is usually deferred and loaded on demand by the
[Main bundle](#main-bundle) or another chunk. Chunks can usually implicitly share and reuse
dependencies from each other and the [Main bundle](#main-bundle).

## Async chunk

A version of a [Chunk](#chunk), which is loaded in an asynchronous manner.
In context of React Native, all [Chunks](#chunk) are loaded asynchronously, so [Chunk](#chunk)
and Async chunk can be used interchangeably.

## Local chunk

A [Chunk](#chunk) stored locally on a filesystem (of a mobile device), contrary to a [Remote chunk](#remote-chunk).

## Remote chunk

A [Chunk](#chunk) stored remotely on the server, CDN or any other network location, contrary to a [Local chunk](#local-chunk).

## Script

Arbitrary file with executable code. Can be a [Bundle](#bundle) created by a _bundler_ (e.g:
webpack, Rollup, etc) or manually by hand.

## Container

A special form of [Bundle](#bundle), which is created in
[Module Federation setup](/docs/features/module-federation.md) and is used by the [Main bundle](#main-bundle).
Containers can also use other Containers and [Chunks](#chunk).



---
url: /api/cli/bundle.md
---

# bundle

`bundle` or `webpack-bundle` is a command-line tool that builds the bundle for the provided project.

## Usage

In the root of an existing project, run this command in your terminal of choice:


```sh [npm]
npm run react-native bundle
```

```sh [yarn]
yarn react-native bundle
```

```sh [pnpm]
pnpm react-native bundle
```

```sh [bun]
bun react-native bundle
```

## Options

:::info

To stay compatible with the `@react-native-community/cli` command, the following flags are included but are not functional:

- `--config-cmd`

:::

### `--entry-file`

- Type: `string`

Path to the root JS file, either absolute or relative to JS root.

### `--platform`

- Type: `string`
- Default: `"ios"`

Either "ios" or "android".

### `--dev`

- Type: `boolean`
- Default: `true`

Enables development warnings and disables production optimizations.

### `--minify`

- Type: `boolean`

Allows overriding whether bundle is minified. This defaults to false if dev is true, and true if dev is false. Disabling minification can be useful for speeding up production builds for testing purposes.

### `--bundle-output`

- Type: `string`

File name where to store the resulting bundle, ex. /tmp/groups.bundle.

### `--sourcemap-output`

- Type: `string`

File name where to store the sourcemap file for resulting bundle, ex. /tmp/groups.map.

### `--assets-dest`

- Type: `string`

Directory name where to store assets referenced in the bundle.

### `--json`

- Type: `string`

Stores stats in a file.

### `--stats`

- Type: `string`

Instructs Rspack on how to treat the stats. Use with `--json` to store stats in a file.

- `'errors-only'` - only output when errors happen
- `'errors-warnings'` - only output errors and warnings happen
- `'minimal'` - only output when errors or new compilation happen
- `'none'` - output nothing
- `'normal'` - standard output
- `'verbose'` - output everything
- `'detailed'` - output everything except chunkModules and chunkRootModules
- `'summary'` - output webpack version, warnings count and errors count

Example:


```sh [npm]
npm run react-native bundle --stats summary --json ./stats.json
```

```sh [yarn]
yarn react-native bundle --stats summary --json ./stats.json
```

```sh [pnpm]
pnpm react-native bundle --stats summary --json ./stats.json
```

```sh [bun]
bun react-native bundle --stats summary --json ./stats.json
```

More details: [Rspack documentation](https://rspack.dev/config/stats)

### `--reset-cache`

- Type: `boolean`

Resets the transformation cache.

### `--verbose`

- Type: `boolean`

Enables verbose logging.

### `--watch`

- Type: `boolean`
- Default: `false`

Watch for file changes.

### `--max-workers`

- Type: `number`

(Rspack only) The maximum number of workers to use for transformation parallelization. By default, the number of workers is derived from available CPU cores.

### `--config`

- Type: `string`

Path to a bundler config file, e.g rspack.config.js.

### `--bundler`

- Type: `"rspack" | "webpack"`

Select the bundler explicitly. Without this option, Re.Pack infers the bundler from the `--config` filename, then checks the standard Rspack and webpack config filenames, and defaults to Rspack.

### `--webpackConfig`

- Type: `string`
- Deprecated: Use [`--config`](#--config) instead

Path to a bundler config file, e.g webpack.config.js.

### `-h`, `--help`

Display help for command.



---
url: /api/cli/init.md
---

# Init

`@callstack/repack-init` is a command-line tool that initializes Re.Pack setup in React Native projects or creates a new React Native app with Re.Pack pre-configured.

The tool detects whether it's being run in an existing React Native project or outside of it and decides what to do based on that.

## Usage


```sh [npx]
npx @callstack/repack-init
```

```sh [yarn]
yarn dlx @callstack/repack-init
```

```sh [pnpm]
pnpm dlx @callstack/repack-init
```

```sh [bunx]
bunx @callstack/repack-init
```

![repack-init](/img/init.png)
## Options

### `--bundler`, `-b`

- Type: `rspack` | `webpack`
- Required: `true`

Specify the bundler to use.

### `--custom-version`, `-c`

- Type: `string`
- Default: `latest`

Specify the version of `@callstack/repack` to install.

### `--entry`, `-e`

- Type: `string`
- Default: `index.js`

Path to the main entry point of the React-Native project.

### `--format`, `-f`

- Type: `mjs` | `cjs`
- Default: `mjs`

Format of the config file.

### `--verbose`, `-v`

- Type: `boolean`
- Default: `false`

Enable verbose logging.

### `--version`

Show version number.

### `--help`

Show help information.



---
url: /api/cli/start.md
---

# start

`start` or `webpack-start` is a command-line tool that starts the React Native development server with webpack integration.

## Usage

In the root of an existing React Native project with Re.Pack, run this command in your terminal of choice:


```sh [npm]
npm run react-native start
```

```sh [yarn]
yarn react-native start
```

```sh [pnpm]
pnpm react-native start
```

```sh [bun]
bun react-native start
```

![start](/img/start.png)

## Options

### `--port`

- Type: `number`

The port number that runs the server on.

### `--host`

- Type: `string`
- Default: `""`

Set the server host.

### `--https`

- Type: `boolean`

Enables HTTPS connections to the server.

### `--key`

- Type: `path`

Path to custom SSL key.

### `--cert`

- Type: `path`

Path to custom SSL certificate.

### `--no-interactive`

- Type: `boolean`

Disables interactive mode.

### `--json`

- Type: `boolean`

Log all messages to the console/stdout in JSON format.

### `--log-file`

- Type: `path`

Enables file logging to specified file.

### `--log-requests`

- Type: `boolean`

Enables logging of all requests to the server.

### `--platform`

- Type: `string`

Run the dev server for the specified platform only. By default, the dev server will bundle for all platforms.

### `--no-reverse-port`

- Type: `boolean`

Disables running ADB reverse automatically when bundling for Android.

### `--reset-cache`, `--resetCache`

- Type: `boolean`

Resets the transformation cache.

### `--verbose`

- Type: `boolean`

Enables verbose logging.

### `--max-workers`

- Type: `number`

(Rspack only) The maximum number of workers to use for transformation parallelization. By default, the number of workers is derived from available CPU cores.

### `--config`

- Type: `path`

Path to a bundler config file, e.g webpack.config.js.

### `--bundler`

- Type: `"rspack" | "webpack"`

Select the bundler explicitly. Without this option, Re.Pack infers the bundler from the `--config` filename, then checks the standard Rspack and webpack config filenames, and defaults to Rspack.

### `--webpackConfig`

- Type: `path`
- Deprecated: Use [`--config`](#--config) instead

Path to a bundler config file, e.g webpack.config.js.

### `-h`, `--help`

Display help for command.



---
url: /api/dev-server.md
---

# DevServer

The Re.Pack DevServer is built on top of [Fastify](https://fastify.dev/) and provides a subset of `webpack-dev-server`  configuration options.

## Usage

The DevServer is configured through the `devServer` option in your configuration:

```js title="rspack.config.mjs"
import * as Repack from '@callstack/repack';

export default {
  // ... other options
  devServer: {
    port: 8081,
    host: 'localhost', 
    hot: true,
    // ... other DevServer options
  },
  plugins: [
    new Repack.RepackPlugin(),
  ],
};
```

## Configuration Options

### host

- Type: `string`
- Default: `'localhost'`

Hostname or IP address under which to run the development server.

Supported special values:

- `'local-ip'` - Listen on all available network interfaces
- `'local-ipv4'` - Listen on local IPv4 address
- `'local-ipv6'` - Listen on local IPv6 address

### port

- Type: `number`
- Default: `8081`

Port under which to run the development server.

### hot

- Type: `boolean`
- Default: `true`

Whether to enable Hot Module Replacement (HMR).

### server

- Type: `'http' | 'https' | { type: 'http' } | { type: 'https'; options?: HttpsServerOptions }`
- Default: `'http'`

Options for running the server as HTTPS. When set to `'https'` or `{ type: 'https' }`, the server will run with HTTPS using default options. For custom HTTPS configuration, provide an options object.

```js title="rspack.config.mjs"
import fs from 'node:fs';

export default {
  devServer: {
    server: 'https', // Simple HTTPS with default options
    // or
    server: {
      type: 'https',
      options: {
        key: fs.readFileSync('/path/to/server.key'),
        cert: fs.readFileSync('/path/to/server.crt'),
      },
    },
  },
};
```

### proxy

- Type: `ProxyConfig[]`
- Default: `undefined`

Configuration for proxying API requests. Each entry in the array defines a proxy rule that forwards matching requests to a target server.

```ts
interface ProxyConfig extends ProxyOptions {
  path?: ProxyOptions['pathFilter'];
  context?: ProxyOptions['pathFilter'];
}
```

The `ProxyConfig` extends [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware) options with webpack-dev-server compatible aliases:

- `path` - Alias for `pathFilter`
- `context` - Alias for `pathFilter`

```js title="rspack.config.mjs"
export default {
  devServer: {
    proxy: [
      {
        context: ['/api', '/auth'],
        target: 'http://localhost:3001',
        changeOrigin: true,
      },
      {
        path: '/graphql',
        target: 'http://localhost:4000',
        ws: true, // Proxy websockets
      },
    ],
  },
};
```

### setupMiddlewares

- Type: `SetupMiddlewaresFunction`
- Default: `undefined`

Function to customize middleware setup, allowing you to reorder, modify, or add custom middlewares.

```ts
type SetupMiddlewaresFunction = (
  middlewares: Middleware[],
  devServer: FastifyInstance
) => Middleware[];
```

The function receives:

- `middlewares` - Array of built-in middlewares
- `devServer` - Fastify server instance

Built-in middlewares include:

- `dev-middleware` - `@react-native/dev-middleware` enabling use of [React Native Devtools](/docs/features/devtools.md)
- `proxy-middleware-*` - proxy middlewares created via [proxy](#proxy)

```js title="rspack.config.mjs"
export default {
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      // Add custom middleware before built-ins
      middlewares.unshift({
        name: 'auth-middleware',
        middleware: (req, res, next) => {
          // Custom authentication logic
          next();
        },
      });
      
      // Add custom route
      devServer.get('/health', async () => {
        return { status: 'ok' };
      });
      
      return middlewares;
    },
  },
};
```

## Example

### Add middleware while respecting middlewares order

Use `unshift()` to run middleware before all other middlewares
or use `push()` to run middleware after all other middlewares:

```js title="rspack.config.mjs"
export default {
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      // add before every other middleware
      middlewares.unshift({
        name: 'first-in-array',
        path: '/foo/path',
        middleware: (req, res) => {
          res.send('Foo!');
        },
      });

      // add after every other middleware
      middlewares.push({
        name: 'hello-world-test-one',
        path: '/foo/bar',
        middleware: (req, res) => {
          res.send('Foo Bar!');
        },
      });

      return middlewares;
    },
  },
};
```

### Add new route to the DevServer directly

```js title="rspack.config.mjs"
export default {
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      devServer.get('/some/path', (_, response) => {
        response.send('/some/path GET response');
      });

      return middlewares;
    },
  },
};
```

### Access the DevServer logger

Access the DevServer instance for routes and logging:

```js title="rspack.config.mjs"
export default {
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      devServer.get('/test', (_, response) => {
        response.send('GET test response');
        devServer.log.info('GET /test called');
      });

      return middlewares;
    },
  },
};
```



---
url: /api/index.md
---

# Overview

## Command Line Interface (CLI)

### [Start](/api/cli/start.md)

- [Usage](/api/cli/start.md#usage)
- [Options](/api/cli/start.md#options)

### [Bundle](/api/cli/bundle.md)

- [Usage](/api/cli/bundle.md#usage)
- [Options](/api/cli/bundle.md#options)

### [Init](/api/cli/init.md)

- [Usage](/api/cli/init.md#usage)
- [Options](/api/cli/init.md#options)
## DevServer

### [DevServer](/api/dev-server.md)

- [Usage](/api/dev-server.md#usage)
- [Configuration Options](/api/dev-server.md#configuration-options)
- [Example](/api/dev-server.md#example)
## Runtime client

### [Script](/api/runtime/script.md)

- [Usage](/api/runtime/script.md#usage)
- [API Reference](/api/runtime/script.md#api-reference)
- [Related](/api/runtime/script.md#related)

### [ScriptManager](/api/runtime/script-manager.md)

- [Usage](/api/runtime/script-manager.md#usage)
- [API Reference](/api/runtime/script-manager.md#api-reference)
- [Events](/api/runtime/script-manager.md#events)
- [Hooks](/api/runtime/script-manager.md#hooks)
- [Advanced Usage](/api/runtime/script-manager.md#advanced-usage)
- [Customizing the native HTTP client](/api/runtime/script-manager.md#customizing-the-native-http-client)
- [Related](/api/runtime/script-manager.md#related)
## Loaders

### [AssetsLoader](/api/loaders/assets-loader.md)

- [Options](/api/loaders/assets-loader.md#options)
- [Example](/api/loaders/assets-loader.md#example)
- [Excluding Assets](/api/loaders/assets-loader.md#excluding-assets)

### [BabelLoader](/api/loaders/babel-loader.md)

- [Options](/api/loaders/babel-loader.md#options)
- [Babel TransformOptions](/api/loaders/babel-loader.md#babel-transformoptions)
- [Example](/api/loaders/babel-loader.md#example)

### [BabelSwcLoader](/api/loaders/babel-swc-loader.md)

- [Options](/api/loaders/babel-swc-loader.md#options)
- [Example](/api/loaders/babel-swc-loader.md#example)

### [FlowLoader](/api/loaders/flow-loader.md)

- [Options](/api/loaders/flow-loader.md#options)
- [Example](/api/loaders/flow-loader.md#example)

### [ReactRefreshLoader](/api/loaders/react-refresh-loader.md)

- [Example](/api/loaders/react-refresh-loader.md#example)
## Plugins

### [RepackPlugin](/api/plugins/repack.md)

- [Usage](/api/plugins/repack.md#usage)
- [Options](/api/plugins/repack.md#options)

### [ModuleFederationV1Plugin](/api/plugins/module-federation-v1.md)

- [Usage](/api/plugins/module-federation-v1.md#usage)
- [Configuration](/api/plugins/module-federation-v1.md#configuration)
- [Examples](/api/plugins/module-federation-v1.md#examples)

### [ModuleFederationV2Plugin](/api/plugins/module-federation-v2.md)

- [Mobile MF Quirks](/api/plugins/module-federation-v2.md#mobile-mf-quirks)
- [Installation](/api/plugins/module-federation-v2.md#installation)
- [Usage](/api/plugins/module-federation-v2.md#usage)
- [Configuration](/api/plugins/module-federation-v2.md#configuration)
- [Examples](/api/plugins/module-federation-v2.md#examples)

### [CodeSigningPlugin](/api/plugins/code-signing.md)

- [Usage](/api/plugins/code-signing.md#usage)
- [Options](/api/plugins/code-signing.md#options)
- [Guide](/api/plugins/code-signing.md#guide)

### [HermesBytecodePlugin](/api/plugins/hermes-bytecode.md)

- [Usage](/api/plugins/hermes-bytecode.md#usage)
- [Options](/api/plugins/hermes-bytecode.md#options)
- [Example](/api/plugins/hermes-bytecode.md#example)

### [Internal plugins](/api/plugins/internal.md)

- [OutputPlugin](/api/plugins/internal.md#outputplugin)
- [LoggerPlugin](/api/plugins/internal.md#loggerplugin)
- [NativeEntryPlugin](/api/plugins/internal.md#nativeentryplugin)
- [DevelopmentPlugin](/api/plugins/internal.md#developmentplugin)
- [RepackTargetPlugin](/api/plugins/internal.md#repacktargetplugin)
- [BabelPlugin](/api/plugins/internal.md#babelplugin)
- [CodegenPlugin](/api/plugins/internal.md#codegenplugin)
## Configuration utilities

### [Constants](/api/utils/constants.md)

- [ASSET_EXTENSIONS](/api/utils/constants.md#asset_extensions)
- [SCALABLE_ASSETS](/api/utils/constants.md#scalable_assets)
- [SCALABLE_RESOLUTIONS](/api/utils/constants.md#scalable_resolutions)

### [getAssetExtensionsRegExp](/api/utils/get-asset-extension-regexp.md)

- [Parameters](/api/utils/get-asset-extension-regexp.md#parameters)
- [Example](/api/utils/get-asset-extension-regexp.md#example)

### [getAssetTransformRules](/api/utils/get-asset-transform-rules.md)

- [Parameters](/api/utils/get-asset-transform-rules.md#parameters)
- [Example](/api/utils/get-asset-transform-rules.md#example)

### [getCodegenTransformRules](/api/utils/get-codegen-transform-rules.md)

- [Example](/api/utils/get-codegen-transform-rules.md#example)

### [getDirname](/api/utils/get-dirname.md)

- [Parameters](/api/utils/get-dirname.md#parameters)
- [Example](/api/utils/get-dirname.md#example)

### [getFlowTransformRules](/api/utils/get-flow-transform-rules.md)

- [Parameters](/api/utils/get-flow-transform-rules.md#parameters)
- [Example](/api/utils/get-flow-transform-rules.md#example)

### [getJsTransformRules](/api/utils/get-js-transform-rules.md)

- [Parameters](/api/utils/get-js-transform-rules.md#parameters)
- [Example](/api/utils/get-js-transform-rules.md#example)

### [getModulePaths](/api/utils/get-module-paths.md)

- [Parameters](/api/utils/get-module-paths.md#parameters)
- [Example](/api/utils/get-module-paths.md#example)

### [getResolveOptions](/api/utils/get-resolve-options.md)

- [Parameters](/api/utils/get-resolve-options.md#parameters)
- [Example](/api/utils/get-resolve-options.md#example)

### [getSwcLoaderOptions](/api/utils/get-swc-loader-options.md)

- [Parameters](/api/utils/get-swc-loader-options.md#parameters)
- [Example](/api/utils/get-swc-loader-options.md#example)



---
url: /api/loaders/assets-loader.md
---

# AssetsLoader

The `AssetsLoader` processes image and other static assets (video, audio, etc.) in your React Native application. It handles asset extraction, copying files to the appropriate platform-specific output directories, and supports additional features like base64 inlining and conversion into remote assets.

:::info Platform-Specific Output
By default, extracted asset files are copied to `assets/` directory for iOS and `drawable-*` directories (e.g. `drawable-mdpi`, `drawable-hdpi`, etc.) for Android which matches Metro's asset handling behavior.
:::

:::tip Guides related to AssetsLoader
Looking to do more with your assets? Check out the guides on:

- [Inlining assets as base64 strings](/docs/guides/inline-assets.md)
- [Converting to remote assets](/docs/guides/remote-assets.md)
- [Adding SVG support](/docs/guides/svg.md)

:::

## Options

```ts
type AssetPathArgs = {
  resourcePath: string;
  resourceFilename: string;
  resourceDirname: string;
  resourceExtensionType: string;
};

type AssetPathFn = (args: AssetPathArgs) => string;

interface AssetsLoaderOptions {
  platform?: string;
  scalableAssetExtensions?: string[];
  scalableAssetResolutions?: string[];
  devServerEnabled?: boolean;
  inline?: boolean;
  maxInlineSize?: number;
  publicPath?: string;
  remote?: {
    enabled: boolean;
    publicPath: string;
    assetPath?: AssetPathFn;
  };
}
```

### platform

- Type: `string`
- Default: `compiler.options.name`

Target platform (e.g. `ios` or `android`). The default value is the name of the compiler which Re.Pack sets to the target platform.

### scalableAssetExtensions

- Type: `string[]`
- Default: `SCALABLE_ASSETS`

Array of file extensions that support scaling suffixes (`@1x`, `@2x` etc).

See [SCALABLE\_ASSETS](/api/utils/constants.md#scalable_assets) for a list of extensions supported by default.

### scalableAssetResolutions

- Type: `string[]`
- Default: `SCALABLE_RESOLUTIONS`

Array of supported resolution scales.

See [SCALABLE\_RESOLUTIONS](/api/utils/constants.md#scalable_resolutions) for a list of resolutions supported by default.

### devServerEnabled

- Type: `boolean`
- Default: `undefined`

Whether development server is enabled. By default, this option is determined by checking if `compiler.options.devServer` is defined.

### inline

- Type: `boolean`
- Default: `false`

When true, assets will be inlined as base64 in the JS bundle instead of being extracted to separate files.

### maxInlineSize

- Type: `number`
- Default: `undefined`

File size threshold in bytes used together with `inline: true`. Assets whose largest scale variant is smaller than or equal to this value will be inlined; larger assets will be extracted as separate files. Has no effect when `inline` is not `true`.

The threshold is compared against the **largest scale variant** (e.g. `@3x`), not the `@1x` file — when an asset is inlined, all scale variants are embedded into the bundle.

:::tip
Learn more about size-based inlining in the [Inlining Assets guide](/docs/guides/inline-assets.md#size-based-inlining).
:::

### publicPath

- Type: `string`
- Default: `undefined`

Public path for local asset URLs.

### remote

- Type: `object`

Configuration for remote asset handling.

#### remote.enabled

- Type: `boolean`
- Required: `true`

When true, assets will be converted to remote assets meant to be served from a CDN or external server.

#### remote.publicPath

- Type: `string`
- Required: `true`

Base URL where remote assets will be hosted. Must start with `http://` or `https://`.

#### remote.assetPath

- Type: `(args: AssetPathArgs) => string`
- Default: `undefined`

Custom function to control how remote asset paths are constructed. Applied to both generated folder paths and URLs.

```ts
type AssetPathArgs = {
  resourcePath: string;
  resourceFilename: string;
  resourceDirname: string;
  resourceExtensionType: string;
};
```

```js
{
  remote: {
    enabled: true,
    publicPath: 'https://cdn.example.com',
    assetPath: ({ resourceFilename }) => `assets/${resourceFilename}`
  }
}
```

## Example

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      {
        test: Repack.getAssetExtensionsRegExp(),
        use: "@callstack/repack/assets-loader",
      },
    ],
  },
};
```

## Excluding Assets

You can exclude specific asset types from being processed by the `AssetsLoader`. This is useful when you want to use a different loader for certain file types (e.g. `.svg` files)

Here's how to exclude `.svg` files and process them with a custom loader instead:

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      // Process all assets except SVGs with AssetsLoader
      {
        test: Repack.getAssetExtensionsRegExp(
          Repack.ASSET_EXTENSIONS.filter((ext) => ext !== "svg")
        ),
        use: "@callstack/repack/assets-loader",
      },
      // Process SVGs with a custom loader
      {
        test: /\.svg$/,
        use: "your-custom-svg-loader",
      },
    ],
  },
};
```



---
url: /api/loaders/babel-loader.md
---

# BabelLoader

The `BabelLoader` runs Babel transformations for JavaScript and TypeScript sources in React Native projects. It chooses the parser based on source type: `hermes-parser` for JavaScript and Flow-typed files, and Babel's standard parser for TypeScript files.

:::info How this loader differs from babel-loader

There are two similarly named loaders: `@callstack/repack/babel-loader` (this loader) and `babel-loader` from npm. This loader is tailored for Re.Pack and aims for Metro parity, so the same Babel config used in Metro works as-is in Re.Pack. It automatically selects the parser by source type (Hermes parser for JS/JSX and Flow, Babel parser for TypeScript).

It is also optimized for parallel transforms. In Rspack, enable [`experiments.parallelLoader`](https://rspack.rs/config/experiments#experimentsparallelloader) to fan out transforms; in webpack, pair it with [`thread-loader`](https://www.npmjs.com/package/thread-loader) to run a worker pool. On projects with heavier Babel pipelines, this often translates into noticeably faster builds.

:::

## Options

```ts
// All Babel options from `@babel/core` are supported
type BabelTransformOptions = import('@babel/core').TransformOptions

type BabelLoaderOptions = BabelTransformOptions & {
  babel?: boolean;
  flow?: "all" | "detect";
  reactRuntimeTarget?: "18" | "19";
  sourceType?: "module" | "script" | "unambiguous";
};
```

All options from the [Babel options documentation](https://babeljs.io/docs/options) are supported. See [Babel TransformOptions](#babel-transformoptions) below for more details.

### hermesParserPath

- Type: `string`

Optional path to use for importing `hermes-parser`. By default, the path is obtained automatically.

### hermesParserOverrides

- Type: `HermesParserOverrides`
- Default: `{ babel: true, reactRuntimeTarget: '19' }`

Overrides passed to `hermes-parser` when parsing non-TypeScript files.

```ts
type HermesParserOverrides = {
  babel?: boolean;
  flow?: "all" | "detect";
  reactRuntimeTarget?: "18" | "19";
  sourceType?: "module" | "script" | "unambiguous";
};
```

## Babel TransformOptions

You can pass any standard Babel options (e.g. `presets`, `plugins`, `overrides`, etc.). Source maps are enabled automatically for application code and disabled for `node_modules` by default.

## Example

```js title=rspack.config.mjs
export default {
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: "javascript/auto",
        use: {
          loader: "@callstack/repack/babel-loader",
          options: {
            presets: ["module:@react-native/babel-preset"],
            plugins: ["react-native-reanimated/plugin"],
            comments: true
          },
        },
      },
    ],
  },
};
```



---
url: /api/loaders/babel-swc-loader.md
---

# BabelSwcLoader

The `BabelSwcLoader` pairs Babel with SWC to deliver faster builds without sacrificing compatibility with complex Babel setups. It first runs Babel to respect your project’s configuration, then hands off the supported transforms to SWC.

This loader can be used universally—even if your project does not have SWC. When SWC isn’t available, it cleanly falls back to pure Babel transforms, so you can adopt it incrementally without extra setup.
SWC can be provided either by Rspack (via its built-in integration) or by installing `@swc/core` in your project.

:::danger Heads up!
Do not use `@callstack/repack/babel-swc-loader` together with `getJSTransformRules`. They overlap in functionality and will duplicate transforms when combined in one configuration. It might often result in code that's malformed and won't execute properly in the target mobile environment.
:::

:::tip Maximizing performance
For optimal performance, enable Rspack’s parallel transforms with [`experiments.parallelLoader`](https://rspack.rs/config/experiments#experimentsparallelloader). This allows for transformations to run in parallel through worker threads managed by Rspack.
:::

:::details How does this loader work?
The loader reads your Babel config and checks each plugin against a capability map to see if SWC can produce the same semantics. From that, it builds two ordered sets: transforms that stay in Babel and transforms handed off to SWC. This preserves your original plugin order and avoids behavior changes.

Babel runs first and executes only the Babel‑only pieces while adding the minimal syntax support your sources need (for example, TS/TSX and Hermes‑compatible parsing where applicable). SWC then runs on the result with a generated configuration (including targets and optional lazy imports) and applies its share of the work. Each transform is applied once—never duplicated—and the output matches what you’d get from Babel alone.

If SWC isn’t available, the SWC step is skipped and Babel handles everything.
:::

## Options

```ts
import type { TransformOptions } from "@babel/core";
import type { Options } from "@swc/core";

type BabelOverrides = TransformOptions;
type SwcOverrides = Options;

type BabelSwcLoaderOptions = {
  hideParallelModeWarning?: boolean;
  lazyImports?: boolean | string[];
  babelOverrides?: BabelOverrides;
  swcOverrides?: SwcOverrides;
  hermesParserPath?: string;
  hermesParserOverrides?: {
    babel?: boolean;
    flow?: "all" | "detect";
    reactRuntimeTarget?: "18" | "19";
    sourceType?: "module" | "script" | "unambiguous";
  };
};
```

### lazyImports

- Type: `boolean | string[]`
- Default: `true`

Enables SWC's lazy import functionality, which is roughly equivalent to Metro's `inlineRequires`. You can also provide an allowlist of module names. See [SWC documentation](https://swc.rs/docs/configuration/modules#lazy) for details on how to configure it.

### babelOverrides

- Type: `BabelOverrides`

```ts
type BabelOverrides = import('@babel/core').TransformOptions
```

Additional Babel loader options applied on top of the loader's computed Babel configuration. For available fields, see [Babel Documentation](https://babeljs.io/docs/options).

### swcOverrides

- Type: `SwcOverrides`

```ts
type SwcOverrides = import('@swc/core').Options
```

Additional SWC loader options applied on top of the loader's computed SWC configuration. For available fields, see [SWC Documentation](https://swc.rs/docs/configuration/swcrc).

### hermesParserPath

- Type: `string`

Optional path to use for importing `hermes-parser`. By default, the path is obtained automatically.

### hermesParserOverrides

- Type: `HermesParserOverrides`
- Default: `{ babel: true, reactRuntimeTarget: '19' }`

Overrides passed to `hermes-parser` when parsing non-TypeScript files.

```ts
type HermesParserOverrides = {
  babel?: boolean;
  flow?: "all" | "detect";
  reactRuntimeTarget?: "18" | "19";
  sourceType?: "module" | "script" | "unambiguous";
};
```

### hideParallelModeWarning

- Type: `boolean`
- Default: `false`

Hide the warning about Rspack `experiments.parallelLoader` when the rule isn't marked `parallel: true`.

## Example

```js title=rspack.config.mjs
export default {
  module: {
    rules: [
      {
        test: /\.[cm]?[jt]sx?$/,
        type: "javascript/auto",
        use: {
          loader: "@callstack/repack/babel-swc-loader",
          parallel: true,
          options: {
            lazyImports: true,
          },
        },
      },
    ],
  },
};
```



---
url: /api/loaders/flow-loader.md
---

# FlowLoader

The `FlowLoader` removes Flow type annotations from JavaScript files, ensuring they can be processed by loaders that do not support Flow syntax. It should be positioned before other loaders (e.g. `builtin:swc-loader`) to prevent parsing errors when encountering Flow-specific code.

:::details
This loader uses `flow-remove-types` under the hood. You can learn more about it [here](https://github.com/facebook/flow/tree/main/packages/flow-remove-types).
:::

## Options

```ts
type FlowLoaderOptions = {
  all?: boolean;
  ignoreUninitializedFields?: boolean;
  pretty?: boolean;
  removeEmptyImports?: boolean;
};
```

### all

- Type: `boolean`
- Default: `false`

If true, bypasses looking for an `@flow` pragma comment before parsing.

### ignoreUninitializedFields

- Type: `boolean`
- Default: `false`

If true, removes uninitialized class fields (`foo;`, `foo: string;`) completely rather than only removing the type.

### pretty

- Type: `boolean`
- Default: `false`

If true, removes types completely rather than replacing with spaces. This may require using source maps.

### removeEmptyImports

- Type: `boolean`
- Default: `true`

If true, removes empty import statements (`import {} from 'flow-typed-module';`) which were only used for importing flow types.

## Example

:::info
`flow-loader` is automatically applied thanks to [`getJsTransformRules`](/api/utils/get-js-transform-rules.md) helper that is included by default in Re.Pack v5 configuration and its preset for most common libraries.
:::

```js title=rspack.config.cjs
module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        use: {
          loader: "@callstack/repack/flow-loader",
          options: { all: true },
        },
        type: "javascript/auto",
      },
    ],
  },
};
```



---
url: /api/loaders/react-refresh-loader.md
---

# ReactRefreshLoader

The `ReactRefreshLoader` enables [React Fast Refresh](https://reactnative.dev/docs/fast-refresh) for React components in React Native applications.

:::info
This loader is automatically added to your configuration when Hot Module Replacement (HMR) is enabled. By default, it's configured to process all JavaScript and TypeScript files outside of the `node_modules` directory. You don't need to add it manually to your configuration unless you need to enable React Refresh for some of the node modules.
:::

:::details
The loader works similarly to Rspack's `builtin:react-refresh-loader` from `@rspack/plugin-react-refresh`, but is specifically tailored to account for React Native runtime specifics. It appends necessary runtime code to register and refresh React components, ensuring proper HMR functionality in a React Native environment.
:::

## Example

```js title=rspack.config.cjs
module.exports = {
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        include: [/node_modules\/react-native/],
        use: {
          loader: "@callstack/repack/react-refresh-loader",
        },
      },
    ],
  },
};
```



---
url: /api/plugins/code-signing.md
---

# CodeSigningPlugin

This plugin can be used to sign chunks so that their integrity can be verified before execution. You should consider code-signing your chunks when you are using [code splitting](/docs/features/code-splitting.md) or [ModuleFederation](/docs/features/module-federation.md) and want to deliver parts of your code remotely to the end-user.

## Usage

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  plugins: [
    new Repack.plugins.CodeSigningPlugin({
      // options
    }),
  ],
};
```

## Options

### privateKeyPath

- **Required**
- Type: `string`

Path to the private key. This can be either a relative path or an absolute one. Relative paths are resolved within `context` provided with project configuration.

### enabled

- Type: `boolean`
- Default: `true`

Whether to enable the plugin. You typically want to enable the plugin only for production builds and disable it for development.

### excludeChunks

- Type: `string[] | RegExp | RegExp[]`
- Default: `[]`

Names of chunks to exclude from code-signing. You might want to use this if some of the chunks in your setup are not being delivered remotely and don't need to be verified.

### publicKeyPath

- Type: `string`

Path to the public key file. When provided, the plugin will automatically embed the public key into native project files (`Info.plist` for iOS, `strings.xml` for Android) so that the runtime can verify signed bundles without manual file editing.

Relative paths are resolved from the project root (compiler context).

### nativeProjectPaths

- Type: `{ ios?: string; android?: string }`

Override auto-detected paths to native project files where the public key should be embedded. Only used when `publicKeyPath` is set.

- `ios` — Path to `Info.plist`. Auto-detected from `ios/<AppName>/Info.plist` if not provided.
- `android` — Path to `strings.xml`. Auto-detected from `android/app/src/main/res/values/strings.xml` if not provided.

## Guide

To add code-signing to your app, you first need to generate a pair of cryptographic keys that will be used for both signing the bundles (private key) and verifying their integrity in runtime.

### Creating key pair

In terminal, navigate to your project directory and enter the following commands:

```bash
ssh-keygen -t rsa -b 4096 -m PEM -f code-signing.pem
openssl rsa -in code-signing.pem -pubout -outform PEM -out code-signing.pem.pub
```

:::info

The passphrase must be left empty.

:::

### Add the plugin

After that, you need to add `CodeSigningPlugin` to your configuration. Make sure the `privateKeyPath` points to the location of your `code-signing.pem`.

```js title="rspack.config.cjs" {8-12}
const Repack = require("@callstack/repack");

module.exports = (env) => {
  const { mode } = env;
  return {
    plugins: [
      new Repack.RepackPlugin(),
      new Repack.plugins.CodeSigningPlugin({
        enabled: mode === "production",
        privateKeyPath: "./code-signing.pem",
        publicKeyPath: "./code-signing.pem.pub",
      }),
    ],
  };
};
```

### Add the public key

To be able to verify the bundles in runtime, the public key (`code-signing.pem.pub`) needs to be added to the native project files so that the app can verify signed bundles.

#### Automatic embedding (recommended)

When `publicKeyPath` is provided in the plugin configuration (as shown above), the plugin will **automatically** embed the public key into your native project files:

- **iOS**: Adds `RepackPublicKey` entry to `ios/<AppName>/Info.plist`
- **Android**: Adds `RepackPublicKey` string resource to `android/app/src/main/res/values/strings.xml`

The plugin auto-detects the correct file paths. If your project has a non-standard directory structure, you can specify custom paths:

```js title="rspack.config.cjs" {12-15}
const Repack = require("@callstack/repack");

module.exports = (env) => {
  const { mode } = env;
  return {
    plugins: [
      new Repack.RepackPlugin(),
      new Repack.plugins.CodeSigningPlugin({
        enabled: mode === "production",
        privateKeyPath: "./code-signing.pem",
        publicKeyPath: "./code-signing.pem.pub",
        nativeProjectPaths: {
          ios: "./ios/MyApp/Info.plist",
          android: "./android/app/src/main/res/values/strings.xml",
        },
      }),
    ],
  };
};
```

:::info

The automatic embedding modifies your source files in-place. After the first build with `publicKeyPath` set, the native files will contain the public key and subsequent builds will reuse it. If you change the key pair, the plugin will update the files automatically on the next build.

:::

#### Standalone usage

You can also use the `embedPublicKey` function independently of the plugin, for example in a setup script:

```js title="setup-code-signing.js"
const { plugins } = require("@callstack/repack");

const result = plugins.embedPublicKey({
  publicKeyPath: "./code-signing.pem.pub",
  projectRoot: __dirname,
});

console.log("iOS:", result.ios);
console.log("Android:", result.android);
```

#### Manual setup

If you prefer to add the public key manually (or if automatic detection doesn't work for your project structure), you can follow the steps below.

##### iOS

Add the public key to `ios/<appName>/Info.plist` under the name `RepackPublicKey`. Add the following to your `Info.plist` and then copy the contents of `code-signing.pem.pub` and paste them inside of the `<string>` tags:

```xml title="Info.plist"
<plist>
<dict>
	<key>RepackPublicKey</key>
	<string>
        <!-- contents of your code-signing.pem.pub -->
	</string>
</dict>
</plist>
```

##### Android

Add the public key to `android/app/src/main/res/values/strings.xml` under the name `RepackPublicKey`. Add the following to your `strings.xml` and then copy the contents of `code-signing.pem.pub` and paste them inside of the `<string>` tags:

```xml title="strings.xml"
<resources>
	<string name="RepackPublicKey">
        <!-- contents of your code-signing.pem.pub -->
	</string>
</resources>
```

### Enable verification

By default, the bundles are not verified since code-signing is entirely optional. You can enable bundle verification by modyifing the return value of `resolver` added through `ScriptManager.shared.addResolver`.

Integrity verification can be set (through `verifyScriptSignature`) to one of the 3 levels:

| Value    | Description                                            |
| -------- | ------------------------------------------------------ |
| `strict` | Always verify the integrity of the bundle              |
| `lax`    | Verify the integrity only if the signtarure is present |
| `off`    | Never verify the integrity of the bundle               |

Go to `index.js` and modify your `ScriptManager` setup like this:

```js title="index.js" {17}
import { ScriptManager, Federated } from "@callstack/repack/client";

const containers = {
  MiniApp: "http://localhost:9000/[name][ext]",
};

ScriptManager.shared.addResolver(async (scriptId, caller) => {
  const resolveURL = Federated.createURLResolver({ containers });

  const url = resolveURL(scriptId, caller);
  if (url) {
    return {
      url,
      query: { platform: Platform.OS },
      verifyScriptSignature: __DEV__ ? "off" : "strict",
    };
  }
});
```

### Use multiple public keys

If different teams sign different bundles, the resolver can provide a script-specific public key at runtime. When `publicKey` is present, Re.Pack uses it for verification. When it is omitted, Re.Pack falls back to the key embedded in the app under `RepackPublicKey`.

```js title="index.js"
import { ScriptManager, Federated } from "@callstack/repack/client";

const containers = {
  MiniApp: "https://cdn.example.com/[name][ext]",
};

ScriptManager.shared.addResolver(async (scriptId, caller) => {
  const resolveURL = Federated.createURLResolver({ containers });
  const url = resolveURL(scriptId, caller);

  if (!url) {
    return;
  }

  const metadata = await fetch(
    `https://api.example.com/miniapps/${scriptId}/bundle-metadata`
  ).then((response) => response.json());

  return {
    url,
    query: { platform: Platform.OS },
    verifyScriptSignature: __DEV__ ? "off" : "strict",
    publicKey: metadata.publicKey,
  };
});
```

:::danger Security warning

Only return public keys from a **trusted, authenticated backend**. If both the bundle and its public key can be fetched from the same untrusted location, signature verification no longer protects the download and an attacker can replace both at the same time.

:::



---
url: /api/plugins/hermes-bytecode.md
---

# HermesBytecode Plugin

This plugin is converts JavaScript chunks into [Hermes](https://hermesengine.dev/) bytecode for production-level performance optimization.
It also converts related source maps to be compatible with bytecode bundles.

:::warning Remember to exclude the main bundle!
If you enable Hermes in your project, your `index.bundle` file and it's source-map will be transformed by `react-native`.
You should exclude it from the plugin to avoid processing it twice.
:::

:::details Implementation details
This plugin will only transform assets that are emitted after the compilation. To ensure that asset is always emitted we disable the `compareBeforeEmit` option which is enabled by default in Rspack/webpack.

`compareBeforeEmit` option is used to skip emitting assets that are identical to the
ones present in build directory, which might result in transformation being
skipped when there is a untransformed bundle present in the build directory.

Since this plugin is only meant to be used as a production-level optimization, it should not affect your development experience.
:::

## Usage

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  plugins: [
    new Repack.plugins.HermesBytecodePlugin({
      // options
    }),
  ],
};
```

## Options

### enabled

- Type: `boolean`
- Required: `true`

Use this to enable or disable the plugin. You should only enable this plugin when building for production environment.

### test

- Type: `string[] | RegExp | RegExp[]`
- Required: `true`

Matches all modules that match this resource, and will match against Resource (the absolute path without query and fragment).

### include

- Type: `string[] | RegExp | RegExp[]`
- Default: `undefined`

Matches all modules that match this condition against the absolute path of the resource (without query and fragment).

### exclude

- Type: `string[] | RegExp | RegExp[]`
- Default: `undefined`

Excludes all modules that match this condition and will match against the absolute path of the resource (without query and fragment).

### hermesCLIPath

- Type: `string`
- Default: `undefined`

Path to the Hermes command-line tool. If not specified, the plugin will try to find it automatically.

### reactNativePath

- Type: `string`
- Default: `undefined`

Use this to specify the path to the React Native package. If not specified, the plugin will try to find it automatically.

### compareBeforeEmit

- Type: `boolean`
- Default: `undefined`

Use this to force enable `compareBeforeEmit` Rspack/webpack's output option.

## Example

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = (env) => {
  const { mode } = env;

  return {
    plugins: [
      new Repack.plugins.HermesBytecodePlugin({
        enabled: mode === "production",
        test: /\.bundle$/,
        exclude: /index.bundle$/,
      }),
    ],
  };
};
```



---
url: /api/plugins/internal.md
---

# Internal plugins

## OutputPlugin

## LoggerPlugin

## NativeEntryPlugin

Plugin that sets up the React Native entry point for each compilation entry. It adds React Native polyfills, `InitializeCore`, `InitializeScriptManager`, and `IncludeModules` as entry modules processed through the standard loader pipeline. A companion runtime module (`PolyfillsRuntimeModule`) ensures polyfills execute before Module Federation's startup wrapper, regardless of the federation version or bundler used.

Polyfills are read from React Native's `rn-get-polyfills.js` when present (React Native 0.86 and earlier). React Native 0.87 removed that file together with its dependency on `@react-native/js-polyfills`, so the plugin resolves `@react-native/js-polyfills` from the project instead, falling back through `@react-native/metro-config` (which still depends on it and is a devDependency of the default template). If neither can be found, the build fails with an error asking you to add a version-matched `@react-native/js-polyfills` or `@react-native/metro-config` to your project.

On the React Native 0.87 layout the plugin also prepends two resolve aliases: `react-native/Libraries/Image/AssetRegistry` maps to the relocated `src/asset-registry.js`, and `react-native/src/private` maps to the on-disk directory so first-party deep imports keep resolving when package exports are enabled. Neither alias is added on 0.86 and earlier.

## DevelopmentPlugin

## RepackTargetPlugin

## BabelPlugin

Plugin that adds `babel-loader` fallback to resolveLoader configuration. This ensures babel-loader can be resolved regardless of the package manager used, as some package managers (like `pnpm`) require loaders to be direct dependencies rather than allowing them to be resolved through nested dependencies.

## CodegenPlugin

Plugin that handles React Native Codegen transforms required by the new architecture. It adds a `babel-loader` rule for processing Native components and modules, similar to how it's done in `@react-native/babel-preset`.



---
url: /api/plugins/module-federation-v1.md
---

# ModuleFederationPluginV1

:::caution Deprecated
This plugin is deprecated and maintained only for compatibility reasons.

You should be using [Module Federation Plugin V2](/api/plugins/module-federation-v2.md)
which provides enhanced features like dynamic type hinting, manifest support and Federation Runtime - learn more in the [Module Federation 2.0 documentation](https://module-federation.io/guide/start/index.html#-what-is-module-federation-20).
:::

This plugin is designed to configure Module Federation. It's an enhanced version of the standard Module Federation plugin that's specifically tailored for React Native environments.

:::info About configuration options

This documentation describes only Re.Pack-specific configuration options.

For the complete configuration reference, please use the official bundler specific documentation:

- [Rspack's ModuleFederationPlugin](https://rspack.dev/plugins/webpack/module-federation-plugin-v1)
- [Webpack's ModuleFederationPlugin](https://webpack.js.org/plugins/module-federation-plugin/)

:::

## Usage

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  output: {
    // set uniqueName explicitly to make HMR works
    uniqueName: 'host',
  },
  plugins: [
    new Repack.plugins.ModuleFederationPluginV1({
      // options
    }),
  ],
};
```

## Configuration

### reactNativeDeepImports

- Type: `boolean`
- Default: `true`

Enable or disable adding React Native deep imports to shared dependencies. When enabled, the plugin will automatically add:

- `react-native/` for deep imports from React Native core
- `@react-native/` for deep imports from official React Native packages

This ensures proper sharing of deep imports and single instances of things like `assetsRegistry`.

:::info What are deep imports?
Deep imports are when you import from a specific subdirectory or file within a package rather than the package's main entry point. For example:

```js
// Deep import from React Native core
import { PixelRatio } from "react-native/Libraries/Utilities/PixelRatio";

// Deep import from React Native package
import { something } from "@react-native/assets-registry";
```

React Native uses deep imports extensively in its internal implementation. The `reactNativeDeepImports` option ensures these imports are properly shared between federated modules.

This feature solves a common Module Federation issue where deep imports create separate instances in host and remote apps - see this [Stack Overflow discussion](https://stackoverflow.com/questions/65636979/wp5-module-federation-sharing-deep-imports) for the original problem.
:::

## Examples

### Host Configuration

```js
new Repack.plugins.ModuleFederationPluginV1({
  name: "host",
  shared: {
    react: { singleton: true, eager: true },
    "react-native": { singleton: true, eager: true },
  },
});
```

### Remote Configuration

```js
new Repack.plugins.ModuleFederationPluginV1({
  name: "module1",
  exposes: {
    "./entry": "./src/entry.js",
  },
  shared: {
    react: { singleton: true, eager: false },
    "react-native": { singleton: true, eager: false },
  },
});
```



---
url: /api/plugins/module-federation-v2.md
---

# ModuleFederationV2Plugin

This plugin is designed to configure Module Federation 2.0. It's an enhanced version of the standard Module Federation plugin that's specifically tailored for React Native environments.

:::info About configuration options
This documentation describes only Re.Pack-specific configuration options. For the complete configuration reference, please see the [official Module Federation 2.0 documentation](https://module-federation.io/configure/index.html#configuration-overview).

All standard Module Federation 2.0 options are supported in addition to the options described below.
:::

## Mobile MF Quirks

The plugin extends the standard Module Federation 2.0 plugin with functionality specific to mobile React Native apps:

1. **Default Shared Dependencies** - Adds `react` and `react-native` as shared dependencies with `singleton: true` and `eager: true` by default.
2. **Default Share Strategy** - Uses `loaded-first` share strategy by default.
3. **Default Runtime Plugins** - Comes with pre-configured runtime plugins for React Native:
   - `@callstack/repack/mf/core-plugin` - Core functionality
   - `@callstack/repack/mf/resolver-plugin` - React Native-specific module resolution
4. **React Native Deep Imports Support** - Automatically handles sharing of deep imports from React Native core and official packages.
5. **Container Name Validation** - Enforces valid JavaScript identifiers for container names (`name` option) to prevent runtime issues

## Installation

First, install the official `@module-federation/enhanced` package which is required by Re.Pack:


```sh [npm]
npm install @module-federation/enhanced
```

```sh [yarn]
yarn add @module-federation/enhanced
```

```sh [pnpm]
pnpm add @module-federation/enhanced
```

```sh [bun]
bun add @module-federation/enhanced
```

```sh [deno]
deno add npm:@module-federation/enhanced
```

If you would like to use the runtime capabilites of MF2 (like adding remotes on the fly),
you should install the `@module-federation/runtime` package as well:


```sh [npm]
npm install @module-federation/runtime
```

```sh [yarn]
yarn add @module-federation/runtime
```

```sh [pnpm]
pnpm add @module-federation/runtime
```

```sh [bun]
bun add @module-federation/runtime
```

```sh [deno]
deno add npm:@module-federation/runtime
```

:::tip Having trouble?
Check out the [official Module Federation 2.0 quick start guide](https://module-federation.io/guide/start/quick-start.html) for more information.
:::

## Usage

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  output: {
    // set uniqueName explicitly to make HMR works
    uniqueName: 'host',
  },
  plugins: [
    new Repack.plugins.ModuleFederationPluginV2({
      // options
    }),
  ],
};
```

## Configuration

### reactNativeDeepImports

- Type: `boolean`
- Default: `true`

Enable or disable adding React Native deep imports to shared dependencies. When enabled, the plugin will automatically add:

- `react-native/` for deep imports from React Native core
- `@react-native/` for deep imports from official React Native packages

This ensures proper sharing of deep imports and single instances of things like `assetsRegistry`.

:::info What are deep imports?
Deep imports are when you import from a specific subdirectory or file within a package rather than the package's main entry point. For example:

```js
// Deep import from React Native core
import { PixelRatio } from "react-native/Libraries/Utilities/PixelRatio";

// Deep import from React Native package
import { something } from "@react-native/assets-registry";
```

React Native uses deep imports extensively in its internal implementation. The `reactNativeDeepImports` option ensures these imports are properly shared between federated modules.

This feature solves a common Module Federation issue where deep imports create separate instances in host and remote apps - see this [Stack Overflow discussion](https://stackoverflow.com/questions/65636979/wp5-module-federation-sharing-deep-imports) for the original problem.
:::

### defaultRuntimePlugins

- Type: `string[]`
- Default: `["@callstack/repack/mf/core-plugin", "@callstack/repack/mf/resolver-plugin"]`

List of default runtime plugins for Federation Runtime. These plugins provide core functionality and React Native-specific resolution for Module Federation.

You can modify this list to:

- Disable default plugins by providing an empty array
- Replace default plugins with your own implementation

```js
new Repack.plugins.ModuleFederationPluginV2({
  name: "host",
  // Disable default plugins completely
  defaultRuntimePlugins: [],

  // Or use only the core plugin
  defaultRuntimePlugins: ["@callstack/repack/mf/core-plugin"],
});
```

## Examples

### Host Configuration

```js
new Repack.plugins.ModuleFederationPluginV2({
  name: "host",
  remotes: {
    module1: "module1@http://example.com/module1.container.bundle",
  },
  shared: {
    react: { singleton: true, eager: true },
    "react-native": { singleton: true, eager: true },
  },
});
```

### Remote Configuration

```js
new Repack.plugins.ModuleFederationPluginV2({
  name: "module1",
  filename: "module1.container.bundle",
  exposes: {
    "./entry": "./src/entry.js",
  },
  shared: {
    react: { singleton: true, eager: false },
    "react-native": { singleton: true, eager: false },
  },
});
```



---
url: /api/plugins/repack.md
---

# RepackPlugin

This is the main plugin that enables React Native app development & bundling with Re.Pack and should be included in all of your configurations. It abstracts the configuration of other core internal plugins into one plugin.

:::warning About internal plugins

Plugins configured by the `RepackPlugin` are considered internal and there is no need to use or configure them directly. Their use is heavily discouraged and they are only included for the sake of completeness of the API.

You can learn more about internal plugins [here](/api/plugins/internal.md).

:::

## Usage

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  plugins: [
    new Repack.RepackPlugin({
      // options
    }),
  ],
};
```

## Options

### platform

- Type: `string`
- Default: `compiler.options.name`

Target application platform. This value is used by various plugins to determine platform-specific behavior. The default value is the name of the compiler which Re.Pack sets to the target platform.

### logger

- Type: `Object | boolean`
- Default: `{ console: true }`

Options to configure the logger's output. Setting this to `false` disables the LoggerPlugin completely. When set to `true` or left undefined, it uses default logger configuration with console output enabled.

### logger.console

- Type: `boolean`
- Default: `true`

Enable or disable logging to the console. When enabled, build progress, warnings, errors, and other messages will be displayed in the terminal.

:::tip Verbose logging

You can enable verbose logging by passing `--verbose` flag to either of CLI commands or by setting the `REPACK_VERBOSE` environment variable to `1` or `true`.

:::

### logger.file

- Type: `string`
- Default: `undefined`

Absolute path to a file where logs should be saved. If not specified, file logging will be disabled.

### logger.listener

- Type: `(log: LogEntry) => void`
- Default: `undefined`

Custom listener function that will be called for each log entry.

```ts
interface LogEntry {
  timestamp: number;
  issuer: string;
  type: "debug" | "info" | "warn" | "error" | "success";
  message: any[];
}
```

```js
new Repack.RepackPlugin({
  logger: {
    console: true,
    file: "/absolute/path/to/logs/build.log",
    listener: (log) => {
      // Custom log processing
    },
  },
});
```

### output

- Type: `Object`
- Default: `{}`

Options are passed directly to the OutputPlugin.

### output.auxiliaryAssetsPath

- Type: `string`
- Default: `undefined`

Path to a directory, where [remote assets](/docs/guides/remote-assets.md) should be saved.

### initializeCore

- Type: `string`
- Default: `require.resolve('react-native/Libraries/Core/InitializeCore.js')`

Absolute location to JS file with initialization logic for React Native. This is particularly useful when building for out-of-tree platforms.

### extraChunks

- Type: `DestinationSpec[]`
- Default:

```js
[
  {
    include: /.*/,
    type: "remote",
    outputPath: "<projectRoot>/build/outputs/<platform>/remotes",
  },
];
```

Options specifying how to deal with extra chunks generated in the compilation, usually by using dynamic `import()` function. Each entry in the array should conform to the `DestinationSpec` type:

```ts
interface DestinationSpec {
  test?: RegExp;
  include?: RegExp;
  exclude?: RegExp;
  type: "local" | "remote";
  outputPath?: string;
}
```

| Property     | Description                                                                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `test`       | Pattern to test chunk names against                                                                                                                            |
| `include`    | Pattern to include chunk names                                                                                                                                 |
| `exclude`    | Pattern to exclude chunk names                                                                                                                                 |
| `type`       | Determines where the chunk will be saved. Use `'local'` to bundle with the main application or `'remote'` for setting the chunk aside for potential CDN upload |
| `outputPath` | Absolute or relative path where chunks should be saved. Required when `type` is `'remote'`                                                                     |

The plugin uses these specifications to classify chunks into two categories:

1. **Local chunks** - Bundled with the main application bundle and included in the `.ipa`/`.apk` file
2. **Remote chunks** - Saved separately and can be downloaded on demand

By default, all chunks are treated as remote and saved under `<projectRoot>/build/outputs/<platform>/remotes` directory.

:::warning
Specifying custom value for this option will disable the default setting - you will need to configure `outputPath` for `type: 'remote'` yourself.
:::

Example configuration:

```js title="rspack.config.cjs"
const Repack = require("@callstack/repack");

module.exports = {
  plugins: [
    new Repack.RepackPlugin({
      extraChunks: [
        {
          // Make `my-chunk` local
          include: /my-chunk/,
          type: "local",
        },
        {
          // Make any other chunk remote
          exclude: /my-chunk/,
          type: "remote",
          outputPath,
        },
      ],
    }),
  ],
};
```



---
url: /api/runtime/script-manager.md
---

# ScriptManager

The `ScriptManager` is a low-level utility for managing script resolution, downloading, and execution in React Native applications. It's particularly useful when working with code splitting, dynamic imports, and Module Federation.

:::info Why is it called ScriptManager?

It can be used to download, manage and execute external (either local or remote) JavaScript code.

:::

## Usage

```js
import { Script, ScriptManager } from "@callstack/repack/client";

ScriptManager.shared.addResolver(async (scriptId, caller) => {
  if (__DEV__) {
    return {
      url: Script.getDevServerURL(scriptId),
      cache: false,
    };
  }

  return {
    url: Script.getRemoteURL(`https://mycdn.example/assets/${scriptId}`),
  };
});

// Example usage with React.lazy and dynamic imports
const TeacherModule = React.lazy(() => import("./Teacher.js"));
const StudentModule = React.lazy(() => import("./Student.js"));

export function App({ role }) {
  if (role === "teacher") {
    return <TeacherModule />;
  }

  return <StudentModule />;
}
```

## API Reference

### ScriptManager.shared

The globally shared instance of `ScriptManager`. You should always use this instead of creating new instances.

- Type: `ScriptManager`

### addResolver

Adds a new script locator resolver to handle script resolution.

- Type: `addResolver(resolver: ScriptLocatorResolver, options?: ResolverOptions): void`
- Parameters:
  - `resolver`: Async function that resolves script location data
  - `options`: Configuration options for the resolver
    - `priority`: Priority of the resolver (default: `2`)
    - `key`: Unique key to identify the resolver

### removeResolver

Removes a previously added resolver.

- Type: `removeResolver(resolver: ScriptLocatorResolver | string): boolean`
- Parameters:
  - `resolver`: The resolver function or its unique key to remove
- Returns: `true` if resolver was found and removed, `false` otherwise

### removeAllResolvers

Removes all previously added resolvers.

- Type: `removeAllResolvers(): void`

### setStorage

Sets a storage backend for caching resolved script locator data.

- Type: `setStorage(storage: StorageApi): void`
- Parameters:
  - `storage`: Storage API implementation with `getItem` and `setItem` methods

### loadScript

Resolves, downloads, and executes a script.

- Type: `loadScript(scriptId: string, caller?: string, webpackContext?: any, referenceUrl?: string): Promise<void>`
- Parameters:
  - `scriptId`: Id of the script to load
  - `caller`: Name of the calling script (optional)
  - `webpackContext`: Webpack context (optional)
  - `referenceUrl`: Reference URL for resolution (optional)

### prefetchScript

Downloads a script without executing it.

- Type: `prefetchScript(scriptId: string, caller?: string, webpackContext?: any, referenceUrl?: string): Promise<void>`
- Parameters:
  - `scriptId`: Id of the script to prefetch
  - `caller`: Name of the calling script (optional)
  - `webpackContext`: Webpack context (optional)
  - `referenceUrl`: Reference URL for resolution (optional)

### invalidateScripts

Clears cache and removes downloaded files for given scripts.

- Type: `invalidateScripts(scriptIds?: string[]): Promise<string[]>`
- Parameters:
  - `scriptIds`: Array of script ids to invalidate (optional)
- Returns: Promise resolving to array of invalidated script ids

## Events

The `ScriptManager` extends `EventEmitter` and provides a comprehensive event system for monitoring and reacting to script loading lifecycle events. Events can be used to track script resolution, loading progress, and handle errors.

### Available Events

The following events are emitted by `ScriptManager`:

| Event Name    | Description                                                      |
| ------------- | ---------------------------------------------------------------- |
| `resolving`   | Emitted when script resolution begins                            |
| `resolved`    | Emitted when script resolution succeeds                          |
| `prefetching` | Emitted when script prefetching begins                           |
| `loading`     | Emitted when script loading begins                               |
| `loaded`      | Emitted when script loading succeeds                             |
| `error`       | Emitted when an error occurs during script resolution or loading |
| `invalidated` | Emitted when scripts are invalidated from cache                  |

### Subscribing to Events

```js
import { ScriptManager } from "@callstack/repack/client";

// Listen for script loading events
ScriptManager.shared.on("loading", (script) => {
  console.log(`Loading script: ${script.scriptId}`);
});

ScriptManager.shared.on("loaded", (script) => {
  console.log(`Successfully loaded script: ${script.scriptId}`);
});

ScriptManager.shared.on("error", (error) => {
  console.error("Script loading failed:", error);
});
```

## Hooks

The `ScriptManager` provides a hook system that allows developers to intercept and customize the script loading process at various stages. The hooks provide fine-grained control over script resolution and loading, enabling advanced use cases like custom caching strategies, script transformation, and error handling.

### Available Hooks

#### Resolution Hooks

| Hook Name       | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `beforeResolve` | Called before script resolution begins, allows you to modify the arguments |
| `resolve`       | Customise / override the script resolution process                         |
| `afterResolve`  | Modify the resolved script locator after resolution succeeds               |
| `errorResolve`  | Provide a fallback for resolution request when normal resolution fails     |

#### Loading Hooks

| Hook Name    | Description                                                             |
| ------------ | ----------------------------------------------------------------------- |
| `beforeLoad` | Called before script loading begins, allows you to modify the arguments |
| `load`       | Customise / override the script resolution process                      |
| `afterLoad`  | React to successful script loading event                                |
| `errorLoad`  | Provide a fallback for a script when normal loading procedure fails     |

### Using hooks

```js
ScriptManager.shared.hooks.beforeResolve(async (args) => {
  console.debug("ScriptManager.shared.hooks.beforeResolve", args);
  return args;
});

ScriptManager.shared.hooks.resolve(async (args) => {
  console.debug("ScriptManager.shared.hooks.resolve", args);
  const { scriptId, caller, referenceUrl } = args.options;
  for (const [, , resolve] of args.resolvers) {
    const locator = await resolve(scriptId, caller, referenceUrl);
    if (locator) return locator;
  }
});

ScriptManager.shared.hooks.afterResolve(async (args) => {
  console.debug("ScriptManager.shared.hooks.afterResolve", args);
  return args;
});

ScriptManager.shared.hooks.beforeLoad(async (args) => {
  console.debug("ScriptManager.shared.hooks.beforeLoad", args);
  return args;
});

ScriptManager.shared.hooks.load(async (args) => {
  console.debug("ScriptManager.shared.hooks.load", args);
  await args.loadScript();
  return true;
});

ScriptManager.shared.hooks.afterLoad(async (args) => {
  console.debug("ScriptManager.shared.hooks.afterLoad", args);
  return args;
});
```

## Advanced Usage

### Custom Resolver with Retry Logic

```js
import { ScriptManager } from "@callstack/repack/client";

ScriptManager.shared.addResolver(async (scriptId) => {
  return {
    url: `https://mycdn.example/assets/${scriptId}`,
    retry: 3, // Number of retry attempts
    retryDelay: 1000, // Delay between retries in milliseconds
    headers: {
      Authorization: "Bearer token",
    },
  };
});
```

### Code signing with a per-script public key

When different teams sign remote bundles with different private keys, your resolver can provide the matching public key for each script. Re.Pack will use `publicKey` when present and fall back to the app-embedded `RepackPublicKey` only when it's omitted.

```js
import { ScriptManager } from "@callstack/repack/client";

ScriptManager.shared.addResolver(async (scriptId) => {
  const metadata = await fetch(`https://myapp.example/scripts/${scriptId}`).then(
    (response) => response.json()
  );

  return {
    url: metadata.bundleUrl,
    verifyScriptSignature: "strict",
    publicKey: metadata.publicKey,
  };
});
```

Only use a `publicKey` value that comes from a trusted source. If both the bundle and the public key can be tampered with by the same attacker, signature verification no longer protects the download.

### Enabling caching through AsyncStorage

```js
import { ScriptManager } from "@callstack/repack/client";
import AsyncStorage from "@react-native/async-storage";

ScriptManager.shared.setStorage({
  getItem: (key) => AsyncStorage.getItem(key),
  setItem: (key, value) => AsyncStorage.setItem(key, value),
});
```

### Using per-script caching strategy

```js
ScriptManager.shared.hooks.afterResolve(async (args) => {
  const { locator, options } = args;
  // Implement custom caching logic
  if (shouldCache(locator)) {
    locator.cache = true;
  }
  return args;
});
```

### Override script locator URL after resolution

```js
ScriptManager.shared.hooks.afterResolve(async (args) => {
  const { locator, options } = args;

  // Transform locator URL after it's resolved
  locator.url = transformUrl(locator.url);

  return args;
});
```

### Adding fallback for failed loading of a script

```js
ScriptManager.shared.hooks.errorLoad(async (args) => {
  const { error, options } = args;
  // Implement custom error handling
  if (isRecoverableError(error)) {
    await retryLoading(options);
    return true;
  }
  return false;
});
```

## Customizing the native HTTP client

Remote scripts are downloaded by the native side of Re.Pack - `OkHttpClient` on Android and `NSURLSession` on iOS. By default a plain client is used, but you can provide your own to customize networking behavior such as **SSL/certificate pinning**, **interceptors**, **proxies**, **custom headers**, or **timeouts**.

The factory must be set **before any remote script is loaded** - the earliest app lifecycle hook is the safest place (Android `Application.onCreate`, iOS `application:didFinishLaunchingWithOptions:`). The client is created lazily and reused for all subsequent downloads.

:::warning Native customization only

This applies to the native HTTP client used for downloading scripts. Per-request options exposed to JavaScript (such as `headers`, `method`, `body`, `timeout` and `retry`) are still configured through the [resolver](#addresolver).

:::

### Android

Assign a factory to `RemoteScriptLoader.okHttpClientFactory`:

```kotlin
// MainApplication.kt
import com.callstack.repack.RemoteScriptLoader
import okhttp3.OkHttpClient
import java.util.concurrent.TimeUnit

class MainApplication : Application(), ReactApplication {
  override fun onCreate() {
    super.onCreate()

    RemoteScriptLoader.okHttpClientFactory = {
      OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .addInterceptor(MyAuthInterceptor())
        // .certificatePinner(...) for SSL pinning
        .build()
    }
    // ...
  }
}
```

### iOS

Assign a factory to `ScriptManager.urlSessionFactory`. Assign `nil` to restore the default `[NSURLSession sharedSession]`.

```swift
// AppDelegate.swift
import callstack_repack

func application(
  _ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  ScriptManager.urlSessionFactory = {
    let configuration = URLSessionConfiguration.default
    configuration.timeoutIntervalForRequest = 30
    configuration.httpAdditionalHeaders = ["X-Custom-Header": "value"]
    // Pass a delegate for SSL pinning if needed.
    return URLSession(configuration: configuration)
  }
  // ...
}
```

```objc
// AppDelegate.mm
#import <callstack_repack/callstack_repack-Swift.h> // or "ScriptManager.h"

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  ScriptManager.urlSessionFactory = ^NSURLSession * {
    NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration defaultSessionConfiguration];
    configuration.timeoutIntervalForRequest = 30;
    return [NSURLSession sessionWithConfiguration:configuration];
  };
  // ...
}
```

## Related

- [Script](/api/runtime/script.md) - Utility class for generating script URLs used with resolvers



---
url: /api/runtime/script.md
---

# Script

The `Script` class provides utility methods for generating script URLs used with `ScriptManager` resolvers. It handles URL construction for different script hosting scenarios: development servers, filesystem, and remote servers.

:::info When to use Script

Use `Script` static methods when configuring resolvers in `ScriptManager.shared.addResolver()` to generate properly formatted URLs for your scripts. The class handles webpack context integration and URL formatting automatically.

:::

## Usage

```js
import { Script, ScriptManager } from "@callstack/repack/client";

ScriptManager.shared.addResolver(async (scriptId, caller) => {
  // Development: load from dev server
  if (__DEV__) {
    return {
      url: Script.getDevServerURL(scriptId),
      cache: false,
    };
  }

  // Production: load from remote CDN
  return {
    url: Script.getRemoteURL(`https://mycdn.example/assets/${scriptId}`),
  };
});
```

## API Reference

### Script.DEFAULT\_TIMEOUT

Default timeout for script fetch requests.

- Type: `number`
- Value: `30000` (30 seconds)

### Script.getDevServerURL

Generates a URL for scripts hosted on the development server. This method returns a function that uses webpack context to construct the full URL with the correct public path and script filename.

- Type: `getDevServerURL(scriptId: string): (webpackContext) => string`
- Parameters:
  - `scriptId`: Id of the script to load
- Returns: Function that generates the dev server URL when called with webpack context

```js
ScriptManager.shared.addResolver(async (scriptId) => {
  if (__DEV__) {
    return {
      url: Script.getDevServerURL(scriptId),
      cache: false,
    };
  }
});
```

### Script.getFileSystemURL

Generates a URL for scripts stored on the device's filesystem. Useful when scripts are bundled with the app or downloaded to local storage. The method automatically prepends `file:///` to the scriptId.

- Type: `getFileSystemURL(scriptId: string): (webpackContext) => string`
- Parameters:
  - `scriptId`: Id of the script to load
- Returns: Function that generates the filesystem URL when called with webpack context

```js
ScriptManager.shared.addResolver(async (scriptId) => {
  // Load pre-bundled scripts from filesystem
  return {
    url: Script.getFileSystemURL(scriptId),
    absolute: true,
  };
});
```

### Script.getRemoteURL

Generates a URL for scripts hosted on a remote server. By default, appends the `.chunk.bundle` extension to the URL.

- Type: `getRemoteURL(url: string, options?: { excludeExtension?: boolean }): string | (webpackContext) => string`
- Parameters:
  - `url`: Base URL to the remote location where the script is stored
  - `options`: Additional options
    - `excludeExtension`: When `true`, returns the URL as-is without appending the chunk extension (default: `false`)
- Returns: URL string (if `excludeExtension: true`) or function that generates the URL with extension

```js
ScriptManager.shared.addResolver(async (scriptId) => {
  // Standard usage - extension will be appended
  return {
    url: Script.getRemoteURL(`https://mycdn.example/assets/${scriptId}`),
  };
});

// With excludeExtension for custom file extensions
ScriptManager.shared.addResolver(async (scriptId) => {
  return {
    url: Script.getRemoteURL(
      `https://mycdn.example/assets/${scriptId}.custom.js`,
      { excludeExtension: true }
    ),
  };
});
```

### Script.getScriptUniqueId

Generates a unique identifier for a script, used internally for caching purposes.

- Type: `getScriptUniqueId(scriptId: string, caller?: string): string`
- Parameters:
  - `scriptId`: Id of the script
  - `caller`: Optional caller name to prefix the script id
- Returns: Unique identifier string

```js
// Without caller
Script.getScriptUniqueId("TeacherModule"); // "TeacherModule"

// With caller
Script.getScriptUniqueId("TeacherModule", "host"); // "host_TeacherModule"
```

## Related

- [ScriptManager](/api/runtime/script-manager.md) - The manager class that uses Script for URL resolution



---
url: /api/utils/constants.md
---

# Constants

## ASSET\_EXTENSIONS

Array of all supported asset extensions.

```ts
type ASSET_EXTENSIONS = string[];
```

Contains all extensions from `SCALABLE_ASSETS` plus additional extensions for:

- Video formats: `m4v`, `mov`, `mp4`, `mpeg`, `mpg`, `webm`
- Audio formats: `aac`, `aiff`, `caf`, `m4a`, `mp3`, `wav`
- Document formats: `html`, `pdf`, `yaml`, `yml`
- Font formats: `otf`, `ttf`
- Other: `zip`, `obj`

## SCALABLE\_ASSETS

Array of file extensions for scalable image assets.

```ts
type SCALABLE_ASSETS = string[];
```

Contains the following extensions: `bmp`, `gif`, `jpg`, `jpeg`, `png`, `psd`, `svg`, `webp`, `tiff`.

## SCALABLE\_RESOLUTIONS

Array of supported asset resolutions.

```ts
type SCALABLE_RESOLUTIONS = string[];
```

Contains the following resolutions: `0.75`, `1`, `1.5`, `2`, `3`, `4`.



---
url: /api/utils/get-asset-extension-regexp.md
---

# getAssetExtensionsRegExp

Creates a RegExp from an array of asset extensions.

## Parameters

```ts
type GetAssetExtensionsRegExp = (extensions?: string[]) => RegExp;
```

### extensions

- Type: `string[]`
- Default: `ASSET_EXTENSIONS`

Array of extensions to include in the RegExp pattern.

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      {
        test: Repack.getAssetExtensionsRegExp(Repack.ASSET_EXTENSIONS),
        use: {
          loader: "@callstack/repack/assets-loader",
          options: { platform },
        },
      },
    ],
  },
};
```



---
url: /api/utils/get-asset-transform-rules.md
---

# getAssetTransformRules

A helper function that generates `module.rules` configuration for handling assets in React Native applications.

:::tip
This helper function allows you to create a single configuration for all assets in your project. If you need more granular control over asset processing, refer to the [`assetsLoader`](/api/loaders/assets-loader.md) documentation.
:::

## Parameters

```ts
interface GetAssetTransformRulesOptions {
  inline?: boolean;
  maxInlineSize?: number;
  remote?: {
    publicPath: string;
    assetPath?: (args: {
      resourcePath: string;
      resourceFilename: string;
      resourceDirname: string;
      resourceExtensionType: string;
    }) => string;
  };
  svg?: "svgr" | "xml" | "uri" | { type: "svgr", options: Record<string, any> };
}
```

### options

Configuration options for asset transformations.

### options.inline

- Type: `boolean`

Whether to inline assets as base64 URIs.

:::tip
Learn more about the inlining assets in the [Inlining Assets guide](/docs/guides/inline-assets.md).
:::

### options.maxInlineSize

- Type: `number`

File size threshold in bytes used together with `inline: true`. Assets whose largest scale variant is smaller than or equal to this value will be inlined; larger assets will be extracted as separate files. Has no effect when `inline` is not `true`.

:::tip
Learn more about size-based inlining in the [Inlining Assets guide](/docs/guides/inline-assets.md#size-based-inlining).
:::

### options.remote

- Type: `object`

Configuration for remote asset loading.

:::tip
Learn more about using remote assets in the [Remote Assets guide](/docs/guides/remote-assets.md).
:::

### options.remote.publicPath

- Type: `string`
- Required: `true`

Public path for loading remote assets.

See [`assetsLoader` documentation](/api/loaders/assets-loader.md#remotepublicpath) for reference.

### options.remote.assetPath

- Type: `(args: { resourcePath: string; resourceFilename: string; resourceDirname: string; resourceExtensionType: string; }) => string`

A function to customize how the asset path is generated for remote assets.

See [`assetsLoader` documentation](/api/loaders/assets-loader.md#remoteassetpath) for reference.

### options.svg

- Type: `'svgr' | 'xml' | 'uri' | { type: "svgr", options: Record<string, any>}`

Determines how SVG files should be processed:

- `'svgr'`: Uses `@svgr/webpack` to transform SVGs into React Native components
  - `type: "svgr"`: Uses `@svgr/webpack` to transform SVGs into React Native components and allows to configure additional options to `@svgr/webpack`.
- `'xml'`: Loads SVGs as raw XML source to be used with `SvgXml` from `react-native-svg`
- `'uri'`: Loads SVGs as inline URIs to be used with `SvgUri` from `react-native-svg`

#### options.svg.options

- Type: `Record<string, any>`

Allows to configure additional options to `@svgr/webpack`. The full list of available options can be found in the [svgr doc](https://react-svgr.com/docs/options/).

:::tip
Learn more about using SVG in the [SVG guide](/docs/guides/svg.md).
:::

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      ...Repack.getAssetTransformRules({
        svg: "svgr",
      }),
    ],
  },
};
```



---
url: /api/utils/get-codegen-transform-rules.md
---

# getCodegenTransformRules

A helper function that returns `module.rules` configuration for handling React Native codegen transformation, which is required for projects using [New Architecture](https://reactnative.dev/architecture/landing-page).

:::info
This helper function is a part of [`getJsTransformRules`](/api/utils/get-js-transform-rules.md).
:::

:::warning
This helper function is only relevant when using Rspack as your bundler. If you are using webpack with `babel`, you don't need to use this helper function, since it's already included as part of `@react-native/babel-preset`.
:::

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [...Repack.getCodegenTransformRules()],
  },
};
```



---
url: /api/utils/get-dirname.md
---

# getDirname

Convert a `file:///` URL to an absolute directory path. This utility is particularly useful in ESM Rspack/webpack configs where `__dirname` is not available.

## Parameters

```ts
type GetDirname = (fileUrl: string) => string;
```

### fileUrl

- Type: `string`
- Required: `true`

The `file:///` URL of a module, typically obtained from `import.meta.url`.

## Example

```js title=rspack.config.mjs
import * as Repack from "@callstack/repack";

export default (env) => {
  const { context = Repack.getDirname(import.meta.url) } = env;

  return {
    // ... config
  };
};
```



---
url: /api/utils/get-flow-transform-rules.md
---

# getFlowTransformRules

A helper function that generates `module.rules` configuration for handling Flow type annotations in JavaScript files. The rules use `@callstack/repack/flow-loader` to remove Flow types from the code before other processing.

:::info
This helper function is a part of [`getJsTransformRules`](/api/utils/get-js-transform-rules.md).
:::

:::warning
This helper function is only relevant when using Rspack as your bundler. If you are using webpack with `babel`, you don't need to use this helper function, since it's already included as part of `@react-native/babel-preset`.
:::

## Parameters

```ts
interface GetFlowTransformRulesOptions {
  include?: string[];
  exclude?: string[];
  all?: boolean;
  ignoreUninitializedFields?: boolean;
  removeEmptyImports?: boolean;
}
```

### options

- Required: `false`

Configuration options for Flow transformations

### options.include

- Type: `string[]`
- Default: predefined set of React Native libraries that use Flow

Array of module names to include for Flow transformation.

:::tip
Pass module names as they appear in `package.json`. You can use full package names or scopes.
:::

```js
{
  include: [
    // Include specific package
    "react-native",
    "react-native-vector-icons",
    // Include all packages from a scope
    "@react-native",
  ];
}
```

### options.exclude

- Type: `string[]`
- Default: `[]`

Array of module names to exclude from Flow transformation.

:::tip
Pass module names as they appear in `package.json`. You can use full package names or scopes.
:::

```js
{
  exclude: [
    // Exclude specific package
    "react-native-vector-icons",
    // Exclude all packages from a scope
    "@react-native-community",
  ];
}
```

### options.all

- Type: `boolean`
- Default: `true`

Whether to bypass looking for `@flow` pragma comment before parsing

### options.ignoreUninitializedFields

- Type: `boolean`

Whether to remove uninitialized class fields completely rather than only removing the type (defaults to false)

### options.removeEmptyImports

- Type: `boolean`
- Default: `true`

Whether to remove empty import statements which were only used for importing flow types (defaults to true)

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      ...Repack.getFlowTransformRules({
        include: ["react-native", "@react-native"],
        all: true,
        ignoreUninitializedFields: false,
        removeEmptyImports: true,
      }),
    ],
  },
};
```



---
url: /api/utils/get-js-transform-rules.md
---

# getJsTransformRules

A helper function that generates Rspack `module.rules` configuration for transforming JavaScript, TypeScript, and Flow files. You can consider it an equivalent of `@react-native/babel-preset`, but for SWC.

:::info
This helper function combines other helper functions, preconfigured for convenience:

- [getSwcLoaderOptions](/api/utils/get-swc-loader-options.md)
- [getFlowTransformRules](/api/utils/get-flow-transform-rules.md)
- [getCodegenTransformRules](/api/utils/get-codegen-transform-rules.md)

:::

:::warning
This helper function is only relevant when using Rspack as your bundler. If you are using webpack with `babel`, you don't need to use this helper function, since it's already included as part of `@react-native/babel-preset`.

You can consider it an equivalent of `@react-native/babel-preset`, but for SWC.
:::

## Parameters

```ts
interface GetJsTransformRulesOptions {
  swc?: {
    disableImportExportTransform?: boolean;
    externalHelpers?: boolean;
    importSource?: string;
    jsxRuntime?: "automatic" | "classic";
    lazyImports?: boolean | string[];
  };
  flow?: {
    enabled?: boolean;
    include?: string[];
    exclude?: string[];
    all?: boolean;
    ignoreUninitializedFields?: boolean;
    removeEmptyImports?: boolean;
  };
  codegen?: {
    enabled?: boolean;
  };
}
```

### options

- Type: `GetJsTransformRulesOptions`
- Required: `false`

Configuration options for JavaScript/TypeScript transformations

### options.swc

- Type: `object`
- Default: `{}`

Configuration options for SWC transformations. For detailed documentation of the options, see [getSwcLoaderOptions](/api/utils/get-swc-loader-options.md).

```js
{
  swc: {
    disableImportExportTransform: false,
    externalHelpers: true,
    importSource: 'react',
    jsxRuntime: 'automatic',
    lazyImports: false,
  }
}
```

### options.flow

- Type: `object`

Configuration for enabling/disabling Flow transformations. When enabled, the transformation will be applied according to the configuration from [getFlowTransformRules](/api/utils/get-flow-transform-rules.md).

```js
{
  flow: {
    enabled: true,
    include: FLOW_TYPED_MODULES,
    exclude: [],
    all: true,
    ignoreUninitializedFields: false,
    removeEmptyImports: true,
  }
}
```

#### options.flow\.enabled

- Type: `boolean`
- Default: `true`

Whether to enable Flow transformations in the JavaScript transform pipeline.

### options.codegen

- Type: `object`

Configuration for enabling/disabling codegen transformations. When enabled, the transformation will be applied according to the configuration from [getCodegenTransformRules](/api/utils/get-codegen-transform-rules.md).

```js
{
  codegen: {
    enabled: true;
  }
}
```

#### options.codegen.enabled

- Type: `boolean`
- Default: `true`

Whether to enable codegen transformations in the JavaScript transform pipeline.

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      ...Repack.getJsTransformRules({
        swc: {
          jsxRuntime: "automatic",
          externalHelpers: true,
        },
        flow: {
          enabled: true,
          include: ["react-native"],
        },
        codegen: {
          enabled: true,
        },
      }),
    ],
  },
};
```



---
url: /api/utils/get-module-paths.md
---

# getModulePaths

A helper function that generates regular expressions for matching module paths across different package manager formats (npm, yarn, pnpm, bun). You can use these regex patterns in your Rspack/webpack configuration to properly resolve modules regardless of which package manager you use.

## Parameters

```ts
type GetModulePaths = (moduleNames: string[]) => RegExp[];
```

### moduleNames

- Type: `string[]`
- Required: `true`

Array of module names to generate path patterns for.

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      {
        include: Repack.getModulePaths([
          "react-native",
          "react-native-macos",
          "react-native-windows",
        ]),
      },
    ],
  },
};
```



---
url: /api/utils/get-resolve-options.md
---

# getResolveOptions

Get resolve options preset to properly resolve files within the project. The preset matches closely Metro's behavior.

- resolve platform extensions (e.g. `file.ios.js`)
- resolve native extensions (e.g. `file.native.js`)
- optionally use package exports (`exports` field in `package.json`) instead of main fields (e.g. `main` or `browser` or `react-native`)

## Parameters

```ts
type GetResolveOptions = (
  platform: string,
  options: {
    enablePackageExports?: boolean;
    preferNativePlatform?: boolean;
  }
) => ResolveOptions;
```

### platform

- Type: `string`
- Required: `true`

Target application platform (e.g. `ios` or `android`).

### options.enablePackageExports

- Type: `boolean`
- Default: `false`

Whether to enable Package Exports support. When enabled, uses the `exports` field in `package.json` instead of main fields.

:::warning
Package Exports support differs significantly between Metro and Re.Pack. Since this option is still marked as experimental in Metro, it's recommended to avoid using in Re.Pack for best compatbility.

For more details, please refer to the [Module Resolution guide](/docs/features/module-resolution.md).
:::

### options.preferNativePlatform

- Type: `boolean`
- Default: `true`

Whether to prefer native platform over generic platform when resolving extensions. When enabled, Re.pack will try `.native.${ext}` before `.${ext}` and after `.${platform}.${ext}` during resolution.

:::info
This matches Metro's [preferNativePlatform](https://metrobundler.dev/docs/resolution#prefernativeplatform-boolean) behavior.
:::

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = (env) => {
  const { platform } = env;

  return {
    resolve: {
      ...Repack.getResolveOptions(platform, {
        enablePackageExports: false,
        preferNativePlatform: true,
      }),
    },
  };
};
```



---
url: /api/utils/get-swc-loader-options.md
---

# getSwcLoaderOptions

A helper function that creates SWC loader configuration options optimized for React Native bundling.

:::info
This helper function is a part of [`getJsTransformRules`](/api/utils/get-js-transform-rules.md).
:::

## Parameters

```ts
interface MakeSwcLoaderConfigOptions {
  syntax: "js" | "ts";
  jsx: boolean;
  externalHelpers?: boolean;
  jsxRuntime?: "automatic" | "classic";
  disableImportExportTransform?: boolean;
  importSource?: string;
  lazyImports?: boolean | string[];
}
```

### options

- Required: `true`

Configuration options for SWC loader.

### options.syntax

- Type: `"js" | "ts"`
- Required: `true`

The source code syntax type.

### options.jsx

- Type: `boolean`
- Required: `true`

Whether to enable JSX/TSX parsing and transformation.

### options.externalHelpers

- Type: `boolean`
- Default: `true`

Whether to use external helpers for transformations.

See [SWC `jsc.externalHelpers`](https://swc.rs/docs/configuration/compilation#jscexternalhelpers).

### options.jsxRuntime

- Type: `"automatic" | "classic"`
- Default: `"automatic"`

The JSX runtime to use - 'automatic' for React 17+ new JSX transform or 'classic' for traditional JSX transform.

See [SWC `jsc.transform.react.runtime`](https://swc.rs/docs/configuration/compilation#jsctransformreactruntime).

### options.disableImportExportTransform

- Type: `boolean`
- Default: `false`

Whether to disable transformation of `import`/`export` statements.

### options.importSource

- Type: `string`
- Default: `"react"`

The source module for JSX runtime imports.

See [SWC `jsc.transform.react.importSource`](https://swc.rs/docs/configuration/compilation#jsctransformreactimportsource).

### options.lazyImports

- Type: `boolean | string[]`
- Default: `false`

Enable lazy loading for all imports or specific modules.

See [SWC `module.lazy`](https://swc.rs/docs/configuration/modules#lazy).

## Example

```js title=rspack.config.cjs
const Repack = require("@callstack/repack");

module.exports = {
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: {
          loader: "builtin:swc-loader",
          options: Repack.getSwcLoaderOptions({
            syntax: "ts",
            jsx: true,
            jsxRuntime: "automatic",
            externalHelpers: true,
          }),
        },
      },
    ],
  },
};
```



---
url: /404.md
---

404

# PAGE NOT FOUND

[Take me home](/)


---
url: /index.md
---

# Modern build tool for React Native

> Re.Pack brings Rspack and webpack ecosystem to mobile React Native apps

[Get started](/docs/getting-started/quick-start) | [Learn more](/docs/getting-started/introduction)

## Features

- <img src="/icons/layout-columns.svg" /> **Mobile Microfrontends**: Leverage Module Federation v2 to split JS or Hermes bytecode bundle into smaller chunks and download on-demand from a server.
- <img src="/icons/repeat.svg" /> **Powered by webpack / Rspack**: Use the full webpack ecosystem of plugins and loaders. Enhance with Rspack for build and fast refresh speed.
- <img src="/icons/layout-distribute-vertical.svg" /> **Drop-in Metro Replacement**: Use instead of Metro—a default React Native bundler. Migrate with a single command. All platforms supported.
- <img src="/icons/trending-down.svg" /> **Smaller App Size**: Use advanced optimizations like Tree Shaking to produce smaller Hermes bytecode size, improving app startup.
- <img src="/icons/sliders-2.svg" /> **React Native DevTools**: Integrated modern debugging experience for React Native with console, breakpoints, CPU, Memory and React profiling.
- <img src="/icons/server.svg" /> **Fully-featured Dev Server**: Take advantage of built-in support for Hot Module Replacement, Fast Refresh, error symbolication, and source maps support.