In a web build, what does `import thumbUrl from './specimen-thumb.png'` give your code, and when does the bundler inline the image instead?
answer
- a generated module stands in
- default export is a string
- emitted copy under a new name
- a size threshold decides
- data URL inside the importer
basics
~20 sThe import becomes a small generated module whose default export is a URL string pointing at a copy of the image the build emits. Files below a size threshold are often inlined instead, as a base64 data URL inside the importing file.
solid answer
~40 sA bundler's module graph is made of JavaScript, so it turns `specimen-thumb.png` into a tiny generated module whose default export is the URL the image will be served from. During development that URL points at the source file; in the production build the bundler copies the file into its output, usually under a content-hashed name, and your code receives that final URL. Files under a size threshold, typically a few kilobytes, can be inlined instead: the export becomes a `data:` URL that carries the bytes in base64. Inlining saves a request, but the bytes grow by about a third, ride inside the importing JavaScript or CSS file, are downloaded again whenever that file changes, and get no cache entry of their own. A `url()` in an imported stylesheet goes through the same emit-or-inline decision.
code
javascript · 9 linesimport thumbUrl from './specimen-thumb.png' // 48 KB photo
import pinUrl from './icons/map-pin.png' // 600-byte icon
// development: a dev-server URL that maps to the source file
// production: thumbUrl === '/assets/specimen-thumb.3f9a1c2e.png'
// production: pinUrl === 'data:image/png;base64,iVBORw0KGgo...'
document.querySelector('#thumb').src = thumbUrl
document.querySelector('#pin').src = pinUrlgo deeper
Remember that an image import gives you a URL string, not the image. In production that URL points at a copy the build emitted, not at your source file.
Explain the generated module, the emit-or-inline decision by size threshold, and that url() in imported CSS follows the same rule. Know the base64 overhead.
Weigh inlining by caching, not just request count: an inlined asset is re-sent with every change to its importer. Spot production-only bugs caused by code that bypasses the import.
Treat the inline threshold as a shared default with caching and size consequences across apps, and decide when teams may override it per file rather than globally.
## What the import actually is A bundler's **module graph** is built from JavaScript modules, so every node it ships must end up as JavaScript. When it meets `import thumbUrl from './specimen-thumb.png'`, it does not put a picture into your code. It replaces the image with a small **generated module** whose only job is to export a value. For images, fonts, video and other binary files, that value is a **URL string**: ```js // what the generated module amounts to export default '/assets/specimen-thumb.3f9a1c2e.png' ``` Your code then does whatever it would do with any URL: assigns it to `img.src`, passes it to a component, or builds a CSS background from it. The browser downloads the file the normal way, as a separate request. Key properties of this model: - The import is **resolved at build time**, so a missing or misspelt file fails the build instead of producing a broken image in production. - The URL is **whatever the build decides**: during development it usually points at the source file, and in the production build it points at the copy the build wrote. - `url()` references inside an imported stylesheet are treated the same way, so a `background: url('./fern.png')` is emitted or inlined and rewritten exactly like a JavaScript import. ## Emitting a file For anything above the inline threshold, the bundler **emits** the file: it copies it into the output folder, usually with a content hash in the name, and makes the generated module export the URL of that copy. Two consequences follow: 1. The deployed site serves the file from the build output, not from your source tree, so only files the graph reached are there. 2. The file gets its own HTTP cache entry, independent of the JavaScript that references it. Why a hash in the name helps caching is a separate topic; here it only matters that the URL is computed by the build. A variable font referenced from an `@font-face` rule is normally emitted this way: it is far above any inline threshold, and a font inlined into a stylesheet would make the stylesheet itself heavy. How the browser then loads and swaps fonts is its own subject. ## Inlining below a threshold Small files, such as the museum's 600-byte map-pin icon, can instead be **inlined**: the generated module exports a `data:` URL that contains the file's bytes, typically base64-encoded. Build tools pick their own default threshold, usually a few kilobytes, and let you change it or force the choice per file. | | Emitted file | Inlined data URL | |---|---|---| | What the import exports | URL of a separate file | `data:image/png;base64,...` string | | Network requests | One more request for the file | None for the asset itself | | Size on the wire | Original bytes | About one third larger before compression | | Caching | Its own cache entry | Cached only as part of the importing file | | When the importing code changes | Asset stays cached | Asset bytes are downloaded again | Inlining is a trade, not a free win: - It **saves a request**, which matters most for tiny files and less on connections that multiplex many requests. - It **moves bytes into the importer**, making that JavaScript or CSS file larger and slower to arrive before it can run or apply. - It **ties the asset's caching to the importer**: every release that touches the importing chunk re-sends the icon, even if the icon never changed. ## Other output forms of the same idea The generated module does not have to export a URL. The same mechanism can expose a file's **raw text** as a string, which is how an SVG sprite's markup or a shader source can be inserted into the page. Tools usually make that an explicit opt-in per import, because "give me the URL" and "give me the contents" are different contracts for the same file. JSON and WebAssembly files have their own module forms, covered separately. ## Why this breaks only in production The usual production-only failures come from code that bypasses the import: - A **hard-coded path string** to a source image works when a dev server serves the source tree, but the build never saw it, so no file is emitted. - Code that **assumes a file name** (for example by string-concatenating `specimen-thumb.png`) misses the name the build actually emitted. - Code that expects an `http` URL and receives a `data:` URL, for example to derive a file name from it, breaks only for files small enough to be inlined. The rule that avoids all three: let the import hand you the URL, and treat that URL as opaque.
- Why not inline every image to save requests?Base64 makes the bytes about a third larger, and they move into the importing JavaScript or CSS file, which grows and arrives later. The asset also loses its own cache entry: whenever the importing chunk changes, the inlined image is downloaded again even though it did not change. Inlining pays off only for small, rarely changing files.
- How would you get the text of an SVG sprite instead of its URL?Ask the build for the file's contents rather than its URL. The same generated-module mechanism then exports a string holding the markup, which you can insert into the document. Tools expose this as an explicit opt-in per import, because the URL form and the text form are different contracts for the same file.
- What does the build do with `url('./fern.png')` inside an imported stylesheet?It treats the reference as a dependency of the stylesheet: it resolves the file, emits or inlines it under the same threshold rule as a JavaScript import, and rewrites the `url()` so it points at the result from wherever the emitted stylesheet ends up.
- Importing an image always puts the image bytes into the JavaScript bundle.
- The imported variable holds the source path exactly as it was written.
- Inlining is always faster because it removes a network request.
- A data URL gets its own cache entry, like a separate file.
- Only JavaScript files can take part in the module graph.