What Are the Core Technologies Used in LunaTV?

LunaTV is built on a modern stack comprising Next.js 14 with TypeScript, Tailwind CSS for styling, ArtPlayer with HLS.js for adaptive streaming, and Kvrocks/Redis for state persistence, all containerized with Docker.

LunaTV is an open-source, cross-platform video aggregation web application developed by MoonTechLab. Understanding the core technologies used in LunaTV reveals how the project achieves its fast, responsive, and portable streaming experience across devices.

Frontend Foundation: Next.js 14 and TypeScript

LunaTV leverages Next.js 14 with the App Router architecture as its primary frontend framework. This choice enables server-side rendering, API routes, and static site generation for SEO-friendly pages. The framework is written in TypeScript 4, providing static typing across the entire codebase to catch bugs early and improve developer productivity.

App Router Architecture

The application structure follows Next.js 14 conventions with the App Router pattern. Key pages like the video player reside in src/app/play/page.tsx, where server and client components coexist to optimize performance. TypeScript interfaces ensure type safety throughout the component hierarchy.

Styling with Tailwind CSS 3

The user interface relies on Tailwind CSS 3, a utility-first CSS framework that keeps stylesheets minimal while enabling fully responsive designs. LunaTV implements a desktop sidebar combined with mobile bottom navigation using Tailwind's breakpoint utilities.

Responsive Navigation Components

In src/components/Sidebar.tsx, the navigation uses Tailwind's responsive prefixes to switch between hidden mobile views and expanded desktop layouts:

export default function Sidebar() {
  return (
    <nav className="hidden lg:flex flex-col w-64 h-full bg-gray-900 text-white p-4">
      {/* Logo */}
      <div className="mb-8 flex items-center justify-center">
        <img src="/logo.png" alt="LunaTV" className="h-12 w-12" />
        <span className="ml-2 text-xl font-bold">LunaTV</span>
      </div>
      {/* Navigation links */}
      <ul className="space-y-2">
        <li><a href="/" className="block py-2 px-3 rounded hover:bg-gray-800">Home</a></li>
        <li><a href="/live" className="block py-2 px-3 rounded hover:bg-gray-800">Live</a></li>
        {/* …more items */}
      </ul>
    </nav>
  );
}

The tailwind.config.ts file defines custom theme extensions and purge settings to optimize the production build.

Video Playback Engine

At the heart of LunaTV is its video playback system combining ArtPlayer and HLS.js. ArtPlayer provides the rich UI controls (play/pause, subtitles, speed control), while HLS.js handles adaptive streaming of .m3u8 sources for browsers lacking native HLS support.

ArtPlayer and HLS.js Integration

The src/app/play/page.tsx file initializes the player with fallback logic for HLS support:

import Artplayer from 'artplayer';
import Hls from 'hls.js';

const videoEl = useRef<HTMLVideoElement>(null);
useEffect(() => {
  if (videoEl.current && videoUrl) {
    // If the browser supports native HLS, use it; otherwise fall back to Hls.js
    if (videoEl.current.canPlayType('application/vnd.apple.mpegurl')) {
      videoEl.current.src = videoUrl;
    } else if (Hls.isSupported()) {
      const hls = new Hls();
      hls.loadSource(videoUrl);
      hls.attachMedia(videoEl.current);
      // expose the Hls instance on the video element (used elsewhere)
      videoEl.current.hls = hls;
    }
    const player = new Artplayer({
      container: document.querySelector('#artplayer')!,
      url: videoUrl,
      // …other options like autoplay, theme, etc.
    });
    // Clean‑up on unmount
    return () => player.destroy();
  }
}, [videoUrl]);

This implementation ensures smooth playback across Safari (native HLS) and Chrome/Firefox (via HLS.js).

Data Persistence Layer

LunaTV uses Kvrocks, Redis, or Upstash as its key-value data store for user-specific data. The abstraction layer in src/lib/db.client.ts provides a unified interface for watch history, favorites, and sync progress across devices.

KV Store Abstraction

The database client supports multiple Redis-compatible backends. Functions like savePlayRecord persist video progress using hash sets:

import { getClient } from '@/lib/db.client';

export async function savePlayRecord(
  userId: string,
  videoId: string,
  currentTime: number,
) {
  const client = getClient();               // abstracts Kvrocks / Redis / Upstash
  await client.hset(`play:${userId}`, videoId, String(currentTime));
}

This architecture ensures cross-device synchronization of viewing progress while maintaining low-latency reads.

Developer Experience and Deployment

Quality Control Tooling

The project enforces code quality through ESLint for linting, Prettier for formatting, and Jest for unit testing. These tools are configured in the repository root to maintain consistent code style and prevent regressions.

Docker Containerization

LunaTV ships with an official Docker image defined in the Dockerfile. This containerization guarantees reproducible runtime environments and simplifies deployment to Docker-compatible platforms like Zeabur or self-hosted infrastructure. The next.config.js handles image optimization and routing configurations within the containerized environment.

Summary

• Next.js 14 with App Router provides the framework foundation for server-side rendering and static generation.
• TypeScript 4 ensures type safety across the entire LunaTV codebase.
• Tailwind CSS 3 enables responsive layouts with utility-first styling as seen in src/components/Sidebar.tsx.
• ArtPlayer and HLS.js work together in src/app/play/page.tsx to deliver adaptive streaming with rich UI controls.
• Kvrocks/Redis/Upstash via src/lib/db.client.ts handles persistent storage of user data like watch history.
• Docker containerization ensures consistent deployment environments across different hosting platforms.

Frequently Asked Questions

What frontend framework does LunaTV use?

LunaTV uses Next.js 14 with the App Router architecture. The framework provides server-side rendering capabilities, API routes for backend functionality, and static generation for performance. The entire frontend is written in TypeScript for type safety.

How does LunaTV handle video streaming?

The application uses ArtPlayer for the user interface and HLS.js for handling adaptive bitrate streaming. In src/app/play/page.tsx, the code detects native HLS support first, falling back to HLS.js for browsers that require it, ensuring compatibility across Safari, Chrome, and Firefox.

What database does LunaTV use for user data?

LunaTV uses Kvrocks, Redis, or Upstash as its key-value store. The abstraction in src/lib/db.client.ts allows seamless switching between these Redis-compatible backends to store watch history, favorites, and playback progress.

Is LunaTV containerized for deployment?

Yes, LunaTV includes an official Docker image configuration. The Dockerfile in the repository root defines a reproducible environment, making deployment straightforward on Docker-compatible platforms including Zeabur and self-hosted solutions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}