Telemetry: Disambiguate traffic coming from error/upgrade links

[shilman]

Closes N/A

Telescopes on #32286

What I did

Better disambiguate traffic coming from error/upgrade links

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

Greptile Summary

This PR adds UTM tracking parameters to Storybook documentation links throughout the codebase to improve telemetry and traffic attribution. The changes systematically add ?ref=error parameters to links that appear in error messages and ?ref=upgrade parameters to links that appear in upgrade/migration contexts, while also adding ?utm_source=ui to links accessed from UI components.

The implementation spans 28 files across the Storybook codebase, touching error handling systems, CLI tools, UI components, and documentation blocks. Key areas affected include:

• Error handling: The core StorybookError class and various specific error classes now append ?ref=error to all storybook.js.org URLs in error messages
• CLI and upgrade flows: Migration guides and upgrade documentation links now include ?ref=upgrade parameters
• UI components: Documentation links in manager components, addon panels, and docs blocks now include ?utm_source=ui parameters
• Test files: Multiple test files have been updated with new expected URL formats to match the implementation changes

This telemetry enhancement builds on PR #32286 and enables the Storybook team to distinguish between different traffic sources (error-driven, upgrade-driven, and UI-driven) when users navigate to documentation. The changes are purely additive and cosmetic, maintaining all existing functionality while providing valuable analytics data.

Confidence score: 4/5

• This PR is generally safe to merge with low risk of breaking functionality, as changes are primarily cosmetic URL modifications
• Score reflects the comprehensive scope across many files and some complexity in URL parameter handling logic that could introduce edge cases
• Pay close attention to code/core/src/storybook-error.ts for potential URL construction issues with nested ternary operators

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 6aa17df

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	46s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-08-20 04:57:38 UTC

[storybook-app-bot]

Package Benchmarks

^{Commit: 6aa17df, ran on 20 August 2025 at 04:44:28 UTC}

No significant changes detected, all good. 👏

[greptile-apps]

_{29 files reviewed, 3 comments}

_{Edit Code Review Bot Settings | Greptile}

[jonniebigodes]

@shilman this is shaping up nicely, I left some items for you to consider when you can. The major one i'm concerned is the URL structure usage.

Approving to unblock you.

[jonniebigodes]

@shilman just a heads up, this will point to an incorrect URL as we don't have actual documentation about it except the following entry in the monorepo's migration guide and in the main.js|ts API reference

[shilman]

@jonniebigodes Thanks for your diligence on this. I think we should add a section on ESM only to the configuration overview page as part of SB10 release, so I'm going to leave this as is for now. But if we want to keep the existing structure we can link to the main.ts|js reference instead. I'll let you guys take care of that separately cc @kylegach