transpilePackages -- missing details - how it works, especially with webpack resolve aliases

[fbartho]

Goals

1. Details about the different compilation configurations would be helpful
2. It'd be great to know if I've discovered a bug or I'm misusing the option.
3. It'd be great to know if I need to file a feature request or if I'm doing it wrong.
4. It'd be great if we solve my confusion / find a working combination of next.config flags to achieve my outcome.

Non-Goals

No response

Background

1. With a project using react-native / react-native-web (which is working great using a webpack config for the alias), I wanted to add react-native-reanimated.
2. A naive integration lead to errors when loading the module. The errors pointed to an uncompiled JSX expression.
3. Documentation suggested using the end-of-life/dead next-transpile-modules package -- I found the NextJS post saying to migrate to using transpilePackages
4. Using that unfortunately didn’t work either — as it tried to compile react-native-reanimated and then tried to transpile react-native which was not appropriate here since there was a module alias configured in the webpack config that it never processed.

Proposal

1. NextJS should either respect the webpack configuration for resolve aliases or it should provide an alternative configuration option for the combination of transpilePackages & a package alias.
2. If someone can help me with a pointer to a modern working solution, then I'd be thrilled to contribute documentation around the nuances of transpilePackages or any other appropriate documentation. (As you can see, the documentation for that option is extremely limited today)

[weyniis]

Hey, u're absolutely right that the documentation around transpilePackages is currently limited, and the behavior with webpack resolve.alias can be a bit confusing, especially when coming from next-transpile-modules.

Let’s clarify a few things and suggest a working approach.

---

What's happening

The new transpilePackages option in Next.js is intended to replace the older next-transpile-modules package, but it currently doesn’t respect custom webpack resolve.alias settings when applied to transpiled modules. That’s likely why u're getting errors when trying to transpile something like react-native-reanimated that uses a custom alias setup.

This becomes especially tricky when dealing with packages like react-native-web + react-native-reanimated, where aliases are critical to resolve module paths cleanly.

---

What can u do to make it work?

For now, if u want to use transpilePackages AND custom aliasing, here’s a workaround:

1. Keep using webpack.resolve.alias in your next.config.js
2. Use transpilePackages to handle only the non-aliased parts
3. Ensure babel.config.js is also properly resolving for aliased packages

Example setup:

// next.config.js
const path = require("path");

const nextConfig = {
  webpack: (config) => {
    config.resolve.alias["react-native$"] = "react-native-web";
    config.resolve.alias["react-native-reanimated"] = path.resolve(
      __dirname,
      "node_modules/react-native-reanimated"
    );
    return config;
  },
  transpilePackages: ["react-native-reanimated"],
};

module.exports = nextConfig;

This forces the webpack alias to take effect, while still letting Next.js transpile the external package.


 Notes:

transpilePackages only tells Next.js to process the package through Babel. It does not automatically apply webpack aliases.

If the module (like react-native-reanimated) relies on a specific alias or react-native path, that alias must be defined manually in webpack.resolve.alias.

If u’re importing JSX that fails to compile, that’s usually a sign that Babel didn’t process it — either because the alias didn’t work, or transpilePackages didn’t apply.

Proposal Feedback:

u're spot on — this could definitely use better integration or at least clearer documentation. It would be ideal if Next.js supported a merged config between aliasing and transpilation.

Until then, using a combination like above should work. If u’re up for contributing docs once u stabilize your setup, it would definitely help others in the same situation.

[fbartho]

To @weyniis’s human operator: I’m not entirely opposed to talking with an LLM. Just disclose it on your profile and/or in the comments you make (ideally, both). This account shouldn’t pretend to be a human.

---

The response above unfortunately doesn’t work. The transpiled package (react-native-reanimated) depends on react-native which needs to be aliased to react-native-web.

Perhaps there’s a correct babel.config.js that would tell nextjs how to handle that alias. Do you or others have any advice on that?