Getting Started

Consumer-first guide for installing the runtime package, generating artifacts at build time, and letting AutoSkeleton use them at runtime.

1. Install the runtime package

Use the single published package in your app

Runtime

bash

# Install the single published package
pnpm add @ghostframes/runtime

# Use the runtime surface in your app
import { AutoSkeleton, GhostframesProvider } from "@ghostframes/runtime";

2. Add build-time generation commands

Keep the consumer surface to generation plus validation

Build time

json

{
  "scripts": {
    "skeleton:generate": "ghostframes capture --config ghostframes.capture.config.mjs",
    "skeleton:validate": "ghostframes validate --manifest .ghostframes/generated/manifest.json --json-out .ghostframes/validate.json",
    "prebuild": "pnpm skeleton:generate",
    "build": "next build"
  }
}

3. Ship the generated artifacts

The app deploys the manifest and loader, not the expensive generation pipeline

Deploy

The consumer app should bundle the generated files alongside the app so runtime only needs to read and resolve them.

bash

# Build-time artifacts produced by the consumer app
.ghostframes/generated/manifest.json
.ghostframes/generated/manifest-loader.ts
.ghostframes/validate.json
.ghostframes/diff.json
.ghostframes/report.json

4. Wire AutoSkeleton at runtime

Provide the generated manifest once, then render by skeleton key

Runtime

GhostframesProvider makes the manifest available to the tree.
AutoSkeleton resolves the matching blueprint by skeletonKey.
When the manifest has a hit, the precomputed skeleton renders immediately.
When it misses or is invalid, AutoSkeleton falls back to live measurement or the configured fallback path.

tsx

import { AutoSkeleton, GhostframesProvider } from "@ghostframes/runtime";
import generatedManifest from "../.ghostframes/generated/manifest-loader";

export function AppShell({ loading }: { loading: boolean }) {
  return (
    <GhostframesProvider manifest={generatedManifest} policy={{ mode: "hybrid" }}>
      <AutoSkeleton loading={loading} skeletonKey="ProductCard">
        <ProductCard />
      </AutoSkeleton>
    </GhostframesProvider>
  );
}

Minimal consumer contract

The recommended public surface stays small

2 commands

skeleton:generate creates the manifest and loader during prebuild or CI.
skeleton:validate gates the generated output before deployment.
build remains the app build only and should not own capture logic.
report stays optional for deeper CI diagnostics or debugging sessions.

End-to-end flow

One view of the full consumer app lifecycle

Checklist

text

1. Install @ghostframes/runtime in the consumer app.
2. Run skeleton:generate and skeleton:validate before the app build.
3. Ship the generated manifest and loader with the app bundle.
4. Let AutoSkeleton resolve from the manifest first, then fall back only when needed.