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.

intent

Use this skill to set up Motion Canvas projects from scratch and create programmatic animations using TypeScript, generator functions, and reactive signals. This skill covers the full project initialization, critical ESM/CommonJS interoperability fixes, and common troubleshooting. Apply it when you need to create animated videos with precise synchronization, build procedural graphics, or work with real-time preview workflows. The skill handles domain-specific knowledge about generator-based animation flows, signal reactivity, Canvas API integration, audio synchronization, and vector graphics rendering.

inputs

Environment & Dependencies:

• Node.js 18+ with npm or yarn
• @motion-canvas/core>=3.0.0 - Core animation engine
• @motion-canvas/2d>=3.0.0 - 2D rendering and components
• @motion-canvas/ui>=3.0.0 - Web UI editor (required, non-optional)
• @motion-canvas/vite-plugin>=3.0.0 - Vite plugin (CommonJS distribution, requires workaround)
• vite>=5.0.0 - Build tool and dev server
• typescript>=5.0.0 - TypeScript compiler
• Modern editor with TypeScript support (VSCode recommended)

Project Context:

• Target output format (mp4, webm, png sequence)
• Scene duration and frame rate requirements (default 60fps)
• Audio files for sync (if using voice-overs or background tracks)
• Custom component or third-party animation library needs (if any)

External Connections:

• None required. Vite dev server runs locally on port 5173 by default.

procedure

1. Initialize Project Directory

Input: Project name string. Action: Create project folder and initialize npm.

mkdir my-motion-canvas-project
cd my-motion-canvas-project
npm init -y

Output: Empty package.json file in project root.

2. Configure package.json for ESM

Input: Freshly initialized package.json. Action: Add "type": "module" to top level and configure build scripts.

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

Output: Updated package.json with ESM flag and npm scripts.

3. Install All Required Dependencies

Input: Updated package.json. Action: Run npm install with all required packages. Must include @motion-canvas/ui or the plugin will fail silently.

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

Output: node_modules/ directory and package-lock.json with all transitive dependencies resolved.

4. Create Project Directory Structure

Input: Project root directory. Action: Create subdirectories and placeholder files.

my-motion-canvas-project/
├── package.json
├── vite.config.js
├── tsconfig.json
├── index.html
└── src/
    ├── project.ts
    └── scenes/
        └── example.tsx

Output: Directory tree matching structure above (files created in steps 5-9).

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

Input: Project root directory. Action: Write Vite config in plain JavaScript (not TypeScript) using createRequire to load CommonJS plugin. Use .js extension, not .ts.

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',
    }),
  ],
});

Output: vite.config.js file at project root. Must be .js not .ts to avoid type resolution overhead.

6. Create tsconfig.json

Input: Project root directory. Action: Write TypeScript configuration with ESM interop flags set.

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

Output: tsconfig.json at project root with all required compiler options.

7. Create index.html

Input: Project root directory. Action: Write HTML entry point that loads the Motion Canvas project module.

<!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>

Output: index.html at project root.

8. Create src/project.ts

Input: /src directory. Action: Write project configuration that registers all scenes and exports to Motion Canvas runtime.

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

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

Output: src/project.ts file. Note the ?scene query parameter on scene imports (required by Vite plugin).

9. Create src/scenes/example.tsx

Input: /src/scenes directory. Action: Write first animation scene using generator syntax and Signal API.

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
  yield* circleRef().size(140, 1);
  // Animate position
  yield* circleRef().position.x(300, 1);
  // Animate color
  yield* circleRef().fill('#e6a700', 1);

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

Output: src/scenes/example.tsx file with working animation.

10. Start Development Server

Input: Initialized project with all files from steps 1-9. Action: Run Vite dev server.

npm run dev

Output: Dev server running at http://localhost:5173. Browser opens Motion Canvas editor with live preview. Hot module reloading active.

11. Build for Production

Input: Completed animation project. Action: Run Vite build command to generate output.

npm run build

Output: Compiled video file(s) in /dist directory (format depends on Motion Canvas export configuration).

decision points

If using a TypeScript Vite config (vite.config.ts):

• Problem: Adds type compilation overhead and can cause the createRequire workaround to fail.
• Decision: Switch to vite.config.js (plain JavaScript). Vite Vite config runs before TypeScript compilation, so plain JS is more reliable.

