Skip to content

Core: Add sourceUrl and expanded to the enabled refs type - #36145

Open
theRizwan wants to merge 5 commits into
storybookjs:nextfrom
theRizwan:fix/refs-type-source-url
Open

theRizwan wants to merge 5 commits into
storybookjs:nextfrom
theRizwan:fix/refs-type-source-url

Conversation

@theRizwan

Copy link
Copy Markdown

Closes #32239

What I did

The enabled variant of the refs entry of StorybookConfig was typed as { title: string; url: string }. It is missing two fields that the documentation lists and that the manager honours at runtime:

  • sourceUrl, which the sidebar's ref indicator uses to render the "View source code" link for a composed Storybook (code/core/src/manager/components/sidebar/RefIndicator.tsx:171);
  • expanded, documented as "Optional, true by default" on an enabled ref, but which only existed on the disabled variant.

So the exact example on https://storybook.js.org/docs/api/main-config/main-config-refs fails to typecheck in a typed main.ts, even though both values work. This adds the two optional fields to the enabled variant. The disabled variant is untouched, so no existing config stops compiling.

A new core-common.test-d.ts compiles the documented example against StorybookConfigRaw['refs'], so the type cannot drift from the docs again without failing the core project's vitest typecheck. I confirmed it fails on next today with Object literal may only specify known properties, and 'sourceUrl' does not exist in type ....

Claude Code assisted with the investigation and the patch, as CONTRIBUTING.md asks contributors to disclose. I reviewed and tested every change.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

  • stories
  • unit tests
  • integration tests
  • end-to-end tests

code/core/src/types/modules/core-common.test-d.ts is a type level test, run by the core project's vitest typecheck:

cd code/core
../../node_modules/.bin/vitest run --config vitest.config.ts src/types/modules/core-common.test-d.ts

Manual testing

  1. In a TypeScript project running this branch, paste the refs example from the refs docs page into .storybook/main.ts, keeping expanded: false and sourceUrl.
  2. Run tsc --noEmit on the project, or open the file in an editor. Before this change sourceUrl and expanded are reported as unknown properties on the enabled ref. With it, the file typechecks.
  3. Start Storybook and open the composed ref in the sidebar. The "View source code" link still points at sourceUrl, exactly as before, since only the type changed.

Documentation

  • Add or update documentation reflecting your changes
  • If you are deprecating/removing a feature, make sure to update
    MIGRATION.MD

No documentation change. The docs already describe this shape, the type now matches them.

Checklist for Maintainers

  • When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

  • Declare whether manual QA will be needed for this PR during the next release, through qa:needed or qa:skip

  • Make sure this PR contains one of the labels below:

    Available labels
    • bug: Internal changes that fixes incorrect behavior.
    • maintenance: User-facing maintenance tasks.
    • dependencies: Upgrading (sometimes downgrading) dependencies.
    • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
    • cleanup: Minor cleanup style change. Will not show up in release changelog.
    • documentation: Documentation only changes. Will not show up in release changelog.
    • feature request: Introducing a new feature.
    • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
    • other: Changes that don't fit in the above categories.

🦋 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 publish.yml --field pr=<PR_NUMBER>

The enabled variant of `StorybookConfig['refs']` was typed as
`{ title: string; url: string }`, so the documented `sourceUrl` (used by the
sidebar's ref indicator to link to the source code) and `expanded` (documented
as optional and true by default) were rejected in a typed `main.ts`, although
both are honoured at runtime. Add both optional fields and a type test that
compiles the documented example.

Closes storybookjs#32239
@github-actions

github-actions Bot commented Sep 2, 2026 •

Copy link
Copy Markdown
Contributor
Fails
🚫

PR is not labeled with one of: ["qa:needed","qa:skip","qa:success"]

Generated by 🚫 dangerJS against 7be2db9

@coderabbitai

coderabbitai Bot commented Sep 2, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: ee72d40b-033e-4f8f-b7ef-112c16369fdd

📥 Commits

Reviewing files that changed from the base of the PR and between c496da6 and d8fa0ea.

📒 Files selected for processing (2)
  • code/core/src/types/modules/core-common.test-d.ts
  • code/core/src/types/modules/core-common.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.


