Skip to main content
EmbyTok can be run as a Progressive Web App (PWA) in any modern browser. This guide covers installing dependencies, running the development server, and building for production.

​
Prerequisites

Before installing EmbyTok, ensure you have:
  • Node.js v14 or higher (v20 recommended)
  • npm, yarn, or pnpm package manager
  • Git (to clone the repository)

​
Installation

1

Clone the repository

Clone the EmbyTok repository to your local machine:
git clone https://github.com/your-username/embytok.git
cd embytok
2

Install dependencies

Install the required npm packages using your preferred package manager:
npm install
This will install all dependencies including:
  • React 18 and React DOM
  • Vite (build tool)
  • TypeScript
  • Tailwind CSS
  • Capacitor (for mobile apps)
  • Lucide React (icons)
  • PWA plugin
3

Start the development server

Launch the development server with one of these commands:
npm run dev
The application will be available at:
  • Web only: http://localhost:5173
  • LAN access: http://0.0.0.0:5173 or http://<your-ip>:5173
  • Full stack: Frontend at Vite port + API proxy to port 5176
The npm run dev command starts both the frontend development server and the local file server backend for testing the Folder Server mode.

​
Development Commands

CommandDescription
npm run devStart full stack (frontend + backend file server)
npm run dev:webStart frontend only (Vite dev server)
npm run dev:lanStart frontend with LAN access (0.0.0.0)
npm run dev:stackAlias for dev - full stack mode
npm run buildBuild production bundle
npm run previewPreview production build locally

​
Building for Production

1

Build the application

Compile TypeScript and bundle assets for production:
npm run build
This command:
  1. Runs TypeScript compiler (tsc)
  2. Builds optimized production bundle with Vite
  3. Outputs to the dist/ directory
2

Preview the production build (optional)

Test the production build locally:
npm run preview
The preview server will start on port 4173 by default.
3

Deploy the dist folder

Deploy the dist/ folder to your web server or hosting platform:
  • Static hosting: Netlify, Vercel, GitHub Pages, Cloudflare Pages
  • Traditional server: Nginx, Apache, Caddy
  • With file server backend: Use the LAN media server (see below)

​
Running with File Server Backend

EmbyTok includes a built-in file server for serving local media files without Emby/Plex:
1

Build the frontend

npm run build
2

Start the LAN media server

Start the server with optional environment variables:
npm run lan:server
3

Access the application

Open your browser to http://localhost:5176 (or your custom port).The server will display LAN access URLs in the console.

​
File Server Environment Variables

VariableDefaultDescription
PORT5176Server port
HOST0.0.0.0Listen address (0.0.0.0 for LAN access)
SERVE_WEBtrueServe static web files
WEB_ROOTdistWeb files directory
LAN_CONFIG_FILE./lan-media-config.jsonService configuration file
MEDIA_ROOT-Default media directory for initial setup
BROWSE_ROOTS-Comma-separated browsable root directories
The file server provides both the web UI and REST API endpoints for folder browsing and video streaming.

​
Troubleshooting

If you see errors like:
http proxy error: /api/admin/...
connect ECONNREFUSED 127.0.0.1:5176
Solution: The backend file server is not running. Use npm run dev (which starts both frontend and backend) instead of npm run dev:web.
If port 5173 (Vite) or 5176 (file server) is already in use:Solution: Change the port using environment variables:
PORT=8080 npm run dev:web
# or for file server
PORT=8088 npm run lan:server
Solution: Ensure you’re using TypeScript 5.2 or higher:
npm install typescript@latest --save-dev
npm run build

​
Progressive Web App (PWA)

EmbyTok is configured as a PWA with offline support:
  • Automatic updates: Service worker updates automatically
  • Install prompt: Available on mobile browsers and desktop Chrome/Edge
  • Offline assets: Static files are cached for offline use
  • Portrait mode: Optimized for vertical video viewing
To install as PWA:
  1. Open EmbyTok in Chrome/Edge/Safari
  2. Look for the install prompt in the address bar
  3. Click “Install” to add to home screen

​
Next Steps

Docker Deployment

Deploy with Docker for production environments

Android App

Build native Android application with Capacitor

iOS App

Create native iOS app with UIKit

Configuration

Configure Emby/Plex servers and settings

Build docs developers (and LLMs) love

Get started for freeTalk to us