# The Stremio Addon SDK turns a JSON HTTP service into a media addon

> stremio-addon-sdk is the Node.js toolkit for writing Stremio addons: you declare a manifest, write handlers for catalogs, metadata, streams and subtitles, and the SDK provides the server, the CORS and caching headers, a landing page with an install button and the publishing call. The addon is never run by the Stremio app, it is only called over HTTP.

**Stremio/stremio-addon-sdk** — 🧙 A Node.js SDK for creating and publishing Stremio add-ons

- Repository: https://github.com/Stremio/stremio-addon-sdk
- Website: https://www.stremio.com/addon-sdk
- Stars: 1,431 · Forks: 455
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/stremio-stremio-addon-sdk

## An addon is a handful of JSON endpoints

Stremio is a modern media center that discovers, organises and streams video content through addons, and an addon is a small HTTP service that answers a handful of JSON requests: which catalogs it offers, what an item is, and where to stream it from. This SDK gives you the builder, the HTTP server and the publishing tools so you only write the handlers.

The most useful sentence in the readme is the one about scope. Stremio runs on Windows, macOS, Linux, Android and iOS, and one addon serves all of them, which is the property that makes writing one worth the effort.

The implementation is JavaScript, the licence is MIT, and the package version is 1.6.10. The last push was on 2026-10-02, and the release list is a single entry, v1.1.4 from 2019, which is worth noting: the version that people actually install has moved on considerably from the last tagged release in the list.

The documentation is unusually good for a small package, with a protocol specification, a set of guides, an addon guide on a separate site and a link to the SDK reference, and the badges cover the build, the npm version, the downloads and the licence.

## Scaffolding an addon with one command

You need Node.js 12 or newer, and then the quickest route to a working addon is the bootstrap command.

```bash
npm install -g stremio-addon-sdk # use sudo on Linux
addon-bootstrap hello-world
cd hello-world
npm install
npm start -- --launch
```

The bootstrap command asks which resources and types you want to support and generates a working addon. The --launch flag opens Stremio Web with the addon installed, and --install installs it into the desktop app instead.

That last distinction matters more than it looks. Stremio Web runs in a browser, so the addon is reached over the network from a page, whereas the desktop app can reach a local server, which is why the launch and install flows are separate.

The CLI lives in the cli/ directory of the repository and is registered as the addon-bootstrap executable in the package manifest, so the global install is what puts it on your path.

## Writing one by hand, in a dozen lines

The readme also shows the hand written form, and it is short enough to be the real documentation of the API.

```javascript
const { addonBuilder, serveHTTP, publishToCentral } = require('stremio-addon-sdk')

const builder = new addonBuilder({
    id: 'org.myexampleaddon',
    version: '1.0.0',
    name: 'simple example',
    catalogs: [],
    resources: ['stream'],
    types: ['movie'],
    idPrefixes: ['tt']
})
```

The constructor is the manifest. The properties that determine when Stremio picks the addon are the types, the idPrefixes and the catalog extra filters, and in the example the addon declares streams for items of type movie whose id starts with tt, which is the IMDb identifier prefix.

The handler is then a function of the request arguments that returns a promise of the response object, and the server is one call at the end, with serveHTTP taking the interface from the builder and a port. The publishToCentral call is commented out in the example, because it only works once the addon is publicly reachable.

And the install is an ordinary dependency.

```bash
npm install stremio-addon-sdk
node ./addon.js
```

The process prints a URL you can use to install the addon in Stremio.

## Stremio never runs your code

The How it works section is the part that explains the whole design, and it is one sentence.

Stremio never runs your code. The app reads your manifest, decides which addons are relevant for a request from their types, idPrefixes and catalog extra filters, and calls the matching resources over HTTP. The SDK turns those calls into handler invocations and turns your return values into protocol-conformant JSON.

So there is no plugin API, no sandbox and no in-process contract. Your addon is a web service, and the SDK is a convenience layer that saves you from writing the routing, the header handling and the JSON shapes by hand.

The resources it exposes are listed in a table, and it is the clearest description of the protocol you will find anywhere.

The manifest answers what the addon is and when to call it, and it is the builder constructor. The catalog handler answers with lists of meta previews for the Board, the Discover and Search. The meta handler answers with the full meta object for the details page. The stream handler answers with streams, which can be HTTP, BitTorrent, YouTube and more. The subtitles handler answers with subtitle files for a video. And the addon_catalog handler answers with a list of other addons, which is how an addon points at a companion.

Each of those has a matching define method, and each links to the request and response documentation.

## CORS, HTTPS and the landing page are handled for you

The feature list covers the parts of running an addon that are not about your data, and they are the parts that usually waste a weekend.

