Bundling non-JavaScript static resources details

This article is translated from https://web.dev/bundling-non-js-resources/. The original text has not been modified

Suppose you are developing a web application. In this case, you’re likely dealing not only with JavaScript modules, but also various other resources — Web Workers (which are also JavaScript, but have their own separate build dependency graph), images, CSS, fonts, WebAssembly modules, and so on.

One possible way to load static resources is to reference them directly in the HTML, but usually they are logically coupled with other reusable components. For example, CSS of a custom dropdown menu is tied to its JavaScript portion, the icon image is tied to the toolbar component, and WebAssembly module is tied to its JavaScript glue. In these cases, it is often more convenient and quicker to reference the assets directly from their JavaScript modules and load them dynamically when the corresponding component is loaded.

However, most build systems for larger projects will perform additional optimizations and reorganization of content - such as bundling and minimize . A build system cannot execute code and predict what the result will be, and there is no reason to iterate over every possible string in JavaScript and determine whether it is a resource URL. So, how can we make them "see" the dynamic resources loaded by JavaScript components and include them in the build product?

1. Custom import in packaging tools

A common approach is to leverage the existing static import syntax. Some bundlers may automatically detect the format by file extension, while others allow plugins to use a custom URL Scheme , such as the following example:

// Normal JavaScript importimport { loadImg } from './utils.js';

// Special "URL import" static resources import imageUrl from 'asset-url:./image.png';
import wasmUrl from 'asset-url:./module.wasm';
import workerUrl from 'js-url:./worker.js';

loadImg(imageUrl);
WebAssembly.instantiateStreaming(fetch(wasmUrl));
new Worker(workerUrl);

When a bundler plugin sees an import with an extension or URL Scheme it recognizes ( asset-url: and js-url: in the examples above), it adds the referenced resource to the build graph, copies it to the final destination, performs optimizations appropriate to the resource type, and returns the final URL for use at runtime.

The benefits of this approach are: reusing JavaScript import syntax and ensuring that all URLs are static relative paths, which makes it easy for the build system to locate such dependencies.

However, it has an obvious drawback: such code will not work directly in browsers, because browsers don't know how to handle those custom import schemes or extensions. Of course, if you control all of your code and are relying on a bundler for development anyway, this sounds great. However, to reduce the hassle, it is becoming more and more common to use JavaScript modules directly in the browser (at least during development). A small demo may not need a bundler at all, even in production.

2. Common import syntax in browsers and bundlers

If you’re developing a reusable component, you’ll want it to function in any environment, whether it’s used directly in the browser or pre-built as part of a larger application. Most modern bundlers accept the following JavaScript module import syntax:

new URL('./relative-path', import.meta.url)


It looks like a special syntax, but it is indeed a valid JavaScript expression that can be used directly in the browser and can also be statically detected and processed by bundlers.

Using this syntax, the previous example can be rewritten as:

// regular JavaScript import
import { loadImg } from './utils.js';
loadImg(new URL('./image.png', import.meta.url));
WebAssembly.instantiateStreaming(
  fetch(new URL('./module.wasm', import.meta.url)),
  { /* … */ }
);
new Worker(new URL('./worker.js', import.meta.url));

Let's analyze how it works: new URL(...) constructor resolves the URL corresponding to the relative URL in the first parameter based on the absolute URL in the second parameter. In our case, the second argument is import.meta.url [1] , which is the URL of the current JavaScript module, so the first argument can be any path relative to it.

It has advantages and disadvantages similar to dynamic import. While it is possible to import content using import(...) , such as import (someUrl) , bundlers treat imports with static URL import ('./some-static-url.js') specially: as a way to preprocess known dependencies at compile time, chunking the code and loading it dynamically.

Likewise, you can use new URL (...) , as in new URL (relativeUrl, customAbsoluteBase) , however new URL ('...', import.meta.url) syntax explicitly tells the bundler to preprocess the dependency and bundle it with the main JavaScript asset.

3. Ambiguous relative URLs

You might be wondering why bundlers can’t detect other common syntax — for example, fetch ('./module.wasm') without new URL wrapper?

The reason is that, unlike the import keyword, any dynamic requests are relative to the document itself, not relative to the current JavaScript file being parsed. Let's say we have the following structure:

index.html:

<script src="src/main.js" type="module"></script>


src/

main.js

module.wasm

If you want to load module.wasm from main.js , your first instinct might be to use a relative path reference like fetch('./module.wasm') .

However, fetch has no knowledge of the URL of the JavaScript file it is executing; instead, it resolves the URL relative to the document. Therefore, fetch ('./module.wasm') will end up trying to load http://example.com/module.wasm instead of the expected http://example.com/src/module.wasm , causing it to fail (or, in worse luck, silently load a different resource than you expected).

By wrapping relative URLs in new URL ('...', import.meta.url) , you can avoid this problem and ensure that any provided URL is resolved relative to the current JavaScript module's URL ( import.meta.url ) before being passed to any loaders.

Simply replacing fetch ('./module.wasm') with fetch (new URL('./module.wasm', import.meta.url)) will successfully load the intended WebAssembly module while giving bundlers a reliable way to find these relative paths at build time.

4. Support in the tool chain

4.1 Packaging Tools

The following bundlers already support the new URL syntax:

• Webpack v5
• Rollup (supported via plugins: @web/rollup-plugin-import-meta-assets for generic assets and @surma/rollup-plugin-off-main- thread for Workers.)
• Parcel v2 (beta)
• Vite

5. WebAssembly

When using WebAssembly , you typically don't load Wasm modules manually, but instead import JavaScript glue code emitted by the toolchain. The following toolchain can generate the new URL(...) syntax for you:

