boneyard README

The project's README from github.com/0xGF/boneyard. As one markdown file: README.md.

Boneyard

boneyard

Pixel-perfect skeleton loading screens, extracted from your real UI. No manual measurement, no hand-tuned placeholders.

Works with React, Preact, Vue, Svelte 5, Angular, and React Native.

Quick start

npm install boneyard-js

React

import { Skeleton } from 'boneyard-js/react'

function BlogPage() {
  const { data, isLoading } = useFetch('/api/post')
  return (
    <Skeleton name="blog-card" loading={isLoading}>
      {data && <BlogCard data={data} />}
    </Skeleton>
  )
}

With <Suspense> / useSuspenseQuery

Drop in <BoneSuspense> anywhere you'd use a <Suspense> boundary. The skeleton renders as the fallback at runtime, and the CLI captures bones from the resolved children at build time.

import { BoneSuspense } from 'boneyard-js/react'

function Page() {
  return (
    <BoneSuspense name="user-card">
      <UserCard />  {/* uses useSuspenseQuery */}
    </BoneSuspense>
  )
}

No initialData or placeholderData required — the build-time --wait window lets the query resolve naturally. Pass a fixture if the query can't finish in time.

Vue

<script setup>
import Skeleton from 'boneyard-js/vue'
import './bones/registry'
const loading = ref(true)
</script>

<template>
  <Skeleton name="card" :loading="loading">
    <Card />
  </Skeleton>
</template>

Svelte 5

<script>
  import Skeleton from 'boneyard-js/svelte'
  import '$lib/bones/registry'
  let loading = true
</script>

<Skeleton name="card" {loading}>
  <Card />
</Skeleton>

Preact

import { Skeleton } from 'boneyard-js/preact'

function BlogPage() {
  const { data, isLoading } = useFetch('/api/post')
  return (
    <Skeleton name="blog-card" loading={isLoading}>
      {data && <BlogCard data={data} />}
    </Skeleton>
  )
}

Angular

import { SkeletonComponent } from 'boneyard-js/angular'

@Component({
  imports: [SkeletonComponent],
  template: `
    <boneyard-skeleton name="card" [loading]="isLoading">
      <app-card />
    </boneyard-skeleton>
  `
})

React Native

import { Skeleton } from 'boneyard-js/native'

<Skeleton name="profile-card" loading={isLoading}>
  <ProfileCard />
</Skeleton>

npx boneyard-js build --native --out ./bones
# Open your app on device — bones capture automatically

Dynamic Type: Generate bones at default font scale. Boneyard automatically scales bone positions at runtime to match the user's text size setting.

Generate bones

# CLI — works with any framework
npx boneyard-js build

# Watch mode — re-captures on HMR changes
npx boneyard-js build --watch

# React Native — scans from device
npx boneyard-js build --native

Then import the registry once in your app entry:

import './bones/registry'

Vite plugin

For Vite-based projects (React, Preact, Vue, Svelte), use the plugin instead of the CLI — no second terminal needed:

// vite.config.ts
import { boneyardPlugin } from 'boneyard-js/vite'

export default defineConfig({
  plugins: [boneyardPlugin()]
})

Bones are captured automatically when the dev server starts and re-captured on every HMR update.

How it works

Web: The CLI (or Vite plugin) opens a headless browser, visits your app, finds every <Skeleton name="...">, and snapshots their layout at multiple breakpoints.

React Native: The <Skeleton> component auto-scans in dev mode when the CLI is running. It walks the fiber tree, measures views via UIManager, and sends bone data to the CLI. Zero overhead in production.

All frameworks output the same .bones.json format — cross-platform compatible.

CLI flags

Flag Default Description
[url] auto-detected URL to visit
--breakpoints 375,768,1280 Viewport widths, comma-separated
--wait 800 ms to wait after page load
--out ./src/bones Output directory
--force — Skip incremental cache
--watch — Re-capture on HMR changes
--native — React Native device scanning
--no-scan — Skip filesystem route scanning
--cdp — Connect to existing Chrome via debug port
--env-file — Load env vars from file

