nextjs-plugin

Next.js plugin for Editframe — zero-config local JIT transcoding via a sidecar server and automatic rewrites.

Integrates the Editframe media server into a Next.js project. A sidecar HTTP server starts alongside next dev, and Next.js rewrites all Editframe API paths to it transparently — elements work on the same origin as your app without any api-host configuration.

Installation

npm install --save-dev @editframe/nextjs-plugin

Configuration

// next.config.mjs
import { withEditframe } from "@editframe/nextjs-plugin";

export default withEditframe(
  {
    root: "./src",
    cacheRoot: "./src/assets/.cache",
  },
  {
    // your existing Next.js config
  },
);

// next.config.js (CommonJS)
const { withEditframe } = require("@editframe/nextjs-plugin");

module.exports = withEditframe(
  { root: "./src", cacheRoot: "./src/assets/.cache" },
  {
    // your existing Next.js config
  },
);

Then run next dev as normal.

Options

Option	Type	Default	Description
`root`	`string`	required	Base directory for resolving local media file paths
`cacheRoot`	`string`	required	Directory where transcoded tracks and thumbnails are cached
`port`	`number`	`3099`	Port for the sidecar dev server
`nextOrigin`	`string`	`http://localhost:3000`	Public-facing Next.js origin — override when Next.js runs on a non-default port or behind a reverse proxy

Environment variables

Variable	Description
`EF_TOKEN`	Your Editframe API token — required for URL signing
`EF_HOST`	Override the Editframe API host (optional)

How it works

When NODE_ENV is development, the plugin:

Starts a sidecar HTTP server on port (default 3099) that handles JIT transcoding, asset serving, and URL signing
Adds Next.js rewrites so /api/v1/* and /@ef-* requests are transparently proxied to the sidecar

Because requests proxy through the same origin as the Next.js app, window.location.origin resolves correctly and elements need no additional configuration.

The sidecar shuts down cleanly when next dev exits, releasing the port for the next run.

Referencing media

// Local file at src/clip.mp4
<Video src="/clip.mp4" />

// Remote URL — transcoded on demand
<Video src="https://cdn.example.com/footage.mp4" />

No apiHost prop or <Configuration> wrapper needed.

Non-default port or reverse proxy

If Next.js runs on a port other than 3000, or behind a reverse proxy (e.g. Traefik), pass nextOrigin so JIT manifest endpoint URLs point at the correct public-facing origin:

withEditframe(
  {
    root: "./src",
    cacheRoot: "./src/assets/.cache",
    nextOrigin: "http://localhost:3030",
  },
  nextConfig,
);

Stale sidecar

If you force-quit next dev, the sidecar port may remain occupied. Free it with:

lsof -ti:3099 | xargs kill -9