jellyfin-web/CONTRIBUTING.md

Contributing to Jellyfin Web

Thanks for taking the time to contribute! 💜 Jellyfin is an entirely volunteer-driven project, so without contributors like you it could not exist!

Below are some general guidelines and information about this project. If you have any questions, please join one of our development chat rooms to discuss them!

Contributor Guidelines

New Code

• New files MUST be written in TypeScript.
• API interactions MUST be made using the Jellyfin TypeScript SDK.
• SHOULD be covered by unit tests when possible (legacy component/view code is deemed untestable).
• SHOULD avoid whitespace only changes in unchanged sections of code.
• SHOULD NOT overuse dynamic imports. We use dynamic imports at the page level; otherwise we should let our build tooling deal with code-splitting for the best bundle sizes.
• SHOULD NOT reference browser globals. Globals exist for plugins/legacy compatibility. Use direct imports for any dependencies instead.

Localization

• Translation changes or additions MUST be made via the Jellyfin Weblate instance except for the source language (en-us).
• Existing translation keys SHOULD NOT be renamed without a significant reason. Weblate cannot track key name changes so a key name change requires retranslation in ALL languages.

Pull Requests

• MUST follow project guidelines.
  • SHOULD NOT use "Conventional Commits" for titles or commit messages.
  • SHOULD NOT rebase once reviews are in progress.
• MUST follow the LLM development policy.
• MUST test that the change works as expected before marking a PR as ready for review.
• SHOULD represent a singular focus (i.e. a PR to fix a bug should not include unrelated refactoring).
• SHOULD NOT update from master needlessly once opened (only update if conflicts exist).

Application Architecture

Tech Stack

• Bulletproof React based structure (official reference) — General file structure
• TypeScript — Programming language
• Jellyfin TypeScript SDK — Jellyfin API library
• React — User Interface library
• React Router — Routing library
• TanStack Query — State management library for server data
• MUI components (in Dashboard and Experimental layouts) — UI component library
• Webpack — Bundler / build tooling
• Vitest — Test library

Legacy Stack

Library	Replacement
Emby WebComponents	MUI components (Dashboard + Experimental apps ONLY; Untested on TVs)
App Router	React Router
View Manager	React Router
Jellyfin ApiClient	Jellyfin TypeScript SDK
jQuery	None (use plain JavaScript/TypeScript)

Supported Browsers

This codebase supports a wide variety of platforms including TVs that are stuck on ancient versions of browser engines. As a result, we can only use JavaScript and CSS features that are either directly supported by these browser versions or can be otherwise compiled or polyfilled for compatibility. The official list of supported browser versions can be found in the browserlist section of the package.json file.

Application Components

• Stable App src/apps/stable
  • Main user application
  • Supports TV layout
• Experimental App src/apps/experimental
  • Ongoing rewrite of the Stable App using MUI components
  • Currently reuses (most) pages from the Stable App to maintain parity
  • Does not currently support TV layout!
• Dashboard App src/apps/dashboard
  • Admin dashboard and metadata editor pages
  • Almost completely rewritten using MUI components
  • No TV support (dashboard pages are not available)
• Wizard App src/apps/wizard
  • First time setup wizard
• Plugins src/plugins
  • This is a terrible name as it has nothing to do with server plugins
  • Modular functionality that is loaded dynamically at runtime
  • ALL media player implementations are plugins
  • Allows native wrapper overrides