Forem: Abdullah Al Fahad

I shipped a video player to npm — twice. What I learned about scoped CSS, "use client", and Nuxt modules.

Abdullah Al Fahad — Sat, 09 May 2026 10:28:33 +0000

A small, HLS-capable video player for React and Vue, with zero global CSS side-effects. Built in the open. Try it: https://video-player-playgraound.vercel.app/

The annoying gap

I needed an embeddable video player for a side project. Requirements were boring:

HLS streaming (.m3u8)
A clean play button overlay, optional close button, optional desktop/mobile aspect-ratio toggle
Fits the design system without fighting it
Works in Next.js App Router without a "ReactServerComponentsError" headache
Works in Nuxt 3 without manually wiring a plugin

I tried the popular options. Each was almost right.

react-player is mature but the API is geared toward "give me a URL and a giant control bar."
video.js is overkill for an embed and ships a chunk of theme CSS that fights Tailwind.
plyr, vidstack — beautiful, but either too heavy or too opinionated about styling.

The thing that kept biting me was CSS bleed. Every "drop-in" player I tried shipped global resets, theme tokens, or * selectors that quietly nudged my buttons by 1px or rewrote my form input borders. In a design system you've spent weeks tuning, that's a paper cut you don't want.

So I built one. Then, because half the consumers I had in mind were on Vue, I built it twice.

@glitchlab/react-video-player — https://www.npmjs.com/package/@glitchlab/react-video-player
@glitchlab/vue-video-player — https://www.npmjs.com/package/@glitchlab/vue-video-player

Both are at v1.0.2 today. Both are MIT. Both have the same prop surface, same UI, and ship under 4 KB gzipped of CSS + JS.

There's a live playground on Vercel where you can drop in a file or paste an HLS URL and try it end-to-end:

→ https://video-player-playgraound.vercel.app/

This post is the build-in-public version of how I got there. Three decisions ended up doing most of the work — the rest was just plumbing.

Decision 1: kill the global CSS

The first version of this player used Tailwind v4. I wrote the components, ran vite build --lib, and the resulting dist/style.css was 17 KB of:

:root, :host {
  --color-violet-700: ...;
  --font-sans: ui-sans-serif, system-ui, ...;
  /* ... */
}
*, ::before, ::after, ::backdrop {
  --tw-translate-x: 0;
  /* ... */
}

That's the entire Tailwind preflight, baked in. Anyone who imported @glitchlab/react-video-player/style.css would get my theme tokens injected into :root and global resets on every element on their page.

For an internal app this is whatever. For a published library it's malpractice. So I rewrote the CSS by hand.

The full stylesheet now scopes everything under a single class:

.gvp-root {
  position: relative;
  overflow: hidden;
  border-radius: 1.5rem;
  background-color: rgb(23 23 23 / 0.3);
  /* ... */
}

.gvp-root *,
.gvp-root *::before,
.gvp-root *::after {
  box-sizing: border-box;
}

.gvp-play {
  background-color: rgb(91 33 182 / 0.5);
  /* ... */
}

No :root, no * selectors at the document level. The component owns its subtree and nothing else. The CSS file dropped from 17 KB to 2.8 KB.

The bonus: consumers can now override with predictable specificity:

.gvp-root { border-radius: 8px; }
.gvp-play { background-color: rebeccapurple; }
.gvp-toggle-btn.is-active { color: deeppink; }

That's the whole "design system" story. No @apply, no :where() tricks, no Tailwind dependency in the lib. Tailwind users still get to use Tailwind in their own app — the player just stops yelling at theirs.

Lesson: if you ship CSS in an npm package, treat it like API. Every selector you publish is a contract. :root { --color-foo: ...; } is a worse breaking change than removing a prop, because it breaks silently.

Decision 2: preserve "use client" through the build

The React package targets Next.js App Router. That means every file that uses hooks needs "use client"; at the top, otherwise Next refuses to render it from a server component.

The component source had it:

"use client";
import React, { useRef, useState } from "react";
// ...

But here's the gotcha: rollup strips top-of-file directives during bundling unless you tell it not to. I ran vite build --lib, looked at dist/index.mjs, and the directive was gone. Importing the package from a Next App Router server component blew up with the classic "You're importing a component that needs useState" error.

The fix is a tiny rollup output plugin that re-prepends the directive after bundling:

// vite.config.ts (excerpt)
function preserveUseClient() {
  return {
    name: "preserve-use-client",
    renderChunk(code: string) {
      if (code.includes('"use client"') || code.includes("'use client'")) return null;
      return { code: `"use client";\n${code}`, map: null };
    },
  };
}

export default defineConfig({
  // ...
  build: {
    rollupOptions: {
      output: {
        plugins: [preserveUseClient()],
      },
    },
  },
});

