# 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](https://opencut.app), whose source lives at [opencut-app/opencut-classic](https://github.com/opencut-app/opencut-classic). The rewrite will eventually take over at [new.opencut.app](https://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:
| Capability | Status in this repo |
|---|---|
| Web application shell (server-rendered) | ✅ Working — boots and serves a page |
| Routing | ✅ One route (`/`), rendered server-side |
| UI component library (shadcn/ui) | ✅ 56 components installed and ready to use |
| Styling system (Tailwind CSS v4) | ✅ Configured with a full theme |
| Cloudflare Workers deployment | ✅ Configured (`wrangler` + custom domain) |
| Video editor (timeline, preview, export) | ❌ Not built yet |
| Media import, audio, text, rendering | ❌ Not built yet |
> [!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](https://discord.gg/zmR9N35cjK) or [open an issue](https://github.com/opencut-app/opencut/issues).
---
## 2. Requirements
You need three things to run this repository.
| Requirement | Version / Notes |
|---|---|
| **Bun** | `1.3.11` (declared as the project's package manager) |
| **Node.js runtime compatibility** | The Cloudflare Worker build runs with the `nodejs_compat` flag; a current Node.js (18+) is recommended for tooling |
| **Git** | Any recent version, to clone the 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](https://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.
```bash
# 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`:
```text
$ 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)
| Command | What it does |
|---|---|
| `bun run dev` | Starts the dev server for every app via Turborepo (`turbo dev`) |
| `bun run dev:web` | Starts the dev server for the web app only (`turbo dev --filter=@opencut/web`) |
| `bun run build` | Builds every app for production (`turbo build`) |
| `bun run deploy` | Builds, then deploys (`turbo deploy`) |
### Web app commands (run from `apps/web`)
| Command | What it does |
|---|---|
| `bun run dev` | Starts Vite on port `5173` (`vite dev --port 5173`) |
| `bun run build` | Produces a production build (`vite build`) |
| `bun run preview` | Serves the production build locally (`vite preview`) |
| `bun run test` | Runs the test suite once with Vitest (`vitest run`) |
| `bun run deploy` | Builds, then deploys to Cloudflare (`bun run build && wrangler deploy`) |
> [!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](https://ui.shadcn.com) 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](https://base-ui.com) and Radix UI primitives.
### Components by category
| Category | Components |
|---|---|
| **Buttons & actions** | `button`, `button-group`, `toggle`, `toggle-group`, `kbd` |
| **Inputs & forms** | `input`, `input-group`, `input-otp`, `textarea`, `native-select`, `select`, `combobox`, `checkbox`, `radio-group`, `switch`, `slider`, `label`, `field`, `form` |
| **Overlays & menus** | `dialog`, `alert-dialog`, `drawer`, `sheet`, `popover`, `hover-card`, `tooltip`, `dropdown-menu`, `context-menu`, `menubar`, `command` |
| **Navigation** | `navigation-menu`, `breadcrumb`, `pagination`, `tabs`, `sidebar` |
| **Layout & structure** | `card`, `accordion`, `collapsible`, `separator`, `resizable`, `scroll-area`, `aspect-ratio`, `item`, `empty` |
| **Data display** | `table`, `chart`, `calendar`, `avatar`, `badge`, `carousel` |
| **Feedback** | `alert`, `progress`, `skeleton`, `spinner`, `sonner` (toasts) |
| **Utility** | `direction` |
### Importing a component
Components are imported through the `#/` path alias, which maps to `apps/web/src/`.
```tsx
import { Button } from '#/components/ui/button'
import { Card, CardHeader, CardTitle, CardContent } from '#/components/ui/card'
function Example() {
return (
Hello from OpenCut
)
}
```
> [!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.
```bash
# From inside apps/web
bun run deploy
```
This runs `vite build` and then `wrangler deploy`. Expected output ends with:
```text
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)](https://github.com/opencut-app/opencut/issues/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:**
```bash
# 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`:
```bash
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](https://opencut.app) ([source](https://github.com/opencut-app/opencut-classic)).
**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](https://discord.gg/zmR9N35cjK) or through [issues](https://github.com/opencut-app/opencut/issues).
**Q: What package manager does it use?**
Bun (version `1.3.11`). Use `bun install` and `bun run