Skip to content

Publish usable source maps for production documentation bundles - #3693

Open
reakaleek wants to merge 5 commits into
mainfrom
special-washer
Open

reakaleek wants to merge 5 commits into
mainfrom
special-washer

Conversation

@reakaleek

@reakaleek reakaleek commented Jul 22, 2026 •

Copy link
Copy Markdown
Member

Release builds now ship the Parcel source maps that the bundles already reference. Production no longer 404s those .map files.

Affects: Site UI

Prompt summary: Publish usable source maps with the production documentation bundles. Confirm that old hashed maps cannot pile up in the AOT binary.

Why

Release bundles already contain sourceMappingURL comments. The Site project only embedded .js.map and .css.map in Debug, so Lighthouse and production debuggers hit 404s (#3689). Parcel does not empty distDir. Old hashed maps used to accumulate and bloat the binary, which is why maps were Debug-only.

What

Production source maps

EmbedGeneratedAssets includes *.js.map and *.css.map in every configuration. Static serving already maps .map to JSON.

Hashed asset cleanup

Cleanup no longer waits for IsPublishing. NpmRunBuild deletes hashed JS, CSS, and maps immediately before Parcel runs. Incremental builds that skip NpmRunBuild keep the current chunks.

Verify

dotnet test tests/Elastic.Markdown.Tests/ --filter FullyQualifiedName~EmbeddedStaticAssetTests
# EmbedGeneratedAssets_includes_source_maps_unconditionally
# NpmRunBuild_deletes_hashed_source_maps_before_parcel
# Site_assembly_embeds_js_and_css_source_maps

Out of scope: The external https://www.elastic.co/elastic-nav.js map.

Closes #3689

Release bundles already advertise sourceMappingURL, but maps were only
embedded in Debug, so production tooling hit 404s (#3689).

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@Mpdreamz

Copy link
Copy Markdown
Member

We did this because old maps could acrue and we're being checked in. At some point our binary size started ballooning.

Are we sure parcel cleans up old versions properly now?

@reakaleek

Copy link
Copy Markdown
Member Author

We did this because old maps could acrue and we're being checked in. At some point our binary size started ballooning.

Are we sure parcel cleans up old versions properly now?

Will check

reakaleek and others added 2 commits September 21, 2026 11:09
Parcel does not empty distDir. Cleanup now runs inside NpmRunBuild so stale
hashed maps cannot accumulate into the embedded AOT binary.

Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@reakaleek

Copy link
Copy Markdown
Member Author

We did this because old maps could acrue and we're being checked in. At some point our binary size started ballooning.

Are we sure parcel cleans up old versions properly now?

Parcel does not empty distDir. A dirty local _static still shows that: 13 copies of VersionDropdown.js.map, ~40MB of maps vs ~23MB for one clean Parcel generation. Maps are gitignored now, so they are not checked in. The ballooning was from embedding whatever sat in _static.

CleanOldHashedAssets already deleted hashed maps, but only when IsPublishing was true, and as BeforeTargets of a skippable NpmRunBuild. Fixed in 6f9593e: the delete now lives inside NpmRunBuild, so it runs only when Parcel actually rebuilds. A planted VersionDropdown.deadbeef.js.map is gone after that rebuild.

Co-Authored-By: Cursor Grok 4.6 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions

Copy link
Copy Markdown
Contributor

Docs preview (local build)

Handbook preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/3693/

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE: no actionable issues found.


What is this? | From workflow: PR Review

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

Main replaced Parcel with Vite and already deletes stale hashed outputs
inside NpmRunBuild, so the conflicting cleanup block in the Site csproj
is taken from main. The branch's remaining change, embedding source maps
in every configuration, is re-applied to main's EmbedGeneratedAssets
globs.

EmbeddedStaticAssetTests is ported to TUnit and to the Vite layout: it
now checks main's cleanup and the unconditional map embeds, and only
asserts JS maps in the assembly because Vite emits no CSS maps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment on lines +33 to +35
var csproj = File.ReadAllText(SiteCsprojPath());
csproj.Should().Contain("""Include="_static/main-*" """);
csproj.Should().NotContain("CleanOldHashedAssets");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Severity: P3 (Low)

This cleanup test passes even if the Delete task is removed or cleanup is moved outside NpmRunBuild: it only checks that a glob appears somewhere in the project and that one target name is absent. It therefore does not protect the stale-map cleanup or incremental-build safety that this test claims to cover. Add coverage that verifies stale bundles and maps are deleted when the target runs and current outputs survive when it is skipped.

Generated by Libra. React with 👍 or 👎 to give feedback on this comment.

This branch was successfully deployed

2 active deployments
docs-preview — ecac9330 Deployed Nov 4, 2026 by github-actions[bot]
assembler-preview — ecac9330 Deployed Nov 4, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Publish usable source maps for production documentation bundles

2 participants