ClipMotion

ClipMotion is a CLI tool that turns animation ideas from real‑world videos (Instagram reels, TikTok, YouTube, etc.) into reusable components for modern web frameworks.

You can:

• Add ready‑made animation components to your project
• Generate a registry of components from source files
• Find components by video URL
• Scaffold new components for contributors using a shared structure

✨ Features

• clipmotion init – initialize project config and paths
• clipmotion add – add animation components to your project
• clipmotion find – find components by video URL (Instagram, TikTok, YouTube, …)
• clipmotion create – scaffold new components for contribution
• clipmotion registry:build – build JSON registry used by the CLI

Supports multiple frameworks:

• Next.js
• React
• Vue
• Angular

📦 Installation

# Global install (recommended for day-to-day use)
npm install -g clipmotion

# Or with pnpm
pnpm add -g clipmotion

# Or with yarn
yarn global add clipmotion

You can also run it via npx without global install:

npx clipmotion --help

Testing

ClipMotion includes comprehensive test suites to ensure reliability.

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:cli          # Unit tests only
npm run test:registry     # registry tests only
npm run test:e2e          # End-to-end tests only

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

CI/CD

Tests run automatically on every push and pull request via GitHub Actions. View the workflow status in the Actions tab.

🚀 Getting Started (User Flow)

1. Initialize ClipMotion in your project

clipmotion init

This will:

• Detect your framework (Next.js, React, Vue, Angular)
• Create clipmotion-components.json with:
  • framework
  • aliases.components
  • aliases.utils
  • registry.baseUrl (points to the hosted JSON registry)

Example config:

{
  "$schema": "https://clipmotion.dev/schema.json",
  "framework": "nextjs",
  "aliases": {
    "components": "components",
    "utils": "components/utils"
  },
  "registry": {
    "baseUrl": "https://raw.githubusercontent.com/nerdboi008/clipmotion/main/public/r"
  }
}

Note: Utils are placed inside the components folder by default to avoid conflicts with existing lib/utils files in your project.

2. Add a component

clipmotion add blur-image-toggle

This will:

• Fetch the component definition from the registry
• Install any required npm dependencies
• Write component files to your configured components alias

Options:

clipmotion add blur-image-toggle --overwrite      # overwrite files if they exist
clipmotion add blur-image-toggle --debug          # verbose logs
clipmotion add blur-image-toggle --path src/ui    # custom target path

Framework Override

By default, Clipmotion installs components for the framework defined in your configuration.

If a component is not available for your current framework, you can override it:

clipmotion add blur-toggle --framework react

Example: Your project is Next.js, but the component only exists for React:

clipmotion add some-component --framework react

Installing Multiple Components

You can install multiple components in a single command:

clipmotion add blur-toggle fade-in --framework vue

Helpful Suggestions

If a component is not available for the selected framework, the CLI will:

• Detect available frameworks for that component
• Suggest compatible alternatives
• Provide clear, actionable error messages

This ensures you always know what’s available and how to proceed.

3. Find a component by video URL

If you saw an animation in a reel / short / TikTok and it’s in the registry:

clipmotion find https://www.instagram.com/p/DRPOaKMiItG/

The command will:

• Look up the URL in the registry index
• Show details (name, difficulty, supported frameworks, tags)
• Let you choose to:
  • Install the component
  • View demo
  • See implementation guide

You can also auto‑install:

clipmotion find <video-url> --install

🔧 Handling Utils Files

ClipMotion components may depend on shared utilities like cn() (className merger).

How it works:

1. First component with utils → Creates components/utils/index.ts
2. Second component with utils → Merges new functions into existing file (if not duplicate)
3. Duplicate functions → Skipped automatically

Example:

clipmotion add blur-toggle
# Creates components/utils/index.ts with cn()

clipmotion add fade-in
# Merges any new utils into components/utils/index.ts
# Skips cn() if already present

Manual override:

clipmotion add component-name --overwrite
# Replaces utils file entirely (use with caution)

🧱 Repository Structure (For Contributors)

In this repo, source components live in registry/ and are compiled into JSON under public/r/ for the CLI.

registry/
├── nextjs/
│   ├── ui/           # Next.js components
│   ├── lib/          # Shared utilities (optional)
│   └── hooks/        # Hooks (optional)
├── react/
├── vue/
└── angular/

public/
└── r/
    ├── nextjs/       # Generated JSON for Next.js components
    ├── react/
    ├── vue/
    ├── angular/
    └── index.json    # Registry index used by `clipmotion find`

The CLI commands use:

• registry/* as the source of truth
• public/r/* as the runtime registry for installs

🛠 CLI Commands

clipmotion init

Initialize ClipMotion in an existing project.

• Detects framework from files (next.config.*, angular.json, vite.config.*, package.json)
• Asks for confirmation or manual choice if needed
• Sets default component + utils paths
• Installs framework‑specific deps (clsx, tailwind-merge, etc., where relevant)

clipmotion add

Add one or more components from the registry:

clipmotion add <components...>

Supports:

• Registry dependencies (other internal components/utils)
• npm dependencies and devDependencies
• Overwrite checks for existing files
• Debug logging

clipmotion find

Find and optionally install a component by video URL:

clipmotion find <video-url> [options]

• Matches normalized URLs against public/r/index.json
• Shows metadata and next steps (install / demo / guide)

clipmotion create

Scaffold a new component inside this repo for contributors:

clipmotion create <component-name>

The command will:

• Ask for framework, video URL, description, category, difficulty
• Create:
  • registry/<framework>/ui/<component-name>.tsx|.vue
  • registry/<framework>/examples/<component-name>.tsx|.vue
  • registry/<framework>/<component-name>.README.md
  • registry/<framework>/CONTRIBUTING.md (if missing)

This is the recommended way for contributors to start a new animation.

clipmotion registry:build

Build the JSON registry used by add and find:

clipmotion registry:build

What it does:

• Scans registry/<framework>/ui, lib, hooks
• Extracts:
  • Files
  • npm dependencies
  • dev dependencies
  • registry dependencies (e.g., @/lib/utils)
• Emits public/r/<framework>/*.json with a RegistryItem structure
• Generates public/r/index.json with:
  • List of animations
  • Framework support
  • Basic metadata
  • lastUpdated timestamp

🤝 Contributing

Contributions are welcome and encouraged.

• Read the CONTRIBUTING.md for:

  • Local setup
  • Component creation flow
  • Registry build process
  • PR checklist

• Please also review the Code of Conduct.

Typical flow for adding a new animation:

# 1. Create component scaffold
clipmotion create blur-image-toggle

# 2. Implement animation in registry/<framework>/ui/...
# 3. Build registry
clipmotion registry:build

# 4. Test installation in a sample project
clipmotion init
clipmotion add blur-image-toggle

# 5. Commit & open a PR

🧪 Development

Run the CLI locally without global install:

# From repo root
npm install
npm run build    # if applicable
node build/index.cjs --help

Or with a local link:

npm link
clipmotion --help

📄 License

This project is open‑source under the MIT License.
See LICENSE for details.

🙌 Acknowledgements

• Inspired by tools like shadcn/ui and other component CLIs
• Built to help developers quickly recreate and share animations seen in the wild

If you build something with ClipMotion, consider sharing it and linking back to the repo so others can discover it too.