docs(error-tracking): add safe Angular sourcemap build flow

[hpouillot]

Executive summary

Angular creates ngsw.json during ng build. The previous guide then told users to run posthog-cli sourcemap inject, which changed JavaScript after Angular recorded its SHA-1 hashes. Angular's service worker rejects that application version and can leave existing users on an old cached release.

This change documents the coordinated fix from PostHog/posthog-js#4644 and PostHog/posthog#85637:

• Install @posthog/esbuild-plugin with @angular-builders/custom-esbuild.
• Add PostHog's runtime registration before esbuild computes content-hashed filenames.
• Let Angular generate ngsw.json from the final JavaScript.
• Run only the non-mutating posthog-cli sourcemap upload command after the build.
• Keep official ngsw-config regeneration as the fallback when a project cannot replace its builder.

Fixes the documentation part of PostHog/posthog#86046.

Verification

• Ran Prettier on the changed MDX file.
• Ran the repository MDX spacing fixer.
• git diff --check passes.
• Tested the documented setup against Angular 22.1.3 with the PWA service worker. Every JavaScript SHA-1 in ngsw.json matched, source-map IDs matched content-hashed filenames, and repeated builds were byte-identical.
• Started the local Gatsby development server twice. The full site did not become ready within the available timeout. The first run exposed the existing local Sharp installation issue; rebuilding Sharp fixed that issue. The second run completed schema generation without an MDX error but did not finish the full development bundle before timeout.

No navigation or component files changed.

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Aug 25, 2026 03:01PM

[github-actions]

Vale prose linter → found 0 errors, 2 warnings, 0 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/error-tracking/upload-source-maps/angular.mdx — 0 errors, 2 warnings, 0 suggestions

Line	Severity	Message	Rule
27:21	warning	'esbuild' is a possible misspelling.	PostHogBase.Spelling
89:49	warning	'esbuild' is a possible misspelling.	PostHogBase.Spelling

[github-actions]

Bundle report

Total JS (gzip)

8.09 MiB (-0.1 KiB / -0.0%)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint	Eager size	Budget	Modules
✅ app	16.87 MiB (-0.4 KiB / -0.0%)	report-only	2032

Largest modules in the app closure

Module	Size
./src/data/mcp-tools.json	1038.9 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css	757.5 KiB
./src/components/Stickers/Stickers.tsx	696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js	481.4 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules	395.1 KiB
./src/hooks/useCustomers.tsx + 55 modules	369.8 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js	354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules	351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 126 modules	301.7 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js	281.9 KiB
./src/components/SearchUI/index.tsx + 87 modules	273.0 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/magnifying-glass.mjs	254.7 KiB
./node_modules/.pnpm/framer-motion@10.18.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/dom/motion.mjs + 109 modules	253.9 KiB
./node_modules/.pnpm/d3@7.9.0/node_modules/d3/src/index.js + 208 modules	247.4 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules	240.1 KiB

---

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).