Name	Name	Last commit message	Last commit date
parent directory ..
__mocks__	__mocks__
addons	addons
e2e	e2e
env	env
jest	jest
loaders	loaders
plugins	plugins
src	src
template	template
utils	utils
web-default	web-default
.eslintignore	.eslintignore
.eslintrc.js	.eslintrc.js
LICENSE	LICENSE
LICENSE-third-party	LICENSE-third-party
README.md	README.md
getWebExtensions.js	getWebExtensions.js
jest-puppeteer.config.js	jest-puppeteer.config.js
package.json	package.json
tsconfig.json	tsconfig.json
webpack.config.d.ts	webpack.config.d.ts
webpack.config.js	webpack.config.js

👋 Welcome to
`@expo/webpack-config`

Webpack config that's optimized for running universal React and react-native-web projects

Documentation

To learn more about how to use this Webpack config, check out the docs here: Customizing the Webpack config

Contributing to the docs

API

Running expo customize:web will generate this default config in your project.

const createExpoWebpackConfigAsync = require('@expo/webpack-config');

module.exports = async function (env, argv) {
  const config = await createExpoWebpackConfigAsync(env, argv);
  // Customize the config before returning it.
  return config;
};

Types

`Environment`

The main options used to configure how @expo/webpack-config works.

name	type	default	description
`projectRoot`	`string`	required	Root of the Expo project.
`https`	`boolean`	`false`	Should the dev server use https protocol.
`mode`	`Mode`	required	The Webpack mode to bundle the project in.
`platform`	`ExpoPlatform`	required	The target platform to bundle for.
`pwa`	`boolean`	`true`	Generate the PWA image assets in production mode.
`babel`	`ExpoBabelOptions`	`undefined`	Control how the default Babel loader is configured.

`Environment` internal

name	type	default	description
`config`	`ExpoConfig`	`undefined`	The Expo project config, this should be read using `@expo/config`.
`locations`	`FilePaths`	`undefined`	Paths used to locate where things are.

`ExpoPlatform`

| type | description | | ------ | ----------- | ----- | ----------- | ---------------------------------------------------------------------------------------------------------- | | 'ios' | 'android' | 'web' | 'electron' | The target platform to bundle for. Native platforms are experimental and require a special native runtime. |

`ExpoBabelOptions`

Control how the default Babel loader is configured.

name	type	default	description
`dangerouslyAddModulePathsToTranspile`	`string[]`	`undefined`	Add the names of node_modules that should be included transpilation step.

Guides

PWAs

See the docs for expo-pwa to learn more about creating the assets manually.
Disable automatic PWA generation with expo build:web --no-pwa.
expo build:web will automatically skip any PWA asset that's already linked in the project's local web/index.html.
Having sharp CLI installed globally will speed up asset generation, if it's not installed, Jimp will be used instead.

Chrome PWAs

Manifest.json

The manifest.json will be created using the values in the project's app.config.js:

Generating the manifest.json will be skipped if the following exists in the project's web/index.html:

Show HTML

<link rel="manifest" href="..." />

If the icons array is defined in your manifest.json, then Chrome PWA icon generation will be skipped.

Chrome PWA Icons

Icons will be generated using the file defined in your app.config.js under android.icon and it'll fallback to icon.

Show manifest.json

{
  "icons": [
    {
      "src": "...",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "...",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "...",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Favicons

Favicons will be generated using the file defined in your app.config.js under web.favicon and it'll fallback to icon.

Asset generation for Favicons will be individually skipped if any of the following fields exist in your web/index.html:

Show HTML

<link rel="icon" type="image/png" sizes="16x16" href="..." />
<link rel="icon" type="image/png" sizes="32x32" href="..." />
<link rel="shortcut icon" href="..." />

Safari PWAs

Icons will be generated using the file defined in your app.config.js under ios.icon and it'll fallback to icon. The splash screens look at ios.splash and fallback to splash.

Asset generation for Safari PWA icons/splash screens will be individually skipped if any of the following fields exist in your web/index.html:

Icons

Show HTML

<link rel="apple-touch-icon" sizes="180x180" href="..." />

Splash Screens

Show HTML

<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2) and (orientation: landscape)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2) and (orientation: portrait)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 3) and (orientation: landscape)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 3) and (orientation: portrait)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 2) and (orientation: landscape)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 414px) and (device-height: 896px) and (-webkit-device-pixel-ratio: 2) and (orientation: portrait)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 375px) and (device-height: 812px) and (-webkit-device-pixel-ratio: 3) and (orientation: landscape)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 375px) and (device-height: 812px) and (-webkit-device-pixel-ratio: 3) and (orientation: portrait)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 414px) and (device-height: 736px) and (-webkit-device-pixel-ratio: 3) and (orientation: landscape)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 414px) and (device-height: 736px) and (-webkit-device-pixel-ratio: 3) and (orientation: portrait)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2) and (orientation: landscape)"
  href="..."
