Motion Canvas Video

Motion Canvas — Production-Ready Video Creation with TypeScript

Create programmatic videos with Motion Canvas: TypeScript animations built from generator functions and reactive signals, previewed live via Vite. Includes the critical ESM/CommonJS setup workaround.

CRITICAL: ESM/CommonJS Interop

@motion-canvas/vite-plugin is distributed as CommonJS, so the plain import motionCanvas from '@motion-canvas/vite-plugin' will not work in ESM projects (throws TypeError: motionCanvas is not a function). You must load it with createRequire (shown below).

Core Concepts

• Generator functions: describe animations with function* and yield* — each yield* awaits a tween.
• Signals: reactive values that auto-update dependent properties.
• Real-time preview: live Vite-powered editor for instant feedback.
• Canvas API + TypeScript-first: high-performance 2D vector rendering, fully typed.
• Audio sync: align animations precisely with voice-overs.

Setup

1. Init & enable ESM — npm init -y, then in package.json set "type": "module" and scripts { "dev": "vite", "build": "vite build" }.

2. Install ALL deps (omitting @motion-canvas/ui makes the plugin fail):

npm i -D @motion-canvas/core @motion-canvas/2d @motion-canvas/vite-plugin @motion-canvas/ui vite typescript

3. vite.config.js (use .js, NOT .ts — config runs before TS compilation, and the require workaround is reliable in plain JS):

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

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

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

4. tsconfig.json — must include esModuleInterop and allowSyntheticDefaultImports, and JSX from Motion Canvas:

{
  "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"]
}

5. index.html — a <div id="root"> and <script type="module" src="/src/project.ts">.

6. src/project.ts:

import {makeProject} from '@motion-canvas/core';
import example from './scenes/example?scene'; // note the ?scene suffix
export default makeProject({scenes: [example]});

7. First scene 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 circle = createRef<Circle>();
  view.add(<Circle ref={circle} size={70} fill="#e13238" />);

  yield* circle().size(140, 1);            // tween size over 1s
  yield* circle().position.x(300, 1);
  yield* all(                               // parallel tweens
    circle().scale(1.5, 0.5),
    circle().rotation(360, 1),
  );
});

8. Run — npm run dev, open http://localhost:5173.

Best Practices

1. Always use the createRequire workaround for the Vite plugin.
2. Use vite.config.js, not .ts.
3. Install @motion-canvas/ui — the plugin needs it.
4. Write all scene animation as function* / yield*.
5. Use signals for reactive property dependencies; use refs (createRef) for precise control.
6. Second tween arg is duration in seconds; use all() for parallel, sequence()/plain yield* for serial.
7. Preview frequently; split complex work into multiple scenes.

Troubleshooting

• motionCanvas is not a function → missing createRequire workaround.
• Cannot find module '@motion-canvas/ui' → install the UI package.
• Property 'default' does not exist ... → add esModuleInterop/allowSyntheticDefaultImports to tsconfig.
• Failed to resolve import "*.tsx?scene" → check the ?scene suffix and the plugin's project path.
• CJS build of Vite's Node API is deprecated → harmless warning from the CommonJS plugin; ignore.

Output

Return the scene .tsx plus the project config files (project.ts, vite.config.js, tsconfig.json, package.json with "type": "module") so the animation runs out of the box. Full API details: https://motioncanvas.io/docs.