JavaScript

Step 1 — Build config and packages

Show relevant package versions, using the package manager the repo uses:

Use non-zero depth — @posthog/cli and Rollup are often transitive dependencies of the build plugin or framework.

Inspect the relevant config files:

• Vite/Rollup: vite.config.*, rollup.config.*
• Webpack: webpack.config.*
• Next.js: next.config.*
• Nuxt: nuxt.config.*

Search for PostHog upload config:

For Vite/Rollup, confirm source map generation is enabled for production builds. Hidden maps are fine for upload:

Step 2 — Local artifacts

List emitted JS and map files:

Inspect with the bundled helper. This is the canonical check — it summarizes JS chunk-id markers and source map shape (mappings_length, sources_length, sources_content_length, names_length):

Resolve scripts/inspect_sourcemaps.py relative to the skill directory. It accepts files, directories, and globs.

If the helper isn’t accessible (CI runner without Python, etc.), a jq one-liner gives a coarse summary of one source map:

For a quick sanity grep on whether chunk IDs landed in the JS:

Expected local artifact shape:

• JS has a chunkId marker and _posthogChunkIds registration.
• JS has sourceMappingURL only when maps are intentionally public. Hidden source maps may omit it.
• Map has non-empty mappings.
• Map has non-empty sources.
• sourcesContent is present when source context should appear in PostHog.

Smoking gun — empty mappings

If inspect_sourcemaps.py reports "empty_mappings": true on a .map file (and sources_length: 0, names_length: 0), the bundler emitted a structurally valid but data-less source map. This is the single strongest signal that the bug is upstream of PostHog upload — the CLI faithfully uploads whatever is on disk.

For Vite/Rollup this can happen when config.build.sourcemap was unset and a Vite-internal plugin (vite:css-post, vite:build-import-analysis) skipped sourcemap generation during renderChunk because it reads config.build.sourcemap directly rather than the Rollup output option. This is reproducible in Vite 7/Rollup builds with CSS/IIFE/import-analysis paths. Check the build log for:

Workaround: set build.sourcemap: 'hidden' (or true) in vite.config.*. Hidden maps still get uploaded but are not advertised via sourceMappingURL in the served JS.

For other bundlers, the same class of bug shows up when a transform/plugin returns a sourcemap object with empty fields instead of null. Inspect the local artifact first, before suspecting upload or processing.

Inspecting an extracted symbol set

After Step 3 extracts a JS symbol set with posthog-cli symbol-sets extract, run the helper on the resulting directory:

The helper operates on plain .js / .map files. If you point it at a raw .bin container by mistake, it prints a redirect error pointing back at posthog-cli symbol-sets extract.

CLI and plugin logging

PostHog build plugins call posthog-cli sourcemap process. For direct CLI checks, use environment variables:

For plugin-based builds, set logLevel: "debug" inside the same posthog({ ... }) options object that holds personalApiKey/projectId in vite.config.* / webpack.config.* / framework wrapper.

Useful log facts:

• which files were processed.
• which chunk IDs were injected.
• whether uploads were skipped because content already matched.
• whether changed content was skipped because forced overwrite was not enabled.
• whether a source map was missing, empty, or unparsable.

JS-specific fixes

In addition to the platform-neutral fixes in SKILL.md Step 5:

• Enable production source maps in the bundler (build.sourcemap: true or 'hidden' for Vite/Rollup).
• Move the PostHog plugin later in the plugin order so it sees final emitted JS chunks.
• Remove post-build minification, CDN rewrites, asset transforms, or compression steps that change JS after upload.

JS-specific failure rows

Add these to the cross-platform matrix in SKILL.md: