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. Capture starts off: tick Capture in the HUD (or pass capture: true) and, when the component renders for real, xray captures its Plate into plates/. The HUD tracks Coverage across every width band; commit the Plate and you are shipping faithful skeletons.
   localhost:5173

   xray — 3 plates

   CaptureLight BoxCapture all views

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

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

   catalog[0,∞)

The skeleton is your component

A skeleton is the cheapest wait you can give a user: it shows the shape of what's coming and holds the layout. Building one is the miserable part. You hand-make a second copy of a component you already wrote, guess the sizes, and match the styles by eye. It's stale the day you ship: the component changes, the skeleton doesn't, and no test catches the drift.

@0xGF pioneered the fix withboneyard: generate the skeleton from the real component, so it starts out faithful. xray is a from-scratch take that pushes it further. It keeps your real structure and CSS, so the skeleton reflows with the component at every width. It captures inside the dev server you already run, as you browse: no CLI, no headless browser, no second copy to maintain. 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 walks the DOM it produced and copies the author CSS that styles it, @media rules and all. It keeps the rules rather than 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. A resize captures another View into the same Plate, and any drift shows up as a diff in review, never a silent lie in production.

Bake

When the virtual module resolves, xray bakes the Plate into ready-to-paint HTML and CSS. Production ships markup and a stylesheet, never 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.

Features

• Zero layout shift

  A skeleton reserves the exact box its content will fill. Nested skeletons (Stitches) resolve in any order without reflowing the page, and each one captures and updates independently.

  Nested skeletons →

• Flash prevention

  A 250ms grace delay keeps fast loads skeleton-free; a 600ms minimum keeps a shown skeleton from blinking away. Three CSS tokens, tunable globally or per plate.

  Display timing →

• Breakpoint detection

  Views are captured per width band, derived from the component's own @mediarules and matchMedia calls. The browser selects the active View with plain CSS: no runtime width measurement, SSR-safe.

  Responsive & Views →

• In-session capture

  Capture runs in the browser tab you develop in: authenticated, real data, no headless browser. The HUD shows per-Plate Coverage; Light Box forces every mounted skeleton on for inspection.

  The HUD & Light Box →

• Automated width sweep

  With the companion extension connected, one press of record drives the viewport through every derived breakpoint, captures each View, and writes the plates — sweep, save, done.

  The Sweep →

• CSS-based config

  Tokens cascade from :root, per plate, per bone kind, or per instance, withlight-dark() for themes. No props, no JS config.

  Theming →

• Custom bones

  data-xr-ignore drops decoration, data-xr-bone-kind collapses a widget to a single bone, and a programmable walker applies project-wide rules.

  Capture customization →

• Data fixtures

  Record a component's render input once; replay it so every re-capture renders the same state. A dev-only sidecar committed next to the Plate.

  Fixtures →

Go deeper

Guides

API reference