When a web build emits source maps, how do inline, external and hidden maps differ in what reaches the browser, and when does each fit?
answer
- where the map's bytes live
- a data URL inside the bundle
- a separate file the comment names
- the same file with no comment
- unlinked is not the same as private
basics
~20 sAn inline map is a data URL inside the shipped file, so every user downloads it. An external map is a separate file the comment names. A hidden map is that file emitted without the comment, so nothing points at it.
solid answer
~50 sAn **inline** map is the whole map encoded as a `data:` URL in the `sourceMappingURL` comment: with `sourcesContent` it is fully self-contained, but every copy of the file carries it, so it suits development or a single file you hand around, not production. An **external** map is a separate `.map` file that the comment (or a `SourceMap` header) names; ordinary page loads do not need it, and anyone who follows the link can read it, so it fits when the maps may be public or the URL is restricted. A **hidden** map is the external file with the comment left out: it exists, but nothing in the shipped code points to it, which suits maps meant only for internal tooling. Hidden is not private by itself: if the deploy copies `app.3f9a.js.map` next to the bundle, anyone who guesses the name can fetch it.
go deeper
Recall the three forms by where the map lives: inside the file, in a separate linked file, or in a separate unlinked file.
Explain what each form makes every visitor download and who can reach the map, and why inline maps belong to development builds.
Show that hidden is about the link, not access: check what the deploy actually uploads, and use a restricted location or a selective header when staff need maps in the browser.
Turn the choice into a policy per environment: which audience may read maps, where they are stored, and how the build and deploy steps enforce it for every app.
## Three forms of the same map A build that emits source maps writes the same JSON in one of three places, and the choice decides **who receives it and how**. The map's content is identical in all three; what differs is where its bytes live and whether the shipped file points at them. | Form | Where the map lives | Link in the shipped file | What each visitor downloads | Typical use | |---|---|---|---|---| | **Inline** | Inside the generated file, as a `data:` URL | The `sourceMappingURL` comment carries the map itself | The full map, every time the file is fetched | Development, a single self-contained file | | **External** | A separate `.map` file | The comment (or a `SourceMap` header) names its URL | Only the bundle; the map is fetched by tools on demand | Maps that may be public, or are served from a restricted URL | | **Hidden** | A separate `.map` file | None | Only the bundle; nothing tells tools the map exists | Maps reserved for internal tooling | ## Inline maps ECMA-426 allows the map URL to be a `data:` URL, and notes that a data URL together with `sourcesContent` gives a **completely self-contained** map. That is convenient: - nothing else has to be served or kept in step with the file; - a single file can be passed around and still debugged; - the map can never drift from the code it describes, because they are the same file. The cost is size. A map with embedded source text is often **larger than the code it describes**, and an inline map is downloaded by every visitor on every uncached fetch, whether or not anyone opens developer tools. It also publishes the full original source to everyone. That is why inline maps belong to development builds. ## External maps An external map is written to its own file, usually named after the bundle with `.map` appended, and the bundle ends with `//# sourceMappingURL=app.3f9a.js.map`. Running the page never needs the map, so an ordinary page load has no reason to request it; developer tools and error tooling fetch it when they want to translate positions. The link is public, though. Anyone who reads the bundle can follow the comment and download the map, and with it whatever the map contains. External maps are the right choice when: 1. publishing the maps is acceptable, for example for an open-source app; or 2. the URL in the comment, or in a `SourceMap` header the server adds, points to a location only staff can reach, so a public visitor gets a refusal while an authorised developer gets the map. ## Hidden maps A hidden map is an external map **emitted without the comment**. The build still writes the `.map` file; the shipped bundle simply never mentions it. Developer tools therefore load nothing, unless someone attaches the map by hand or a server adds a `SourceMap` header for selected requests. This fits maps meant only for internal tooling: the build produces them, and a separate step hands them to whatever translates error positions (how that pipeline uploads them is a separate topic). Two facts are often missed: - **Hidden is about the link, not the file.** If the deploy copies every build output, maps included, to the public server, `app.3f9a.js.map` sits next to `app.3f9a.js` at a guessable URL, and anyone can download it. - **A hidden map is still generated.** The build pays the full cost of producing it; the only difference from an external map is the missing comment. ## Choosing - During development, accuracy and convenience matter and nobody outside the team sees the build: inline maps, or external ones served by the dev server, are both fine. - In production, decide first **who may read the maps**. If everyone may, use external maps. If only staff may, either serve external maps from a restricted location, or emit hidden maps and keep them out of the public deploy entirely. - Whatever the form, make sure the maps come from the **same build** as the files they describe; a map from another build points at the wrong positions. ## Misconceptions to avoid - "Inline maps are free because no extra request is made": the bytes moved into every download instead. - "Hidden maps are never generated": they are, and they are as complete as external ones. - "Removing the comment makes the maps secret": only keeping the files off the public server does that.
- Can a hidden map still be loaded by developer tools for a production page?Yes, in two ways. A developer can attach the map file to the script by hand in tools that support it, or the server can send a `SourceMap` response header for selected requests, such as those from the internal network. Nothing in the shipped file changes in either case.
- Why can an inline map be bigger than the code it describes?It usually carries `sourcesContent`, the full original text with comments and whitespace that minification removed, plus the `mappings` string, and all of it is then typically Base64-encoded into a `data:` URL, which adds about a third again. Every visitor downloads that with the file.
- What goes wrong if production serves maps from a different build than the bundles?The positions no longer match: the map describes a file with different code at different columns, so tools show the wrong original lines or none at all. Maps and bundles must be produced and deployed together, which content-hashed names make easier to keep straight.
- An inline map costs nothing because it saves a separate request.
- A hidden map is never generated, only referenced differently.
- Removing the sourceMappingURL comment makes the maps private.
- External maps are downloaded by every visitor along with the bundle.
- An inline map stores only line numbers, so it is smaller than an external one.