Props

Prop Type Default Description
loading boolean — Show skeleton or real content
name string — Unique name (generates name.bones.json)
color string rgba(0,0,0,0.08) Bone fill color
darkColor string rgba(255,255,255,0.06) Bone color in dark mode
animate 'pulse' | 'shimmer' | 'solid' 'pulse' Animation style
stagger number | boolean false Stagger delay between bones in ms (true = 80ms)
transition number | boolean false Fade out duration when loading ends (true = 300ms)
boneClass string — CSS class applied to each bone element
fixture ReactNode / Snippet / Slot — Mock content for CLI capture (dev only)
initialBones ResponsiveBones — Pass bones directly (overrides registry)
fallback ReactNode / Snippet / Slot — Shown when loading but no bones available

Config file

{
  "breakpoints": [375, 768, 1280],
  "out": "./src/bones",
  "wait": 800,
  "color": "#e5e5e5",
  "animate": "pulse"
}

Save as boneyard.config.json. Per-component props override config values.

Package exports

Import Use
boneyard-js snapshotBones, renderBones, computeLayout
boneyard-js/react React <Skeleton>
boneyard-js/preact Preact <Skeleton> (no compat needed)
boneyard-js/vue Vue <Skeleton>
boneyard-js/svelte Svelte <Skeleton>
boneyard-js/angular Angular <boneyard-skeleton>
boneyard-js/native React Native <Skeleton>
boneyard-js/vite Vite plugin boneyardPlugin()

Star History

Star History Chart

License

MIT

boneyard (0xGF/boneyard)

Searching Database…

7.5K ·GitHub
Boneyard
What is this?Boneyard generates pixel-perfect skeleton loading screens directly from your real UI, instead of you hand-drawing placeholder shapes.
Is it a library or does it also come with a CLI tool?It is a JavaScript library (with per-framework entry points) plus a CLI/Vite plugin that captures layout data by rendering your app in a headless browser.
How do I get it running in my app?Drop the component in wherever you'd render a loading boundary, run the CLI (or Vite plugin for Vite-based projects) to capture bones, then import the generated registry once in your app entry.
Which frameworks does it work with?React, Preact, Vue, Svelte 5, Angular, and React Native, each with a dedicated package export like boneyard-js/react or boneyard-js/vue.
Does bone capture work differently for React Native?Yes — on web, the CLI snapshots layout via a headless browser, while on React Native the component auto-scans in dev mode by walking the fiber tree and measuring views with UIManager; it has zero overhead in production either way.
Who would use this?Frontend developers building apps in React, Vue, Svelte, Angular, or React Native who want accurate loading skeletons without manually measuring layouts.
Does it handle text size changes on mobile?Yes, for React Native it generates bones at the default font scale and automatically scales bone positions at runtime to match the user's text size setting (Dynamic Type).
What animation styles are available for the skeleton bones?Bones support three animation styles via the animate prop: pulse (default), shimmer, and solid, plus optional stagger delays and fade-out transitions.
Can I provide mock content if a real query won't resolve in time during capture?Yes, pass a fixture prop with mock content so the CLI has something to measure during build-time capture if the real data can't load fast enough.
Does it re-capture bones automatically while developing?With the Vite plugin, bones are captured when the dev server starts and automatically re-captured on every HMR update; the CLI also supports a --watch flag for the same purpose.
What are similar projects?loadersz-core, storybook, blobatar, shaders, ng-native, pragmatic-drag-and-drop, mitosis, styled-components
Which topics is it in?svelte, angular, react-native, vite, javascript-library, vue, animation, ios, android, react, npm, frontend
Creator
0xGF
Size
1.2 MB
Stars
7.5K
Updated
CommitAug 31Releasev1.10.0Aug 31
Age
6mo
Commits · 90 Days