elastic / elastic/docs-builder

Publish usable source maps for production documentation bundles

Open
#3,689 0 comments 0 reactions 0 assignees View on GitHub
enhancement needs triage observability
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Problem

Lighthouse reports missing or unreachable source maps for large first-party JavaScript bundles, including:

- `docs/_static/main.js` → `main.js.map` returns 404
- `NavigationSearchComponent.*.js` maps return 404
- VersionDropdown, FullPageSearch, Diagnostics, AskAi, and other generated chunk maps return 404

Parcel emits source map references, but `src/Elastic.Documentation.Site/Elastic.Documentation.Site.csproj` embeds `*.js.map` and `*.css.map` only when `$(Configuration) == Debug`. Release JavaScript therefore advertises maps that are not deployed.

This does not directly reduce runtime work, but it prevents Lighthouse and production debugging tooling from attributing large tasks and forced reflows to source modules.

## Relevant code

- `src/Elastic.Documentation.Site/Elastic.Documentation.Site.csproj` (`EmbedGeneratedAssets`)
- `src/tooling/docs-builder/Http/StaticWebHost.cs` (already maps `.map` to `application/json`)
- Parcel production build configuration under `src/Elastic.Documentation.Site/`

## Proposed implementation

Choose and implement one consistent production policy:

1. Preferred: publish generated `.js.map`/`.css.map` resources in Release output and verify hashed maps are copied with their bundles; or
2. If public source maps are intentionally prohibited, configure the Release build to omit `sourceMappingURL` references so bundles do not advertise guaranteed 404s, and document the loss of production attribution.

Before publishing maps, confirm the maps contain no embedded secrets or generated private content. Source code disclosure should be an explicit accepted trade-off, not accidental.

## Acceptance criteria

- Release bundles no longer reference source maps that return 404.
- If maps are published, every generated map is deployed with the corresponding hashed asset and served as JSON with appropriate caching.
- Old hashed map cleanup remains aligned with old hashed JS/CSS cleanup.
- A Release build test or artifact assertion covers the selected policy.
- Lighthouse no longer reports missing maps for docs-builder-owned bundles.
- The external `https://www.elastic.co/elastic-nav.js` map remains explicitly out of scope.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.