docs(onboarding): add a performance tuning step for Shopify

[posthog]

Problem

• A paying agency running nine Shopify stores asked how to install PostHog with the lowest page-weight cost, and support had nothing to link.
• The in-app Shopify onboarding emits two steps: open the theme editor, paste the snippet. It never mentions a single option that reduces client work.
• No page under docs/onboarding/ mentions autocapture, disable_session_recording, or any other overhead-reducing option, in any SDK.
• Nothing is broken. The shared snippet already loads array.js async from the assets host and guards double init (c21e3775), so the base install is non-blocking. A store owner cannot tell that from the docs.

Changes

• The Shopify onboarding gains a third step, badged optional, that names the posthog.init options which cut per-page work, with a one-line note on what each one gives up.
• The step appears in both the product analytics and web analytics Shopify flows, exported as getShopifyPerformanceStep so neither flow selects it by title.
• Follow-up prose says which options to leave out, and links posthog.capture() as the replacement when autocapture is off.

Option	What it saves	What it costs
disable_session_recording	recorder.js download	no session replay
disable_surveys	surveys.js download	no surveys
advanced_disable_flags	one request per page load	no flags, experiments, or surveys
autocapture: false	click and form listeners, event volume	manual capture() calls
capture_heatmaps: false	heatmap collection	no heatmaps
capture_performance: false	web vitals and network timing	no web vitals

The public docs page and its stale pixel snippet are fixed in PostHog/posthog.com#20013, since that content lives in the other repo.

How did you test this code?

Rendered the Shopify flow in Storybook through a throwaway story wrapped in OnboardingDocsContentWrapper, then removed the story before committing. Confirmed the new step renders in order, <ph_project_token> and <ph_client_api_host> substitute, the markdown links resolve, and the block does not clip at a 520px scene width.

Rendered step 3, at 900px

3. Tune for performance   optional

The snippet loads PostHog asynchronously from a separate assets host, so it does not
block your store from rendering. To reduce the work PostHog does on each page, add
these options to the posthog.init call you just pasted. Each option removes a feature,
so set only the ones you can do without.

posthog.init('<ph_project_token>', {
    api_host: '<ph_client_api_host>',
    defaults: '2026-05-30',
    autocapture: false, // no click or form capture
    capture_heatmaps: false, // no heatmap data
    disable_session_recording: true, // no session replay script
    disable_surveys: true, // no surveys script
    capture_performance: false, // no web vitals or network timing
    advanced_disable_flags: true, // no /flags request
})

No tests added. docs/onboarding has no test suite, and a semgrep rule already forbids selecting a step by its display title, so a copy assertion is exactly what this area avoids. Verification here is the render.

Every option name was checked against the published JavaScript config reference rather than recalled. oxfmt and oxlint pass on both changed files. hogli is not installed in this sandbox, so ci:preflight did not run.

Automatic notifications

• Publish to changelog?

Docs update

Covered by the companion PR on the docs site.

🤖 Agent context

Autonomy: Fully autonomous

• Authored by Claude Opus 5 in PostHog Desktop, from an inbox report.
• Skills invoked: /writing-user-facing-copy, writing-simplified-technical-english.
• Duplicate check: gh pr list --state open --search shopify returns #96580, which adds cart and checkout capture steps to the same file. It does not touch performance guidance, so this PR is still needed. Expect a small conflict in getShopifySteps if both land.
• Considered putting the tuning advice inside getShopifyInstallSteps so web analytics inherited it implicitly. A separate exported step reads better in the step list and keeps each flow's composition explicit.
• Considered a generic tuning snippet under _snippets/ for every web SDK. Held off: the option set that suits a store is not the set that suits an app, and one Shopify page answers the request.
• Public artifact: the work started from a customer request relayed in the report. No customer name, store, project, or figure appears in the diff or this description. The option list derives from the public config reference.
• The report also stated that the docs page's pixel example makes stores load the library twice on checkout. That could not be confirmed: Shopify runs custom pixels in a sandboxed frame, and the pasted snippet's own __SV check makes a repeat call a no-op. The example is still wrong for a verifiable reason, which the companion PR states.

---

Created with PostHog Desktop from this inbox report.

[trunk-io]

Merging to master in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[github-actions]

🤖 CI report

✅ Trunk lane — non-backend lane

This PR is assigned to the non-backend lane. It does not run backend Python tests and may merge in parallel with PRs in other lanes.

⚠️ Bundle size — 🔺 +15 B (+0.0%)

Uncompressed size of every built .js bundle, compared against the base branch.

Total: 68.68 MiB · 🔺 +15 B (+0.0%)

No file changed by more than 1000 B.

_{Posted automatically by build-bundle-size-report · uncompressed bytes from dist-report}

✅ Eager graph — within budget

How much code each root ships on the eager path — downloaded and parsed before the surface is interactive. Measured from the esbuild output chunks (post-tree-shake, static imports only); lazy import() / React.lazy chunks are not counted.

Root	Eager (shipped)	Δ vs base	Budget
entry (logged-out pages, app bootstrap) src/index.tsx	1.50 MiB · 22 files	no change	███░░░░░░░ 33.2% of 4.51 MiB
logged-out boot: index + App + bootApp (preloaded by every page, including /login) src/index.tsx + src/scenes/App.tsx + src/scenes/bootApp.ts	5.24 MiB · 668 files	no change	█████████░ 93.1% of 5.63 MiB
authenticated shell (every logged-in page) src/scenes/AuthenticatedShell.tsx	7.66 MiB · 2,677 files	no change	█████████░ 87.3% of 8.77 MiB

🟢 node_modules/monaco-editor/ stays out of src/index.tsx
🟢 src/lib/components/ActivityLog/describers stays out of src/index.tsx
🟢 [object Object] stays out of src/index.tsx
🟢 [object Object] stays out of src/index.tsx
🟢 node_modules/monaco-editor/ stays out of src/index.tsx + src/scenes/App.tsx + src/scenes/bootApp.ts
🟢 src/layout/navigation-3000/navigationLogic.tsx stays out of src/index.tsx + src/scenes/App.tsx + src/scenes/bootApp.ts
🟢 src/scenes/dashboard/dashboardLogic.tsx stays out of src/index.tsx + src/scenes/App.tsx + src/scenes/bootApp.ts
🟢 node_modules/monaco-editor/ stays out of src/scenes/AuthenticatedShell.tsx
🟢 src/lib/components/ActivityLog/describers stays out of src/scenes/AuthenticatedShell.tsx
🟢 [object Object] stays out of src/scenes/AuthenticatedShell.tsx
🟢 src/scenes/session-recordings/player/sessionRecordingPlayerLogic.ts stays out of src/scenes/AuthenticatedShell.tsx
🟢 [object Object] stays out of src/scenes/AuthenticatedShell.tsx
🟢 [object Object] stays out of src/scenes/AuthenticatedShell.tsx

Largest files eagerly shipped from src/index.tsx

Size	File
126.8 KiB	../node_modules/.pnpm/react-dom@18.3.1_react@18.3.1/node_modules/react-dom/cjs/react-dom.production.min.js
24.6 KiB	../node_modules/.pnpm/buffer@6.0.3/node_modules/buffer/index.js
6.3 KiB	../node_modules/.pnpm/react@18.3.1/node_modules/react/cjs/react.production.min.js
4.5 KiB	../node_modules/.pnpm/@jspm+core@2.1.0/node_modules/@jspm/core/nodelibs/browser/process.js
3.9 KiB	../node_modules/.pnpm/scheduler@0.23.2/node_modules/scheduler/cjs/scheduler.production.min.js
1.4 KiB	../node_modules/.pnpm/base64-js@1.5.1/node_modules/base64-js/index.js
1.3 KiB	src/RootErrorBoundary.tsx
1.0 KiB	src/index.tsx
912 B	../node_modules/.pnpm/ieee754@1.2.1/node_modules/ieee754/index.js
854 B	src/scenes/ChunkLoadErrorBoundary.tsx

Largest files eagerly shipped from src/index.tsx + src/scenes/App.tsx + src/scenes/bootApp.ts

Size	File
281.8 KiB	../node_modules/.pnpm/posthog-js@1.428.6_@types+react@18.3.27_react@18.3.1/node_modules/posthog-js/dist/module.mjs
267.7 KiB	../node_modules/.pnpm/@posthog+icons@0.38.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js
255.4 KiB	src/taxonomy/core-filter-definitions-by-group.json
126.8 KiB	../node_modules/.pnpm/react-dom@18.3.1_react@18.3.1/node_modules/react-dom/cjs/react-dom.production.min.js
104.2 KiB	src/lib/api.ts
79.0 KiB	src/products.tsx
68.8 KiB	src/lib/lemon-ui/icons/icons.tsx
62.8 KiB	src/lib/utils/eventUsageLogic.ts
38.8 KiB	../node_modules/.pnpm/@dnd-kit+core@6.0.8_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@dnd-kit/core/dist/core.esm.js
33.9 KiB	../node_modules/.pnpm/kea@4.0.0-pre.6_patch_hash=139b8d1f1304f9d9da452a9a1244c94ea679dbcb85687d8999563146879fb6f5_react@18.3.1/node_modules/kea/lib/index.cjs.js

