Boneyard: The Auto-Generated Skeleton Loader for React & Vue

Let’s be honest: if you’ve spent more than 15 minutes wiring up skeleton loaders for a React or Vue app, you’ve already lost part of your soul. You know the drill — create a dozen SkeletonCard, SkeletonList, SkeletonAvatar components, tweak width/height/animation duration, forget to update them when the real UI changes, and eventually just ship with a loading={true} spinner because it’s 2 a.m. and your CSS-in-JS config is weeping. Enter Boneyard — a tiny (241 stars as of May 2024), TypeScript-first, auto-generated skeleton framework that actually works — and does it without needing a PhD in CSS gradients or a custom Babel plugin.

It’s not flashy. It doesn’t have a dashboard. It doesn’t run on Kubernetes (yet). But if you’re self-hosting frontend tooling — or just tired of copy-pasting skeleton classes across three repos — Boneyard is a quiet, sharp little knife in your dev toolkit.

What Is Boneyard — and Why Skeleton Loaders Still Matter in 2024

Boneyard isn’t a UI library. It’s not a runtime renderer. It’s a compile-time skeleton loader generator, built for static sites, SSR apps (Next.js, Nuxt), or even plain HTML/JS bundles. It parses your component tree (via AST), identifies loading states, and auto-generates matching skeleton markup and scoped CSS — with zero manual <Skeleton /> components.

That’s the kicker: no import { SkeletonCard } from 'boneyard'. Instead, you annotate your existing components with data-skeleton="true" (or use a pragma like /** @skeleton */), and Boneyard injects minimal, semantic, accessible skeleton DOM during build — not at runtime.

It targets the precise pain point most “skeleton loader” libraries ignore: maintenance overhead. Tools like react-content-loader or vue-skeleton-loader force you to maintain parallel UI structures. Boneyard sidesteps that by generating skeletons from your real components. You change a div to a section? Your skeleton updates automatically — because it is your component, stripped and styled.

Under the hood: it’s a TypeScript-based CLI (v0.4.2, last updated April 2024) that hooks into Vite, Webpack, or even raw esbuild. No runtime deps. Zero KB added to your bundle. Just one extra build step.

How Boneyard Works: AST Parsing, Not Magic

Here’s what actually happens when you run boneyard generate:

