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	Description
`root`	`string`	—
`cacheRoot`	`string`	—
`port?`	`number`	Port for the sidecar dev server. Defaults to 3099.
`nextOrigin?`	`string`	The public-facing origin of the Next.js dev server. Defaults to http://localhost:3000 (or $PORT / $NEXT_PORT if set). Used to embed the correct base URL in JIT manifest endpoint templates so the browser fetches segments through the Next.js rewrite proxy rather than directly from the sidecar port.

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