Remotion Development Workflow: A Complete Guide to Contributing

The Remotion development workflow uses a Bun-based monorepo managed by Turbo Build, where developers install dependencies with bun i, build with bun run build, develop in watch mode with bun run watch, and test changes using the packages/example testbed before rendering videos with the CLI.

The Remotion development workflow is designed for efficiency in a large TypeScript monorepo. As implemented in the remotion-dev/remotion repository, this workflow leverages Bun as the package manager and runtime, combined with Turbo Build's incremental build system to provide fast feedback loops when modifying video rendering logic or React components.

Prerequisites and Environment Setup

Before contributing to Remotion, you must install the specific toolchain versions used by the project.

Installing Bun

Remotion requires Bun ≥ 1.3.3 as specified in packages/docs/docs/contributing/index.mdx. Install it using the official installer:

curl -fsSL https://bun.com/install | bash -s "bun-v1.3.3"

Repository Structure

The Remotion monorepo organizes all packages under the packages/ directory. The root package.json declares workspaces, enabling a single bun i command to install dependencies across the entire codebase. Key configuration files include turbo.json (defining the build pipeline) and package.json (containing high-level scripts).

Initial Setup Steps

After cloning the repository, you must perform an initial build to compile TypeScript and prepare the workspace.

Clone the repository using a shallow clone to save bandwidth:

git clone --depth=1 https://github.com/remotion-dev/remotion.git && cd remotion

Install all workspace dependencies:

bun i

Build the entire monorepo once. This executes the make Turbo task defined in turbo.json:

bun run build

This command runs bunx turbo run make, which builds packages in the correct dependency order according to the task graph.

Daily Development Workflow with Turbo Build

Once the initial setup is complete, the daily Remotion development workflow centers on Turbo Build's watch mode for incremental rebuilds.

Watch Mode for Continuous Rebuilding

Start the development watcher to automatically rebuild packages when files change:

bun run watch

This executes bunx turbo run watch, which monitors all packages in the monorepo. When you edit a source file in packages/**, Turbo detects the change and rebuilds only the affected package and its dependents, maintaining fast feedback loops even in a large codebase.

Making and Testing Changes

Edit source files within the packages/ directory while the watch process runs. The architecture automatically handles dependency resolution through Turbo's pipeline defined in turbo.json, where tasks like "test" explicitly depend on "make" (the build task), ensuring tests run against the latest compiled code.

Testing and Rendering

The Remotion development workflow includes multiple validation layers, from unit tests to full video rendering.

Running the Test Suite

Execute the full test suite across the monorepo:

bun run test

This runs bunx turbo run test, which executes tests in parallel while respecting the dependency graph. The turbo.json configuration ensures the test task depends on both "^make" (upstream builds) and "make" (local build), guaranteeing all TypeScript is compiled before tests execute.

Using the Example Testbed

The packages/example directory contains a minimal Remotion project serving as the primary development sandbox. Run it locally to test changes interactively:

cd packages/example
bun run dev

This starts a development server with a sample composition, allowing you to verify React component changes and Remotion APIs in real-time before committing.

Rendering Videos Locally

Validate the complete rendering pipeline by producing an actual video file from the example project:

cd packages/example
bunx remotion render ten-frame-tester --output ../../out/video.mp4

This command uses the locally built CLI to render the ten-frame-tester composition, writing the output to out/video.mp4 in the repository root. This step confirms that your changes work correctly through the entire rendering chain.

Publishing Releases

When preparing a new version, the workflow requires manual version bumping followed by an automated release script.

First, update the version constant in packages/core/src/version.ts. Then execute:

bun run release

This runs the publish.ts script defined in the root package.json, which handles the complex release process across all packages in the monorepo.

Summary

• The Remotion development workflow operates in a Bun-based monorepo managed by Turbo Build for incremental compilation.
• Initial setup requires Bun ≥ 1.3.3, followed by bun i and bun run build to compile the workspace.
• Daily development uses bun run watch for automatic rebuilding, while packages/example serves as the interactive testbed.
• Testing spans bun run test for unit tests and bunx remotion render for full video pipeline validation.
• Releases require updating packages/core/src/version.ts before running bun run release.

Frequently Asked Questions

What version of Bun is required for Remotion development?

Remotion requires Bun version 1.3.3 or higher, as specified in the contributing documentation at packages/docs/docs/contributing/index.mdx. This version ensures compatibility with the workspace configuration and Turbo Build integration used throughout the monorepo.

How does Turbo Build improve the Remotion development workflow?

Turbo Build provides incremental builds and intelligent caching through the turbo.json configuration. When running bun run watch, Turbo monitors file changes and rebuilds only affected packages and their dependents, rather than the entire monorepo. The task graph also ensures proper build order, with tasks like test automatically depending on make (compilation).

What is the purpose of the packages/example directory?

The packages/example directory functions as the primary development sandbox and testbed. It contains a minimal Remotion project that developers can run with bun run dev to test changes interactively. It also serves as the target for CLI testing and video rendering validation using commands like bunx remotion render.

How do you publish a new release of Remotion?

To publish a new release, first manually update the version number in packages/core/src/version.ts, then run bun run release from the repository root. This executes the publish.ts script defined in the root package.json, which orchestrates the release process across all packages in the monorepo.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}