Welcome to the Vega App Provider Template! Providers are JS scripts that run in a sandbox environment. This repository provides the structure and tools you need to create custom providers (extensions) for the Vega App.
Follow these steps to create your own providers:
Click the "Fork" button at the top right of this page to create your own copy of this repository.
Recommended: Name your forked repository exactly vega-providers. This makes it easier to add your providers to the Vega app later!
Clone your newly forked repository to your local machine:
git clone https://github.com/YOUR_USERNAME/vega-providers.git
cd vega-providers
npm installThere is a sample provider included in the providers/example folder to help you get started.
- Review the code in
providers/exampleto see how everything is connected. - Once you're ready, delete the
examplefolder and create a new folder for your own provider (e.g.,providers/myProvider).
When you have finished writing your provider's code, you need to bundle it into the dist/ directory before the app can use it:
npm run buildMake sure to commit and push the built files to your GitHub repository so the app can fetch them.
To install your custom provider in the Vega app:
- Open the app and navigate to the Extensions/Providers settings.
- If you named your repository exactly
vega-providers, simply enter your GitHub Username. - If you used a different name, you must enter the Full Repository URL (e.g.,
https://github.com/YOUR_USERNAME/your-repo-name).
Each provider lives in its own folder under providers/:
providers/
myProvider/
catalog.ts
meta.ts
posts.ts
stream.ts
episodes.ts (optional)
The manifest.json file located in the root of the repository defines the metadata for all providers included in your repository. The Vega app reads this manifest to discover, display, and configure your providers.
Example manifest.json:
[
{
"display_name": "My Provider",
"value": "myProvider",
"version": "1.0",
"icon": "",
"type": "global",
"disabled": false
}
]display_name: The human-readable name of your provider shown in the app.value: The internal ID of your provider. This must exactly match the name of the folder you created inproviders/(e.g.,myProvider).version: The current version of your provider (after changes in a provider bump the version provider will update autmatically in app).icon: An optional URL to an icon image for your provider.type: The scope of your provider (usually set to"global").disabled: If set totrue, the app will hide and disable this provider.
Important: Every time you add a new provider folder to providers/, you must add a corresponding entry to manifest.json!
- Purpose: Defines the categories or filters available for your provider.
- How it's used:
- The
titleproperty will be shown as the heading on the home page (e.g., "Popular Movies"). - The
filterproperty is passed to thegetPostsfunction inposts.ts. - For example, if you define
{ title: "Popular Movies", filter: "/category/popular-movies" }, then home-page heading will show "Popular Movies" and/category/popular-movieswill be sent togetPostsas thefilterargument. YourgetPostsimplementation should use this to fetch and return the relevant items (e.g., popular movies). - The same logic applies to
genres: each genre object has atitle(displayed as a heading) and afilter(used to fetch genre-specific items).
- The
- Exports:
catalog: An array of objects withtitleandfilterfields.genres: (optional) An array for genre filters.
- Purpose: Fetches metadata for a specific item (movie, show, etc.).
- Exports:
getMeta({ link, providerContext }): Returns anInfoobject with details like title, synopsis, image, etc.
- Purpose: Fetches lists of items (posts) and handles search.
- Exports:
getPosts({ filter, page, providerValue, signal, providerContext }): Returns an array ofPostobjects for a given filter and page.getSearchPosts({ searchQuery, page, providerValue, signal, providerContext }): (optional) Returns search results as an array ofPostobjects.
- Purpose: Fetches streaming and downloadable links/sources for a given item.
- Exports:
getStream({ link, type, signal, providerContext, isDownload }): Returns an array ofStreamobjects with streaming info.isDownload?: booleanparameter:- When
true, the user is downloading the media (quick download or download sheet). Providers can prioritize download-friendly or download-only servers at the top of the returned array. - When
falseor omitted, providers should prioritize streaming-friendly servers (e.g. HLS/m3u8, direct streaming web players). - Important: Always return all available servers regardless of
isDownload. The app will use the 1st server for Quick Download while enabling the user to choose alternative servers in the download dialog.
- When
- Purpose: Handles episode-specific logic for series.
- When to use:
- This file is optional and not required for all providers. Some providers return the full episode list directly in the metadata from
getMeta, but others require a separate request to fetch episodes for a specific season. - If your provider's
getMetafunction cannot return all episodes at once, you can return alinkListlike this:linkList: [ { title: "season 1", episodesLink: "/season-1", }, ];
- When a user selects a season, the
episodesLinkvalue (e.g.,/season-1) will be sent as theurlargument togetEpisodesinepisodes.ts. - Your
getEpisodesfunction should then fetch and return the list of episodes for that season.
- This file is optional and not required for all providers. Some providers return the full episode list directly in the metadata from
- Exports:
getEpisodes({ url, providerContext }): Returns an array ofEpisodeLinkobjects for the given season or episode group.
providerContext is an object passed to each function, providing shared utilities and dependencies, such as:
axios: For HTTP requestscheerio: For HTML parsingcommonHeaders: Standard HTTP headers
This ensures all providers use the same tools and patterns, making code easier to maintain and extend.
All function signatures and return types should use the interfaces from providers/types.ts:
Post,Info,Stream,EpisodeLink, etc.
import { Post, ProviderContext } from "../types";
export const getPosts = async function ({
filter,
page,
providerValue,
signal,
providerContext,
}: {
filter: string;
page: number;
providerValue: string;
signal: AbortSignal;
providerContext: ProviderContext;
}): Promise<Post[]> {
// ...implementation...
};
export const getSearchPosts = async function ({
searchQuery,
page,
providerValue,
signal,
providerContext,
}: {
searchQuery: string;
page: number;
providerValue: string;
signal: AbortSignal;
providerContext: ProviderContext;
}): Promise<Post[]> {
// ...implementation...
};// catalog.ts
export const catalog = [
{ title: "Popular Movies", filter: "/category/popular-movies" },
{ title: "Latest TV Shows", filter: "/category/latest-tv-shows" },
];
export const genres = [
{ title: "Action", filter: "/genre/action" },
{ title: "Drama", filter: "/genre/drama" },
];// meta.ts
import { Info, ProviderContext } from "../types";
export const getMeta = async function ({
link,
providerContext,
}: {
link: string;
providerContext: ProviderContext;
}): Promise<Info> {
// Fetch and parse metadata for the item
// ...implementation...
return {
title: "Example Movie",
synopsis: "A sample synopsis.",
image: "https://example.com/image.jpg",
imdbId: "tt1234567",
type: "movie",
linkList: [],
};
};// stream.ts
import { Stream, ProviderContext } from "../types";
export const getStream = async function ({
link,
type,
signal,
providerContext,
isDownload,
}: {
link: string;
type: string;
signal?: AbortSignal;
providerContext: ProviderContext;
isDownload?: boolean;
}): Promise<Stream[]> {
// Fetch and return streaming sources
// If isDownload is true, place download-optimized servers first:
// const servers = ...
return [
{
server: "ExampleServer",
link: "https://example.com/stream.m3u8",
type: "m3u8",
quality: "1080",
},
];
};// episodes.ts
import { EpisodeLink, ProviderContext } from "../types";
export const getEpisodes = async function ({
url,
providerContext,
}: {
url: string;
providerContext: ProviderContext;
}): Promise<EpisodeLink[]> {
// Fetch and return episode links
// ...implementation...
return [
{ title: "Episode 1", link: "https://example.com/ep1" },
{ title: "Episode 2", link: "https://example.com/ep2" },
];
};The linkList property in the object returned by getMeta is used to describe available seasons, episodes, or direct download/stream links for the item.
- Each entry in
linkListcan represent a season or anything you want; it will be shown in the dropdown. - If your provider requires an extra request to fetch episodes for a season, set the
episodesLinkproperty. When the user selects that season, the app will callgetEpisodeswith this value. - If your provider does not require an extra request (i.e., you already have all episode links), you can return them directly in the
directLinksarray. EachdirectLinksentry should have alink,title, andtype(e.g., "movie" or "series"). - The
qualityproperty can be used to indicate video quality (e.g., "1080").
linkList: [
{
title: "Season 2",
episodesLink: "",
directLinks: [
{
link: "https://example.com/download",
title: "Episode 1",
type: "movie",
},
// ...more episodes or links
],
quality: "1080",
},
];- If you use
directLinks, the app will send the selected link directly togetStreamwhen needed, skipping the need for an extra episode request. - If you use
episodesLink, the app will callgetEpisodesto fetch the episode list for that season or group.
This gives you flexibility to support both providers that need extra requests for episodes and those that can return all links up front.
Providers can expose custom settings in the Vega app (such as custom mirror URLs, quality preferences, resolution filters, API keys, or toggles) and persist state across sessions using the built-in Key-Value Store (kvStore).
To provide a native settings UI in the Vega App's Provider Settings, add a settings.ts file inside your provider folder.
Export an async function getSettingsSchema:
import { ProviderContext, SettingsField } from "../types";
export const getSettingsSchema = async function ({
providerContext,
}: {
providerContext: ProviderContext;
}): Promise<SettingsField[]> {
return [
// Array of settings field definitions
];
};| Field Type | UI Component | Value Type | Properties |
|---|---|---|---|
'select' |
Native Dropdown Menu | string |
key, label, description?, options: { label, value }[], defaultValue? |
'multiselect' |
Checkbox List Group | string[] |
key, label, description?, options: { label, value }[], defaultValue?: string[] |
'toggle' |
Switch Toggle (On/Off) | boolean |
key, label, description?, defaultValue?: boolean |
'text' |
Text Input Field | string |
key, label, description?, placeholder?, defaultValue?: string |
'number' |
Numeric Input Field | number |
key, label, description?, min?, max?, defaultValue?: number |
import { ProviderContext, SettingsField } from "../types";
export const getSettingsSchema = async function ({
providerContext,
}: {
providerContext: ProviderContext;
}): Promise<SettingsField[]> {
return [
{
key: "preferredQuality",
type: "select",
label: "Preferred Streaming Quality",
description: "Default streaming quality when multiple are available",
options: [
{ label: "Auto (Best Available)", value: "auto" },
{ label: "1080p Full HD", value: "1080" },
{ label: "720p HD", value: "720" },
{ label: "480p SD", value: "480" },
],
defaultValue: "auto",
},
{
key: "allowedResolutions",
type: "multiselect",
label: "Allowed Resolutions",
description: "Choose which video resolutions to show in playback sources",
options: [
{ label: "4K Ultra HD (2160p)", value: "2160" },
{ label: "1080p Full HD", value: "1080" },
{ label: "720p HD", value: "720" },
{ label: "480p SD", value: "480" },
],
defaultValue: ["2160", "1080", "720"],
},
{
key: "baseUrlOverride",
type: "text",
label: "Custom Mirror Domain",
description: "Override default domain if main website is blocked in your region",
placeholder: "https://my-mirror.com",
defaultValue: "",
},
{
key: "autoSubtitles",
type: "toggle",
label: "Auto-enable English Subtitles",
description: "Automatically load English subtitles when available",
defaultValue: true,
},
{
key: "requestTimeout",
type: "number",
label: "Request Timeout (seconds)",
description: "Maximum response wait time for requests",
defaultValue: 15,
min: 5,
max: 60,
},
];
};Each provider has access to an isolated, persistent Key-Value Store through providerContext.kvStore.
Values configured by the user via the Settings modal are automatically saved to this store under the corresponding key. You can also write, read, and delete custom data directly in your scraper functions.
interface ProviderKvStore {
// Retrieve a stored value by key
get: <T = unknown>(key: string) => Promise<T | undefined>;
// Store a value (serializable objects, arrays, primitives)
set: (key: string, value: unknown) => Promise<void>;
// Delete a specific key
delete: (key: string) => Promise<boolean>;
// List all stored keys for this provider
keys: () => Promise<string[]>;
// Clear all stored data for this provider
clear: () => Promise<void>;
}import { Stream, ProviderContext } from "../types";
export const getStream = async function ({
link,
type,
signal,
providerContext,
isDownload,
}: {
link: string;
type: string;
signal?: AbortSignal;
providerContext: ProviderContext;
isDownload?: boolean;
}): Promise<Stream[]> {
const { axios, kvStore } = providerContext;
// 1. Read user configured settings
const customDomain = (await kvStore.get<string>("baseUrlOverride")) || "https://example.com";
const preferredQuality = (await kvStore.get<string>("preferredQuality")) || "auto";
const allowedResolutions = (await kvStore.get<string[]>("allowedResolutions")) || ["1080", "720"];
// 2. Use in scraper requests
const response = await axios.get(`${customDomain}${link}`);
// ... parse streams and filter by allowedResolutions ...
return streams;
};- Run
npm test -- provider_name(example:npm test -- showbox)- This will do full testing by picking random posts and episodes and testing end-to-end.
- Run
npm run test:provider -- provider_name function_name(example:npm run test:provider -- showbox getPosts)- This is for testing a single function, such as getPosts, getSearchPosts, getStream, etc. After entering manually, enter the input.
Use Node.js 20.12 or newer, run npm install, and install Microsoft Edge or Google Chrome locally. The CLI uses playwright-core with your installed browser; no browser download is required.
For a custom browser location, copy .env.example to .env in the repository root and set an absolute executable path:
VEGA_BROWSER_PATH="C:/Program Files/Google/Chrome/Application/chrome.exe"Both CLI commands automatically load this .env file. You can also set VEGA_BROWSER_PATH in your shell; shell values take precedence. Leave it empty to find Edge, then Chrome automatically. Custom paths support Chromium browsers (Chrome, Edge, Chromium, Brave); Firefox and Safari are unsupported. An invalid custom path reports an error. Local .env files are ignored by Git.
npm run test:provider -- myProvider getPosts --rebuild
npm run test:provider -- myProvider getStream --rebuild
npm test -- myProviderBoth test commands provide providerContext.openWebView(url, options). When your provider calls it, a visible browser opens so you can complete the verification. No extra WAF flag is needed. Press Enter in the terminal when finished, or use waitForCookie or an injected script to complete automatically:
const result = await providerContext.openWebView(url, {
title: "Complete security verification",
waitForCookie: "cf_clearance",
timeoutMs: 120000,
});
// result.data contains rendered HTML, or data sent by the injected script.
// result.cookies, result.cookieMap, result.url and result.userAgent are available.headers and injectedJavaScript are supported. Injected scripts can return data using window.ReactNativeWebView.postMessage(JSON.stringify({ __waf: true, data: value })); scripts are installed again after navigation. Closing the browser cancels the request, and verification times out after two minutes by default. This interactive helper requires a desktop browser session. It does not automatically solve challenges or reproduce every mobile WebView behavior. Keep browser dependencies in the test harness; provider code should only call the injected providerContext API.
Use this method with Vega mobile and desktop builds that support HTTP provider sources. It uses the normal provider installation flow and needs no app code changes or test mode.
- Build your provider and start the server from the template folder:
Alternatively, run
npm run build npm run dev
npm run autoto build, start the server, and rebuild when provider files change. - In the app, open Settings > Provider Manager > Available Providers, choose Add Provider Source (the plus button), and enter the server URL:
- Desktop on the same computer:
http://localhost:3001 - Mobile or another computer: the printed Mobile Test URL, for example
http://192.168.1.20:3001 - You can also enter the full manifest URL, such as
http://192.168.1.20:3001/manifest.json.
- Desktop on the same computer:
- Select the added source and install your provider. Its entry must be present in
manifest.json, and its built files must be available underdist/. - Browse, search, and play in the app to test the provider. WAF verification uses the app's own browser/WebView; the CLI's
VEGA_BROWSER_PATHsetting does not apply here. - After changing provider code, rebuild it (or let
npm run autorebuild), then update or reinstall the provider in the app. Normal source installation uses installed files and does not hot reload. Increase the provider's manifest version when testing the normal update flow.
For a phone or another computer, keep both devices on the same network and allow the dev server through your computer's firewall on port 3001. On a phone, localhost points to the phone, so use the computer's local IP instead. Keep the server running while fetching or updating provider files. If your installed app rejects HTTP sources, update to a build with HTTP source support or use the secondary method below when building the app yourself.
Use this method when developing the Vega app itself or when you need its test-mode provider loading behavior. It requires access to the app source and rebuilding the app.
- Start the provider server with
npm run auto, or runnpm run buildfollowed bynpm run dev. - In the mobile or desktop app project, open
src/lib/services/ExtensionManager.tsand configure:Use the server's printed Mobile Test URL for a phone, orprivate testMode = true; private baseUrlTestMode = "http://192.168.1.20:3001";
http://localhost:3001for desktop on the same computer. Preserve the file's existing quote style. - Rebuild and run the app, then test your local providers. Keep the server running and rebuild provider files after edits, or use
npm run auto. - Restore
testMode = falsewhen finished, before creating a normal app build.
This workflow allows you to quickly test and debug new providers before deploying them.
Follow this structure and naming convention to ensure your provider integrates smoothly with the project.
Providers can return Stream.drm for inline ClearKey or license-server DRM.
See DRM configuration, examples, and platform limits.