Largest files eagerly shipped from src/scenes/AuthenticatedShell.tsx

Size	File
281.8 KiB	../node_modules/.pnpm/posthog-js@1.428.6_@types+react@18.3.27_react@18.3.1/node_modules/posthog-js/dist/module.mjs
267.7 KiB	../node_modules/.pnpm/@posthog+icons@0.38.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js
255.4 KiB	src/taxonomy/core-filter-definitions-by-group.json
153.8 KiB	../node_modules/.pnpm/re2js@0.4.1/node_modules/re2js/build/index.esm.js
126.8 KiB	../node_modules/.pnpm/react-dom@18.3.1_react@18.3.1/node_modules/react-dom/cjs/react-dom.production.min.js
104.2 KiB	src/lib/api.ts
95.8 KiB	../packages/quill/packages/quill/dist/index.js
93.3 KiB	../node_modules/.pnpm/prosemirror-view@1.40.1/node_modules/prosemirror-view/dist/index.js
90.6 KiB	../node_modules/.pnpm/@tiptap+core@3.20.6_@tiptap+pm@3.20.6/node_modules/@tiptap/core/dist/index.js
79.0 KiB	src/products.tsx

_{Posted automatically by check-eager-graph · sizes are eager output bytes (shipped, post-tree-shake) from the esbuild metafile · part of #32479}

✅ Toolbar bundle — eager 2.29 MiB within budget

What the toolbar ships to customer pages, measured from the esbuild output (minified, post-tree-shake). The eager set is the entry plus everything statically imported from it — fetched before any feature runs; deferred chunks load lazily. The eager guardrail is 5.72 MiB. Each output file must also stay below 10 MB, where CloudFront stops compressing it. The module boundary is enforced separately by check-toolbar-graph.

Metric	Size	Δ vs base	Budget
Eager (shipped) entry + static imports	2.29 MiB · 18 files	no change	████░░░░░░ 40.0% of 5.72 MiB
Deferred (lazy)	2.11 MiB · 45 files	no change	n/a — loads on demand
Loader dist/toolbar.js	1.1 KiB	no change	█░░░░░░░░░ 5.8% of 19.5 KiB

Largest eagerly-shipped chunks

Size	File
756.4 KiB	dist/toolbar/toolbar-app-LA4JX7FS.css
608.8 KiB	dist/toolbar/chunk-chunk-P3PF5T4P.js
484.7 KiB	dist/toolbar/chunk-chunk-RPV3NYRJ.js
136.6 KiB	dist/toolbar/chunk-chunk-6MQWLXON.js
131.8 KiB	dist/toolbar/chunk-chunk-FDH2IBXT.js
72.2 KiB	dist/toolbar/toolbar-app-VLT4VAGU.js
69.0 KiB	dist/toolbar/chunk-chunk-TSAL54PB.js
35.6 KiB	dist/toolbar/chunk-chunk-DTB5C7AH.js
21.0 KiB	dist/toolbar/chunk-chunk-35CVENAR.js
6.8 KiB	dist/toolbar/chunk-chunk-DV7IWQNF.js

_{Posted automatically by check-toolbar-size · sizes are toolbar output bytes (shipped, post-tree-shake) from the esbuild metafile}

✅ Dist folder size — 🔺 +9.0 KiB (+0.0%)

Total size of the built frontend/dist folder (all assets), compared against the base branch.

Total: 1458.38 MiB · 🔺 +9.0 KiB (+0.0%)

ℹ️ Docs preview — preview build triggered

Docs from this PR will be published at posthog.com.

Project	Preview	Updated (UTC)
posthog.com	Open preview	Sep 8, 2026, 6:38 PM

The preview should be ready in about 10 minutes. Open the preview at /handbook/engineering/.

[scheduled-actions-posthog]

This PR hasn't seen activity in a week! Should it be merged, closed, or further worked on? If you want to keep it open, please remove the stale label – otherwise this will be closed in another week. If you want to permanently keep it open, use the waiting label.