1# enhanced-resolve 2 3Offers an async require.resolve function. It's highly configurable. 4 5## Features 6 7* plugin system 8* provide a custom filesystem 9* sync and async node.js filesystems included 10 11 12## Getting Started 13### Install 14```sh 15# npm 16npm install enhanced-resolve 17# or Yarn 18yarn add enhanced-resolve 19``` 20 21### Creating a Resolver 22The easiest way to create a resolver is to use the `createResolver` function on `ResolveFactory`, along with one of the supplied File System implementations. 23```js 24const { 25 NodeJsInputFileSystem, 26 CachedInputFileSystem, 27 ResolverFactory 28} = require('enhanced-resolve'); 29 30// create a resolver 31const myResolver = ResolverFactory.createResolver({ 32 // Typical usage will consume the `NodeJsInputFileSystem` + `CachedInputFileSystem`, which wraps the Node.js `fs` wrapper to add resilience + caching. 33 fileSystem: new CachedInputFileSystem(new NodeJsInputFileSystem(), 4000), 34 extensions: ['.js', '.json'] 35 /* any other resolver options here. Options/defaults can be seen below */ 36}); 37 38// resolve a file with the new resolver 39const context = {}; 40const resolveContext = {}; 41const lookupStartPath = '/Users/webpack/some/root/dir'; 42const request = './path/to-look-up.js'; 43myResolver.resolve({}, lookupStartPath, request, resolveContext, (err/*Error*/, filepath/*string*/) => { 44 // Do something with the path 45}); 46``` 47 48For more examples creating different types resolvers (sync/async, context, etc) see `lib/node.js`. 49#### Resolver Options 50| Field | Default | Description | 51| ------------------------ | --------------------------- | ---------------------------------------------------------------------------------- | 52| alias | [] | A list of module alias configurations or an object which maps key to value | 53| aliasFields | [] | A list of alias fields in description files | 54| cacheWithContext | true | If unsafe cache is enabled, includes `request.context` in the cache key | 55| descriptionFiles | ["package.json"] | A list of description files to read from | 56| enforceExtension | false | Enforce that a extension from extensions must be used | 57| enforceModuleExtension | false | Enforce that a extension from moduleExtensions must be used | 58| extensions | [".js", ".json", ".node"] | A list of extensions which should be tried for files | 59| mainFields | ["main"] | A list of main fields in description files | 60| mainFiles | ["index"] | A list of main files in directories | 61| modules | ["node_modules"] | A list of directories to resolve modules from, can be absolute path or folder name | 62| roots | [] | A list of directories to resolve request starting with `/` from | 63| ignoreRootsErrors | false | Ignore fatal errors happening during handling of `roots` (allows to add `roots` without a breaking change) | 64| preferAbsolute | false | Prefer to resolve server-relative urls as absolute paths before falling back to resolve in roots | 65| unsafeCache | false | Use this cache object to unsafely cache the successful requests | 66| plugins | [] | A list of additional resolve plugins which should be applied | 67| symlinks | true | Whether to resolve symlinks to their symlinked location | 68| cachePredicate | function() { return true }; | A function which decides whether a request should be cached or not. An object is passed to the function with `path` and `request` properties. | 69| moduleExtensions | [] | A list of module extensions which should be tried for modules | 70| resolveToContext | false | Resolve to a context instead of a file | 71| restrictions | [] | A list of resolve restrictions | 72| fileSystem | | The file system which should be used | 73| resolver | undefined | A prepared Resolver to which the plugins are attached | 74 75## Plugins 76Similar to `webpack`, the core of `enhanced-resolve` functionality is implemented as individual plugins that are executed using [`Tapable`](https://github.com/webpack/tapable). These plugins can extend the functionality of the library, adding other ways for files/contexts to be resolved. 77 78A plugin should be a `class` (or its ES5 equivalent) with an `apply` method. The `apply` method will receive a `resolver` instance, that can be used to hook in to the event system. 79 80### Plugin Boilerplate 81```js 82class MyResolverPlugin { 83 constructor(source, target) { 84 this.source = source; 85 this.target = target; 86 } 87 88 apply(resolver) { 89 const target = resolver.ensureHook(this.target); 90 resolver.getHook(this.source).tapAsync("MyResolverPlugin", (request, resolveContext, callback) => { 91 // Any logic you need to create a new `request` can go here 92 resolver.doResolve(target, request, null, resolveContext, callback); 93 }); 94 } 95} 96``` 97 98Plugins are executed in a pipeline, and register which event they should be executed before/after. In the example above, `source` is the name of the event that starts the pipeline, and `target` is what event this plugin should fire, which is what continues the execution of the pipeline. For an example of how these different plugin events create a chain, see `lib/ResolverFactory.js`, in the `//// pipeline ////` section. 99 100## Tests 101 102``` javascript 103npm test 104``` 105 106[](http://travis-ci.org/webpack/enhanced-resolve) 107 108 109## Passing options from webpack 110If you are using `webpack`, and you want to pass custom options to `enhanced-resolve`, the options are passed from the `resolve` key of your webpack configuration e.g.: 111 112``` 113resolve: { 114 extensions: ['', '.js', '.jsx'], 115 modules: ['src', 'node_modules'], 116 plugins: [new DirectoryNamedWebpackPlugin()] 117 ... 118}, 119``` 120 121## License 122 123Copyright (c) 2012-2016 Tobias Koppers 124 125MIT (http://www.opensource.org/licenses/mit-license.php) 126
){kind=link}