docs: add Shopify performance guidance and fix the pixel snippet

[posthog]

Changes

Why: A paying agency running nine Shopify stores asked how to install PostHog with the lowest page-weight cost. This page had no performance section, and a search of the docs for Shopify performance guidance returned only blog posts, so support had nothing to send them.

• New Reducing the impact on page speed section, under the theme install steps. It states that the snippet does not block rendering, then names the posthog.init options that cut per-page work and what each one gives up.
• The custom web pixel example no longer pastes its own copy of the snippet. The page now renders the shared integrate/snippet.mdx include, and the example shows only the analytics.subscribe body.
• Instructions now say to put the snippet at the pixel's top level, above any subscribe call, rather than inside a callback that re-runs per event.

The pasted copy had drifted badly. It loaded array.js from the ingestion host instead of -assets.i.posthog.com, and it stubbed a method list from several releases back, so a reader who copied it got a slower load and missing methods such as captureException and setPersonProperties. Using the include means it cannot drift again.

Option documented	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 matching in-app onboarding step is added in PostHog/posthog#96878.

Every option name was checked against contents/docs/libraries/js/config.mdx rather than recalled. prettier --check passes on the changed file.

Note

The originating report stated that this 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 the reasons above.

Checklist

• I've read the docs and/or content style guides.
• Words are spelled using American English
• Use relative URLs for internal links
• I've checked the pages added or changed in the Vercel preview build
• If I moved a page, I added a redirect in vercel.json — no page moved

---

Created with PostHog Desktop from this inbox report.

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Sep 08, 2026 07:08PM

[github-actions]

Vale prose linter → found 1 errors, 9 warnings, 1 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/libraries/shopify.mdx — 1 errors, 9 warnings, 1 suggestions

Line	Severity	Message	Rule
9:66	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
9:104	warning	Use 'Shopify' instead of 'shopify'.	Vale.Terms
11:66	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
11:104	warning	Use 'Shopify' instead of 'shopify'.	Vale.Terms
13:18	warning	Avoid trivializing words. 'easy to' can sound dismissive to the reader.	PostHogDocs.Trivializers
18:53	warning	Use 'X' instead of 'x'.	Vale.Terms
29:69	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
106:132	warning	Use bold (text) for UI elements, not quotes.	PostHogDocs.UIBoldNotQuotes
114:224	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
151:194	warning	'webpages' is a possible misspelling.	PostHogBase.Spelling
178:12	warning	'regionality' is a possible misspelling.	PostHogBase.Spelling

[github-actions]

Bundle report

Total JS (gzip)

8.85 MiB (+0.2 KiB / +0.0%)

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

Entrypoint	Eager size	Budget	Modules
✅ app	18.44 MiB (+1.7 KiB / +0.0%)	report-only	2052

Largest modules in the app closure

Module	Size
./src/data/mcp-tools.json	1097.0 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.9 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/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs	480.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules	395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs	385.7 KiB
./src/hooks/useCustomers.tsx + 55 modules	370.0 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	302.5 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js	281.9 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs	281.7 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs	275.6 KiB
./src/components/SearchUI/index.tsx + 87 modules	273.0 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).