wikis / Remotion / wiki / concepts / installation-setup.md view as markdown

Installation & Project Setup

Definition

Remotion is a framework for creating videos programmatically using React: you express frames as React components and Remotion turns them into video. There are two ways to start — scaffold a fresh project with npx create-video@latest, or install Remotion into an existing app ("brownfield"). Either way, every Remotion project boils down to an entry point that calls registerRoot() with a root component that returns one or more <Composition> elements.

How It Works

Scaffolding a new project

The fastest path, including TailwindCSS, the blank template, and Agent Skills:

npx create-video@latest --yes --blank my-video
cd my-video
npm i
npx remotion skills add
npm run dev

Running npx create-video@latest without flags launches a wizard where you pick a template (Hello World is recommended for a first project), and toggle Tailwind and Agent Skills. Package-manager equivalents: pnpm create video, yarn create video, bun create video (Bun as a runtime is mostly supported).

For coding agents (Claude Code, Codex, OpenCode), the official prompt is:

Ensure Node.js is installed. Install Remotion Skills: npx -y skills@latest add remotion-dev/skills -g -y Then use them to create a video.

Starting the Studio

For regular templates, npm run dev opens remotion studio. In the Next.js + React Router 7 templates, npm run dev starts the app and npm run remotion starts the Studio.

Project structure: entry point and root

The structure is two files with distinct jobs:

• Entry point (e.g. src/index.ts) — calls registerRoot(RemotionRoot). This is what CLI commands point at.
• Root component (e.g. src/Root.tsx) — returns your <Composition> list, wrapped in a React Fragment if there is more than one.

import {registerRoot} from 'remotion';
import {RemotionRoot} from './Root';

registerRoot(RemotionRoot);

registerRoot() must live in a separate file from the composition list: with React Fast Refresh, all code in a refreshed file re-executes, but registerRoot() should only ever run once. If you need to load something first (a dynamic import, WebAssembly), you may defer the call — loadWebAssembly().then(() => { registerRoot(RemotionRoot); }) — without needing delayRender().

Brownfield install into an existing app

Remotion installs into Next.js, React Router, Vite, Create React App, and server-only Node.JS projects. Base packages:

npm i remotion @remotion/cli

Then add by use case: @remotion/player to embed videos in your React app (see player), @remotion/renderer for Node.JS rendering APIs, @remotion/lambda for lambda rendering.

Create a folder (conventionally remotion/ at the project root) with three files: Composition.tsx (your video component), Root.tsx (the <Composition> list), and index.ts (calls registerRoot()). Then point the CLI at your entry point:

npx remotion studio remotion/index.ts
npx remotion render remotion/index.ts MyComp out.mp4

Optionally install the ESLint plugin (npm i -D @remotion/eslint-plugin) and scope its recommended rules to the Remotion files only:

{
  "plugins": ["@remotion"],
  "overrides": [
    {
      "files": ["remotion/*.{ts,tsx}"],
      "extends": ["plugin:@remotion/recommended"]
    }
  ]
}

Key Parameters

• System requirements: Node.js (or Bun) at a minimum supported version; macOS 15 (Sequoia) or later; Linux distros need Libc ≥ 2.35 plus additional packages. Alpine Linux and nixOS are unsupported.
• create-video flags: --yes (skip prompts), --blank (blank template); positional arg is the directory name.
• Entry point path: first argument to npx remotion studio / npx remotion render — defaults differ per template, always replaceable.
• Core package: npm i remotion gives the essential building blocks; pure functions like interpolate() and interpolateColors() work even outside Remotion.

When To Use

• New, video-first project → npx create-video@latest with a template.
• Adding video generation to an existing product (e.g. a SaaS that renders personalized clips) → brownfield install, then @remotion/player for in-app preview or @remotion/renderer/@remotion/lambda for server rendering. See rendering path picker for choosing a render path and framework integrations for framework-specific guidance.

Risks & Pitfalls

• Calling registerRoot() in the same file as compositions breaks Fast Refresh semantics (it would re-execute on every refresh). Keep it in its own file.
• TypeScript path aliases: a paths alias without a prefix in tsconfig.json can resolve import {...} from "remotion" to your local remotion/ folder instead of the npm package.
• Unsupported platforms: older macOS versions, Alpine, and nixOS will not work; Linux requires extra system packages.
• License: Remotion has a special license — some companies must obtain a paid company license. See licensing.

Related Concepts

• compositions fundamentals — what goes inside the root component
• player — embedding videos in an existing React app
• rendering ssr — rendering with @remotion/renderer
• cli reference — npx remotion studio / render and friends
• remotion studio — the editor started by npm run dev
• ai integration — Agent Skills and coding-agent workflows

Sources

• raw/github_doc-packages-docs-docs-getting-started-mdx.md — scaffolding, wizard, system requirements
• raw/github_doc-packages-docs-docs-brownfield-installation-mdx.md — existing-project install, folder structure, ESLint plugin
• raw/github_doc-packages-docs-docs-register-root-mdx.md — registerRoot() contract and deferral
• raw/github_doc-packages-docs-docs-remotion-mdx.md — core package installation
• raw/github_doc-readme-md.md — framework positioning, license note