/>
<link
  rel="apple-touch-startup-image"
  media="screen and (device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2) and (orientation: portrait)"
  href="..."
/>

Include modules

You may find that you want to include universal modules that aren't part of the default modules. You can do this by customizing the Webpack config:

const createExpoWebpackConfigAsync = require('@expo/webpack-config');

module.exports = async function (env, argv) {
  const config = await createExpoWebpackConfigAsync(
    {
      ...env,
      babel: {
        dangerouslyAddModulePathsToTranspile: [
          // Ensure that all packages starting with @evanbacon are transpiled.
          '@evanbacon',
        ],
      },
    },
    argv
  );
  return config;
};

withUnimodules

If you're adding support to some other Webpack config like in Storybook or Gatsby you can use the same process to include custom modules:

const { withUnimodules } = require('@expo/webpack-config/addons');

module.exports = function () {
  const someWebpackConfig = {
    /* Your custom Webpack config */
  };

  // Add Expo support...
  const configWithExpo = withUnimodules(someWebpackConfig, {
    projectRoot: __dirname,
    babel: {
      dangerouslyAddModulePathsToTranspile: [
        // Ensure that all packages starting with @evanbacon are transpiled.
        '@evanbacon',
      ],
    },
  });

  return configWithExpo;
};

This method should be used instead of using the expo.web.build.babel.include field of the app.json.

Modify the babel loader

If you want to modify the babel loader further, you can retrieve it using the helper method getExpoBabelLoader like this:

const createExpoWebpackConfigAsync = require('@expo/webpack-config');
const { getExpoBabelLoader } = require('@expo/webpack-config/utils');

module.exports = async function (env, argv) {
  const config = await createExpoWebpackConfigAsync(env, argv);
  const loader = getExpoBabelLoader(config);
  if (loader) {
    // Modify the loader...
  }
  return config;
};

Service workers

Example of using service workers with Expo: npx create-react-native-app -t with-workbox

This webpack config currently does not supply service workers by default, they can be added to the project locally: Adding Service Workers.

Environment Variables

EXPO_WEBPACK_DEFINE_ENVIRONMENT_AS_KEYS: Should the define plugin explicitly set environment variables like process.env.FOO instead of creating an object like proces.env: { FOO }. Defaults to false. Next.js uses this to prevent overwriting injected environment variables.
IMAGE_INLINE_SIZE_LIMIT: By default, images smaller than 10,000 bytes are encoded as a data URI in base64 and inlined in the CSS or JS build artifact. Set this to control the size limit in bytes. Setting it to 0 will disable the inlining of images. This is only used in production.

Exports

addons

For adding features to an existing Webpack config.

`withUnimodules`

import { withUnimodules } from '@expo/webpack-config/addons';

Wrap your existing webpack config with support for Unimodules (Expo web). ex: Storybook ({ config }) => withUnimodules(config)

params

