---
title: "Installation & Project Setup"
type: concept
tags: [setup, getting-started, project-structure, studio, brownfield]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-getting-started-mdx.md", "raw/github_doc-packages-docs-docs-remotion-mdx.md", "raw/github_doc-packages-docs-docs-register-root-mdx.md", "raw/github_doc-packages-docs-docs-brownfield-installation-mdx.md", "raw/github_doc-readme-md.md"]
---

# 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:

```sh
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 [[entities/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.

```ts
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 [[concepts/player]]), `@remotion/renderer` for Node.JS rendering APIs, `@remotion/lambda` for [[concepts/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:

```json
{
  "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 [[syntheses/rendering-path-picker]] for choosing a render path and [[entities/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 [[concepts/licensing]].

## Related Concepts

- [[concepts/compositions-fundamentals]] — what goes inside the root component
- [[concepts/player]] — embedding videos in an existing React app
- [[concepts/rendering-ssr]] — rendering with `@remotion/renderer`
- [[concepts/cli-reference]] — `npx remotion studio` / `render` and friends
- [[entities/remotion-studio]] — the editor started by `npm run dev`
- [[entities/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