{"id":20519440,"url":"https://github.com/moxystudio/next-webpack-oneof","last_synced_at":"2025-04-14T02:10:47.438Z","repository":{"id":38425092,"uuid":"213628075","full_name":"moxystudio/next-webpack-oneof","owner":"moxystudio","description":"Wraps all webpack loader rules into a single oneOf rule","archived":false,"fork":false,"pushed_at":"2023-03-04T04:56:45.000Z","size":1350,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-27T16:09:31.767Z","etag":null,"topics":["loader","next","nextjs","oneof","plugin","rules","webpack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moxystudio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-08T11:49:00.000Z","updated_at":"2023-11-23T21:32:22.000Z","dependencies_parsed_at":"2023-01-31T22:10:26.465Z","dependency_job_id":null,"html_url":"https://github.com/moxystudio/next-webpack-oneof","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxystudio%2Fnext-webpack-oneof","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxystudio%2Fnext-webpack-oneof/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxystudio%2Fnext-webpack-oneof/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moxystudio%2Fnext-webpack-oneof/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moxystudio","download_url":"https://codeload.github.com/moxystudio/next-webpack-oneof/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809046,"owners_count":21164896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["loader","next","nextjs","oneof","plugin","rules","webpack"],"created_at":"2024-11-15T22:13:42.693Z","updated_at":"2025-04-14T02:10:47.397Z","avatar_url":"https://github.com/moxystudio.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# next-webpack-oneof\n\n[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][build-status-image]][build-status-url] [![Coverage Status][codecov-image]][codecov-url] [![Dependency status][david-dm-image]][david-dm-url] [![Dev Dependency status][david-dm-dev-image]][david-dm-dev-url]\n\n[npm-url]:https://npmjs.org/package/@moxy/next-webpack-oneof\n[downloads-image]:https://img.shields.io/npm/dm/@moxy/next-webpack-oneof.svg\n[npm-image]:https://img.shields.io/npm/v/@moxy/next-webpack-oneof.svg\n[build-status-url]:https://github.com/moxystudio/next-webpack-oneof/actions\n[build-status-image]:https://img.shields.io/github/workflow/status/moxystudio/next-webpack-oneof/Node%20CI/master\n[codecov-url]:https://codecov.io/gh/moxystudio/next-webpack-oneof\n[codecov-image]:https://img.shields.io/codecov/c/github/moxystudio/next-webpack-oneof/master.svg\n[david-dm-url]:https://david-dm.org/moxystudio/next-webpack-oneof\n[david-dm-image]:https://img.shields.io/david/moxystudio/next-webpack-oneof.svg\n[david-dm-dev-url]:https://david-dm.org/moxystudio/next-webpack-oneof?type=dev\n[david-dm-dev-image]:https://img.shields.io/david/dev/moxystudio/next-webpack-oneof.svg\n\nWraps all webpack loader rules into a single oneOf rule.\n\nBy default webpack loaders will test all files for all loaders. However, webpack does support [`oneOf` rules](https://webpack.js.org/configuration/module/#ruleoneof), within which only the first matching rule will be used.\n\nThis plugin transfers all rules into a single `oneOf` rule, so no file will match more than one condition.\n\n\n## Installation\n\n```sh\n$ npm install --save @moxy/next-webpack-oneof\n```\n\n\n## Motivation\n\nIn webpack loaders, rules to match against filenames are typically structured with the expectation that all files will try to match against all rules. With simple configurations this is not an issue, but can become problematic as complexity grows and, for example, you need different loaders for similar files.\n\nAs it is, the solution is using complex pairs of `include`/`exclude` in the rules. As the complexity of this problem grows, however, implementing these exclusion rules will get more confusing and become a hassle. To avoid this, files would have to **skip all rule matching tests after their first match**, to guarantee that no file matches against more than one rule by default.\n\nWebpack implements a type of rule where that already happens, [`Rule.oneOf`](https://webpack.js.org/configuration/module/#ruleoneof), within which only the first matching rule will be used. We want this to be the default behavior.\n\n\n## How\n\nThis plugin operates directly on the configuration object and wraps all rules into one single oneOf rule so that it becomes the default behavior for all rules.\n\nThis, in effect, changes how to think about loader rules as **the order of rules becomes of imperative importance**.\n\nIn `Next.js` you can use function composition to bundle together multiple operations on your webpack configuration. Given the nature of function composition, the order of execution is inverse to the nesting degree of each function call. As it concerns this plugin, because you always want this plugin to be the last function to be called, **it must be the topmost function in your composition** to guarantee that it has access to all loader rules in your project.\n\n\n## Usage\n\nMultiple configurations can be combined together with function composition. However, as explained above, this plugin must be the topmost function call. For example:\n\n```js\n// next.config.js\nconst withOneOf = require('@moxy/next-webpack-oneof');\nconst withCSS = require('@zeit/next-css');\n\nmodule.exports = withOneOf(\n    withCSS({\n        cssModules: true,\n    }),\n);\n```\n\nTo simplify using multiple plugins, you can also use [`next-compose-plugins`](https://github.com/cyrilwanner/next-compose-plugins). The examples in this document will use `next-compose-plugins`. As with the example above, `next-webpack-oneof` must be the topmost object. For example:\n\n```js\n//next.config.js\nconst withPlugins = require('next-compose-plugins');\nconst withOneOf = require('@moxy/next-webpack-oneof');\nconst withCSS = require('@zeit/next-css');\n\nmodule.exports = withPlugins([\n    withOneOf,\n    [withCSS, {\n        cssModules: true,\n    }],\n]);\n```\n\n\n## Examples\n\nIn the following examples, two loaders are used for `.png` files: one default loader, and one loader for specific `.png` files with `.base64.` somewhere in their filename.\n\n### Without `next-webpack-oneof`\n\nUsing the standard webpack implementation, you would write the rules like so:\n\n```js\n// Without 'next-webpack-oneof'\nconst withPlugins = require('next-compose-plugins');\n\nwithPlugins([\n    {\n        webpack(config) {\n            config.module.rules.push({\n                // More specific rule to catch .png files that also match the `include` pattern\n                test: /\\.png$/,\n                include: /\\.base64\\./,\n                loader: 'some-base64-loader',\n            });\n\n            config.module.rules.push({\n                // General rule to catch all .png files\n                // Exclude files with '.base64.' in their filename\n                test: /\\.png$/,\n                exclude: /\\.base64\\./,\n                loader: 'some-loader',\n            });\n        },\n    },\n])\n```\n\nTo avoid confusing and introducing conflicts in this configuration, you must use a combination of `include` and `exclude` to guarantee that files don't fall through to multiple loaders.\n\n### With `next-webpack-oneof`\n\nUsing `next-webpack-oneof` you can avoid having to declare complex rule exclusions, but you must be careful with the order of your rules. These examples explore how to use this plugin, and explain how the order of rules changes in different contexts.\n\nIf you're setting multiple rules in one plugin, the rules inside will output with the same order as they're written in. When you can expect this to be the case, rules with more specificity should be written before more general rules, like in this example:\n\n```js\n// With 'next-webpack-oneof'\nconst withPlugins = require('next-compose-plugins');\nconst withOneOf = require('@moxy/next-webpack-oneof');\n\nwithPlugins([\n    withOneOf,\n    {\n        webpack(config) {\n            // More specific rule to catch .png files that also match the `include` pattern\n            config.module.rules.push({\n                test: /\\.png$/,\n                include: /\\.base64\\./,\n                loader: 'some-base64-loader',\n            });\n\n            // General rule to catch all .png files\n            config.module.rules.push({\n                test: /\\.png$/,\n                loader: 'some-loader',\n            });\n        },\n    },\n])\n```\n\nHowever, if you're setting rules in different plugins, the bottommost plugin will execute first, with order of execution going upwards from that point. In this case, plugins with rules with more specificity should be below plugins with more general rules, like in this example:\n\n```js\n// With 'next-webpack-oneof'\nconst withPlugins = require('next-compose-plugins');\nconst withOneOf = require('@moxy/next-webpack-oneof');\n\nwithPlugins([\n    withOneOf,\n    {\n        webpack(config) {\n            config.module.rules.push({\n                // General rule to catch all .png files\n                test: /\\.png$/,\n                loader: 'some-loader',\n            });\n        },\n    },\n    {\n        webpack(config) {\n            config.module.rules.push({\n                // More specific rule to catch .png files that also match the `include` pattern\n                test: /\\.png$/,\n                include: /\\.base64\\./,\n                loader: 'some-base64-loader',\n            });\n    },\n})\n```\n\n\n## Tests\n\nAny parameter passed to the `test` command is passed down to Jest.\n\n```sh\n$ npm t\n$ npm t -- --watch  # To run watch mode\n```\n\n## License\n\nReleased under the [MIT License](https://opensource.org/licenses/mit-license.php).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoxystudio%2Fnext-webpack-oneof","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoxystudio%2Fnext-webpack-oneof","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoxystudio%2Fnext-webpack-oneof/lists"}