AGENT SKILL

motion-canvas

暂无简介

License 许可
MIT
最近更新
2026-09-12
Stars
★ 2
Forks
0

02 资源文件 3

03 SKILL.md 正文

Motion Canvas - Production-Ready Video Creation with TypeScript

Complete production-ready skill for creating programmatic videos using Motion Canvas, including critical ESM/CommonJS workarounds, full configuration templates, and comprehensive troubleshooting.

⚠️ CRITICAL: ESM/CommonJS Interoperability Issue

IMPORTANT: The @motion-canvas/vite-plugin package is distributed as CommonJS, which causes import errors in modern ESM projects. The standard import motionCanvas from '@motion-canvas/vite-plugin' WILL NOT WORK.

You MUST use the createRequire workaround documented in the Setup section below.

When to use

Use this skill whenever you are dealing with Motion Canvas code to obtain domain-specific knowledge about:

  • Creating animated videos using TypeScript and generator functions
  • Building animations with signals and reactive values
  • Working with vector graphics and Canvas API
  • Synchronizing animations with voice-overs and audio
  • Using the real-time preview editor for instant feedback
  • Implementing procedural animations with flow control
  • Creating informative visualizations and diagrams
  • Animating text, shapes, and custom components
  • Setting up Motion Canvas projects from scratch with correct configuration
  • Troubleshooting common setup and build errors

Core Concepts

Motion Canvas allows you to create videos using:

  • Generator Functions: Describe animations using JavaScript generators with yield* syntax
  • Signals: Reactive values that automatically update dependent properties
  • Real-time Preview: Live editor with instant preview powered by Vite
  • TypeScript-First: Write animations in TypeScript with full IDE support
  • Canvas API: Leverage 2D Canvas for high-performance vector rendering
  • Audio Synchronization: Sync animations precisely with voice-overs

Complete Setup Guide

Step 1: Initialize Project

# Create project directory
mkdir my-motion-canvas-project
cd my-motion-canvas-project

# Initialize package.json
npm init -y

Step 2: Configure package.json for ESM

CRITICAL: Add "type": "module" to enable ESM imports.