After this, both dist/index.mjs and dist/index.cjs start with "use client";. Consumers can import the package directly from a server component:

// app/page.tsx — server component
import { ReactVideoPlayer } from "@glitchlab/react-video-player";
import "@glitchlab/react-video-player/style.css";

export default function Page() {
  return <ReactVideoPlayer src="/videos/hero.m3u8" />;
}

No client-component wrapper required. Just import and render.

Lesson: if your README claims "Next.js App Router compatible," verify the directive survives the bundler. Open dist/index.mjs after a build. If line 1 isn't "use client";, you're shipping a footgun.

Decision 3: ship a real Nuxt module

The Vue package was supposed to mirror the React one's "drop in and go" feel. For Nuxt, that meant a real module — not a "import this component manually in every page."

Nuxt's module system is a small library of helpers (@nuxt/kit) that lets you add plugins, components, and composables to a Nuxt app. The trick is that @nuxt/kit imports Node-only modules (giget, node:fs, etc.) — so if you naively re-export your Nuxt module from your main entry, the lib's vanilla Vue users get a bundle that tries to require node:fs in the browser.

The fix is to give Nuxt its own subpath export and never let it touch the main entry.

// package.json (excerpt)
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    },
    "./style.css": "./dist/style.css",
    "./nuxt": {
      "types": "./dist/nuxt-module.d.ts",
      "import": "./dist/nuxt-module.mjs",
      "require": "./dist/nuxt-module.cjs"
    }
  }
}

The vite config emits two entries:

build: {
  lib: {
    entry: {
      index: resolve(__dirname, "src/index.ts"),
      "nuxt-module": resolve(__dirname, "src/utils/nuxt-module.ts"),
    },
    formats: ["es", "cjs"],
  },
  rollupOptions: {
    external: ["vue", "hls.js", "@nuxt/kit", "#app", /^node:.*/],
  },
}

The Nuxt module itself is mostly boilerplate:

// src/utils/nuxt-module.ts
import { addPlugin, createResolver, defineNuxtModule } from "@nuxt/kit";

export default defineNuxtModule({
  meta: {
    name: "@glitchlab/vue-video-player",
    configKey: "vueVideoPlayer",
    compatibility: { nuxt: ">=3.0.0" },
  },
  setup(_options, _nuxt) {
    const resolver = createResolver(import.meta.url);
    addPlugin(resolver.resolve("./nuxt-plugin"));
  },
});

And the plugin auto-registers the component globally:

// src/utils/nuxt-plugin.ts
import { defineNuxtPlugin } from "#app";
import VideoPlayer from "../VideoPlayer.vue";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.component("VueVideoPlayer", VideoPlayer);
});

Now Nuxt 3 users get one-line integration:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@glitchlab/vue-video-player/nuxt"],
  css: ["@glitchlab/vue-video-player/style.css"],
});

And the component is available globally — no import, just <VueVideoPlayer src="..." /> anywhere.

Lesson: subpath exports aren't optional for libraries with framework-specific entry points. Putting a Nuxt module behind ./nuxt means non-Nuxt consumers never load @nuxt/kit and its Node-only deps. Their browser bundle stays clean.

A bug that took an hour to find: Vue HLS first-mount race

I want to call this one out because it's a category of bug that's easy to ship and almost impossible to catch with smoke tests.

The Vue HLS player initialized like this:

<script setup lang="ts">
const videoEl = ref<HTMLVideoElement | null>(null);

watch(
  () => props.src,
  (src) => {
    if (src) initPlayer(src);
  },
  { immediate: true }   // 👈 the bug
);
</script>

Looks fine. Tests passed. The deployed playground showed the player frame, the play button, the native controls bar — but the video never loaded. Click play, the play button vanished (so play() resolved), but no pixels.

The cause: watch(..., { immediate: true }) fires the callback during setup(), before the template renders. At that point videoEl.value is still null. initPlayer() early-returns, the watcher's already fired, and props.src doesn't change again — so HLS never attaches.

The React side wasn't affected because React effects always run after commit. The ref is bound by the time the effect fires.

The fix is two lines:

onMounted(() => {
  if (props.src) initPlayer(props.src);
});

watch(() => props.src, (src) => {
  if (src) initPlayer(src);
});  // no `immediate`

Now the first init runs in onMounted (template ref is bound), and subsequent src changes are handled by the regular watcher.

Lesson: immediate: true and refs don't mix cleanly in Composition API. If your watcher needs a ref that's bound by the template, use onMounted for the first run and a non-immediate watch for updates.

The playground

I wanted a proof point that wasn't "trust the README." So I built a minimal Next.js app with three things:

