next-video

Next video is a react component for adding video to your next.js application. It extends both the <video> element and your Next app with features for automatic video optimization.

• Smart storage: Store large video files outside of your git repo
• Auto optimized: Optimize video files and deliver via CDN for better playback performance and quality
• Customizable UI: Choose from themes or build your own player controls
• Posters & Previews: Zero-config placeholder images and timeline hover thumbnails
• Wider compatibility: Use videos that aren’t supported natively by all browsers
• Analytics built-in (optional): See how often videos get watched and track video performance
• AI-powered: Add auto-generated captions to your videos and use transcripts

import Video from 'next-video';
import getStarted from '/videos/get-started.mp4';

export default function Page() {
  return <Video src={getStarted} />;
}

Setup

Automatic Setup

In the root of your Next.js project, run:

npx -y next-video init

This will (with prompting):

• install next-video as a dependency
• create a /videos directory and update .gitignore
• update your next.config.js file
• if you're using TypeScript, add types for your video file imports
• add next-video sync -w to your dev script in package.json
• set up Mux credentials in .env.local for remote storage
• add a sample video and demo page to test your setup

It will also update your .gitignore file to ignore video files in the /videos directory. Videos, particularly any of reasonable size, shouldn't be stored/tracked by git. Alternatively, if you'd like to store the original files you can remove the added gitignore lines and install git-lfs.

Remote storage and optimization

Vercel recommends using a dedicated content platform for video because video files are large and can lead to excessive bandwidth usage. By default, next-video uses Mux (a video API for developers), which is built by the the creators of Video.js, powers popular streaming apps like Patreon, and whose video performance monitoring is used on the largest live events in the world.

• Sign up for Mux
• Create an access token
• Add environment variables to .env.local (or however you export local env variables)

# .env.local
MUX_TOKEN_ID=[YOUR_TOKEN_ID]
MUX_TOKEN_SECRET=[YOUR_TOKEN_SECRET]

Manual Setup

<details> <summary><strong>Click to see the manual init steps.</strong></summary>

Install the package

cd your-next-app

# If your project is using NPM (the default for Next.js)
npm install next-video

# If your project is using Yarn
yarn add next-video

# If your project is using pnpm
pnpm add next-video

Create the videos directory

Create a /videos directory in your project root. This is where you'll store your video source files.

mkdir videos

Add the following to your .gitignore to keep video files out of your repo while still tracking their JSON metadata:

# next-video
videos/*
!videos/*.json
!videos/*.js
!videos/*.ts
public/_next-video

Videos, particularly any of reasonable size, shouldn't be stored/tracked by git. Alternatively, if you'd like to store the original files you can remove the added gitignore lines and install git-lfs.

Add Next Video to your Next.js config

next.config.js

If you're using CommonJS modules:

const { withNextVideo } = require('next-video/process');

/** @type {import('next').NextConfig} */
const nextConfig = {}; // Your current Next Config object

module.exports = withNextVideo(nextConfig);

next.config.mjs

If you're using ES modules:

import { withNextVideo } from 'next-video/process';

/** @type {import('next').NextConfig} */
const nextConfig = {};

export default withNextVideo(nextConfig);

Add video import types to tsconfig.json

This is only required if you're using TypeScript, and makes sure your video file imports don't yell at you for missing types. Create a video.d.ts file in your project root:

// video.d.ts
/// <reference types="next-video/video-types/global" />

Then add that file to the include array in tsconfig.json.

{
  // ...
  "include": ["video.d.ts", "next-env.d.ts", /* ... */ ]
  // ...
}

If you're using Turbopack (the default dev server in recent versions of Next.js), you'll also need to add a path alias so that /videos imports resolve correctly. Add the following to compilerOptions.paths in your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@videos/*": ["./videos/*"]
    }
  }
}

Then use @videos/ instead of /videos/ in your imports:

import getStarted from '@videos/get-started.mp4';

Note: If you're using webpack (i.e. running next dev --webpack), /videos imports work without any additional path configuration.

Add the watch command to your dev script

Update your package.json dev script to automatically sync videos while the dev server is running:

// package.json
"scripts": {
  "dev": "next dev & npx next-video sync -w"
}

Set up remote storage with Mux

1. Sign up for Mux if you don't have an account
2. Create an access token with Mux Video permissions
3. Add your credentials to .env.local:

# .env.local
MUX_TOKEN_ID=[YOUR_TOKEN_ID]
MUX_TOKEN_SECRET=[YOUR_TOKEN_SECRET]

Make sure .env.local is in your .gitignore.

Add a test video

Add a video file (e.g. sample-video.mp4) to the /videos directory and run the sync command to upload and process it:

npx next-video sync

Create a demo page

Create a page to verify your setup is working (app/demo-video/page.tsx or pages/demo-video.tsx):

import Video from 'next-video';
import sampleVideo from '/videos/sample-video.mp4';

export default function DemoVideo() {
  return <Video src={sampleVideo} />;
}

Turbopack users: If you configured the @videos/* path alias above, use @videos/sample-video.mp4 instead of /videos/sample-video.mp4 in your imports.

Then build and start your app, and navigate to /demo-video:

npm run dev

</details>

Usage

Local videos (Demo)

Add videos locally to the /videos directory then run npx next-video sync. The videos will be automatically uploaded to remote storage and optimized. You'll notice /videos/[file-name].json files are also created. These are used to map your local video files to the new, remote-hosted video assets. These json files must be checked into git.

npx next-video sync

You can also add next-video sync -w to the dev script to automatically sync videos as they're added to /videos while the dev server is running.

// package.json
"scripts": {
  "dev": "next dev & npx next-video sync -w",
},

Now you can use the <Video> component in your application. Let's say you've added a file called awesome-video.mp4 to /videos

import Video from 'next-video';
import awesomeVideo from '/videos/awesome-video.mp4';

export default function Page() {
  return <Video src={awesomeVideo} />;
}

Turbopack users: Recent versions of Next.js use Turbopack as the default dev server. Turbopack doesn't resolve /videos imports out of the box. You'll need to add a path alias in your tsconfig.json:

"paths": {
  "@/*": ["./src/*"],
  "@videos/*": ["./videos/*"]
}

Then use @videos/awesome-video.mp4 instead of /videos/awesome-video.mp4 in your imports. This is not needed if you're using webpack.

While a video is being uploaded and processed, <Video> will attempt to play the local file. This only happens during local development because the local file is never uploaded to your git repo.

Remote videos

For videos that are already hosted remotely (for example on AWS S3), import the remote URL and refresh the page. This creates a local JSON file in the /videos folder and the sync script will start uploading the video.

import Video from 'next-video';
import awesomeVideo from 'https://www.mydomain.com/remote-video.mp4';

export default function Page() {
  return <Video src={awesomeVideo} />;
}

If the hosted video is a single file like an MP4, the file will be automatically optimized for better deliverability and compatibility.

<details> <summary><strong>Remote videos with string source URL</strong></summary>

In some cases you might not have the remote video URL's available at the time of import.

That can be solved by creating a new API endpoint in your Next.js app for /api/video with the following code.

App router (Next.js >=13)

// app/api/video/route.js
export { GET } from 'next-video/request-handler';

Pages router (Next.js)

// pages/api/video/[[...handler]].js
export { default } f