CellForge

CellForge is an open-source loader system for React teams. It ships animated cell-based loading primitives, a live tuning studio, and a shadcn-style registry so teams can install editable source code instead of adding another runtime package.

• Website: https://cellforge.dev
• Repository: https://github.com/cellforge-dev/cellforge
• License: MIT
• Current distribution: shadcn-style source registry and npm runtime package
• npm package: cellforge-loaders

What You Get

• 71 installable loader items generated from the local registry.
• A gallery for browsing loader families and quick install commands.
• Studio for tuning color, shape, pattern, size, speed, padding, frames, and generated code.
• Playground for deeper prop experiments.
• Manual setup docs for teams that cannot use the shadcn CLI.
• Reduced-motion handling and CSS-only animation paths for shipped loaders.

Install A Loader

The recommended path is the shadcn registry. Add CellForge to components.json:

{
  "registries": {
    "@cellforge": "https://cellforge.dev/r/{name}.json"
  }
}

Then install a loader:

npx shadcn@latest add @cellforge/cell-square-3

Or install directly from the public registry URL:

npx shadcn@latest add https://cellforge.dev/r/cell-square-3.json

Install the complete set:

npx shadcn@latest add @cellforge/all

Basic Usage

Installed loaders are local files in your app, usually under components/ui.

import { CellSquare3 } from "@/components/ui/cell-square-3";

export function SaveButton({ isSaving }: { isSaving: boolean }) {
  return (
    <button type="button" disabled={isSaving} aria-busy={isSaving}>
      {isSaving ? <CellSquare3 size={18} dotSize={3} ariaLabel="Saving" /> : null}
      <span>{isSaving ? "Saving..." : "Save changes"}</span>
    </button>
  );
}

npm Runtime Package

Use the npm package when you prefer a normal React dependency instead of copying source through the registry.

npm install cellforge-loaders

Import the package CSS once in your app:

import "cellforge-loaders/styles.css";

Then import any loader component:

import { CellSquare3 } from "cellforge-loaders";

export function SaveButton({ isSaving }: { isSaving: boolean }) {
  return (
    <button type="button" disabled={isSaving} aria-busy={isSaving}>
      {isSaving ? <CellSquare3 size={18} dotSize={3} ariaLabel="Saving" /> : null}
      <span>{isSaving ? "Saving..." : "Save changes"}</span>
    </button>
  );
}

The package keeps the original Dotm* exports and also exposes CellForge aliases such as CellSquare3, CellOrbit1, CellAngle1, and CellLattice1.

Manual Setup

Use manual setup when the shadcn CLI is not available or your project has a custom folder layout. Copy these files first:

components/ui/cellforge-core.tsx
components/ui/cellforge-hooks.ts
components/cellforge-loader.css
components/ui/cell-square-3.tsx

Then import the CSS once from your global stylesheet if your setup does not do it automatically:

@import "../components/cellforge-loader.css";

The full source snippets are documented at https://cellforge.dev/getting-started/manual.

Local Development

pnpm install
pnpm dev

Useful checks:

pnpm lint
pnpm typecheck
pnpm test
pnpm registry:build
pnpm smoke:consumer
pnpm build

Run the full local validation set:

pnpm check

Build registry files with production metadata:

REGISTRY_HOMEPAGE=https://cellforge.dev pnpm registry:build

On Windows PowerShell:

$env:REGISTRY_HOMEPAGE="https://cellforge.dev"; pnpm registry:build

Project Structure

app/                  Next.js routes for the site, docs, studio, and playground
components/           Site UI and shared editor/gallery controls
loaders/              Source loader primitives and tests
lib/                  Registry metadata, source transforms, and helpers
public/r/             Generated shadcn registry files
public/brand/         Logo and wordmark assets
scripts/              Registry build and consumer smoke checks

Publishing Model

CellForge supports two install models:

• https://cellforge.dev/r/* for shadcn-style source installs.
• cellforge-loaders for npm runtime imports.

The npm package publishes only dist, README.md, and LICENSE. React is a peer dependency, and site-only packages such as Next.js are kept out of the runtime dependency graph.

Repository Health

• CI validates lint, typecheck, tests, registry generation, consumer smoke checks, and production build.
• Issues are enabled for bugs and feature requests.
• Security policy is documented in SECURITY.md.
• Release checklist is documented in docs/release-checklist.md.

License

MIT. See LICENSE.