Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@motion-canvas/core

motion-canvas2.3kMIT3.17.2TypeScript support: included

Web-based tool for creating animations programmatically

readme


<picture> <source media="(prefers-color-scheme: dark)" srcset="https://motion-canvas.github.io/img/logo_dark.svg"> Motion Canvas logo </picture>

published with lerna powered by vite npm package version discord


Motion Canvas

Motion Canvas is two things:

  • A TypeScript library that uses generators to program animations.
  • An editor providing a real-time preview of said animations.

It's a specialized tool designed to create informative vector animations and synchronize them with voice-overs.

Aside from providing the preview, the editor allows you to edit certain aspects of the animation which could otherwise be tedious.

Using Motion Canvas

Check out our getting started guide to learn how to use Motion Canvas.

Developing Motion Canvas locally

The project is maintained as one monorepo containing the following packages:

Name Description
2d The default renderer for 2D motion graphics
core All logic related to running and rendering animations.
create A package for bootstrapping new projects.
docs Our documentation website.
e2e End-to-end tests.
examples Animation examples used in documentation.
internal Internal helpers used for building the packages.
player A custom element for displaying animations in a browser.
template A template project included for developer's convenience.
ui The user interface used for editing.
vite-plugin A plugin for Vite used for developing and bundling animations.

After cloning the repo, run npm install in the root of the project to install all necessary dependencies. Then run npx lerna run build to build all the packages.

Developing Editor

When developing the editor, run the following command:

npm run template:dev

It will start a vite server that watches the core, 2d, ui, and vite-plugin packages. The template package itself contains a simple Motion Canvas project that can be used during development.

Developing Player

To develop the player, first build the template: npm run template:build. Then, start npm run player:dev.

Installing a local version of Motion Canvas in a project

It can be useful to install a local version of Motion Canvas in a standalone project. For example, when you want to use your own fork with some custom-made features to create your animations.

Let's assume the following project structure:

projects/
├── motion-canvas/ <- your local monorepo
└── my-project/ <- a bootstrapped project
    └── package.json

You can link the local packages from the monorepo by updating the package.json of your project. Simply replace the version with a file: followed by a relative path to the package you want to link:

  "dependencies": {
-   "@motion-canvas/core": "^3.11.0",
+   "@motion-canvas/core": "file:../motion-canvas/packages/core",
    // ...
  },

If you're linking the ui package, you'll also need to modify vite.config.ts to allow vite to load external files:

import {defineConfig} from 'vite';
import motionCanvas from '@motion-canvas/vite-plugin';

export default defineConfig({
  server: {
    fs: {
      // let it load external files
      strict: false,
    },
  },
  plugins: [motionCanvas()],
});

This is necessary because the editor styles are loaded using the /@fs/ prefix and since the linked ui package is outside the project, vite needs permission to access it.

Then run npm install in to apply the changes and that's it.

You can use the same technique to test out any custom package you're working on.

Contributing

Read through our Contribution Guide to learn how you can help make Motion Canvas better.

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.17.2 (2024-12-14)

