How to Get Involved with the Invidious Maintainers: A Complete Contributor's Guide

You can get involved with the Invidious maintainers by contributing code via GitHub pull requests, improving documentation, translating the interface through Weblate, or joining the community Matrix and IRC channels.

Invidious is a community-driven, open-source YouTube front-end written in Crystal. If you want to get involved with the Invidious maintainers, the project welcomes contributions ranging from bug fixes and feature development to translation work and infrastructure support. Whether you are a developer, technical writer, or translator, there is an established pathway to participate in the iv-org/invidious repository.

Ways to Contribute to Invidious

The maintainers accept multiple forms of contribution. You do not need to be a software developer to help improve the project.

Code contributions include bug fixes, new features, and performance improvements submitted via GitHub pull requests. Documentation contributions involve updating guides, API references, or installation instructions in the separate iv-org/documentation repository. Translation work happens through the Weblate platform, allowing non-developers to localize the interface into additional languages. Community support includes answering questions in Matrix or IRC channels, reporting bugs with detailed reproduction steps, and helping with instance infrastructure.

Setting Up Your Development Environment

To begin contributing code, you must fork the repository and configure a local Crystal development environment.

1. Fork the repository on GitHub at https://github.com/iv-org/invidious/fork.

2. Clone your fork locally:

   git clone https://github.com/<your-username>/invidious.git
   cd invidious

3. Create a feature branch with a descriptive name:

   git checkout -b my-feature

The scripts/install-dependencies.sh script installs Crystal, required libraries, and video-player assets needed to build the application locally.

Understanding the Invidious Architecture

Invidious is built on Kemal, a Sinatra-style web framework for Crystal. Understanding the directory structure helps you locate where to make changes.

• src/invidious.cr is the application entry point. It loads config.yml, establishes PostgreSQL or SQLite connections via DB.open CONFIG.database_url, registers background jobs, and boots the Kemal server.

• src/invidious/routes/ contains all HTTP route definitions for both the web interface and API endpoints.

• src/invidious/jobs/ houses background workers that refresh channels, update statistics, and send notifications.

• src/invidious/database/ manages database migrations, schema definitions, and integrity checks.

• src/invidious/yt_backend/ handles YouTube data extraction without using the official API, including connection pool management for YT_POOL and GGPHT_POOL.

When the application starts, src/invidious.cr executes a specific sequence: it parses command-line options, initializes database pools, registers background jobs, configures Kemal middleware (compression, authentication, frame-deny headers), and serves static assets before starting the server.

Making Your First Code Contribution

New contributors typically start by adding a route or modifying existing logic in src/invidious/routes/. Below is a complete example that adds a /api/v1/ping endpoint.

Create the route file at src/invidious/routes/ping.cr:

module Invidious::Routes::Ping
  def self.register
    Kemal.get "/api/v1/ping" do |env|
      {status: "alive", time: Time.utc.to_s}.to_json
    end
  end
end

Register the route in your router file (e.g., src/invidious/routes/router.cr):

Invidious::Routes::Ping.register

Run the test suite to ensure changes do not break existing functionality:

crystal spec

Push your changes and open a pull request:

git add .
git commit -m "Add ping endpoint for health checks"
git push origin my-feature

Open the pull request against the upstream iv-org/invidious master branch. The maintainers will review your code and run automated CI checks defined in .github/workflows/.

Documentation and Translation Contributions

Non-code contributions follow different pathways to reach the maintainers.

Documentation resides primarily in the iv-org/documentation repository and appears online at https://docs.invidious.io/. Submit documentation improvements as pull requests to that separate repository.

Translations are coordinated through Weblate at https://hosted.weblate.org/engage/invidious/. You can suggest new strings or correct existing translations without creating a GitHub account. The README file (lines 36-44) contains specific instructions for translators.

Community Channels and Communication

Direct communication with maintainers happens through several bridged channels.

• Matrix: Join #invidious:matrix.org for real-time chat with developers and users.
• IRC: Connect to #invidious on Libera.Chat.
• Fediverse: Follow @[email protected] for project announcements.

These channels appear in the README's "Chat with us" section (lines 42-53). You can also support the project financially through the donation link provided in the README (line 40).

Summary

• Fork and clone the iv-org/invidious repository, then create a feature branch before making changes.
• Entry point: The application boots from src/invidious.cr, which manages configuration, database connections, and the Kemal server.
• Routes: Add new endpoints by creating files in src/invidious/routes/ and registering them in the router.
• Testing: Always run crystal spec before submitting to verify your changes pass the test suite.
• Translations: Use Weblate instead of GitHub to localize interface strings.
• Communication: Reach maintainers via Matrix (#invidious:matrix.org) or IRC (#invidious on Libera.Chat).

Frequently Asked Questions

Do I need to know Crystal to contribute to Invidious?

Yes, code contributions require knowledge of Crystal, the language Invidious is written in. However, you can contribute to documentation, translations, or community support without writing Crystal code. Translators work through the Weblate web interface, and documentation uses standard Markdown.

How do I test my changes locally before submitting a pull request?

Run crystal spec from the repository root to execute the test suite. For manual testing, start the server with crystal run src/invidious.cr -Drelease after configuring your config/config.yml file (copied from config/config.example.yml). You can then test endpoints using curl or a web browser at localhost:3000.

What is the best way to propose a new feature to the maintainers?

Start a discussion in the Matrix room (#invidious:matrix.org) or IRC channel (#invidious on Libera.Chat) before writing code. This allows you to gauge maintainer interest and receive architectural guidance. For straightforward bug fixes or small improvements, you can open a pull request directly with a clear description of the problem and solution.

Where should I add a new API endpoint in the codebase?

Create a new file in src/invidious/routes/ following the existing module pattern, then register it in the router (typically src/invidious/routes/router.cr). Routes use the Kemal framework, so define endpoints using Kemal.get, Kemal.post, or similar methods within a dedicated module under Invidious::Routes.

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