Walkthrough

Changes

Refs type support

Layer / File(s) Summary
Refs contract and validation
code/core/src/types/modules/core-common.ts, code/core/src/types/modules/core-common.test-d.ts
CoreCommon_StorybookRefs now accepts optional expanded and sourceUrl fields for URL-based refs. A type-level test validates these fields and a disabled ref entry.

Fixed issue severity: Medium

Merge Risk: ⚪ Minimal · up to d8405

This localized change expands the enabled refs type to match documented and already-supported fields, with a type-level regression test; no actionable merge-blocking risk remains beyond normal checks and review.

✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Create stacked PR
  • Commit on current branch

Comment @coderabbitai help to get the list of available commands.

@storybook-contribution-review storybook-contribution-review Bot added sev:S4 Low priority. Wait for community PRs. and removed sev:S3 Medium priority. Fix within months if possible. labels Sep 11, 2026
@github-actions github-actions Bot added the Stale label Oct 4, 2026
@storybook-contribution-review storybook-contribution-review Bot added review:1-architecture In automated review pipeline: awaiting stage 1 architecture review review:2-code-quality Stage 1 passed: awaiting stage 2 code quality review review:3-verification Stage 2 passed: awaiting stage 3 proof-of-work verification and removed review:1-architecture In automated review pipeline: awaiting stage 1 architecture review review:2-code-quality Stage 1 passed: awaiting stage 2 code quality review labels Oct 17, 2026

@storybook-contribution-review storybook-contribution-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 I am the Storybook contribution review bot. This message was posted automatically; a human maintainer makes the final decision.
Review phase: Final verdict: Architecture review (stage 1 of 3), Thermo-nuclear code quality review (stage 2 of 3) and Runtime verification (stage 3 of 3) completed

We are trying a three-stage automated review: architecture, code quality, and runtime verification. This message states which stages ran and which were skipped. Messages are posted automatically, and a human maintainer makes the final decision. Please tell us whether the feedback and evidence are useful.

Thanks @theRizwan, this is a clean, well-scoped fix for #32239. All three review stages passed on d8405c85:

  • Architecture: CoreCommon_StorybookRefs is the single type behind StorybookConfig['refs'], so the fix reaches every consumer. It now matches what getRefs already passes through at runtime and what the refs docs describe. Adding optional members is not a breaking change.
  • Code quality: the change is minimal, and the new type test fails against the base type and passes on this branch.
  • Runtime verification: a main.ts-style config typed StorybookConfig with sourceUrl and expanded fails type checking on the base (TS2353: 'sourceUrl' does not exist in type …) and passes on this branch. The function form of refs, disable: true, and rejection of a sourceURL typo behave as before. Not run: a rendered composition check in the manager UI, because the diff only changes types.

I left two optional suggestions inline on the test. They are not needed for merge, and the bot will not review them again. One more optional note without an inline location, because the file is not in this diff: the function-form signature in docs/api/main-config/main-config-refs.mdx shows sourceUrl as required, while the type makes it optional. That predates this PR and could be a small docs follow-up.

@storybook-contribution-review storybook-contribution-review Bot added ci:normal Run our default set of CI jobs (choose this for most PRs). review:verified Three-step review passed: architecture, code quality, runtime verification and removed review:3-verification Stage 2 passed: awaiting stage 3 proof-of-work verification labels Oct 17, 2026

@storybook-contribution-review storybook-contribution-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 I am the Storybook contribution review bot. This message was posted automatically; a human maintainer makes the final decision.
Review phase: Runtime verification (stage 3 of 3)

We are trying a three-stage automated review: architecture, code quality, and runtime verification. This message states which stages ran and which were skipped. Messages are posted automatically, and a human maintainer makes the final decision. Please tell us whether the feedback and evidence are useful.

The merge of next in c6283d6 left this PR's own change as it was, so the earlier architecture and code quality passes still apply and were not re-run. Since then, next has started type-checking *.test-d.ts files with Vitest, and tests--linux now fails on this head because of the new type test. I've moved the PR from review:verified to review:changes-requested for this one item, which is described inline. When it's fixed, I'll re-check only this item.