5.1 C/C++ compiled with Emscripten

When using the Emscripten toolchain, we can ask it to output ES6 module glue code instead of normal JS code with the following option:

$ emcc input.cpp -o output.mjs
## If you don't want to use the mjs extension:
$ emcc input.cpp -o output.js -s EXPORT_ES6

When this option is used, the output glue code will use new URL (..., import.meta.url) syntax so that bundlers can automatically find the relevant Wasm files.

By adding the -pthread parameter, this syntax can also support the compilation of WebAssembly threads.

$ emcc input.cpp -o output.mjs -pthread
## If you don't want to use the mjs extension:
$ emcc input.cpp -o output.js -s EXPORT_ES6 -pthread

In this case, the generated Web Worker will be referenced in the same way and will be loaded correctly by bundlers and browsers.

5.2 Rust compiled with wasm-pack / wasm-bindgen

wasm-pack --WebAssembly The main Rust toolchain for WebAssembly, also with several output modes.

By default, it will output a JavaScript module that relies on WebAssembly ESM integration proposal. At the time of writing this post, this proposal is still experimental and the output will only work when bundled with Webpack .

Alternatively, we can ask wasm-pack to output a browser-compatible ES6 module using the -target web argument:

$ wasm-pack build --target web

The output will use the new URL(..., import.meta.url) syntax described above, and Wasm files will be automatically discovered by the bundler.

If you want to use WebAssembly threads from Rust , it's a bit more complicated. Please see the corresponding section of the guide [13] for more information.

In short, you can't use arbitrary threading APIs, but if you use Rayon [14], you can try the wasm-bingen-rayon [15] adapter, which can generate Workers that can run on the Web. The JavaScript glue used by wasm-bindgen-rayon also includes the [16] new URL (...) syntax, so Workers can also be discovered and imported by bundlers.

6. Future import methods

6.1 import.meta.resolve

One potential future improvement is a specialized import.meta.resolve(...) syntax. It will allow resolving content relative to the current module in a more direct way without the need for extra arguments.

// Current syntax new URL('...', import.meta.url)

// Future syntax await import.meta.resolve('...')

It also integrates better with import maps maps and custom resolvers, since it is processed by the same module resolution system as import syntax. This is also a more reliable signal to bundlers, since it's a static syntax that doesn't rely on runtime APIs like URLs.

import.meta.resolve has been implemented in Node.js as an experimental feature, but there are still some unresolved questions about how it should work on the Web.

6.2 Import Assertions

Import assertions are a new feature that allows importing types outside of ECMAScript modules, though only JSON types are supported for now.

foo.json

{ "answer": 42 }

main.mjs

import json from './foo.json' assert { type: 'json' };
console.log(json.answer); // 42

(Translator's note: There's also some interesting information about this less intuitive syntax choice https://github.com/tc39/proposal-import-assertions/issues/12)

They may also be used by bundlers and replace the scenarios currently supported by the new URL syntax, but the types in the import assertions need to be supported one by one. Currently only JSON is supported. CSS modules are coming soon, but other types of resource imports still need a more general solution.

For more information about this feature, see the feature explanation on v8.dev [19].

7. Summary

As you can see, there are various ways to include non- JavaScript resources on the web, but they have their own pros and cons, and none of them work in all toolchains at the same time. Some future proposal might let us import these resources with a dedicated syntax, but we're not there yet.

Until that day comes, new URL (..., import.meta.url) syntax is the most promising solution, and already works today in browsers, various bundlers, and WebAssembly toolchains.

This is the end of this article about packaging non-JavaScript static resources. For more relevant content about packaging non-JavaScript static resources, please search for previous articles on 123WORDPRESS.COM or continue to browse the related articles below. I hope everyone will support 123WORDPRESS.COM in the future!

8. References

[1]; import.meta.url: https://v8.dev/features/modules#import-meta

[2]; Dynamic import: https://v8.dev/features/dynamic-import

[3]：Code Splitting: https://web.dev/reduce-javascript-payloads-with-code-splitting/

[4]：Webpack v5: https://webpack.js.org/guides/asset-modules/#url-assets

[5]：Rollup: https://rollupjs.org/

[6]: @web/rollup-plugin-import-meta-assets: https://modern-web.dev/docs/building/rollup-plugin-import-meta-assets/

[7]: @surma/rollup-plugin-off-main-thread: https://github.com/surma/rollup-plugin-off-main-thread

[8]: Parcel v2 (beta): https://v2.parceljs.org/languages/javascript/#url-dependencies

[9]：Vite: https://vitejs.dev/guide/assets.html#new-url-url-import-meta-url

[10]：WebAssembly: https://web.dev/webassembly-threads/#c

[11]: wasm-pack: https://github.com/rustwasm/wasm-pack

[12]：WebAssembly ESM integration proposal: https://github.com/WebAssembly/esm-integration

[13]: Corresponding part: https://web.dev/webassembly-threads/#rust

[14]：Rayon: https://github.com/rayon-rs/rayon

[15]: wasm-bindgen-rayon: https://github.com/GoogleChromeLabs/wasm-bindgen-rayon

[16]: Also included: https://github.com/GoogleChromeLabs/wasm-bindgen-rayon/blob/4cd0666d2089886d6e8731de2371e7210f848c5d/demo/index.js#L26

[17]: Experimental feature: https://nodejs.org/api/esm.html#esm_import_meta_resolve_specifier_parent

[18]: There are still some unresolved issues: https://github.com/WICG/import-maps/issues/79

[19]: Functional explanation on v8.dev: https://v8.dev/features/import-assertions