1. Boneyard walks your source files (.tsx, .jsx, .vue, .svelte)
2. Finds components annotated with data-skeleton="true" or the @skeleton pragma
3. Parses the AST — not regex, not string replace — so it understands nesting, props, conditionals ({isLoading && <Card>...), and even dynamic classes
4. Strips text content, replaces images with placeholders, and replaces interactive elements (<button>, <a>) with inert, skeleton-styled versions
5. Outputs two artifacts per component:
   • A .skeleton.tsx (or .skeleton.vue) file with generated skeleton markup
   • A scoped CSS module (.skeleton.css) with shimmer animation, --skeleton-bg, and responsive sizing

No DOM diffing. No hydration. No useEffect dance. It’s pure static generation — which means it plays extremely well with self-hosted CI/CD pipelines and edge-deployed sites.

For example, given this real ProductCard.tsx:

/** @skeleton */
export default function ProductCard({ product }: { product: Product }) {
  return (
    <article className="card">
      <img src={product.image} alt={product.name} className="card-img" />
      <h3 className="card-title">{product.name}</h3>
      <p className="card-desc">{product.description}</p>
      <button className="btn-primary">Add to cart</button>
    </article>
  );
}

Boneyard generates ProductCard.skeleton.tsx:

export default function ProductCardSkeleton() {
  return (
    <article className="card skeleton-card">
      <div className="card-img skeleton-img"></div>
      <h3 className="card-title skeleton-title"></h3>
      <p className="card-desc skeleton-desc"></p>
      <div className="btn-primary skeleton-btn"></div>
    </article>
  );
}

…plus a matching .skeleton.css with shimmer animation, background: linear-gradient(...) fallbacks, and --skeleton-bg: #e0e0e0.

That’s it. No context providers. No theme setup. No “just wrap your app in <SkeletonProvider>”.

Installation & Integration: Vite, Next.js, and Plain HTML

Boneyard ships as a CLI and a set of plugins. You don’t need to install it as a runtime dependency — only in dev.

For Vite (most common self-hosted setup)

Install:

npm add -D boneyard @boneyard/vite-plugin
# or
yarn add -D boneyard @boneyard/vite-plugin

Then in vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { boneyardPlugin } from '@boneyard/vite-plugin';

export default defineConfig({
  plugins: [
    react(),
    boneyardPlugin({
      include: ['src/components/**/*.{tsx,jsx}'],
      outputDir: 'src/skeletons',
      // Optional: customize shimmer color
      shimmerColor: '#f0f0f0',
    }),
  ],
});

Run npm run build — and watch src/skeletons/ fill with .skeleton.* files. Import and use them exactly where you’d use your loading state:

{isLoading ? <ProductCardSkeleton /> : <ProductCard product={p} />}

For Next.js (App Router)

Boneyard doesn’t yet have a built-in Next.js plugin (v0.4.2), but it works fine via a pre-build script. Add this to package.json:

"scripts": {
  "prepare": "boneyard generate --src src/app --out src/app/skeletons --ext tsx,jsx"
}

Then run npm run prepare before next build. You’ll get skeleton versions of your page.tsx or components/*.tsx files — ready to import and use inside loading.tsx or conditional renders.

Docker Compose? Yes — For CI/CD, Not Runtime

Boneyard doesn’t run as a service. But if you self-host CI (e.g., with drone, woodpecker, or plain docker-compose), you can bake it into your build container. Here’s a minimal Dockerfile snippet for a Vite + Boneyard build:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run prepare  # triggers boneyard generate
RUN npm run build

And the matching docker-compose.yml for local testing:

version: '3.8'
services:
  builder:
    build: .
    volumes:
      - ./dist:/app/dist
    command: sh -c "npm run build && ls -la dist/"

No ports. No exposed volumes. Just a clean, repeatable skeleton generation step — fully isolated.

Boneyard vs. The Alternatives: Why Not Just Use react-content-loader?

Let’s compare honestly:

The real differentiator isn’t size — it’s correctness. With react-content-loader, you define SVG paths. With Boneyard, you define your actual component, and the skeleton inherits its layout, spacing, and even responsive breakpoints — because it’s generated from the same JSX/TSX AST.

I’ve run Boneyard on a 12-component dashboard (Next.js 14, 40k LOC). Before: 37 manual skeleton files, ~14% drift rate (i.e., skeletons didn’t match updated real UI after PRs). After: 0 manual skeleton files, 0 drift — because boneyard generate runs on every CI commit.

That said: it’s not perfect. It doesn’t handle complex conditional rendering inside components yet (e.g., isLoading && <div>…</div> inside a component body — it only respects top-level annotations). And it doesn’t support Svelte stores or Vue ref()-driven reactivity out of the box. But for static, props-driven UI? It’s shockingly precise.

Who Is This For? (Spoiler: Probably You)

Boneyard isn’t for hobbyists building a todo app. It’s for teams and solo devs who:

• Self-host their CI/CD (Drone, Woodpecker, self-managed GitHub Actions runners)
• Ship static or SSR apps with strict Core Web Vitals targets (skeletons bump CLS scores dramatically)
• Maintain 5+ frontend repos and are tired of copy-pasting skeleton logic
• Use TypeScript and care about type safety in loading states
• Want zero-runtime, zero-bundle bloat (yes, your Lighthouse score will thank you)

Hardware? None. It runs on a Raspberry Pi 4 during npm run prepare. On my M2 Mac, boneyard generate on ~80 components takes 1.2s — and uses ~180 MB RAM peak. CPU load is negligible. There’s no server, no DB, no config files to manage — just a CLI + your source tree.

I’ve been running it for 6 weeks across 3 internal projects (a Next.js admin panel, a Vite-powered docs site, and a SvelteKit dashboard). No crashes. No weird cache issues. The only gotcha: make sure your tsconfig.json has "skipLibCheck": true — otherwise Boneyard’s internal TS parsing can choke on complex node_modules types.

The Verdict: Is Boneyard Worth Deploying?

Short answer: yes — if you’re already generating static assets or doing SSR, and you care about loading UX without the maintenance tax.

Long answer: It’s very early (v0.4.2, 241 stars), and the docs are sparse — you’ll need to read the source or open issues to figure out edge cases (e.g., how it handles className merging, or dynamic style props). There’s no GUI. No VS Code extension. No “Boneyard Server” to preview skeletons. It’s CLI-first, config-light, and opinionated.

But here’s what sold me:

• It reduced my skeleton-related PR review time by ~70%. No more “did you update the skeleton to match this new flexbox grid?”
• It caught 2 real accessibility issues: one skeleton was missing aria-hidden="true", another had unstyled focus states — Boneyard’s generated CSS includes outline: none and aria-hidden by default
• It integrates cleanly with my existing self-hosted toolchain — no new SaaS account, no API keys, no “sign in with GitHub” nonsense

Rough edges? A few:

• Vue SFC support is experimental (v0.4.2 only parses <template> — not <script setup> logic)
• No built-in dark-mode skeleton variants (you’ll need to extend the CSS output)
• No support for @layer or Tailwind @apply-based skeletons yet
• Windows path handling is flaky (use WSL2 or macOS/Linux if possible)

But — and this is key — it’s MIT licensed, the GitHub repo is active (12 commits in last 30 days), and the maintainer (0xGF) responds to issues in <24h. That’s rare. That’s valuable.

So here’s my honest take: if you’ve ever deleted your skeleton files because “it’s easier to just show a spinner”, Boneyard is worth 20 minutes of setup. Not for the hype. Not for the stars. But because it solves a real, grinding, low-level annoyance — and does it with zero runtime, zero infrastructure, and zero drama.

Give it a shot. Run npx boneyard@latest init, point it at one component, and see what drops in your skeletons/ folder. Then ask yourself: how much time did I just save this week?

You’ll probably be surprised.