Skip to main content

​
Prerequisites

Before installing the Media Editor SDK, ensure you have:
  • Node.js 16.x or higher
  • Next.js 14.2.15 (not 15+)
  • React 18.2.0 (not React 19)
  • A valid license key (contact your account manager)

​
Step 1: Install the SDK

npm install @distralabs/[email protected]

​
Step 2: Install Required Dependencies

The SDK requires specific versions of Next.js and React for compatibility: 
npm install [email protected] [email protected] [email protected]
npm install framer-motion lucide-react clsx tailwind-merge
Critical: The SDK is built with React 18.2.0 and is not compatible with React 19. Next.js 15+ requires React 19, so you must use Next.js 14.2.15.

​
Step 3: Configure package.json

Update your package.json to enforce React 18:
package.json
{
  "dependencies": {
    "@distralabs/media-editor": "^1.1.9",
    "next": "14.2.15",
    "react": "18.2.0",
    "react-dom": "18.2.0",
    "framer-motion": "^10.16.4",
    "lucide-react": "^0.263.1"
  },
  "devDependencies": {
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "eslint": "^8",
    "eslint-config-next": "14.2.15",
    "typescript": "^5"
  },
  "overrides": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}
The overrides field ensures all dependencies use React 18.2.0.

​
Step 4: Configure Next.js

​
4.1 Rename Config File

Next.js 14 doesn’t support TypeScript config files. Rename if needed: 
mv next.config.ts next.config.js

​
4.2 Update next.config.js

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    // Disable node modules that don't work in browser
    config.resolve.alias = {
      ...config.resolve.alias,
      canvas: false,
      fs: false,
    };
    return config;
  },
};

module.exports = nextConfig;

​
4.3 For Video Editor: Add URL Rewrites

If using the VideoEditor component, add rewrites for WASM files:
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      canvas: false,
      fs: false,
    };
    return config;
  },
  async rewrites() {
    return [
      {
        source: '/studio/:path(MediaInfoModule.wasm|worker.js|const.js|errors.js|decode_worker.js|encode_worker.js)',
        destination: '/:path',
      },
      {
        source: '/studio/umd/:path*',
        destination: '/umd/:path*',
      },
    ];
  },
};

module.exports = nextConfig;

​
Step 5: Import SDK Styles

Add the SDK CSS to your global styles file:
app/globals.css
@import "tailwindcss";

/* IMPORTANT: Import SDK styles */
@import "@distralabs/media-editor/dist/index.css";

/* Your other styles below */

​
Step 6: Update Fonts (Optional)

If you were using Next.js 15’s Geist font, switch to a Next.js 14-compatible font:
app/layout.tsx
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className={inter.className}>
        {children}
      </body>
    </html>
  );
}

​
Step 7: For Video Editor Only - Copy WASM Files

The VideoEditor component requires WebAssembly files for video processing.

​
7.1 Copy Files to Public Folder

# From your Next.js project root
mkdir -p public
cp node_modules/@distralabs/media-editor/dist/MediaInfoModule.wasm public/
cp node_modules/@distralabs/media-editor/dist/worker.js public/
cp node_modules/@distralabs/media-editor/dist/const.js public/
cp node_modules/@distralabs/media-editor/dist/errors.js public/
cp node_modules/@distralabs/media-editor/dist/decode_worker.js public/
cp node_modules/@distralabs/media-editor/dist/encode_worker.js public/
cp -r node_modules/@distralabs/media-editor/dist/umd public/

​
7.2 Verify WASM Files

ls -lh public/
# Should show:
# MediaInfoModule.wasm (2.3 MB)
# worker.js
# const.js
# errors.js
# decode_worker.js
# encode_worker.js
# umd/ffmpeg-core.wasm (31 MB)
These files are only needed for the VideoEditor component. ImageEditor works without them.

​
Step 8: Clean Install

After configuration changes, clean install dependencies: 
rm -rf node_modules package-lock.json
npm install

​
Step 9: Verify Installation

Create a test page to verify the installation:
app/test/page.tsx
'use client';

import dynamic from 'next/dynamic';

const ImageEditor = dynamic(
  () => import('@distralabs/media-editor').then(mod => ({ default: mod.ImageEditor })),
  { ssr: false }
);

export default function TestPage() {
  return (
    <div className="p-6">
      <h1>SDK Installation Test</h1>
      <p>If you see this, the SDK is installed correctly!</p>
    </div>
  );
}
Start the dev server: 
npm run dev
Visit http://localhost:3000/test - no errors should appear in the console.

​
Troubleshooting

​
React Version Errors

Error: “Cannot read properties of undefined (reading ‘ReactCurrentOwner’)” Solution: Downgrade to Next.js 14.2.15 and React 18.2.0 as shown in Step 2.

​
Module Not Found

Error: “Module not found: Can’t resolve ‘@distralabs/media-editor’” Solution:
  1. Verify installation: npm list @distralabs/media-editor
  2. Clean install: rm -rf node_modules && npm install

​
WASM Files 404

Error: “MediaInfoModule.wasm 404 Not Found” Solution:
  1. Copy WASM files to public/ folder (Step 7)
  2. Add URL rewrites to next.config.js (Step 4.3)
  3. Restart dev server
For more issues, see the FAQ.

​
Version Compatibility Matrix

Next.jsReactSDKStatus
15.x19.x1.1.9❌ Not Compatible
14.2.x18.21.1.9✅ Recommended
14.0.x18.21.1.9✅ Compatible
13.x18.21.1.9⚠️ Not Tested

​
Next Steps

Quickstart

Build your first editor in 5 minutes

ImageEditor Guide

Complete ImageEditor integration

VideoEditor Guide

Complete VideoEditor integration

API Reference

Detailed API documentation