Get started

1. Install.

   pnpm add @hueest/xray

2. Add the plugin to your Vite config, and register the virtual-module types.

   vite.config.ts

   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   import { xrayVitePlugin } from '@hueest/xray'
   
   export default defineConfig({
     plugins: [
       react(),
       xrayVitePlugin({ hud: true }),
     ],
   })

   tsconfig.json

   {
     "compilerOptions": {
       "types": ["@hueest/xray/virtual"]
     }
   }

3. Wrap what loads in <Skeleton>. It slots into whatever you fetch with: pass the Plate and a loading boolean, or suspense for anything that suspends.
   Plain fetch

   import { Skeleton } from '@hueest/xray/react'
   import plate from 'virtual:xray/plates/similar-products'
   import { useState, useEffect } from 'react'
   import { ProductHero } from './ProductHero'
   import { SimilarProductsCarousel } from './SimilarProductsCarousel'
   
   export function ProductDetails({ product }) {
     const [similar, setSimilar] = useState(null)
   
     useEffect(() => {
       fetchSimilar(product.id).then(setSimilar)
     }, [product.id])
   
     return (
       <main className="product-details">
         <ProductHero product={product} />
   
         <section aria-labelledby="similar">
           <h2 id="similar">You might also like</h2>
           {similar
             ? <SimilarProductsCarousel products={similar} />
             : <div>Loading...</div>}
           <Skeleton plate={plate} loading={!similar}>
             {similar && <SimilarProductsCarousel products={similar} />}
           </Skeleton>
         </section>
       </main>
     )
   }

   TanStack Query

   import { Skeleton } from '@hueest/xray/react'
   import plate from 'virtual:xray/plates/similar-products'
   import { useQuery } from '@tanstack/react-query'
   import { ProductHero } from './ProductHero'
   import { SimilarProductsCarousel } from './SimilarProductsCarousel'
   
   export function ProductDetails({ product }) {
     const { data: similar, isLoading } = useQuery({
       queryKey: ['similar', product.id],
       queryFn: () => fetchSimilar(product.id),
     })
   
     return (
       <main className="product-details">
         <ProductHero product={product} />
   
         <section aria-labelledby="similar">
           <h2 id="similar">You might also like</h2>
           {isLoading
             ? <div>Loading...</div>
             : <SimilarProductsCarousel products={similar} />}
           <Skeleton plate={plate} loading={isLoading}>
             {!isLoading && <SimilarProductsCarousel products={similar} />}
           </Skeleton>
         </section>
       </main>
     )
   }

   React use()

   import { Skeleton } from '@hueest/xray/react'
   import plate from 'virtual:xray/plates/similar-products'
   import { Suspense, use } from 'react'
   import { ProductHero } from './ProductHero'
   import { SimilarProductsCarousel } from './SimilarProductsCarousel'
   
   export function ProductDetails({ product, similar }) {
     return (
       <main className="product-details">
         <ProductHero product={product} />
   
         <section aria-labelledby="similar">
           <h2 id="similar">You might also like</h2>
           <Suspense fallback={<div>Loading...</div>}>
           <Skeleton plate={plate} suspense>
             <SimilarProductsCarousel products={use(similar)} />
           </Suspense>
           </Skeleton>
         </section>
       </main>
     )
   }

   Server Components

   import { Skeleton } from '@hueest/xray/react'
   import plate from 'virtual:xray/plates/similar-products'
   import { Suspense } from 'react'
   import { ProductHero } from './ProductHero'
   import { SimilarProductsCarousel } from './SimilarProductsCarousel'
   
   export default async function ProductDetails({ params }) {
     const product = await getProduct(params.id)
   
     return (
       <main className="product-details">
         <ProductHero product={product} />
   
         <section aria-labelledby="similar">
           <h2 id="similar">You might also like</h2>
           <Suspense fallback={<div>Loading...</div>}>
           <Skeleton plate={plate} suspense>
             <SimilarProductsCarousel productId={product.id} />
           </Suspense>
           </Skeleton>
         </section>
       </main>
     )
   }

4. Browse your dev server. When the component renders for real, xray captures its Plate into plates/. The HUD tracks coverage across every breakpoint; commit the Plate and you are shipping faithful skeletons.
   localhost:5173

   xray — 3 plates

   Capture Light Box Capture all views

   profile-card [0,768)[768,∞)

   news-feed [0,768)[768,∞)

   offerings [0,∞)

The skeleton is your component

Data takes time to arrive: bytes cross a network, servers do work, and no code opts out of that. Every app waits, and every wait needs something on screen. Like a request waterfall, a loading state is something you minimize, not remove. Spinners, blank space, content that pops in and shoves the layout around: they all just say "not yet." The one that costs the user least is the skeleton. It shows the shape of what's coming, so the wait reads as "almost there" instead of "is this broken?", and holds the layout so nothing jumps.

And skeletons are a pain to build. You hand-make a second copy of a component you already wrote: place the boxes, guess the sizes, match the styles by eye, all to mimic a layout that already exists. Worse, it's stale the day you ship it. The component changes, the skeleton doesn't, and your pixel-perfect work becomes a placeholder that no longer matches, with no test to catch it.

@0xGF pioneered the approach with boneyard: generate the skeleton from the real component instead of drawing it by hand, so it starts out faithful. xray is a from-scratch take on the same idea, pushed further on two fronts. For your users, it keeps your real structure and CSS, so the skeleton reflows with the component at every width. For you, it captures inside the dev server you already run, as you browse. The skeleton you ship is the component you wrote, stripped of its flesh.

The insides

Wire

With xray running in your Vite dev server and a Plate passed to <Skeleton>, the pieces are connected: the Plate ties a capture to its component, and its loading (or suspense) prop marks when the content is still pending. xray already knows what to capture, who it belongs to, and when.

Capture

The first time that component renders in dev, xray crawls the DOM it produced and copies the author CSS that styles it, @media rules and all. It keeps the rules, not frozen pixels, which is what lets the skeleton reflow later.

Store

The result is written to its Plate: a small, self-contained JSON file you commit beside the component. It depends on nothing in your build, and a resize captures another view into the same Plate.

Compute

When the virtual module resolves, xray turns the Plate into ready-to-paint HTML and CSS, so production ships markup, not a capture engine.

Render

While data loads, <Skeleton> paints that HTML and CSS. Every box lands exactly where the real content will, and the bones reflow like the component until it takes over.

• Pixel-faithful, not approximate

  It is your own DOM and CSS, so the bones line up exactly. No fixed-height guesses, no absolute-position hacks, no separate placeholder to keep in sync by hand.

• Never out of date

  It is derived from the real render and re-captured as you browse, so it tracks the component instead of a snapshot you took once. The Plate is committed JSON, so any drift shows up as a diff in review, never a silent lie in production.

• Every breakpoint, truly responsive

  The bones keep your real structure and your own CSS, @media rules and all. The skeleton reflows exactly like the component at every width: a living layout, not a fixed picture stretched to fit.

• Just Vite, no side steps

  One plugin, one component. No CLI, no headless browser, no extra service. Capture runs in the dev server you already use; production ships a tiny renderer and a JSON file.

• Lives in git

  A Plate is JSON committed beside the component. Review it, diff it, blame it: your skeletons are version-controlled like everything else, not hidden in a snapshot service.

• Slots into any data fetching

  useEffect, TanStack Query, Suspense with use(), Server Components: the same <Skeleton>, no data-layer lock-in.

Go deeper

Guides

API reference