OpenCut User Guide

OpenCut is a free and open-source video editor for web, desktop, and mobile, published under the MIT license by the OpenCut project. This guide documents the OpenCut-app/OpenCut repository exactly as it exists today — and that requires an important clarification before you go any further.

Important

This repository is the ground-up rewrite of OpenCut, and it is still an early scaffold. At this commit it is a freshly generated TanStack Start web application — the editor itself has not been built yet. The application's home page intentionally renders nothing. If you want to edit a video today, use the classic version at opencut.app, whose source lives at opencut-app/opencut-classic. The rewrite will eventually take over at new.opencut.app.

This guide therefore covers what you can actually do with this repository right now: clone it, install it, run the development server, explore the bundled UI component library, and deploy the shell to Cloudflare. It also lays out the published roadmap so you know what is coming.

1. What This Repository Is

OpenCut is being rebuilt from scratch with a new architecture. This repository holds the web application shell of that rewrite. Think of it as the foundation that the new editor will be built on top of.

What is present today:

Note

Because the home page renders nothing, starting the app and seeing a blank page is the expected, correct behavior at this stage. Nothing is broken.

Tip

The project is not yet accepting outside code contributions while its architecture is being designed. If you want to follow along or ask questions, join the OpenCut Discord or open an issue.

2. Requirements

You need three things to run this repository.

Note

OpenCut uses Bun as its package manager and script runner, not npm, pnpm, or Yarn. The repository ships a bun.lock lockfile. Install Bun from bun.sh before continuing.

Important

The repository's bunfig.toml sets minimumReleaseAge = 604800 (7 days). This means Bun will refuse to install any dependency version that was published less than a week ago. This is a deliberate supply-chain safety measure — it is not an error if a brand-new package version is skipped.

3. Quick Start

Get the application running locally in four steps.

# 1. Clone the repository
git clone https://github.com/OpenCut-app/OpenCut.git
cd OpenCut

# 2. Install dependencies with Bun (from the repository root)
bun install

# 3. Start the development server
bun run dev

# 4. Open the app in your browser
#    http://localhost:5173

Expected output from bun run dev:

$ turbo dev
• Running dev for @opencut/web
@opencut/web:dev: VITE ready
@opencut/web:dev: ➜  Local:   http://localhost:5173/

When you open http://localhost:5173, the browser tab title reads “OpenCut rewrite — beta.opencut.app” and the page body is empty. That is correct — the editor UI has not been built yet.

Tip

To run only the web application (skipping the Turborepo wrapper), use bun run dev:web, or run Vite directly from inside apps/web with bun run dev. Both serve on port 5173.

Note

The development server runs through Vite with the TanStack Start and Cloudflare plugins. The first start may take a few seconds while Vite pre-bundles dependencies.

4. Available Commands

All commands are run with Bun. The repository is a monorepo, so commands exist at two levels: the root (orchestrated by Turborepo across all apps) and inside apps/web (the web application directly).

Root commands (run from the repository root)

Web app commands (run from apps/web)

Note

bun run test is wired up (Vitest with jsdom and Testing Library), but the repository currently contains no test files, so the command completes without running any tests. This is expected at the scaffold stage.

5. Exploring the Bundled UI Component Library

The most tangible thing in this repository today is a complete shadcn/ui component library — 56 ready-to-use React components living in apps/web/src/components/ui/. These are the building blocks the new editor interface will be assembled from. If you are following the rewrite or experimenting, you can import and render any of them.

The components use the shadcn “base-mira” style with a neutral base color, CSS-variable theming, and the Hugeicons icon set. They are built on top of Base UI and Radix UI primitives.

Components by category

Importing a component

Components are imported through the #/ path alias, which maps to apps/web/src/.

import { Button } from '#/components/ui/button'
import { Card, CardHeader, CardTitle, CardContent } from '#/components/ui/card'

function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello from OpenCut</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
      </CardContent>
    </Card>
  )
}

Tip

The cn() helper in #/lib/utils merges Tailwind class names safely (it combines clsx and tailwind-merge). Use it whenever you compose conditional class names: cn('px-4', isActive && 'bg-primary').

Note

A useIsMobile() hook is available at #/hooks/use-mobile. It returns true when the viewport is narrower than 768px, and updates live as the window resizes. The bundled sidebar component uses it.

6. Deploying to Cloudflare

The application is configured to deploy to Cloudflare Workers. The build is produced by Vite and uploaded with Wrangler.

