Visualize Your Ideas With Code
feat(docs): add migration guide for v10 (#37)
Jacob0905daa60f42
diff --git a/README.md b/README.mdindex 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 installall necessary dependencies.diff --git a/packages/docs/config/darkCodeTheme.js b/packages/docs/config/darkCodeTheme.jsindex 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.mdnew file mode 100644index 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_.ymlnew file mode 100644index 00000000..52e96ed7--- /dev/null+++ b/packages/docs/docs/guides/migration/_category_.yml@@ -0,0 +1,2 @@+label: Migration+position: 3