@@ -0,0 +1,20 @@
import { expectTypeOf } from 'vitest';

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: tests--linux fails on c6283d6 with Error: No test suite found in file …/core-common.test-d.ts (CircleCI job 2334363). next now runs *.test-d.ts files through Vitest typecheck, and Vitest requires every test file to contain at least one test or describe. If this merges as it is, tests--linux fails on next.

Please wrap the assertions in a test(...) block, as the other *.test-d.ts files do (for example code/core/src/backgrounds/index.test-d.ts):

import { expectTypeOf, test } from 'vitest';

import type { StorybookConfigRaw } from './core-common.ts';

type Refs = NonNullable<StorybookConfigRaw['refs']>;

test('accepts the documented refs shape', () => {
  // The documented shape of `refs`: https://storybook.js.org/docs/api/main-config/main-config-refs
  const refs = {
    // ...unchanged...
  } satisfies Refs;

  expectTypeOf(refs).toExtend<Refs>();
});

@storybook-contribution-review storybook-contribution-review Bot added review:changes-requested Review paused: changes requested; the review comment names the failing stage and removed review:verified Three-step review passed: architecture, code quality, runtime verification labels Oct 19, 2026
@storybook-contribution-review

Copy link
Copy Markdown
Contributor

🤖 I am the Storybook contribution review bot. This message was posted automatically; a human maintainer makes the final decision.
Review phase: Inactivity follow-up

Hi @theRizwan, thanks again for this contribution! Our review on 2026-10-19 asked for some changes, and this PR has had no new activity since 2026-10-19.

If you are still working on it, push your changes or reply here: any new commit or reply keeps the PR open. Without new activity, this PR will be closed automatically on or after 2026-11-02. A maintainer can reopen it later if you come back to it.

@valentinpalkovic valentinpalkovic removed the ci:normal Run our default set of CI jobs (choose this for most PRs). label Oct 27, 2026
Vitest now typechecks *.test-d.ts files and needs a test or describe in each.
Also add a negative case so the new optional members cannot loosen the
excess-property check.
@storybook-contribution-review storybook-contribution-review Bot added review:3-verification Stage 2 passed: awaiting stage 3 proof-of-work verification and removed review:changes-requested Review paused: changes requested; the review comment names the failing stage labels Oct 28, 2026

@storybook-contribution-review storybook-contribution-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 I am the Storybook contribution review bot. This message was posted automatically; a human maintainer makes the final decision.
Review phase: Runtime verification (stage 3 of 3)

We are trying a three-stage automated review: architecture, code quality, and runtime verification. This message states which stages ran and which were skipped. Messages are posted automatically, and a human maintainer makes the final decision. Please tell us whether the feedback and evidence are useful.

Thanks @theRizwan, the update in 7be2db9 fixes the item from our last review. Vitest now finds core-common.test-d.ts as a test suite, and both tests pass with no type errors in the core typecheck project (run locally, because CI has not run on this head). The @ts-expect-error test fails as expected when the key is changed to the valid sourceUrl, so it guards against the typo for the right reason.

We re-ran the original check on this head: a StorybookConfig with a ref that sets sourceUrl and expanded fails on the base with TS2353 and type-checks on this PR. The function form of refs, disable: true, and the rejection of unknown keys work as before.

Stages: only runtime verification (stage 3) re-ran for this follow-up. The architecture and code quality passes from the first round still apply, because this update changes only the type test file. Not run: the full CI tests--linux job and rendering in the manager UI (the change is types only).

All three stages have now passed, and the PR is marked review:verified. A maintainer decides on the merge.

@storybook-contribution-review storybook-contribution-review Bot added ci:focus Run the focused single-job CI workflow. review:verified Three-step review passed: architecture, code quality, runtime verification and removed review:3-verification Stage 2 passed: awaiting stage 3 proof-of-work verification labels Oct 28, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-scan:human bug ci:focus Run the focused single-job CI workflow. composition core review:verified Three-step review passed: architecture, code quality, runtime verification sev:S4 Low priority. Wait for community PRs. Stale typescript

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

[Bug]: no refs.sourceUrl in StorybookConfig Typescript type

2 participants