CORS and caching are handled, in the sense that the SDK sets the headers Stremio expects and you set the cache lifetimes. The landing page is included, since every addon gets a homepage with an Install button out of the box. Publishing is a single call, publishToCentral, which submits your addon to the public addon collection.

Serving is a choice between two shapes. You can start a server with serveHTTP, or you can mount the addon as an Express router with getRouter, which is the option when the addon is part of a larger Express application rather than a service of its own.

There is one hard requirement, and it is about deployment rather than code. Addon URLs must be served over HTTPS with CORS enabled, except for 127.0.0.1, and the SDK handles the CORS while HTTPS is up to your host.

That exception for 127.0.0.1 is what makes local development possible without a certificate, and it is also a reminder that the SDK has no way to help with the TLS side, so a public addon needs a host that terminates HTTPS for it.

## The documentation, the examples and the tooling

The documentation section is a table of guides, and it covers more than the bare protocol.

The SDK reference lists every export, namely addonBuilder, serveHTTP, getRouter, publishToCentral and the addonInterface. The Resources guide explains how catalogs, metas, videos, streams and subtitles relate to each other and how Stremio picks an addon. Advanced usage covers searching and filtering catalogs, pagination, Cinemeta, user data and configuration pages. Native EPG explains live TV channels with a programme guide, with a runnable example in examples/epg-livetv.js. Deep links covers linking into Stremio with the stremio:// protocol. Testing covers trying the addon in the app and in Stremio Web, and Deploying covers hosting options with BeamUp as the recommended one. There is also a protocol specification for people writing addons without this SDK, and the examples page points at demo addons, examples in other languages and video tutorials.

The tooling in the package is modest and matches the era. The dependencies are express for the server, cors for the headers, chalk for the terminal output, inquirer for the interactive bootstrap, node-fetch for the calls the addon makes, opn to open a browser, mkdirp, and stremio-addon-linter, which is how a manifest gets validated. The test setup is tape with supertest, and the type check is tsc over the declaration files.

TypeScript types are bundled, the feature list says, since version 1.6.10, so you no longer need a separate @types package for the SDK.

## Conclusion

Adopt the Stremio Addon SDK when you are writing an addon that pulls catalogues from a source Stremio does not ship itself, since the protocol is small and the SDK removes the protocol plumbing. Do not adopt it to build a standalone media application, because an addon is a small JSON service and nothing more. Verify first that your addon will be served over HTTPS with CORS enabled unless it is on 127.0.0.1, that the SDK version you install matches the Stremio protocol you target, and that the resources you declare in the manifest are the ones you actually implement, because Stremio decides which addon to call from those declarations alone.

## FAQ

### What is the Stremio Addon SDK?

It is a Node.js SDK for creating and publishing Stremio addons. An addon is a small HTTP service that answers a handful of JSON requests, and the SDK provides the builder, the HTTP server, the CORS and caching headers, a landing page and the publishing call so you only write the handlers.

### How do I scaffold a new Stremio addon?

Run npm install -g stremio-addon-sdk, then addon-bootstrap hello-world, then npm install and npm start -- --launch. The bootstrap command asks which resources and types you want to support and generates a working addon, and --launch opens Stremio Web with it installed while --install installs it into the desktop app.

### What resources can a Stremio addon serve?

The manifest, which says what the addon is and when to call it, plus handlers for catalog, meta, stream, subtitles and addon_catalog, each with a matching define method and its own request and response documentation.

### Does Stremio run my addon code?

No. Stremio reads your manifest, decides which addons are relevant from their types, idPrefixes and catalog extra filters, and calls the matching resources over HTTP. The SDK turns those calls into handler invocations and your return values into protocol-conformant JSON.

### What are the hosting requirements for an addon?

Addon URLs must be served over HTTPS with CORS enabled, except for 127.0.0.1. The SDK sets the CORS and cache headers, but the HTTPS is up to your host, and the deployment guide points at BeamUp as the recommended option.

### How do I publish an addon?

With publishToCentral, which submits the addon to the public addon collection, and it only works once the addon is publicly reachable over HTTPS. You can also serve it with serveHTTP or mount it as an Express router with getRouter.

## Sources

- [License: MIT](https://github.com/Stremio/stremio-addon-sdk/blob/master/LICENSE)
- [Project website](https://www.stremio.com/addon-sdk)
- [README](https://github.com/Stremio/stremio-addon-sdk/blob/master/README.md)
- [Releases](https://github.com/Stremio/stremio-addon-sdk/releases)
- [Stremio/stremio-addon-sdk on GitHub](https://github.com/Stremio/stremio-addon-sdk)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/stremio-stremio-addon-sdk