Install

Get up and running with hollows-ui in under five minutes. Install the package, create a config file, and run your first build.

Prerequisites

  • Node.js 18 or later
  • A React, Vue, Svelte, or Angular project with components that render data
  • A dev server that can be started via a CLI command (e.g. npm run dev)

Install the package

Install hollows-ui as a dev dependency. The CLI runs at build time only — nothing is added to your production bundle except the tiny runtime adapter (~2 KB gzipped).

npm
bash
npm install --save-dev hollows-ui
yarn
bash
yarn add --dev hollows-ui
pnpm
bash
pnpm add -D hollows-ui

The package includes the CLI, the AST scanner, the Playwright-based analyzer, and all framework adapters. Playwright browsers are installed automatically on first run.

Framework adapter

Import the adapter for your framework. Each adapter provides a <Hollow> component that reads from the generated registry at runtime.

React
tsx
import { Hollow } from 'hollows-ui/react'
Vue
tsx
import { Hollow } from 'hollows-ui/vue'
Svelte
tsx
import { Hollow } from 'hollows-ui/svelte'
Angular
tsx
import { HollowComponent } from 'hollows-ui/angular'

Configuration file

Create a hollows.config.ts file in your project root. This tells the CLI where your source files live and how to start your dev server.

hollows.config.ts
typescript
1import { defineConfig } from 'hollows-ui'23export default defineConfig({4  // Glob patterns to scan for <Hollow> components5  include: ['src/**/*.tsx', 'src/**/*.vue', 'src/**/*.svelte'],67  // Files to ignore8  exclude: ['src/**/*.test.*', 'src/**/*.stories.*'],910  // Dev server command and URL11  devServer: {12    command: 'npm run dev',13    url: 'http://localhost:3000',14    readyPattern: 'ready on',15  },1617  // Output directory for generated assets18  outDir: 'src/hollows',1920  // Theme configuration21  theme: {22    mode: 'dark',23    accentColor: '#f0a030',24    borderRadius: 12,25    fontFamily: 'inherit',26  },2728  // Illustration style29  illustrations: {30    style: 'line',    // 'line' | 'flat' | 'outline' | 'custom'31    color: 'accent',  // Use accent color for illustrations32  },33})

You can also use a hollows.config.js or hollows.config.mjs file. The CLI auto-detects the format. You can also use the --config flag to specify a custom path.

To generate the config file interactively, run:

Terminal
bash
npx hollows-ui init

First build

With your config in place and at least one <Hollow> component in your source code, run the build command:

Terminal
bash
npx hollows-ui build

You should see output similar to:

Terminal output
bash
  hollows-ui v1.0.0  Scanning...    Found 4 hollows in 12 files  Launching browser...    Dev server ready at http://localhost:3000  Analyzing...    user-inbox      → list       (confidence: 0.94)    search-results  → search     (confidence: 0.89)    file-gallery    → upload     (confidence: 0.91)    analytics-panel → dashboard  (confidence: 0.87)  Generating...    4 empty states generated    4 illustrations selected  Writing...    src/hollows/.hollows.json    src/hollows/registry.js    src/hollows/illustrations/inbox-empty.svg    src/hollows/illustrations/search-empty.svg    src/hollows/illustrations/upload-empty.svg    src/hollows/illustrations/dashboard-empty.svg  Done in 3.2s

Finally, import the registry in your app entry point so the <Hollow> components can resolve their definitions at runtime:

app/layout.tsx (Next.js) or main.tsx (Vite)
tsx
// Import the generated registry — this registers all empty statesimport './hollows/registry'

CI integration

You can run the build step in CI to keep your empty states up to date with every deploy. Add it to your build script in package.json:

package.json
json
{  "scripts": {    "build": "hollows-ui build && next build",    "hollows": "hollows-ui build",    "hollows:watch": "hollows-ui build --watch"  }}

The --watch flag re-runs the build whenever a file containing a <Hollow> component changes. This is useful during development.

Terminal
bash
npx hollows-ui build --watch
Previous
How it works
Next
Output