#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).

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.

#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 and the native module for it.

#Generic usage

On a high-level, all functionalities that enable usage of Webpack's Code Splitting, are powered by Re.Pack's ScriptManager, which consists of the JavaScript part and the native part.

The ScriptManager has methods which allows to:

1. Download and execute script - loadScript
2. Prefetch script (without executing immediately) - prefetchScript
3. Resolve script location - resolveScript
4. Invalidate cache - invalidateScripts

In order to provide this functionalities, a resolver has to be added using ScriptManager.shared.addResolver:

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.

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
   • Manually when using Scripts approach or 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
   • 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.

#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.

#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:

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

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

// 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.

#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.

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

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

And adding a resolver to the ScriptManager to resolve your scripts:

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 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.

#Source code

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

// 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:

// 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:

// 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} />
      ) : (
        <TeacherSize 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:

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(...), so it can resolve the chunks:

// 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 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.

#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.

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 option to named in Webpack config.
2. Use /* webpackChunkName: "<name>" */ magic comment in import(...).

#NamedchunkIds config option

Setting optimization.chunkIds option to named in your Webpack config will force Webpack to always use the human-readable form for the name of the chunks.

/* ... */

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

  return {
    /* ... */

    optimization: {
      /* ... */

      chunkIds: "named",
    },

    /* ... */
  };
};

#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:

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

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

#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 to RepackPlugin:

/* ... */

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.

#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.

You can customize which chunk should be local by providing extraChunks option in RepackPlugin configuration:

/* ... */

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.

Once you have some chunks as local, you need to alter the resolver in ScriptManager.shared.addResolver:

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}`),
    };
  }
});

#Advanced example

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

/* ... */

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:

#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 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 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:

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:

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}`),
  };
});

Usually cache invalidation happens automatically, but it's possible to invalidate chunk manually as well using ScriptManager.shared.invalidateScripts(...), which removes the scripts from filesystem and from the storage.