> ## Documentation Index
> Fetch the complete documentation index at: https://layermetry.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Welcome to the layermetry SDK documentation for Next.js

# layermetry SDK

Welcome to the Next.js integration documentation for `@layermetry/media-editor`.

## Overview

The `@layermetry/media-editor` SDK provides powerful image and video editing capabilities for React applications. This documentation covers everything you need to integrate the SDK into your Next.js project.

<Warning>
  **This page still describes the version 1 setup.** In version 2
  (`@layermetry/media-editor` 2.0.0) `ffmpeg` was removed, so the 31 MB of
  WebAssembly named below no longer ships with the package and there is nothing to
  copy into `public/`. React is no longer pinned to 18.2.0 either — React 18 and
  React 19 both work, and the editor also runs with no React at all.

  Follow [Installation](/docs/installation) for the version 2 setup. This page is being
  rewritten.
</Warning>

## Documentation Files

### Integration Guides

1. **[Next.js ImageEditor Integration](/docs/integration-guides/nextjs-image-editor)**
   * Complete guide for ImageEditor integration
   * Interface documentation and prop reference
   * Theme customization examples
   * Step-by-step implementation
   * Callback handling and export options

2. **[Next.js VideoEditor Integration](/docs/integration-guides/nextjs-video-editor)**
   * Complete guide for VideoEditor integration
   * WASM setup instructions (critical!)
   * Video processing workflow
   * Performance considerations
   * Export and encoding options

### Troubleshooting

3. **[FAQ](/docs/troubleshooting/faq)**
   * Common issues and solutions
   * React version compatibility problems
   * License validation errors
   * WASM loading failures
   * Build and deployment issues
   * Quick troubleshooting checklist

## Quick Start

### 1. Install Dependencies

```bash theme={null}
npm install @layermetry/media-editor
```

### 2. Configure Next.js

**next.config.js:**

```javascript theme={null}
const nextConfig = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      canvas: false,
      fs: false,
    };
    return config;
  },
};

module.exports = nextConfig;
```

### 3. Import SDK Styles

**app/globals.css:**

```css theme={null}
@import "@layermetry/media-editor/dist/index.css";
```

### 4. Use Dynamic Imports

