Motion Core

Getting Started

Init

Initialize a new Motion Core configuration.

Overview

motion-core init prepares an existing Svelte workspace to host Motion Core components. It detects your tooling, writes (or validates) motion-core.json, scaffolds folders, syncs design tokens, and optionally installs the base dependencies declared by the remote registry.

When to run it

  • Right after creating a new SvelteKit/Vite + Svelte project so Motion Core files land in predictable locations.
  • When you clone a project that already uses Motion Core but the scaffolding or Tailwind tokens are missing.
  • Inside CI pipelines to verify the workspace layout by using --dry-run.

Usage

motion-core init [--dry-run]
motion-core init [--dry-run]

Options

Flag Description
--dry-run Print every planned action (config path, directories, dependencies, Tailwind edits) without touching disk. Useful for audits and CI.

What the command does

  1. Framework & package manager detection – reads package.json to ensure svelte >= 5. Missing or older Svelte aborts the command. Tailwind < 4 is allowed but triggers a warning. The CLI walks up the directory tree to locate lockfiles and remember whether to call npm, pnpm, yarn, or bun later.
  2. Configuration bootstrap – if motion-core.json does not exist the CLI writes the default template (including the JSON Schema URL) and tries to locate your Tailwind CSS file automatically. When the file exists it is left untouched unless you edit it yourself afterwards.
  3. Workspace scaffolding – guarantees that the directories referenced by your aliases exist (components, helpers, utils, assets) and downloads the shared utils/cn.ts helper. Every directory or file created is reported in the summary output.
  4. Tailwind token sync – downloads tokens/motion-core.css from the registry (or the local cache when offline), inserts or updates the bundle inside CLI-managed markers (/* motion-core:tokens:start */ / /* motion-core:tokens:end */) in the configured Tailwind CSS file, uses a .motion-core.bak backup for rollback safety on write failures, and stays idempotent across token format changes.
  5. Base dependency check – compares the registry’s base dependency map with your package.json. When a package manager was detected the CLI installs missing packages automatically; otherwise it prints the commands you should run manually.
  6. Summary – prints the detected framework, package manager, whether configuration was created or reused, directories/files touched, dependency changes, and a suggested next command (motion-core add glass-pane).

Dry-run reporting

motion-core init --dry-run uses the same discovery logic but never writes files or runs installs. Instead it shows:

  • Where motion-core.json would live.
  • Which directories/files would be created.
  • Whether Tailwind tokens would be injected and into which file.
  • The list of dependencies that would be installed and via which package manager.

This is ideal when you are upgrading Motion Core or reviewing contributions.

Troubleshooting & tips

  • “Svelte >=5 is required” – upgrade your dependency before retrying, otherwise components may rely on APIs that are missing in older versions.
  • Offline runs – the CLI falls back to cached registry manifests for helpers and tokens. If the cache is empty you will see an error telling you to rerun the command once online.
  • Custom folder layout – edit motion-core.json after initialization to point aliases elsewhere, then re-run motion-core init to recreate missing folders or motion-core add to sync files into the new paths.