import.meta.resolve()
import.meta.resolve()
is a built-in function defined on the import.meta
object of a JavaScript module that resolves a module specifier to a URL using the current module's URL as base.
Syntax
import.meta.resolve(moduleName)
Parameters
moduleName
-
A string that specifies a potentially importable module. This may be a relative path (such as
"./lib/helper.js"
), a bare name (such as"my-module"
), or an absolute URL (such as"https://example.com/lib/helper.js"
).
Return value
Returns a string corresponding to the path that would be imported if the argument were passed to import()
.
Description
import.meta.resolve()
allows a script to access the module specifier resolution algorithm for a name, like this:
// Script at https://example.com/main.js
const helperPath = import.meta.resolve("./lib/helper.js");
console.log(helperPath); // "https://example.com/lib/helper.js"
Note that import.meta.resolve()
only performs resolution and does not attempt to load or import the resulting path. (The explainer for the specification describes the reasoning for this behavior.) Therefore, its return value is the same regardless of whether the returned path corresponds to a file that exists, and regardless of whether that file contains valid code for a module.
It is different from dynamic import, because although both accept a module specifier as the first argument, import.meta.resolve()
returns the path that would be imported without making any attempt to access that path. Therefore, the following two are effectively the same code:
// Approach 1
console.log(await import("./lib/helper.js"));
// Approach 2
const helperPath = import.meta.resolve("./lib/helper.js");
console.log(await import(helperPath));
However, even if "./lib/helper.js"
cannot be successfully imported, the second snippet will not encounter an error until it attempts to perform the import on line 2.
Bare module names
You can pass a bare module name (also known as a bare module specifier) to import.meta.resolve()
, as long as module resolution is defined for the name. For example, you can define this using an import map inside a browser:
<!-- index.html -->
<script type="importmap">
{
"imports": {
"my-module": "./modules/my-module/index.js"
}
}
</script>
<script type="module">
const moduleEntryPath = import.meta.resolve("my-module");
console.log(moduleEntryPath);
</script>
Again, since this snippet does not try to import moduleEntryPath
— neither does the import map — it prints the resolved URL regardless of whether ./modules/my-module/index.js
actually exists.
Comparison with new URL()
The URL()
constructor accepts a second base URL argument. When the first argument is a relative path and the base URL is import.meta.url
, the effect is similar to import.meta.resolve()
.
const helperPath = new URL("./lib/helper.js", import.meta.url).href;
console.log(helperPath);
This is also a useful replacement syntax when targeting older browsers. However, there are some differences:
import.meta.resolve()
returns a string, whilenew URL()
returns aURL
object. It is possible to usehref
ortoString()
on the constructedURL
, but this may still not produce the exact same result in some JavaScript environments or when using tools like bundlers to statically analyze the code.import.meta.resolve()
is aware of additional resolution configurations, such as resolving bare module names using import maps, as described above.new URL()
is not aware of import maps and treats bare module names as relative paths (i.e.new URL("my-module", import.meta.url)
meansnew URL("./my-module", import.meta.url)
).
Some tools recognize new URL("./lib/helper.js", import.meta.url).href
as a dependency on "./lib/helper.js"
(similar to an import), and take this into account for features like bundling, rewriting imports for moved files, "go to source" functionality, etc. However, since import.meta.resolve()
is less ambiguous and specifically designed to indicate a module path resolution dependency, you should use import.meta.resolve(moduleName)
instead of new URL(moduleName, import.meta.url)
for these use cases wherever possible.
Not an ECMAScript feature
import.meta.resolve()
is not specified or documented as part of the ECMAScript specification for JavaScript modules. Instead, the specification defines the import.meta
object but leaves all its properties as "host-defined". The WHATWG HTML standard picks up where the ECMAScript standard leaves off, and defines import.meta.resolve
using its module specifier resolution.
This means that import.meta.resolve()
is not required to be implemented by all conformant JavaScript implementations. However, import.meta.resolve()
may also be available in non-browser environments:
- Deno implements compatibility with browser behavior.
- Node.js also implements the
import.meta.resolve()
function, but adds an additionalparent
parameter if you use the--experimental-import-meta-resolve
flag.
Examples
Resolve a path for the Worker() constructor
import.meta.resolve()
is particularly valuable for APIs that take a path to a script file as an argument, such as the Worker()
constructor:
// main.js
const workerPath = import.meta.resolve("./worker.js");
const worker = new Worker(workerPath, { type: "module" });
worker.addEventListener("message", console.log);
// worker.js
self.postMessage("hello!");
This is also useful to calculate paths for other workers, such as service workers and shared workers. However, if you are using a relative path to calculate the URL of a service worker, keep in mind that the directory of the resolved path determines its registration scope by default (although a different scope can be specified during registration).
Specifications
Specification |
---|
HTML Standard # import-meta-resolve |
Browser compatibility
BCD tables only load in the browser