# From inside apps/web
bun run deploy

This runs vite build and then wrangler deploy. Expected output ends with:

Total Upload: ... KiB
Uploaded opencut-web (x.xx sec)
Deployed opencut-web triggers (x.xx sec)
  https://new.opencut.app

The deployment target is named opencut-web and is bound to the custom domain new.opencut.app.

Important

Deploying requires a Cloudflare account and an authenticated Wrangler session. Run wrangler login once before your first deploy. You also need permission to publish to the new.opencut.app domain — this matters only to the OpenCut maintainers; a personal fork should change the name and routes in apps/web/wrangler.jsonc first.

Caution

Do not deploy a fork to the official new.opencut.app domain. Edit apps/web/wrangler.jsonc and set your own Worker name and remove or replace the routes block before deploying your own copy.

7. What's Coming (Roadmap)

The OpenCut rewrite is being built around a new architecture. The maintainers have published the following goals:

• An Editor API — a programmable interface to the editor.
• First-class third-party plugins — made possible by a plugin-first architecture.
• One codebase for desktop, mobile, and browser — powered by a shared Rust core.
• An MCP server — so AI agents can drive the editor.
• Headless mode — for automation and batch rendering.
• A scripting tab — write scripts directly inside the editor.

Note

None of these capabilities exist in the repository yet — they describe the direction of the rewrite. This guide will grow as they land.

8. Troubleshooting

The page is blank when I open http://localhost:5173

Cause: This is expected. The home route (apps/web/src/routes/index.tsx) intentionally renders null — the editor UI has not been built yet.

Solution: Nothing to fix. Confirm the server is running and the browser tab title shows “OpenCut rewrite — beta.opencut.app”. The shell is working; there is simply no content to display.

Prevention: Track the rewrite progress issue (#811) to see when editor features land.

Error: Unable to build locally

Cause: Most commonly a missing or wrong package manager (the project requires Bun, not npm/pnpm/Yarn), or a dependency skipped by the minimumReleaseAge policy.

Solution:

# Confirm Bun is installed and on a compatible version
bun --version        # expect 1.3.x

# Reinstall from the repository root
rm -rf node_modules
bun install

If a recently published dependency is being skipped, that is the minimumReleaseAge = 604800 (7-day) policy in bunfig.toml working as designed — wait until the version is at least a week old, or adjust the policy in a fork.

Prevention: Always install with bun install from the repository root so the workspace resolves correctly.

Port 5173 is already in use

Cause: Another process (often a previous Vite session) is holding the port.

Solution: Stop the other process, or start Vite on a different port from inside apps/web:

bun run dev -- --port 5174

Prevention: Shut down old dev servers before starting a new one.

wrangler deploy fails with an authentication or permission error

Cause: You are not logged in to Cloudflare, or you do not have rights to the opencut-web Worker / new.opencut.app domain.

Solution: Run wrangler login. If you are deploying a personal fork, edit apps/web/wrangler.jsonc to use your own Worker name and remove the routes custom-domain block.

Prevention: Only the OpenCut maintainers can deploy to the official domain; forks must use their own Cloudflare account and configuration.

9. Frequently Asked Questions

Q: Can I edit a video with this repository? Not yet. This is the in-progress rewrite scaffold. For actual video editing today, use the classic version at opencut.app (source).

Q: Why does the app show a blank page? Because the home route deliberately renders nothing. The editor interface has not been built on top of the shell yet. This is expected, not a bug.

Q: How does this relate to the classic OpenCut? The classic app is the current, fully working editor. This repository is a from-scratch rewrite with a new architecture (plugin-first, Rust core, multi-platform). The rewrite will eventually replace the classic version at the main site.

Q: Can I contribute code? The project is not accepting outside contributions yet while the architecture is being designed. You can follow along and ask questions on the Discord or through issues.

Q: What package manager does it use? Bun (version 1.3.11). Use bun install and bun run <script>, not npm or pnpm.

Q: What framework is it built on? TanStack Start (server-side rendering) with the TanStack React Router file-based router, React 19, Vite, and Tailwind CSS v4. It deploys to Cloudflare Workers.

Q: Where will the finished rewrite live? At new.opencut.app, per the deployment configuration. (The browser tab title in the current code still reads beta.opencut.app.)

Q: Is there a desktop or mobile build here? Not in this repository. Desktop and mobile are planned via a shared Rust core, but only the web application exists today.