Documentation

Motionwind v2

What shipped in Motionwind v2.0.0, how packages are versioned, and how to upgrade safely.

Motionwind v2.0.0

Motionwind v2 is the community release of the shared animate-* utility language. All public packages are synchronized at version 2.0.0.

What's new in v2

`motionwind-core` — the shared foundation

A single package implements the parser, types, constants, syntax registry, configuration, plugins, presets, and adapter contracts. Every official package depends on it.

Typed configuration

motionwind.config.ts provides:

Duration tokens: animate-duration-fast maps to 160ms.
Easing tokens: animate-ease-product maps to a cubic-bezier curve.
Spring tokens: animate-spring-responsive maps to stiffness/damping.
Presets: animate-preset-card-enter expands to a full animation class string.
Strict mode: Error on unknown classes in CI.
Reduced motion: "user", "always", or "never" policy.
Plugins: Extend with custom properties, presets, and diagnostics.

`mw.create(Component)`

Wrap design-system components to use animate-* classes without changing the lowercase host-element compiler path:

const MotionButton = mw.create(Button);
<MotionButton className="animate-hover:scale-105">Save</MotionButton>;

`create-motionwind` CLI

A single CLI with four commands:

Command	Purpose
`init`	Detect framework, install packages, create config
`doctor`	Verify setup, check dependencies, run diagnostics
`migrate`	Apply source code migrations
`add`	Install presets from the registry

Data-driven syntax registry

The same registry powers parsing, editor completions, formatting, linting, Studio, MCP, and AI tools. Adding a new gesture or property updates the entire ecosystem.

Packed-artifact testing

CI installs the same tarballs intended for npm into starter applications for Next.js, React/Vite, Vue/Vite, Nuxt, vanilla, and Expo. Tests validate the actual published packages, not workspace links.

Support tiers

Tier	Frameworks	Commitment
Stable	React, Next.js, React/Vite, Vue, Nuxt, vanilla	Release gates must pass before publishing
Beta	React Native, Expo	Supported subset tested; gaps produce diagnostics
Community	Svelte, Solid, Astro, third-party adapters	Maintainer-owned until promotion policy is met

What changed from v1

Area	v1	v2
Core	Per-framework parsers	Single `motionwind-core` parser
Config	Minimal or none	Typed `motionwind.config.ts` with tokens/presets
Presets	None	`animate-preset-{name}` for reusable interactions
Design systems	Custom wrappers	`mw.create(Component)` typed API
CLI	Basic init	`init`, `doctor`, `migrate`, `add`
Tooling	Per-framework	Single registry powers ESLint, Prettier, VS Code, MCP
Testing	Workspace links	Packed npm tarballs in starter apps

How to upgrade

1. Preview changes

npx create-motionwind@2 init --dry-run

2. Apply migrations

npx create-motionwind@2 migrate src --write

This applies supported source code migrations and shows the diff.

3. Add `motionwind-core` if needed

If your project imports defineConfig, extension helpers, parser types, or the registry, add:

npm install motionwind-core@2

The CLI does this automatically.

4. Verify

npx create-motionwind@2 doctor

5. Pass config to runtime components

For React or React Native runtime trees:

import { MotionwindProvider } from "motionwind-react";
import motionwindConfig from "./motionwind.config";

<MotionwindProvider config={motionwindConfig}>
  <App />
</MotionwindProvider>;

Compatibility policy

ParsedResult is the stable intermediate representation for v2. Breaking changes follow:

Semantic versioning
Canary releases for early testing
Migration guidance in changelogs
At least two minor releases of deprecation before removal

Versioning

All public packages are released together at the same version number. Internal apps (docs, playground) keep their own private versions because they are not published to npm.

Releases use Changesets for version management, generated changelogs, and npm provenance.