Can it work with React's `<Suspense>` and TanStack Query `useSuspenseQuery`?

[udohjeremiah]

Great work @0xGF. Thank you so much for this ❤️❤️❤️

Is there a way to get this to work with React's <Suspense> and TanStack Query useSuspenseQuery, where there's no loading state and the only way to display a skeleton is <Suspense fallback={<Skeleton />}...</Suspense>?

I've been thinking of a way around this, but seems like I would have to either change my architecture or manually write fixture prop for all <Skeleton /> and pass that to fallback, which defeats the whole purpose of auto-generating skeletons.

[0xGF]

Thanks for the kind words, and this is a great question worth thinking through — not just a quick yes/no.

Why the naive pattern doesn't work today

boneyard's whole model needs something to render at build time so the headless browser has a DOM to snapshot. useSuspenseQuery is designed never to return — it throws a promise unconditionally if the query hasn't resolved. At CLI build time in a fresh headless Chromium, nothing has resolved, so any component using useSuspenseQuery suspends and boneyard sees the <Suspense fallback> instead of the real shape.

And the standard <Suspense fallback={<Skeleton name="x" />}> pattern is a chicken-and-egg: the fallback <Skeleton> has no children and no fixture, so there's nothing to capture there either. The bones would be empty.

What works today

Pattern 1 — use useQuery instead of useSuspenseQuery for components you want boneyard to auto-capture. Keep Suspense boundaries elsewhere, but for the leaves where you want skeletons:

function UserCard() {
  const { data, isLoading } = useQuery({ queryKey: ['user'], queryFn: fetchUser })
  return (
    <Skeleton name="user-card" loading={isLoading}>
      {data && <div>{data.name} — {data.email}</div>}
    </Skeleton>
  )
}

At build time, isLoading is irrelevant — window.__BONEYARD_BUILD = true forces the <Skeleton> to render its children regardless, and boneyard captures the real shape. At runtime, bones render while isLoading is true, real content swaps in after. No fixture needed because the real JSX is the fixture.

Pattern 2 — keep useSuspenseQuery and pay the fixture tax, but only once per skeleton. This is what you were dreading, and it is annoying, but the fixture doesn't have to be bespoke markup. You can often reuse the same component with mocked props:

const userCardFixture = <UserCardShape name="Jane Doe" email="jane@example.com" bio="A realistic-length bio here" />

<Suspense fallback={<Skeleton name="user-card" fixture={userCardFixture} loading={true} />}>
  <UserCard />
</Suspense>

If UserCardShape is the pure presentational part of UserCard (separated from the query call), you're just passing stub data. Not ideal but less bad than writing fixture JSX from scratch.

Pattern 3 — capture from a non-Suspense route. If you have a storybook page, a design-system showcase, or a ?mock=true route that renders components with hardcoded data, point the CLI at that: npx boneyard-js build http://localhost:5173/__stories/user-card. The bones are keyed by name so they'll register globally and get used wherever <Skeleton name="user-card"> lives in your real app. This is how I'd architect it on a fresh project — keeps production code Suspense-clean and gives boneyard a stable capture surface.

What I'd consider adding

A <BoneSuspense> (or whatever name) that unifies the two:

<BoneSuspense name="user-card">
  <UserCard />  {/* uses useSuspenseQuery */}
</BoneSuspense>

The compile-time trick would be a React context that, when __BONEYARD_BUILD = true, causes useSuspenseQuery to return mocked/cached data instead of throwing. TanStack Query already has initialData and placeholderData — we could plumb a provider that supplies those during the capture. At runtime the wrapper just becomes <Suspense fallback={<Skeleton name={name} />}>{children}</Suspense>.

The catch: it needs you to supply some stub data. Maybe via a mockQuery prop, maybe via a separate boneyard.mocks.ts file. That's arguably a nicer shape than writing fixture JSX, because you're stubbing data not markup.

Would you use that if it existed? If there's real demand I'll prioritize it — right now Pattern 1 or 3 is what I'd recommend, and Pattern 2 as the escape hatch.

[udohjeremiah]

Thanks for prompt response @0xGF.

One thing we have to note here is that once this library gets very popular, and I already see that happening, this is going to be a real blocker for lots of people.

I've gone through your suggestions and thanks so much.

For pattern 1, I wouldn't even consider it, since suspense plays nicely with TanStack Start and SSR for streaming.

Pattern 2 is the reasonable options we can point people to for now. But I consider it an escape hatch, as people would complain that it defeats the purpose of auto-generation.

Pattern 3 is just too much friction 🤦‍♂️.

I think the <BoneSuspense name="user-card"> is the way to go!!! I'm thinking of a way to implement this myself but there's no way without going into the library internals.

What I think BoneSuspense should look like and yes if this exists, I'm going to use it!!! ☺️😭:

1. Props should be everything <Skeleton> would accept (if possible)
2. User shouldn't be forced to supply initialData or placeholderData. The reason is because that's a real architectural change of how the query would run in prod and most users wouldn't want that if it's going to change how their app would work.
3. Since 2. can't work, maybe it should just work like <Skeleton> but maybe use a longer wait time for the data to be available.

[0xGF]

Your also welcome to contribute if you have a solution in mind im happy to push forward on it if it makes sense.

[udohjeremiah]

Your also welcome to contribute if you have a solution in mind im happy to push forward on it if it makes sense.

Would love to but I've seriously got work on my hand and honestly won't have a spare time for it now. Regardless, would you be prioritising this?

[0xGF]

I also have work right now. So ill leave the issue open for now incase someone else picks it up.

[udohjeremiah]

Okay 👍