Build video upload + HLS playback in Next.js 15 with direct

Build a video upload + HLS playback flow in Next.js 15 (with direct uploads)

This tutorial builds a "user uploads a video, user watches the video" feature in a Next.js 15 app. The browser uploads directly to a managed video API so your server never holds bytes, a webhook flips the database row from processing to ready, and the watch page plays an HLS manifest. The entire implementation is ~120 lines across four files.

Why direct upload? Next.js 15 Server Actions cap request bodies at 1 MB by default. Even Route Handlers with bumped limits will sit there holding a 300 MB file in a serverless function while encoding hasn't started. Direct upload pushes bytes straight to the storage layer.

1. Project setup

npx create-next-app@latest nextjs-video-upload-demo --typescript --app --tailwind
cd nextjs-video-upload-demo
npm install

Create a .env.local:

FASTPIX_TOKEN_ID=pk_...
FASTPIX_SECRET=sk_...
FASTPIX_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_APP_URL=http://localhost:3000
DATABASE_URL=file:./dev.db

The token and secret come from dashboard.fastpix.io (Access Tokens). Webhooks live at https://docs.fastpix.io/docs/webhooks-collection; create a webhook pointing at your tunneled URL.

Required versions: Node 22.x or newer, Next.js 15.x, hls.js 1.6.x for the player.

2. The "create upload" Route Handler

// app/api/uploads/route.ts
import { NextResponse } from &#34;next/server&#34;;
import { db } from &#34;@/lib/db&#34;;

