Skip to content

Visualize Your Ideas With Code

feat(docs): add migration guide for v10 (#37)

Jacob0905daa60f42
diff --git a/README.md b/README.md
index ff039aad..eb1eb869 100644
--- a/README.md
+++ b/README.md
@@ -49,80 +49,11 @@ node -v
### Set up a project
-You can use [the project template][template] to quickly bootstrap your
-project. Otherwise, below are the steps to set it up manually:
-
-1. Create a directory for your project and open it in a terminal.
-2. Initialize a new npm package inside:
- ```shell
- npm init
- ```
-3. Create a `.npmrc` file with the following content:
- ```text
- @motion-canvas:registry=https://npm.pkg.github.com
- ```
-4. Install Motion Canvas
- ```shell
- npm i @motion-canvas/core @motion-canvas/ui
- ```
-5. Create a `tsconfig.json` file with the following content:
- ```json
- {
- "extends": "@motion-canvas/core/tsconfig.project.json",
- "compilerOptions": {
- "baseUrl": "src"
- }
- }
- ```
-6. Create a simple scene in `src/scenes/example.scene.tsx`:
-
- ```ts
- import {makeKonvaScene} from '@motion-canvas/core/lib/scenes';
- import {waitFor} from '@motion-canvas/core/lib/flow';
-
- export default makeKonvaScene(function* example(view) {
- // animation code goes here
-
- yield* waitFor(5);
- });
- ```
-
-7. Initialize the project with your scene in `src/project.ts`:
-
- ```ts
- import '@motion-canvas/core/lib/patches';
- import {bootstrap} from '@motion-canvas/core/lib';
-
- import example from './scenes/example.scene';
-
- bootstrap({
- name: 'my-project',
- scenes: [example],
- });
- ```
-
-8. So far, your project structure should look like this:
- ```text
- my-project/
- ├─ node_modules/ <- Generated automatically
- ├─ output/ <- Create this folder to render your animation
- ├─ src/
- │ ├─ scenes/
- │ │ └─ example.scene.tsx
- │ └─ project.ts
- ├─ .npmrc
- ├─ package.json <- Generated automatically
- ├─ package-lock.json <- Generated automatically
- └─ tsconfig.json
- ```
-9. Add a `serve` script to your `package.json`:
- ```json
- {
- "scripts": {
- "serve": "motion-canvas src/project.ts"
- }
- }
- ```
+Run the following command in order to scaffold a new Motion Canvas project:
+
+```bash
+npm init @motion-canvas
+```
### Run Motion Canvas
@@ -141,12 +72,13 @@ In case of any problems, please visit [our discord server][discord].
The project is maintained as one monorepo containing the following packages:
-| Name | Description |
-| ---------- | -------------------------------------------------------- |
-| `core` | All logic related to running and rendering animations. |
-| `ui` | The user interface used for editing. |
-| `template` | A template project included for developer's convenience. |
-| `docs` | [Our documentation website.][docs] |
+| Name | Description |
+| ------------- | -------------------------------------------------------------- |
+| `core` | All logic related to running and rendering animations. |
+| `ui` | The user interface used for editing. |
+| `template` | A template project included for developer's convenience. |
+| `docs` | [Our documentation website.][docs] |
+| `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.
diff --git a/packages/docs/config/darkCodeTheme.js b/packages/docs/config/darkCodeTheme.js
index 1a37f127..4a6e2c5d 100644
--- a/packages/docs/config/darkCodeTheme.js
+++ b/packages/docs/config/darkCodeTheme.js
@@ -4,6 +4,6 @@ module.exports = {
...darkCodeTheme,
plain: {
color: '#f8f8f8',
- backgroundColor: '#242424',
+ backgroundColor: 'rgba(255, 255, 255, 0.04)',
},
};
diff --git a/packages/docs/docs/guides/migration/10.0.0.md b/packages/docs/docs/guides/migration/10.0.0.md
new file mode 100644
index 00000000..7171f3c2
--- /dev/null
+++ b/packages/docs/docs/guides/migration/10.0.0.md
@@ -0,0 +1,109 @@
+---
+title: v10.0.0
+---
+
+# Migrating to version 10.0.0
+
+:::tip
+
+If you're starting a new project, you can quickly scaffold it using:
+
+```bash
+npm init @motion-canvas
+```
+
+:::
+
+## Install the new version
+
+Upgrade the versions of all motion-canvas packages in your `package.json` file:
+
+```diff
+- "@motion-canvas/core": "9.0.0",
+- "@motion-canvas/ui": "9.0.0",
++ "@motion-canvas/core": "10.0.0",
++ "@motion-canvas/ui": "10.0.0",
+```
+
+To apply the changes, run:
+
+```bash
+npm install
+```
+
+## Switch to Vite
+
+Since version 10, Motion Canvas no longer includes an out-of-the box webpack configuration.
+Instead, you should use `vite` together with our `@motion-canvas/vite-plugin` to build your projects.
+This requires more boilerplate code, but it allows developers to customize the build process
+according to their needs.
+
+First, install `vite` and `@motion-canvas/vite-plugin`:
+
+```bash
+npm install --save-dev vite @motion-canvas/vite-plugin
+```
+
+Next, create a `vite.config.ts` file in the root of your project with the following content:
+
+```ts
+import {defineConfig} from 'vite';
+import motionCanvas from '@motion-canvas/vite-plugin';
+
+export default defineConfig({
+ plugins: [motionCanvas()],
+});
+```
+
+In `package.json`, replace the `motion-canvas` command with `vite`:
+
+```diff
+ "scripts": {
+- "serve": "motion-canvas src/project.ts"
++ "serve": "vite"
+ }
+```
+
+Notice that we don't specify the input file when invoking the `vite` command.
+By default, our vite plugin will look for the `./src/project.ts` file and use it as an entry point.
+You can change that in `vite.config.ts`:
+
+```ts
+export default defineConfig({
+ plugins: [
+ motionCanvas({
+ project: './src/custom.ts', // your custom entry file.
+ }),
+ ],
+});
+```
+
+## Update the entry file
+
+The project file (usually `src/project.ts`) needs the following adjustments:
+
+```diff
+- import '@motion-canvas/core/lib/patches';
+- import {bootstrap} from '@motion-canvas/core/lib/bootstrap';
++ import {Project} from '@motion-canvas/core/lib';
+
+ import example from './scenes/example.scene';
+
+- bootstrap({
++ export default new Project({
+ name: 'base-project',
+ scenes: [example],
+ });
+```
+
+First of all, we no longer import the `@motion-canvas/core/lib/patches` module at the top of the file.<br/>
+Additionally, the file should now export and instance of the `Project` class.
+
+## Reference the types
+
+The types exposed by Motion Canvas are no longer global.<br/>
+Because of this, you need to create an additional `motion-canvas.d.ts` file in the `src` directory:
+
+```ts
+/// <reference types="@motion-canvas/core/project" />
+```
diff --git a/packages/docs/docs/guides/migration/_category_.yml b/packages/docs/docs/guides/migration/_category_.yml
new file mode 100644
index 00000000..52e96ed7
--- /dev/null
+++ b/packages/docs/docs/guides/migration/_category_.yml
@@ -0,0 +1,2 @@
+label: Migration
+position: 3