Motion Canvas

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.