How to Contribute to Invidious: Developer Setup and Contribution Guide

Yes, anyone can contribute to the Invidious project through code submissions, translations, or documentation improvements.

Invidious is an open-source YouTube front-end written in Crystal and built on the Kemal web framework. The iv-org/invidious repository welcomes contributors of all skill levels, whether you are fixing bugs, adding features, or translating the interface. This guide walks you through the modular architecture and the exact steps to submit your first contribution.

Understanding the Invidious Architecture

Before you contribute to Invidious, familiarize yourself with its deliberate modular structure. This organization makes it straightforward to locate the correct place for any change.

Application Bootstrap

The src/invidious.cr file serves as the main entry point. It loads the runtime configuration, establishes the PostgreSQL connection, initializes background jobs, and registers all HTTP routes. When you add new functionality that requires startup initialization, this is the file you modify.

Routing Layer

All request-handling logic lives in src/invidious/routes/**. This directory contains definitions for HTML pages, API endpoints (/api/v1/...), and form submissions. Each route file maps HTTP verbs to specific application logic.

Background Jobs

The src/invidious/jobs/** directory houses periodic workers such as channel refresh, feed refresh, statistics collection, and popular-video polling. These jobs inherit from base classes and run on separate threads to keep the web interface responsive.

Database Layer

Database schema definitions, migration helpers, and query utilities reside in src/invidious/database/**. If your contribution requires new tables or columns, you will add migrations here.

YouTube Backend and Helpers

Low-level interactions with YouTube's public endpoints, including caching logic and HMAC handling, are isolated in src/invidious/yt_backend/**. Shared utilities and helper methods live in src/invidious/helpers/**.

How to Contribute Code to Invidious

The project follows a standard Git-flow model. Follow these steps to ensure your contribution is properly formatted and tested.

Step 1: Fork and Clone the Repository

Click the Fork button on the GitHub page, then clone your personal fork locally:

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

Step 2: Create a Feature Branch

Create a descriptive branch name for your changes:

git checkout -b my-new-feature

Step 3: Implement Your Changes

Edit the appropriate source files based on your goal:

• Add a web page or API: Modify files in src/invidious/routes/
• Create a background task: Add a new file to src/invidious/jobs/
• Update database logic: Work in src/invidious/database/
• Adjust configuration: Reference config.yml.example for the template

Step 4: Run the Test Suite

Invidious uses Crystal's built-in spec library. Execute all tests from the project root:

crystal spec

Ensure all tests pass before committing. The spec files are located in the spec/ directory.

Step 5: Commit and Push

Stage your changes with clear commit messages:

git add .
git commit -m "Add: <description of change>"
git push origin my-new-feature

Step 6: Open a Pull Request

Navigate to https://github.com/iv-org/invidious/compare and select your branch. Fill out the PR template completely, referencing any related issues. Maintainers will review your code and may request changes; push additional commits to the same branch to update the PR automatically.

How to Contribute Translations Without Coding

Invidious uses Weblate for localization, allowing non-developers to contribute.

1. Visit the translation portal at https://hosted.weblate.org/engage/invidious/
2. Sign in with GitHub, GitLab, Google, or another SSO provider
3. Suggest new strings or correct existing translations

No separate account is required, though creating one simplifies repeated contributions. Changes are synced back to the repository automatically.

Practical Code Examples

Adding a Simple API Endpoint

Create a new file in the routes directory:

# src/invidious/routes/api/v1/example.cr

module Invidious::Routes::API::V1
  get "/example" do |env|
    env.response.content_type = "application/json"
    {message: "Hello from Invidious!"}.to_pretty_json
  end
end

The Routing.register_all call in src/invidious/routes/** will pick up the new endpoint automatically.

Creating a Background Job

Implement a new job class:

# src/invidious/jobs/example_job.cr

module Invidious::Jobs
  class ExampleJob < BaseJob
    def initialize(@db : DB::Database)
    end

    def run
      LOG.info "Running example job…"
      # Insert custom logic here (e.g., cleanup, analytics, etc.)

    end
  end
end

Register the job in src/invidious.cr alongside existing jobs:

if CONFIG.example_job_enabled
  Invidious::Jobs.register Invidious::Jobs::ExampleJob.new(PG_DB)
end

Refer to src/invidious/jobs/refresh_channels_job.cr for a complete production pattern.

Updating Translation Files

Translation files are simple JSON documents under locales/. To add or modify strings:

// locales/en-US.json (excerpt)
{
  "welcome_message": "Welcome to Invidious!",
  "new_feature_description": "This feature does X, Y, and Z."
}

After editing, push the change and open a PR; the Weblate sync will handle the rest.

Summary

• Fork the iv-org/invidious repository and create a feature branch for your work
• Navigate the modular codebase: src/invidious.cr for bootstrapping, src/invidious/routes/** for endpoints, and src/invidious/jobs/** for background tasks
• Test all changes with crystal spec before submitting
• Submit a pull request following the repository template
• Translate via Weblate at hosted.weblate.org/engage/invidious/ if you prefer non-code contributions

Frequently Asked Questions

Do I need to know Crystal to contribute to Invidious?

Yes, for code contributions. Invidious is written entirely in Crystal, so you will need familiarity with its syntax and the Kemal framework to modify routes, jobs, or database logic. However, you can contribute translations, documentation, or bug reports without any Crystal knowledge.

How do I run the Invidious test suite locally?

Execute crystal spec from the project root directory. This command runs all spec files located in the spec/ directory. Ensure your changes pass existing tests before opening a pull request.

Can I contribute to Invidious without writing code?

Yes. The project accepts translations through its Weblate instance. Visit https://hosted.weblate.org/engage/invidious/, sign in with a third-party account, and suggest improvements to interface strings in your preferred language.

Where is the main application entry point in the Invidious source code?

The file src/invidious.cr serves as the primary entry point. It loads the configuration, establishes the PostgreSQL database connection via PG_DB, initializes background workers from src/invidious/jobs/, and registers HTTP routes defined in src/invidious/routes/.

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