export async function POST() {
  const auth = Buffer.from(
    `${process.env.FASTPIX_TOKEN_ID}:${process.env.FASTPIX_SECRET}`
  ).toString(&#34;base64&#34;);

  const res = await fetch(&#34;https://api.fastpix.io/v1/on-demand&#34;, {
    method: &#34;POST&#34;,
    headers: {
      Authorization: `Basic ${auth}`,
      &#34;Content-Type&#34;: &#34;application/json&#34;,
    },
    body: JSON.stringify({
      corsOrigin: process.env.NEXT_PUBLIC_APP_URL,
      playbackPolicy: [&#34;public&#34;],
    }),
  });

  if (!res.ok) {
    const txt = await res.text();
    return NextResponse.json({ error: txt }, { status: 502 });
  }

  const data = await res.json();

  const row = await db.video.create({
    data: {
      providerAssetId: data.id,
      status: &#34;processing&#34;,
    },
  });

  return NextResponse.json({
    videoId: row.id,
    uploadUrl: data.uploadUrl,
  });
}

cors_origin matters. The browser is about to PUT bytes from your origin to FastPix's upload host, so the upload URL needs to allow your origin. Get this wrong and Chrome will throw a CORS error.

Note: Don't return assetId to the browser. Stash it server-side and hand the client a stable videoId instead. Keeps the asset-id mapping under your control.

3. The upload component

// app/upload/page.tsx
&#34;use client&#34;;
import { useState } from &#34;react&#34;;
import { useRouter } from &#34;next/navigation&#34;;

export default function UploadPage() {
  const router = useRouter();
  const [progress, setProgress] = useState(0);
  const [error, setError] = useState(null);

  async function handleUpload(file: File) {
    setError(null);
    setProgress(0);

    const r = await fetch(&#34;/api/uploads&#34;, { method: &#34;POST&#34; });
    if (!r.ok) { setError(&#34;Could not create upload&#34;); return; }
    const { videoId, uploadUrl } = await r.json();

    await new Promise((resolve, reject) =&gt; {
      const xhr = new XMLHttpRequest();
      xhr.open(&#34;PUT&#34;, uploadUrl);
      xhr.upload.onprogress = (e) =&gt; {
        if (e.lengthComputable) setProgress(Math.round((e.loaded / e.total) * 100));
      };
      xhr.onload = () =&gt; xhr.status &lt; 300 ? resolve() : reject(new Error(`PUT ${xhr.status}`));
      xhr.onerror = () =&gt; reject(new Error(&#34;Network error&#34;));
      xhr.send(file);
    }).catch((e) =&gt; setError(String(e)));

    router.push(`/watch/${videoId}`);
  }

  return (
    
       e.target.files?.[0] &amp;&amp; handleUpload(e.target.files[0])}
      /&gt;
      {progress &gt; 0 &amp;&amp; <p>Uploading: {progress}%</p>}
      {error &amp;&amp; <p>{error}</p>}
    
  );
}

We use XMLHttpRequest instead of fetch because fetch still doesn't expose upload progress in a useful way in 2026, and "uploading: 47%" is the difference between the user closing the tab and waiting.

Tip: For production, swap this for the official FastPix Web upload SDK. It does chunked uploads, retries, and resume on flaky networks. Worth it for mobile users.

4. The webhook handler

// app/api/webhooks/fastpix/route.ts
import { NextResponse } from &#34;next/server&#34;;
import { createHmac, timingSafeEqual } from &#34;node:crypto&#34;;
import { db } from &#34;@/lib/db&#34;;

export async function POST(req: Request) {
  const raw = await req.text();
  const sig = req.headers.get(&#34;fastpix-signature&#34;) ?? &#34;&#34;;
  const expected = createHmac(&#34;sha256&#34;, process.env.FASTPIX_WEBHOOK_SECRET!)
    .update(raw)
    .digest(&#34;hex&#34;);

  // timing-safe compare
  if (sig.length !== expected.length ||
      !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return NextResponse.json({ error: &#34;bad signature&#34; }, { status: 401 });
  }

  const evt = JSON.parse(raw);

  if (evt.type !== &#34;video.asset.ready&#34;) {
    return NextResponse.json({ ok: true });
  }

  const asset = evt.data;
  await db.video.update({
    where: { providerAssetId: asset.id },
    data: { status: &#34;ready&#34;, playbackId: asset.playbackIds?.[0]?.id },
  });

  return NextResponse.json({ ok: true });
}

Two things to notice:

We read the raw body as text, then JSON-parse it ourselves. If you use req.json() first, the HMAC won't match because Node has already re-serialized the object.
The signature check is timingSafeEqual. Don't compare with ===; it leaks bytes through timing.

Note: Webhook event names and field shapes vary by provider. If swapping in Mux, the event is video.asset.ready too, but the signature header is Mux-Signature and the payload uses playback_ids (snake case). Always read the provider's webhook reference.

Testing webhooks locally

# In one terminal:
npm run dev
# In another, expose 3000 to the internet:
ngrok http 3000
# Register the ngrok URL in dashboard.fastpix.io → Webhooks
# Format: https://abc123.ngrok-free.app/api/webhooks/fastpix

Tail the output. Upload a clip from the dev UI. You should see a POST to /api/webhooks/fastpix within 30 to 90 seconds for a short clip.

5. The watch page

// app/watch/[id]/page.tsx
import { db } from &#34;@/lib/db&#34;;
import { Player } from &#34;./Player&#34;;

export default async function WatchPage({ params }: { params: { id: string } }) {
  const v = await db.video.findUnique({ where: { id: params.id } });
  if (!v) return <p>Not found</p>;
  if (v.status !== &#34;ready&#34; || !v.playbackId) {
    return <p>Still processing. This page auto-refreshes.</p>;
  }
  const src = `https://stream.fastpix.io/${v.playbackId}.m3u8`;
  return ;
}

And a client component for the player:

// app/watch/[id]/Player.tsx
&#34;use client&#34;;
import { useEffect, useRef } from &#34;react&#34;;
import Hls from &#34;hls.js&#34;;

export function Player({ src }: { src: string }) {
  const ref = useRef(null);

  useEffect(() =&gt; {
    const v = ref.current;
    if (!v) return;
    // Safari plays HLS natively.
    if (v.canPlayType(&#34;application/vnd.apple.mpegurl&#34;)) {
      v.src = src;
      return;
    }
    if (!Hls.isSupported()) return;
    const hls = new Hls();
    hls.loadSource(src);
    hls.attachMedia(v);
    return () =&gt; hls.destroy();
  }, [src]);

  return ;
}

That's the whole player for a public asset. For private assets, mint a short-lived JWT on the server and append it as a query string. The JWT is signed with an asymmetric key pair you generate once and store in your secret manager.

6. Sanity-check the round trip

POST /api/uploads 200
PUT https://upload.fastpix.io/... 200   # browser → FastPix
POST /api/webhooks/fastpix 200          # ~30-90s later
GET  /watch/ 200

If the webhook never fires, three things go wrong in this order, every time: ngrok URL changed (re-register it), CORS misconfigured on the upload (check the cors_origin you passed), or the webhook secret in .env.local doesn't match the one in the dashboard.

What about the player UI?

We used `` for this tutorial, which gives you the browser default controls. For a real product you'll want a custom player. Two paths:

Option	When to pick it
FastPix Web Player (custom element)	Default. You drop `` and the player + analytics wiring come together.
Build on hls.js directly	You want full UI control. More code, total ownership of the surface.

What's next

QoE analytics. Wire the Video Data SDK (or your provider's equivalent). FastPix Video Data is free up to 100,000 views per month, which covers most side-project and SaaS workloads before you ever pay.
Resume on interruption. Replace the raw XMLHttpRequest upload with the official Web upload SDK to get chunked uploads and resume.
Signed playback. Switch the playback policy from public to signed and add JWT minting to the watch page.
Thumbnails. The default thumbnail is the middle frame. Pick a better one.

The pattern transfers cleanly. If you build this on Mux, swap the endpoint to https://api.mux.com/video/v1/uploads, the playback URL to https://stream.mux.com/.m3u8, and the webhook handler to verify Mux-Signature. Cloudflare Stream and api.video have the same three pieces with their own dialect.

The thing this tutorial is really about, more than any one provider, is the shape: broker upload tokens on the server, push bytes from the browser, receive webhooks, render manifests. Once you have that shape in your head, the next video feature you build will take an afternoon instead of a sprint.

Build video upload + HLS playback in Next.js 15 with direct uploads