![\"\"](\"http:\/\/iamakulov.com\/notes2\/wp-content\/uploads\/2017\/05\/WINWORD_2017-05-02_22-45-43-21.png\")
<\/p>\nIt took me quite a long time of using ContextReplacementPlugin to finally realize what it really does. I hope this post will save you from that.<\/p>\n
<\/p>\n
Once in a while, you need to write a dynamic import. A dynamic import is when an imported file is only known at runtime:<\/p>\n
require('.\/inputs\/' + inputType + '\/index.js');\r\n<\/code><\/pre>\nWhen you\u2019re bundling this with webpack, webpack can\u2019t know what exact file you\u2019ll need. To make the application work, webpack will find and import all index.js<\/em> files in all subdirectories of the inputs directory, recursively. This can significantly increase your bundle size.<\/p>\nContextReplacementPlugin lets you change how webpack deals with dynamic imports. In this case, you can use it to narrow the search scope and thus cut the bundle size.<\/p>\n
Here\u2019s an example:<\/p>\n
\nContextReplacementPlugin is often used with moment.js, a library for working with dates. The thing with moment.js is that it has a bunch of locales, and it imports them dynamically on runtime:<\/p>\n\/\/ moment.js\r\nrequire('.\/locale\/' + name + '.js');\r\n<\/code><\/pre>\nTo make this work, webpack imports all the locales it can find \u2013 which adds 330 kB of non-minified code.<\/p>\n
In most cases, you only need to support a few locales and don\u2019t need all the other ones. ContextReplacementPlugin lets you specify the specific locales that webpack should import:<\/p>\n
\/\/ webpack.config.js\r\nconst webpack = require('webpack');\r\n\r\nmodule.exports = {\r\n plugins: [\r\n new webpack.ContextReplacementPlugin(\r\n \/moment[\/\\]locale\/,\r\n \/\/ Regular expression to match the files\r\n \/\/ that should be imported\r\n \/(en-gb|ru).js\/\r\n )\r\n ]\r\n};\r\n<\/code><\/pre>\n<\/div>\nThat works, that\u2019s copy-pasteable, but that\u2019s cryptic. Let\u2019s see what all these parameters really mean.<\/p>\n
Context and how to replace it#<\/a><\/h1>\nEach time you compile a dynamic import like this:<\/p>\n
require('.\/locale\/' + name + '.js');\r\n<\/code><\/pre>\nwebpack collects three pieces of information:<\/p>\n
\n- in what directory the files are located (in this case, it\u2019s .\/locale<\/em>),<\/li>\n
- what regular expression should a file match to be imported (in this case, it\u2019s \/^.*.js$\/<\/em>),<\/li>\n
- and if webpack should look for the files in the subdirectories (recursive flag;<\/em> always true<\/em> by default).<\/li>\n<\/ul>\n
These three pieces of information are called context<\/em>.<\/p>\nThen, webpack searches the appropriate files using the context. That means it looks into the directory specified in the context, looks into its subdirectories if the flag from the context is true, and uses the regular expression from the context to match and import the files.<\/p>\n
Now, the key point. ContextReplacementPlugin lets you replace the context that webpack uses for search<\/mark> \u2013 e.g. override the directory in which webpack should look for the files or the regular expression that webpack should use to match the files.<\/p>\n\nFor example, with the moment.js<\/em> example from above, ContextReplacementPlugin replaces the original regular expression \/^.*.js$\/<\/em> with another expression we pass \u2013 \/(en-gb|ru).js\/<\/em>. This way, we import only the necessary locales.\n<\/p>\nTo replace the context, you pass the parts you want to replace as the last parameters of ContextReplacementPlugin: <\/p>\n
new webpack.ContextReplacementPlugin(\r\n \/\/ The criterion to search; we\u2019ll get to it in a moment\r\n searchCritetion: RegExp,\r\n \/\/ The new directory to look for the files\r\n [newDirectory]: String,\r\n \/\/ The new recursive flag. True by default.\r\n \/\/ Pass false to disable recursive lookup\r\n [newRecursiveFlag]: Boolean,\r\n \/\/ The new regular expression to match\r\n \/\/ and import the files\r\n [newFilesRegExp]: RegExp\r\n)\r\n<\/code><\/pre>\n\nExamples#<\/a><\/h2>\nIf you don\u2019t fully understand how webpack generates context, here\u2019re examples:<\/p>\n
\n- of imports and contexts they create<\/a>,<\/li>\n
- of ContextReplacementPlugin calls<\/a>.<\/li>\n<\/ul>\n<\/div>\n
Finding the original context to replace#<\/a><\/h1>\nSo, you\u2019ve got a case when you have a dynamic import, and you need to replace its context with another one. How do you find this import and pass it to the plugin? You search by the context that the import generates.<\/p>\n
ContextReplacementPlugin allows you to search by the context\u2019s directory. This means that if you want to find an import, you should calculate what context it creates, and then pass a regular expression matching that directory to the context. That sounds complex, so let\u2019s just see how it works:<\/p>\n
\nYou have an import like this:<\/p>\nrequire('.\/locale\/' + name + '.js')\r\n<\/code><\/pre>\nand you want to apply ContextReplacementPlugin to it to limit the number of the included files.<\/p>\n
Step 1. Calculate the context that will be created by the import<\/b>
With this import, the context has three parts:<\/p>\n\n- directory, which is .\/locale<\/em>,\n
- the regular expression to match the files, which is \/^.*.js$\/<\/em>.\n
- and the recursive flag (always true<\/em>).\n<\/ul>\n
Step 2. Extract the directory from the context<\/b>
Here, the directory from the original context is \/\/.\/locale\/\/.<\/p>\n
Step 3. Find the full absolute path of the directory<\/b>
On your machine, the full path of the directory could be something like '\/usr\/\u2026\/my-project\/node_modules\/moment\/locale'<\/em>.<\/p>\nStep 4. Create a regular expression that matches the path<\/b>
This could be as simple as \/locale\/<\/em>. Or this could be something more specific, like \/moment[\/\\]locale\/<\/em> (cross-platform version of \/moment\/locale\/<\/em>).<\/p>\nI recommend to be as specific as possible: a simple regular expression, like \/locale\/<\/em>, can unexpectedly match other imports, like require('.\/images\/flags\/locale\/' + localeName)<\/em>.<\/p>\nStep 5. Pass the regular expression as the first parameter of ContextReplacementPlugin<\/b>
Like this:<\/p>\nnew webpack.ContextReplacementPlugin(\r\n \/moment[\/\\]locale\/,\r\n \u2026\r\n)\r\n<\/code><\/pre>\n<\/div>\n\nNormalModuleReplacementPlugin#<\/a><\/h2>\nNote: ContextReplacementPlugin works only with dynamic imports. If you ever want to configure a redirect for a normal, non-dynamic import, use NormalModuleReplacementPlugin<\/a>. It works with static imports (only with them), and it\u2019s way simpler to understand.\n<\/div>\nBonus point: webpack 2#<\/a><\/h1>\nThe traditional usage of ContextReplacementPlugin is to replace one context with another context. However, webpack 2 brought a new API that you can use to granularly redirect imports:<\/p>\n
new ContextReplacementPlugin(\r\n \/moment[\/\\]locale\/,\r\n path.resolve(__dirname, 'src'),\r\n {\r\n '.\/en.js': '.\/dir1\/en.js',\r\n '.\/ru.js': '.\/dir2\/ru.js',\r\n }\r\n)\r\n<\/code><\/pre>\nThe code above:<\/p>\n
\n- will add two files, .\/src\/dir1\/en.js<\/em> and .\/src\/dir2\/ru.js<\/em>, to the bundle,<\/li>\n
- will redirect all runtime requests from node_modules\/moment\/locale\/en.js<\/em> to dir1\/en.js<\/em>,<\/li>\n
- will redirect all runtime requests from node_modules\/moment\/locale\/ru.js<\/em> to dir2\/ru.js<\/em>.<\/li>\n<\/ul>\n
This is something that can\u2019t be achieved with traditional ContextReplacementPlugin. Unfortunately, this API is only briefly mentioned in a GitHub issue<\/a>.<\/p>\nWhen is this helpful? I can only think of some cases when a large existing project is being migrated to webpack \u2013 but I haven\u2019t seen any practical example. If you know any, share them in the comments!<\/p>\n
Here\u2019s how you write your own redirection:<\/p>\n
new ContextReplacementPlugin(\r\n \/\/ Specify the criterion for search\r\n \/moment[\/\\]locale\/,\r\n \r\n \/\/ Specify any directory that\u2019s common\r\n \/\/ for all the redirection targets.\r\n \/\/ It can\u2019t be __dirname: for some reason,\r\n \/\/ that doesn\u2019t work\r\n path.resolve(__dirname, 'src'),\r\n \r\n \/\/ Specify the mapping in form of\r\n \/\/ { runtime request : compile-time request }\r\n \/\/ IMPORTANT: runtime request should exactly match\r\n \/\/ the text that is passed into `require()`\r\n \/\/ IMPORTANT: compile-time request should be relative\r\n \/\/ to the directory from the previous parameter\r\n {\r\n '.\/en.js': '.\/dir1\/en.js',\r\n '.\/ru.js': '.\/dir2\/ru.js',\r\n }\r\n)\r\n<\/code><\/pre>\n\u03a3#<\/a><\/h1>\nThe key points:<\/p>\n
\n- Each time you do a dynamic import, webpack creates a context. Context is an object containing the directory to look into, the recursive flag and the regular expression for matching files.<\/p>\n<\/li>\n
- \n
Use ContextReplacementPlugin to change how webpack handles dynamic imports. This can be helpful when you need to decrease the bundle size or migrate some complex code to webpack.<\/p>\n<\/li>\n
- \n
You can granularly redirect compile-time requests to the different files with webpack 2.<\/p>\n<\/li>\n<\/ul>\n
Further reading#<\/a><\/h1>\nHere\u2019re some related links:<\/p>\n
\n- Webpack docs about context<\/a><\/li>\n
- Webpack docs about ContextReplacementPlugin<\/a><\/li>\n
- GitHub issue with a large discussion around the plugin<\/a><\/li>\n<\/ul>\n
\nThis is an article in my series of articles about webpack. The next one, \u201cSpeeding up build and improving the development workflow\u201d, is coming in July. Leave your email to know when it\u2019s out:
\n(you\u2019ll receive an email about this post + a couple of more webpack-related posts if I write them; no spam)<\/small><\/p>\n\n \n