A drag-and-drop file zone (uploads create blob URLs and feed them to the player)
A URL input with validation (paste any HTTP/HTTPS link, including .m3u8)
The player itself, configured to remount cleanly on source change via key={videoSrc}

It's deployed at https://video-player-playgraound.vercel.app/. You can:

Paste the test HLS stream https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8 and watch it play
Paste a CORS-permissive .mp4 URL and watch it play
Drop a local file and watch the blob URL feed the player

It runs on the actual published @glitchlab/react-video-player from npm. Every time I publish a new version, I bump the dep and redeploy — the playground exercises the real published bundle, not source.

The Vue package shares the same UX in the local playground at playground/vue/ in the monorepo. The deployed demo is React because that's what Vercel templates make easy; the Vue version is one pnpm dev:vue away if you clone the repo.

What's in v1.0.2

Both packages at v1.0.2 today:

Same prop surface across React and Vue. src, poster, showDeviceToggle, defaultDevice, hoverPlay, tooltipText, muted, loop, controls, frameMaxWidth, aspectRatio, hlsConfig, isHls. React adds onClose + children; Vue uses closable + @close event + default slot.
HLS via hls.js with automatic native fallback for Safari (no hls.js cost when MSE isn't needed).
Captions/subtitles passthrough. Pass <track> elements as React children or Vue default slot.
Hover-play with race-safe play/pause. Tracks the play promise so a quick mouse-leave can't trigger a DOMException.
hlsConfig is memoizable. Pass a stable reference (useMemo / shallowRef) to avoid HLS rebuilds on render.
TypeScript types, full source maps, MIT licensed.
Smoke tests in vitest (8 React, 7 Vue).

Bundle size: ~3 KB JS gzipped + ~1 KB CSS gzipped, per package.

What's not in v1.0.2 (yet)

Picture-in-Picture toggle — the API is trivial, the UI affordance isn't. Holding off until I know how it should look in the toggle pill.
Playback speed control — same. Will land when I find a non-busy way to expose it.
Audio language switcher — for HLS streams with multiple audio renditions (dubs, descriptive audio, secondary languages). hls.js exposes audioTracks and audioTrack already, so the wiring is small; the open question is the UI affordance, same as PiP.
Caption track UI. You can pass <track> elements but the component doesn't render a captions menu. Native browser controls (controls={true}) handle this for now.
An actual stable Nuxt module ecosystem release — currently the module exists and works, but isn't on https://nuxt.com/modules. That's a separate process I'll do when the API has settled for a quarter or two.

Try it

# React
npm install @glitchlab/react-video-player hls.js

# Vue
npm install @glitchlab/vue-video-player hls.js

// React + Next.js App Router
import { ReactVideoPlayer } from "@glitchlab/react-video-player";
import "@glitchlab/react-video-player/style.css";

export default function Page() {
  return <ReactVideoPlayer src="/videos/hero.m3u8" controls />;
}

// Nuxt 3
export default defineNuxtConfig({
  modules: ["@glitchlab/vue-video-player/nuxt"],
  css: ["@glitchlab/vue-video-player/style.css"],
});

<!-- anywhere in your Nuxt app -->
<VueVideoPlayer src="/videos/hero.m3u8" :controls="true" />

Live demo: https://video-player-playgraound.vercel.app/
React package: https://www.npmjs.com/package/@glitchlab/react-video-player
Vue package: https://www.npmjs.com/package/@glitchlab/vue-video-player

Source: https://github.com/im-fahad/react-video-player and https://github.com/im-fahad/vue-video-player.

Issues, PRs, and feature requests welcome. If something's broken in your setup, the playground is the fastest way to reproduce it — drop your URL in, screenshot what you see, file an issue.

If you got value from this, the cheapest way to support is hitting the GitHub star button or sharing the playground link with someone fighting the same CSS-bleed problem. Both packages are MIT and will stay that way.

Implementing User Authentication in Next.js 14 using AuthJs Credentials (REST API)

Abdullah Al Fahad — Mon, 19 Feb 2024 04:55:13 +0000

Let’s talk step by step about how to implement Next.js 14’s user authentication with Auth.js (credentials) and REST API.

To start, begin by creating a Next.js application.

npx create-next-app@latest

Then, integrate the Auth.js library into your application.

npm install next-auth@beta
Next, you will need to add a AUTH_SECRET and NEXTAUTH_URL to your env file. Although during development you could leave AUTH_SECRET it empty, during production it would raise an error.

Now, proceed to create the auth.ts file within your /src directory. This file will handle authentication by interfacing with a REST API, specifically for login functionality. Depending on your API structure, the response may vary, but you can reference the example API response provided here to guide your implementation.

import type {NextAuthConfig} from "next-auth";
import NextAuth from "next-auth";

import CredentialsProvider from "next-auth/providers/credentials";
import $axios from "@/lib/Axios";

async function login(credentials: any) {
    try {
        return await $axios.post("your-login-api", credentials).then((res: any) => {
            const {user} = res;
            return {
                name: user.name,
                email: user.email,
                image: user.profile_photo,
                accessToken: res.access_token,
                // If you need any other information you can add here...
            };
        });
    } catch (e) {
        throw new Error("Something went wrong.");
    }
}

export const config: NextAuthConfig = {
    pages: {signIn: "/login"},
    providers: [
        CredentialsProvider({
            name: "Credentials",
            credentials: {
                email: {label: "Email", type: "email", placeholder: "example@email.com"},
                password: {label: "Password", type: "password", placeholder: "******"}
            },
            async authorize(credentials,) {
                try {
                    return login(credentials);
                } catch (e) {
                    return {};
                }
            },
        }),
    ],
    callbacks: {
        async jwt({user, token}) {
            if (user) {
                token.user = user;
            }
            return token;
        },
        async session({session, token}: any) {
            session.user = token.user;
            return session;
        },
    },
    debug: process.env.NODE_ENV === "development",
};

export const {handlers, auth, signIn, signOut} = NextAuth(config);

The jwt() callback is called user when the user first logs in. The user object will be populated with the object that is returned from the authorize function. The object that is returned from the jwt callback is what will be saved on the session cookie.

The session() callback receives the session cookie content in its token parameter. Whatever is returned from this callback is what will be presented when useSession or getServerSession is called.

Next, establish a api directory within either your /src/app or /app directory. Inside this api directory, create a route.ts file within the api/auth/[...nextauth] directory structure.

import {handlers} from "@/auth";

export const {GET, POST} = handlers;
Then create another route.ts file inside api/protected directory.

import {auth} from "@/auth";

export const GET = auth((req) => {
    if (req.auth) {
        return Response.json({data: "Protected data"});
    }

    return Response.json({message: "Not authenticated"}, {status: 401});
}) as any;

In your layout.tsx file, you'll utilize the SessionProvider to manage session data. This component enables your application to interact with the user authentication state across various components. You can use it to display different content or UI elements based on whether a user is authenticated or not.

"use client";
import React from "react";
import {SessionProvider} from "next-auth/react";
...

export default function RootLayout({children}: { children: React.ReactNode }) {
    return (
        <SessionProvider>
            <html lang="en">
            <body className="pintoe">
                {children}
            </body>
            </html>
        </SessionProvider>
    );
}

Well done, your Auth.js setup is complete. Now you can use your session data on every page (route). ex: app/pages.tsx

"use client";

import {useSession} from "next-auth/react";
import Image from "next/image";

export default function HomePage() {
    const {data: session} = useSession();

    return (
        <div>
            <h2>{session?.user.name}</h2>

            <Image src={session?.user.image} alt="User Avatar" width={200} height={200}/>
        </div>
    );
}

Now you can use a higher order component to protect authenticated routes. On my side, I create a AuthGuard.tsx file in src/ components directory.

"use client";
import React, {useEffect, useState} from "react";
import {useSession} from "next-auth/react";
import {usePathname, useRouter} from "next/navigation";

export default function AuthGuard({children}: { children: React.ReactNode }) {
    const {data: status}: any = useSession();
    const router = useRouter();
    const pathname = usePathname();
    const [loading, setLoading] = useState<boolean>(true);

    const guestRoutes: string[] = [
        "/login",
        "/register"
    ];

    useEffect(() => {
        const isGuestRoute = !!guestRoutes.find(route => route === pathname);
        setLoading(true);

        if (status === "loading") {
            return;
        } else if (status === "authenticated" && isGuestRoute) {
            router.push("/");
        } else if (status === "unauthenticated" && !isGuestRoute) {
            router.push("/login");
        } else {
            setLoading(false);
        }
    }, [pathname, status]);

    return (loading ?
        <div>
            Loading...
        </div> : children);
};

Use the AuthGuard component in your layout.tsx file.

"use client";
import "@/assets/styles/tailwind.css";
import React from "react";
import {SessionProvider} from "next-auth/react";
import AuthGuard from "@/lib/AuthGurad";

export default function RootLayout({children}: { children: React.ReactNode }) {
    return (
        <SessionProvider>
            <html lang="en">
            <body className="pintoe">
            <AuthGuard>
                {children}
            </AuthGuard>
            </body>
            </html>
        </SessionProvider>
    );
}

Now the AuthGuard component will automatically handle guest/auth route redirects based on login session data.

Next, we will discuss step by step how to implement redux-toolkit in Next.js 14 and how to configure Axios to get access-token from the auth session.