Installation

Requirements

Install

Install @elah/editor and lucide-react. The decode/export backend (mediabunny) ships bundled — there's nothing else to add:

npm install @elah/editor lucide-react

Using a different package manager:

pnpm add @elah/editor lucide-react
yarn add @elah/editor lucide-react
bun add @elah/editor lucide-react

CLI (optional)

Want to render on a server instead of (or alongside) the browser? Install @elah/cli— it runs core's real export pipeline headlessly, so output is bit-identical to the editor:

npm install -g @elah/cli

See CLI & Server for commands, the build spec, and self-hosting a render server.

Peer Dependencies

@elah/editor expects your app to provide react, react-dom, and lucide-react (the timeline uses it for clip icons). @elah/core, @elah/react, @elah/timeline, and mediabunny are pulled in transitively. A typical package.json looks like:

{
  "dependencies": {
    "@elah/editor": "^0.4.1",
    "lucide-react": "^0.400.0",
    "react": "^18 || ^19",
    "react-dom": "^18 || ^19"
  }
}

npm auto-installs peer dependencies, so omitting lucide-react can appear to work — pnpm and yarn do not, and neither do most AI hosting sandboxes. Always declare it.

The package ships ESM with bundled TypeScript declarations — no separate @types install required.

Building custom UI on @elah/core without the full editor? Install @elah/react directly for the hooks (useTracksStore, useAudioMixer, etc.) without pulling in @elah/timeline's UI components.

Next.js Setup

Add the SDK packages to transpilePackages so the bundler can resolve the export Web Worker that @elah/core spawns via new URL('./ExportWorker.js', import.meta.url):

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  // @elah/editor (+ its @elah/core / @elah/react / @elah/timeline deps) and
  // mediabunny ship modern ESM that must be transpiled by the consuming app.
  // Required — without it the build fails on the @elah/editor barrel.
  transpilePackages: ['@elah/editor', '@elah/core', '@elah/react', '@elah/timeline', 'mediabunny'],
}

export default nextConfig

The editor touches browser-only APIs (Canvas, Web Audio, Workers), so render it client-side only with a dynamic import:

'use client'

import dynamic from 'next/dynamic'

// ssr: false keeps the editor out of the server bundle.
const Editor = dynamic(() => import('@/components/Editor'), {
  ssr: false,
})

export default function Page() {
  return <Editor />
}

Vite Setup

Serve the SDK packages from their real files (instead of esbuild's pre-bundle) so the new URL(...) worker reference inside @elah/core resolves correctly:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  worker: {
    // @elah/core spawns the MP4 export worker as a module worker. Vite's default
    // worker format is IIFE, which cannot use `import` — the export would crash.
    format: 'es',
  },
  optimizeDeps: {
    // Serve these from their real files so the `new URL(...)` worker reference
    // survives esbuild's pre-bundle step.
    exclude: ['@elah/editor', '@elah/core', '@elah/react', '@elah/timeline', 'mediabunny'],
  },
})

Both settings are required, and both are about the export worker — omit either and MP4 export fails at runtime.