Bug Fixes

  • core: fix incorrect rollup ordering (4743b92)
  • vite-plugin, ui: project file path on selection (#1090) (f15b375)

3.17.1 (2024-08-17)

Bug Fixes

3.17.0 (2024-08-13)

Bug Fixes

Features

  • 2d: use SVG component in Latex and support tweening (#800) (92a5659)
  • ui: add render and present url params (#631) (8209843)
  • vite-plugin: let plugins override config (#1054) (9b01eb5)

3.16.0 (2024-05-16)

Bug Fixes

Features

3.15.2 (2024-04-02)

Bug Fixes

3.15.1 (2024-03-21)

Bug Fixes

3.15.0 (2024-03-21)

Bug Fixes

Features

3.14.2 (2024-02-08)

Bug Fixes

3.14.1 (2024-02-06)

Bug Fixes

3.14.0 (2024-02-04)

Bug Fixes

Features

3.13.0 (2024-01-10)

Bug Fixes

Features

3.12.4 (2024-01-05)

Bug Fixes

Reverts

3.12.3 (2024-01-04)

Bug Fixes

3.12.2 (2023-12-31)

Bug Fixes

3.12.1 (2023-12-31)

Bug Fixes

3.12.0 (2023-12-31)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.11.0 (2023-10-13)

Bug Fixes

  • 2d: add missing Curve properties to Circle (#805) (38c7900)
  • 2d: point arrow heads in correct direction (#792) (52ed52e), closes #783
  • core: handle malicious event names (#819) (aba8eba)

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.10.1 (2023-07-25)

Bug Fixes

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.10.0 (2023-07-23)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.9.0 (2023-05-29)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.8.0 (2023-05-13)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.7.0 (2023-05-10)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.6.2 (2023-05-09)

Bug Fixes

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.6.1 (2023-05-08)

Bug Fixes

  • prevent consumePromises from halting (#657) (363a189)

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.6.0 (2023-05-08)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.5.1 (2023-04-08)

Bug Fixes

  • 2d: fix curve arrow alignment when animating start signal (#615) (2fefc40)

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.5.0 (2023-04-06)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.4.0 (2023-03-28)

Bug Fixes

Features

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.3.4 (2023-03-19)

Bug Fixes

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.3.3 (2023-03-18)

Bug Fixes

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.3.2 (2023-03-18)

Bug Fixes

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.3.1 (2023-03-18)

Bug Fixes

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.3.0 (2023-03-18)

Bug Fixes

Features

3.2.1 (2023-03-10)

Bug Fixes

3.2.0 (2023-03-10)

Bug Fixes

Features

3.1.0 (2023-03-07)

Bug Fixes

Features

3.0.2 (2023-02-27)

Bug Fixes

3.0.1 (2023-02-27)

Bug Fixes

3.0.0 (2023-02-27)

Bug Fixes

Code Refactoring

Features

Reverts

  • feat: upgrade code-fns for new theme options and lazy loading (#435) (3f5e439)

BREAKING CHANGES

  • multiple name changes

To avoid collisions, names of certain classes have changed:

  • Text => Txt
  • Image => Img
  • Rect (type) => BBox

Cache related methods of Node have changed:

  • getCacheRect => getCacheBBox
  • cacheRect => cacheBBox
  • fullCacheRect => fullCacheBBox

The CodeBlock property has changed:

  • CodeBlock.selectionOpacity => CodeBlock.unselectedOpacity

  • makeProject no longer accepts some settings.

Settings such as background and audioOffset are now stored in the project meta file.

2.6.0 (2023-02-24)

Bug Fixes

  • 2d: handle division by zero in lines (#407) (a17871a)

Features

2.5.0 (2023-02-20)

Bug Fixes

Features

2.4.0 (2023-02-18)

Bug Fixes

Features

2.3.0 (2023-02-11)

Bug Fixes

Features

  • 2d: add antialiased signal to Shape (#282) (7c6905d)
  • 2d: add LaTeX component (#228) (4c26d2a)
  • 2d: add smooth corners and sharpness to rect (#310) (f7fbefd)
  • added a theme property to the CodeBlock component (#279) (fe34fa8)
  • core: add debug helper function (#293) (b870873)
  • core: additional easing functions (#274) (f81ce43)
  • core: disallow tweening to/from undefined values (#257) (d4bb791)
  • docs: always re-build api references in build mode (#298) (27a4d96), closes #294

2.2.0 (2023-02-09)

Features

2.1.0 (2023-02-07)

Bug Fixes

Features

2.0.0 (2023-02-04)

Bug Fixes

Code Refactoring

Features

Reverts

BREAKING CHANGES

  • remove legacy package
  • change names of timing and interpolation functions

TweenFunction is now called InterpolationFunction. Individual functions are now called [type]Lerp instead of [type]Tween. For instance: colorTween is now colorLerp.

InterpolationFunction is now called TimingFunction. This name is better aligned with the CSS spec.

  • change to import paths

See the migration guide for more info.

  • change the way scenes are imported

Scene files no longer need to follow the pattern: [name].scene.tsx. When importing scenes in the project file, a dedicated ?scene query param should be used:

import example from './scenes/example?scene';

export default new Project({
  name: 'project',
  scenes: [example],
});
  • change the overall structure of a project

vite and @motion-canvas/vite-plugin packages are now required to build a project:

npm i -D vite @motion-canvas/vite-plugin

The following vite.config.ts file needs to be created in the root of the project:

import {defineConfig} from 'vite';
import motionCanvas from '@motion-canvas/vite-plugin';

export default defineConfig({
  plugins: [motionCanvas()],
});

Types exposed by Motion Canvas are no longer global. An additional motion-canvas.d.ts file needs to be created in the src directory:

/// <reference types="@motion-canvas/core/project" />

Finally, the bootstrap function no longer exists. Project files should export an instance of the Project class instead:

import {Project} from '@motion-canvas/core/lib';

import example from './scenes/example.scene';

export default new Project({
  name: 'project',
  scenes: [example],
  // same options as in bootstrap() are available:
* Animator.inferTweenFunction now returns deepTween,
which does not work exactly as before, though should be a viable
replacement in most cases.
* `scene.transition()` has been replaced by `useTransition`

Any use of slide transition must be updated from
```ts
yield* scene.transition(slideTransition());

to

yield * slideTranstion();

Any transitions must be rewritten to utilize useTransition.

  • Konva patches are not imported by default

Projects using KonvaScenes should import the patches manually at the very top of the file project:

import '@motion-canvas/core/lib/patches'
// ...
bootstrap(...);

getset import path has changed:

import {getset} from '@motion-canvas/core/lib/decorators/getset';
  • change the type exported by scene files

Scene files need to export a special SceneDescription object instead of a simple generator function.

  • change event naming convention

The names of all public events now use the following pattern: "on[WhatHappened]". Example: "onValueChanged".

  • change how images are imported

By default, importing images will now return their urls instead of a SpriteData object. This behavior can be adjusted using the ?img and ?anim queries.

  • change time events API
  • waitFor and waitUntil were moved

They should be imported from @motion-canvas/core/lib/flow.