boneyard-svelte

Pixel-perfect skeleton loading screens for Svelte 5 and SvelteKit. Zero manual measurement — snapshots your real DOM layout and replays it as animated bones.

📦 Installation

Install the package using your preferred package manager:

npm install -D boneyard-svelte
# or
pnpm add -D boneyard-svelte
# or
bun add -d boneyard-svelte

Note: boneyard-svelte requires playwright to be installed to capture skeletons.

npm install -D playwright
npx playwright install chromium

⚡️ Vite Automation

We've integrated a custom Vite plugin to handle the bone generation lifecycle automatically.

1. Enable the Plugin

Add it to your vite.config.ts:

import { boneyard } from "boneyard-svelte/vite";

export default defineConfig({
  plugins: [
    // ...
    boneyard({ watchDir: "src/routes/blocks" }), // Required: Watches src/routes/blocks for changes
  ],
});

2. The "Blocks" Pattern

Instead of snapshotting your real app pages (which might be gated by auth), create mock UI templates in apps/web/src/routes/blocks/**.

• Automatic Sync: Every time you save a file in /blocks, the plugin re-crawls that route and updates src/bones/registry.js.
• Hot Reloading: Your browser will instantly reflect the updated skeleton bones.

✨ Features

🌓 Automatic Theme Sync

The <Skeleton> component automatically detects the theme by watching for the .dark class on the document element (compatible with mode-watcher).

📏 Intelligent Spacing

Bones are automatically shrunken by a few pixels (insets) during capture. This ensures that text lines and grid items have natural "gutters" and don't look like a solid block of color.

🚀 Usage

1. Register Bones (Startup)

Import the auto-generated registry once in your root +layout.svelte.

<script>
	import '../bones/registry';
</script>

2. Standalone Component

<script>
	import { Skeleton } from 'boneyard-svelte';
	let { loading, data } = $props();
</script>

<Skeleton name="my-card" {loading}>
	<div class="card">
		<h1>{data.title}</h1>
	</div>
</Skeleton>

🦴 Standard Bone Library

The package comes with several pre-registered skeletons for common UI patterns. You can use these immediately by name without any snapshotting:

| Name | Description | | ----------------- | ----------------------------------- | | activity | List of activity items with avatars | | calendar | Calendar grid or date-based list | | chat | Messaging interface with bubbles | | dashboard-stats | Grid of metric cards | | sidebar-nav | Vertical navigation list | | user-table | Data table rows | | chart-traffic | Generic line/bar chart placeholder |

⚙️ Configuration

| Prop | Type | Default | Description | | ----------- | --------- | ------------------------ | ---------------------------------------- | | loading | boolean | Required | Toggles the skeleton overlay | | name | string | — | The registry key to resolve bones from | | animate | boolean | true | Enables the pulse animation | | color | string | rgba(0,0,0,0.08) | Light mode base color | | darkColor | string | rgba(255,255,255,0.06) | Dark mode base color | | fixture | Snippet | — | Content shown ONLY during CLI build mode |