{
  "name": "my-motion-canvas-project",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Step 3: Install ALL Required Dependencies

CRITICAL: Must include @motion-canvas/ui - the plugin will fail without it.

npm install --save-dev @motion-canvas/core @motion-canvas/2d @motion-canvas/vite-plugin @motion-canvas/ui vite typescript

Step 4: Create Project Structure

my-motion-canvas-project/
├── package.json          # "type": "module" required
├── vite.config.js        # Use .js NOT .ts (see Step 5)
├── tsconfig.json         # TypeScript configuration
├── index.html            # HTML entry point
└── src/
    ├── project.ts        # Project configuration with scenes
    └── scenes/
        └── example.tsx   # Animation scene

Step 5: Create vite.config.js with ESM/CommonJS Workaround

CRITICAL: Use vite.config.js (NOT .ts) with the createRequire workaround.

File: vite.config.js

import {defineConfig} from 'vite';
import {createRequire} from 'module';

// WORKAROUND: @motion-canvas/vite-plugin is CommonJS, must use require
const require = createRequire(import.meta.url);
const motionCanvasModule = require('@motion-canvas/vite-plugin');
const motionCanvas = motionCanvasModule.default || motionCanvasModule;

export default defineConfig({
  plugins: [
    motionCanvas({
      project: './src/project.ts',
    }),
  ],
});

Why .js instead of .ts?

  • Vite config runs before TypeScript compilation
  • The createRequire workaround works reliably in plain JavaScript
  • Avoids additional type resolution complexity

Step 6: Create tsconfig.json

CRITICAL: Include esModuleInterop and allowSyntheticDefaultImports.

File: tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ES2020",
    "lib": ["ES2020", "DOM"],
    "jsx": "react-jsx",
    "jsxImportSource": "@motion-canvas/2d/lib",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Step 7: Create index.html

File: index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Motion Canvas Project</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="/src/project.ts"></script>
</body>
</html>

Step 8: Create src/project.ts

File: src/project.ts

import {makeProject} from '@motion-canvas/core';
import example from './scenes/example?scene';

export default makeProject({
  scenes: [example],
});

Step 9: Create First Animation Scene

File: src/scenes/example.tsx

import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
import {Circle} from '@motion-canvas/2d/lib/components';
import {createRef} from '@motion-canvas/core/lib/utils';
import {all} from '@motion-canvas/core/lib/flow';

export default makeScene2D(function* (view) {
  const circleRef = createRef<Circle>();

  view.add(
    <Circle
      ref={circleRef}
      size={70}
      fill="#e13238"
    />,
  );

  // Animate circle size and position
  yield* circleRef().size(140, 1);
  yield* circleRef().position.x(300, 1);
  yield* circleRef().fill('#e6a700', 1);

  // Parallel animations
  yield* all(
    circleRef().scale(1.5, 0.5),
    circleRef().rotation(360, 1)
  );
});

Step 10: Run Development Server

npm run dev

Open browser at http://localhost:5173 to see the Motion Canvas editor.

Troubleshooting

Error: TypeError: motionCanvas is not a function

Cause: ESM/CommonJS interoperability issue with @motion-canvas/vite-plugin

Solution: Use the createRequire workaround in vite.config.js (see Step 5)

// ❌ WRONG - Will not work
import motionCanvas from '@motion-canvas/vite-plugin';

// ✅ CORRECT - Use createRequire
import {createRequire} from 'module';
const require = createRequire(import.meta.url);
const motionCanvasModule = require('@motion-canvas/vite-plugin');
const motionCanvas = motionCanvasModule.default || motionCanvasModule;

Error: Cannot find module '@motion-canvas/ui'

Cause: Missing required dependency

Solution: Install the UI package:

npm install --save-dev @motion-canvas/ui

Error: Property 'default' does not exist on type ...

Cause: TypeScript configuration missing ESM interop settings

Solution: Add to tsconfig.json:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Warning: The CJS build of Vite's Node API is deprecated

Status: This is a known warning and can be safely ignored. It appears because @motion-canvas/vite-plugin is CommonJS. The workaround ensures functionality despite the warning.

Error: Failed to resolve import "*.tsx?scene"

Cause: Vite plugin not properly loaded or configured

Solution:

  1. Verify vite.config.js has the correct workaround
  2. Check project path points to correct file: './src/project.ts'
  3. Ensure scene imports use ?scene suffix: import example from './scenes/example?scene';

Build fails with TypeScript errors

Solution:

  1. Verify tsconfig.json includes all required options (see Step 6)
  2. Check jsxImportSource is set to @motion-canvas/2d/lib
  3. Ensure all dependencies are installed

How to use

Read individual rule files for detailed explanations and code examples:

Core Animation Concepts

For additional topics like scenes, shapes, text rendering, audio synchronization, and advanced features, refer to the comprehensive Motion Canvas official documentation.

Complete Working Example

This is a complete, tested project structure that works out of the box:

my-motion-canvas-project/
├── package.json
│   {
│     "name": "my-motion-canvas-project",
│     "type": "module",
│     "scripts": {
│       "dev": "vite",
│       "build": "vite build"
│     },
│     "devDependencies": {
│       "@motion-canvas/core": "^3.0.0",
│       "@motion-canvas/2d": "^3.0.0",
│       "@motion-canvas/vite-plugin": "^3.0.0",
│       "@motion-canvas/ui": "^3.0.0",
│       "vite": "^5.0.0",
│       "typescript": "^5.0.0"
│     }
│   }
│
├── vite.config.js (with createRequire workaround)
├── tsconfig.json (with esModuleInterop)
├── index.html
└── src/
    ├── project.ts (makeProject with scenes array)
    └── scenes/
        └── example.tsx (makeScene2D with animations)

Best Practices

  1. Always use the createRequire workaround - Don't try standard ESM imports for the Vite plugin
  2. Use vite.config.js not .ts - Avoids additional compilation complexity
  3. Include all dependencies - Don't forget @motion-canvas/ui
  4. Use generator functions - All scene animations should use function* and yield* syntax
  5. Leverage signals - Create reactive dependencies between properties
  6. Think in durations - Specify animation duration in seconds as the second parameter
  7. Use refs for control - Create references to nodes for precise animation control
  8. Preview frequently - Take advantage of the real-time editor for instant feedback
  9. Organize scenes - Break complex animations into multiple scenes
  10. Type everything - Use TypeScript for better IDE support and fewer errors

Common Pitfalls to Avoid

  1. ❌ Forgetting "type": "module" in package.json
  2. ❌ Using standard import for @motion-canvas/vite-plugin
  3. ❌ Not installing @motion-canvas/ui
  4. ❌ Missing esModuleInterop in tsconfig.json
  5. ❌ Using vite.config.ts instead of vite.config.js
  6. ❌ Forgetting ?scene suffix in scene imports

Resources

04 同仓库更多 Skills

Carchaloneo22
Carchaloneo22/Claude-Code-template

zapier-make-patterns

No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity - these platforms have their own patterns, pitfalls, and breaking points. This skill covers when to use which platform, how to build reliable automations, and when to graduate to code-based solutions. Key insight: Zapier optimizes for simplicity and integrations (7000+ apps), Make optimizes for power

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

yeet

Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

workflow-automation

Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, workflows resume exactly where they left off. This skill covers the platforms (n8n, Temporal, Inngest) and patterns (sequential, parallel, orchestrator-worker) that turn brittle scripts into production-grade automation. Key insight: The platforms make different tradeoffs. n8n optimizes for accessibility

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

trigger-dev

Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background task, ai background job, long running task.

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

planning-with-files

Transforms workflow to use Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when the user mentions planning, organizing work, tracking progress, or wants structured output.

★ 2
Carchaloneo22
Carchaloneo22/Claude-Code-template

n8n-workflow-patterns

Proven workflow architectural patterns from real n8n workflows. Use when building new workflows, designing workflow structure, choosing workflow patterns, planning workflow architecture, or asking about webhook processing, HTTP API integration, database operations, AI agent workflows, or scheduled tasks.

★ 2