If you see TypeError: motionCanvas is not a function:

• Cause: Attempting standard ESM import of CommonJS @motion-canvas/vite-plugin.
• Decision: Apply the createRequire workaround in vite.config.js. Standard import will not work.

If you see Cannot find module '@motion-canvas/ui':

• Cause: Missing optional-looking but actually required dependency.
• Decision: Install @motion-canvas/ui immediately with npm install --save-dev @motion-canvas/ui. The plugin fails silently without it.

If you see Property 'default' does not exist on type ... during build:

• Cause: TypeScript configuration lacks ESM interop settings.
• Decision: Add "esModuleInterop": true and "allowSyntheticDefaultImports": true to tsconfig.json compilerOptions.

If you see Failed to resolve import "*.tsx?scene":

• Cause: Vite plugin not loaded, misconfigured project path, or missing ?scene query suffix.
• Decision: Check (1) vite.config.js loads plugin correctly using createRequire, (2) project path in plugin config points to correct file (default './src/project.ts'), (3) all scene imports use ?scene suffix like import example from './scenes/example?scene'.

If build fails with TypeScript errors:

• Cause: Missing or wrong tsconfig.json settings.
• Decision: Verify tsconfig.json includes all options from step 6, especially jsxImportSource: "@motion-canvas/2d/lib", target ES2020, module ES2020, and all compiler flags set correctly.

If you see The CJS build of Vite's Node API is deprecated warning:

• Status: Known warning. Safe to ignore.
• Cause: @motion-canvas/vite-plugin is CommonJS while Vite and Motion Canvas are ESM. The createRequire workaround handles it.
• Decision: No action needed. Functionality is unaffected.

If you need multiple scenes:

• Decision: Create additional .tsx files in /src/scenes/, import each with ?scene suffix, and add to scenes array in project.ts. Order in array determines playback order.

If you need to sync with audio:

• Decision: Place audio files in a public assets folder, import them in your scene, and use Motion Canvas audio sync APIs (documented in official Motion Canvas docs). Timing is typically managed via Signal-based duration tracking.

output contract

Successful project setup produces:

1. package.json with "type": "module" and all 6 required devDependencies listed.
2. vite.config.js (not .ts) with working createRequire workaround that runs without errors.
3. tsconfig.json with esModuleInterop: true, allowSyntheticDefaultImports: true, jsxImportSource: "@motion-canvas/2d/lib", and all other flags from step 6.
4. index.html with module script tag pointing to /src/project.ts.
5. src/project.ts exporting a valid makeProject() config with at least one scene imported via ?scene suffix.
6. At least one .tsx scene file in /src/scenes/ using makeScene2D(function* ...) generator syntax.
7. node_modules/ directory with all dependencies installed and resolvable.

File paths must match exactly:

• Dev server config: vite.config.js at root (not .ts).
• Project entry: src/project.ts (path referenced in vite.config.js).
• TypeScript config: tsconfig.json at root.
• HTML entry: index.html at root.
• Scene directory: src/scenes/ (recommended, not mandatory but expected).

Dev server must start cleanly:

• npm run dev launches without errors.
• Vite reports server running at http://localhost:5173.
• Browser loads Motion Canvas editor UI.
• Real-time preview renders the example animation without TypeScript or plugin errors.

Build must complete:

• npm run build completes without errors.
• Output written to dist/ directory (or configured output folder).

outcome signal

The skill worked if:

1. Running npm run dev opens the Motion Canvas editor in your browser at http://localhost:5173 with zero errors in terminal or console.

2. The editor UI displays your project with a live preview pane showing the example red circle animation on the left and timeline/playback controls on the right.

3. The example scene (red circle growing, moving, changing color, rotating) plays in the preview without glitches or console errors.

4. Editing src/scenes/example.tsx and saving the file triggers hot module reloading (HMR). The preview updates in real-time without requiring a manual refresh.

5. Running npm run build completes in under 30 seconds and produces compiled artifacts in the dist/ folder.

6. TypeScript in your editor shows zero errors on all imports from @motion-canvas/* packages.

7. No warnings about missing @motion-canvas/ui or unresolved ?scene queries appear in the console.

8. The createRequire workaround in vite.config.js executes without warnings or deprecation notices related to the plugin loader itself (the "CJS build deprecated" Vite message is expected and safe).