```typescript theme={null}
'use client';

import dynamic from 'next/dynamic';

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

### 5. Copy WASM Files (Video Only)

```bash theme={null}
mkdir -p public
cp node_modules/@layermetry/media-editor/dist/MediaInfoModule.wasm public/
cp node_modules/@layermetry/media-editor/dist/*.js public/
cp -r node_modules/@layermetry/media-editor/dist/umd public/
```

## Key Concepts

### Which React version?

Version 2 works in React 18 and React 19. It also works with no React at all — the editor ships as a browser custom element, so Vue, Angular, Svelte and plain HTML all run the same bundle. If you pinned `react@18.2.0` for version 1, remove the pin.

### Why Dynamic Imports?

The SDK uses browser-only APIs (Canvas, WebAssembly, Web Workers) that don't exist during server-side rendering. Dynamic imports with `ssr: false` ensure the SDK only loads in the browser.

### Why WASM Files?

VideoEditor uses FFmpeg (compiled to WebAssembly) for video processing. These WASM modules (33MB total) must be in your `public/` folder so the browser can load them at runtime.

### Theme System

Both editors support extensive theming through the `theme` prop. You can customize:

* Background colors (primary, secondary, tertiary)
* Text colors (primary, secondary)
* Accent colors (primary, secondary, hover)
* Border colors
* Component-specific colors (buttons, inputs, toolbar, canvas, etc.)

## Architecture

```
Your Next.js App
├── app/
│   ├── globals.css          # Import SDK styles here
│   ├── layout.tsx           # Root layout
│   └── studio/
│       ├── theme.ts         # Shared theme configuration
│       ├── image/
│       │   └── page.tsx     # ImageEditor page
│       └── video/
│           └── page.tsx     # VideoEditor page
├── public/
│   ├── MediaInfoModule.wasm # Video processing (2.3 MB)
│   ├── worker.js            # FFmpeg worker
│   ├── decode_worker.js     # Video decoder
│   ├── encode_worker.js     # Video encoder
│   └── umd/
│       └── ffmpeg-core.wasm # FFmpeg core (31 MB)
└── next.config.js           # Configure webpack and rewrites
```

## Common Patterns

### File Upload with Preview

```typescript theme={null}
const [file, setFile] = useState<File | null>(null);
const [showEditor, setShowEditor] = useState(false);

const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
  const selectedFile = e.target.files?.[0];
  if (selectedFile) {
    setFile(selectedFile);
    setShowEditor(true);
  }
};

return (
  <>
    <input type="file" accept="image/*" onChange={handleFileSelect} />
    {showEditor && file && (
      <ImageEditor
        licenseKey="YOUR_KEY"
        files={file}
        onClose={() => setShowEditor(false)}
        callback={(result) => {
          console.log('Exported:', result.base64);
        }}
      />
    )}
  </>
);
```

### Export and Download

```typescript theme={null}
const handleExport = useCallback((result: any) => {
  // Create download link
  const link = document.createElement('a');
  link.href = result.base64 || result.videoUrl;
  link.download = `edited-${Date.now()}.${result.videoUrl ? 'mp4' : 'png'}`;
  link.click();

  // Or upload to server
  fetch('/api/upload', {
    method: 'POST',
    body: JSON.stringify({ data: result.base64 }),
    headers: { 'Content-Type': 'application/json' }
  });
}, []);
```

### Custom Theme

```typescript theme={null}
const theme = {
  'background.primary': '#0f172a',
  'text.primary': '#ffffff',
  'accent.primary': '#3b82f6',
  'accent.secondary': '#06b6d4',
  'border.default': '#334155',
};

<ImageEditor theme={theme} showThemeCreator={false} />
```

## Example Project

A complete working example is available in the SDK package at `examples/nextjs/`.

This includes:

* Landing page with studio selection
* Image Studio with drag-and-drop
* Video Studio with export modal
* Custom branded theme implementation
* Proper file handling and state management

## API Reference

### ImageEditor Props

| Prop               | Type                        | Required | Description           |
| ------------------ | --------------------------- | -------- | --------------------- |
| `licenseKey`       | `string`                    | ✅        | JWT license key       |
| `onClose`          | `() => void`                | ✅        | Close callback        |
| `apiUrl`           | `string`                    | ❌        | API endpoint override |
| `files`            | `File`                      | ❌        | Initial image file    |
| `callback`         | `(result, extras?) => void` | ❌        | Export callback       |
| `theme`            | `Record<string, string>`    | ❌        | Custom theme          |
| `showThemeCreator` | `boolean`                   | ❌        | Show theme UI         |

### VideoEditor Props

| Prop               | Type                     | Required | Description           |
| ------------------ | ------------------------ | -------- | --------------------- |
| `licenseKey`       | `string`                 | ✅        | JWT license key       |
| `onClose`          | `() => void`             | ✅        | Close callback        |
| `apiUrl`           | `string`                 | ❌        | API endpoint override |
| `defaultVideo`     | `File`                   | ❌        | Initial video file    |
| `onExport`         | `(result) => void`       | ❌        | Export callback       |
| `theme`            | `Record<string, string>` | ❌        | Custom theme          |
| `showThemeCreator` | `boolean`                | ❌        | Show theme UI         |

## Performance Tips

### Image Editor

* ✅ Fast load time (\~500ms)
* ✅ Works on mobile devices
* ✅ Low memory usage (less than 100MB)
* ✅ Instant export

### Video Editor

* ⚠️ Longer load time (\~2s) due to WASM
* ⚠️ Desktop only (mobile not supported)
* ⚠️ High memory usage (500MB+ for HD video)
* ⚠️ Slow export (1-2 minutes for 30s 1080p video)

**Recommendations:**

1. Show loading indicators during export
2. Warn users about processing time
3. Recommend shorter clips or lower resolution
4. Consider server-side processing for production apps

## Version Compatibility

| Next.js | React | SDK   | Status        |
| ------- | ----- | ----- | ------------- |
| 15.x    | 19.x  | 2.0.0 | ✅ Works       |
| 14.2.x  | 18.2  | 2.0.0 | ✅ Works       |
| 14.0.x  | 18.2  | 2.0.0 | ✅ Works       |
| 13.x    | 18.2  | 2.0.0 | ⚠️ Not Tested |

Version 2 no longer brings its own copy of React, so the host framework version
no longer constrains the SDK. The same bundle also runs with no React installed
at all.

## Support

### Documentation

* **Integration Guides**: This folder
* **API Docs**: Coming soon
* **Video Tutorials**: Coming soon

### Getting Help

* 📧 Email: [support@layermetry.com](mailto:support@layermetry.com)
* 💬 Support Portal: Contact your account manager
* 📚 Docs: [https://docs.layermetry.com](https://docs.layermetry.com)

### Reporting Bugs

Please include:

1. Next.js version
2. React version
3. SDK version
4. Error messages
5. Steps to reproduce
6. Browser/OS information

## License

`@layermetry/media-editor` is commercial software. See the [terms of use](https://layermetry.com/termsofuse) for the licence terms.

## Changelog

### v2.0.0 (Current)

* Published as `@layermetry/media-editor`. The old `@distralabs` name is retired.
* Works in React 18 and React 19, in Vue, Angular, Svelte, Next.js and plain HTML — the editor ships as a browser custom element, so the host framework no longer matters.
* One package instead of 162.
* `ffmpeg` removed: 31 MB of WebAssembly is now 0. Export uses the browser's own video hardware.
* A faster export path, measured at 4.4 times the previous exporter. Opt in with `export={{ experimental: true }}`.

### v1.1.9

* Next.js 14 compatibility
* React 18.2 support
* Theme customization
* Video timeline improvements
* Bug fixes

***

**Ready to get started?**

Choose your integration guide:

* [ImageEditor Integration →](/docs/integration-guides/nextjs-image-editor)
* [VideoEditor Integration →](/docs/integration-guides/nextjs-video-editor)

**Having issues?**

* [Check the FAQ →](/docs/troubleshooting/faq)