Contributing

Add a component

Contributing is simple: add your folder, run one command, verify on /components. Everything else on this page is reference.

Quick checklist

Run through this before you open a PR. This is the only flow you need to remember.

  • Added meta.ts
  • Added demo.tsx
  • Added ui/ folder (if the component has local UI files)
  • Added preview at public/previews/{category}/{slug}/preview.mov (compressed to under 5MB)
  • Ran npm run build:registry
  • Ran npm run lint
  • Ran npm run test
  • Responsive on mobile and desktop
  • No console.log
  • No hardcoded secrets or API keys
  • No unnecessary dependencies
  • Tested on localhost/components before pushing

Example: sameer-hero

  1. 1

    Create the component folder

    Create a folder under content/registry/hero-sections/sameer-hero
  2. 2

    Add your source files

    • • meta.ts in the sameer-hero folder
    • • demo.tsx in the same folder
    • • ui/ — add any local UI files inside sameer-hero/ui/
  3. 3

    Add the gallery preview video

    Add public/previews/hero-sections/sameer-hero/preview.mov
  4. 4

    Build the registry

    Run npm run build:registry
  5. 5

    Verify it appears

    Open /components and confirm your card shows up
  6. 6

    Test locally before pushing

    Check localhost:3000/components/sameer-hero — live demo, install command, and code tabs should all work

Folder structure

content/registry/
└ hero-sections/
  └ sameer-hero/
    ├ meta.ts
    ├ demo.tsx
    └ ui/
      └ (optional local components)

public/previews/
└ hero-sections/
  └ sameer-hero/
    └ preview.mov

Naming rules

  • Use lowercase kebab-case (e.g. sameer-hero).
  • meta.slug must match the folder name exactly.
  • Category today is hero-sections — more categories will appear in the sidebar as they are added.

Preview video

Every component needs a lightweight preview.mov (or .mp4). The gallery at /components plays it on hover — no live WebGL in the grid. Full demo runs on the detail page. Keep the video under 5MB — compress with ffmpeg -i preview.mov -vf scale=1280:-2 -r 30 -c:v libx264 -crf 23 -preset fast -movflags +faststart -an preview.mov before committing.

Example meta.ts

export const meta = {
  slug: "sameer-hero",
  title: "Sameer Hero",
  description: "Your one-line description for the gallery and detail page.",
  category: "hero-sections",
  preview: "/previews/hero-sections/sameer-hero/preview.mov",
  github: "your-github-username",
  tags: ["hero", "motion"],
  dependencies: ["framer-motion"],
  registryDependencies: [],
  version: 1,
} as const

Commands

Install component (shadcn CLI)

npx shadcn@latest add https://zepa.design/r/amero-hero.json

Install dependencies (if listed in meta.ts)

npm install framer-motion lucide-react

After adding or updating a component

npm run build:registry

Local dev

npm run dev

Lint & test

npm run lint
npm run test

Playground (optional)

/playground/hero?slug=sameer-hero

What gets generated for you

Never edit these by hand — npm run build:registry overwrites them:

  • content/registry/items.ts
  • content/registry/loaders.ts
  • content/registry/registry.json
  • public/r/{slug}.json

Common mistakes

  • • meta.slug does not match folder name
  • • Missing demo.tsx → demo not found
  • • Missing preview → card hidden from /components
  • • Skipping npm run build:registry before pushing
  • • Using position: fixed in demos — breaks the split layout on the detail page (use absolute inside a relative root)

After deploy

Users can install via shadcn once public/r/your-slug.json is deployed:

npx shadcn@latest add https://zepa.design/r/amero-hero.json

License

Build anything you want with Zepa. Just don't repackage Zepa itself.

You can

  • Use Zepa in unlimited personal & commercial projects
  • Ship it in websites, apps, SaaS, and client work
  • Copy, modify, and customize the components freely

You can't

  • Sell or redistribute the components themselves
  • Republish them — alone, bundled, or as a ported version
  • Include them in another component library, kit, or template

Licensed under MIT + Commons Clause. Free to use, not to resell.