webpackConfig: AnyConfiguration = {} Optional existing Webpack config to modify.
env: InputEnvironment = {} Optional [Environment][#environment] options for configuring what features the Webpack config supports.
argv: Arguments = {}

`withOptimizations`

import { withOptimizations } from '@expo/webpack-config/addons';

`withAlias`

Apply aliases to a Webpack config.

import { withAlias } from '@expo/webpack-config/addons';

`withDevServer`

import { withDevServer } from '@expo/webpack-config/addons';

`withNodeMocks`

import { withNodeMocks } from '@expo/webpack-config/addons';

`withEntry`

import { withEntry } from '@expo/webpack-config/addons';

`withTypeScriptAsync`

import { withTypeScriptAsync } from '@expo/webpack-config/addons';

env

Getting the config, paths, mode, and various other settings in your environment.

`getConfig`

import { getConfig } from '@expo/webpack-config/env';

`getMode`

import { getMode } from '@expo/webpack-config/env';

`validateEnvironment`

import { validateEnvironment } from '@expo/webpack-config/env';

`getAliases`

import { getAliases } from '@expo/webpack-config/env';

`getPaths`

import { getPaths } from '@expo/webpack-config/env';

`getPathsAsync`

import { getPathsAsync } from '@expo/webpack-config/env';

`getServedPath`

import { getServedPath } from '@expo/webpack-config/env';

`getPublicPaths`

import { getPublicPaths } from '@expo/webpack-config/env';

`getProductionPath`

import { getProductionPath } from '@expo/webpack-config/env';

`getAbsolute`

import { getAbsolute } from '@expo/webpack-config/env';

`getModuleFileExtensions`

import { getModuleFileExtensions } from '@expo/webpack-config/env';

loaders

The module rules used to load various files.

`imageLoaderRule`

import { imageLoaderRule } from '@expo/webpack-config/loaders';

This is needed for webpack to import static images in JavaScript files. "url" loader works like "file" loader except that it embeds assets smaller than specified limit in bytes as data URLs to avoid requests. A missing test is equivalent to a match.

`fallbackLoaderRule`

import { fallbackLoaderRule } from '@expo/webpack-config/loaders';

"file" loader makes sure those assets get served by WebpackDevServer. When you import an asset, you get its (virtual) filename. In production, they would get copied to the build folder. This loader doesn't use a "test" so it will catch all modules that fall through the other loaders.

`styleLoaderRule`

import { styleLoaderRule } from '@expo/webpack-config/loaders';

Default CSS loader.

plugins

import /* */ '@expo/webpack-config/plugins';

Custom versions of Webpack Plugins that are optimized for use with native React runtimes.

`ExpoDefinePlugin`

import { ExpoDefinePlugin } from '@expo/webpack-config/plugins';

Required for expo-constants https://docs.expo.dev/versions/latest/sdk/constants/. This surfaces the app.json (config) as an environment variable which is then parsed by expo-constants.

`ExpoHtmlWebpackPlugin`

import { ExpoHtmlWebpackPlugin } from '@expo/webpack-config/plugins';

Generates an index.html file with the <script> injected.

`ExpoInterpolateHtmlPlugin`

import { ExpoInterpolateHtmlPlugin } from '@expo/webpack-config/plugins';

Add variables to the index.html.

utils

Tools for resolving fields, or searching and indexing loaders and plugins.

`resolveEntryAsync`

import { resolveEntryAsync } from '@expo/webpack-config/utils';

What it does not do

Gzip compression: This was supported in beta but later removed in favor of hosting providers like Now and Netlify automatically compressing files in the server.

License

The Expo source code is made available under the MIT license. Some of the dependencies are licensed differently, with the BSD license, for example.

Files

webpack-config

Directory actions

More options

Directory actions

More options

Latest commit

History

webpack-config

Folders and files

parent directory

README.md

👋 Welcome to @expo/webpack-config

Documentation

Contributing to the docs

API

Types

Environment

Environment internal

ExpoPlatform

ExpoBabelOptions

Guides

PWAs

Chrome PWAs

Manifest.json

Chrome PWA Icons

Favicons

Safari PWAs

Icons

Splash Screens

Include modules

Modify the babel loader

Service workers

Environment Variables

Exports

addons

withUnimodules

withOptimizations

withAlias

withDevServer

withNodeMocks

withEntry

withTypeScriptAsync

env

getConfig

getMode

validateEnvironment

getAliases

getPaths

getPathsAsync

getServedPath

getPublicPaths

getProductionPath

getAbsolute

getModuleFileExtensions

loaders

imageLoaderRule

fallbackLoaderRule

styleLoaderRule

plugins

ExpoDefinePlugin

ExpoHtmlWebpackPlugin

ExpoInterpolateHtmlPlugin

utils

resolveEntryAsync

What it does not do

License

👋 Welcome to
`@expo/webpack-config`

`Environment`

`Environment` internal

`ExpoPlatform`

`ExpoBabelOptions`

`withUnimodules`

`withOptimizations`

`withAlias`

`withDevServer`

`withNodeMocks`

`withEntry`

`withTypeScriptAsync`

`getConfig`

`getMode`

`validateEnvironment`

`getAliases`

`getPaths`

`getPathsAsync`

`getServedPath`

`getPublicPaths`

`getProductionPath`

`getAbsolute`

`getModuleFileExtensions`

`imageLoaderRule`

`fallbackLoaderRule`

`styleLoaderRule`

`ExpoDefinePlugin`

`ExpoHtmlWebpackPlugin`

`ExpoInterpolateHtmlPlugin`

`resolveEntryAsync`