Skip to main content
The Core service is the central bridge between the Stremio Web frontend and the stremio-core-web Rust backend. It manages a CoreTransport that runs the core logic inside a WebWorker, and exposes a simple lifecycle API for starting, stopping, and observing state.

​
Constructor

const core = new Core(args);
​
args
object
required
Initialization arguments forwarded verbatim to the core WebWorker via bridge.call(['init'], [args]). The shape of this object is determined by the stremio-core-web init contract.

​
Properties

All properties are read-only (defined with Object.defineProperties).
​
active
boolean
true when the underlying CoreTransport has successfully initialized. Resets to false when stop() is called or an error occurs.
​
error
Error | null
Set to an Error instance if the transport fails to initialize ('Stremio Core Transport initialization failed'). null otherwise, or after stop() clears it.
​
starting
boolean
true while the transport is being created and waiting for the init event. Resets to false once initialization succeeds or fails.
​
transport
CoreTransport | null
The active CoreTransport instance, or null when the service is not running.

​
Methods

​
start()

Initializes the CoreTransport and begins the connection to the core WebWorker. Does nothing if the service is already active, starting, or has an error. 
core.start();
start() is idempotent only in the sense that it exits early when already running or errored. To retry after an error, call stop() first — but note that once error is set, stop() must be called to clear it before start() will run again.

​
stop()

Tears down the transport and resets all state (active, error, starting) to their defaults. Safe to call at any time. 
core.stop();

​
on(name, listener)

Registers a listener on the internal EventEmitter.
​
name
string
required
The event name. Currently only 'stateChanged' is emitted by Core itself.
​
listener
function
required
Callback invoked when the event fires.

​
off(name, listener)

Removes a previously registered listener.
​
name
string
required
The event name.
​
listener
function
required
The exact function reference passed to on().

​
Events

​
stateChanged
event
Emitted whenever any of active, error, or starting changes. Consumers should re-read these properties after receiving this event.
core.on('stateChanged', () => {
    console.log({ active: core.active, error: core.error, starting: core.starting });
});

​
CoreTransport

CoreTransport wraps the stremio-core-web bridge and WebWorker. It is created internally by Core.start() and exposed via core.transport.

​
Constructor

// Created internally — do not instantiate directly.
const transport = new CoreTransport(args);
On construction the transport:
  1. Spawns a WebWorker at ${COMMIT_HASH}/scripts/worker.js.
  2. Creates a Bridge between window and the worker.
  3. Calls bridge.call(['init'], [args]) — emitting 'init' on success or 'error' on failure.
  4. Installs window.onCoreEvent to forward core runtime events into the transport’s event emitter.

​
Methods

​
getState(field)
Promise<object>
Fetches the current state of a named model from the core.
const state = await core.transport.getState('catalogWithFilters');
​
field
string
required
The model name to retrieve.
​
getDebugState()
Promise<object>
Returns the full debug state from the core with no arguments.
const debug = await core.transport.getDebugState();
​
dispatch(action, field?)
Promise<void>
Dispatches an action to the core runtime. Also passes location.hash as context.
await core.transport.dispatch(
    { action: 'Ctx', args: { action: 'Authenticate', args: { ... } } }
);
​
action
Action
required
Action object with the shape:
type Action = {
    action: string;
    args?: {
        model?: string;
        action?: string;
        args?: any;
    };
};
​
field
string
Optional model field scope for the action.
​
decodeStream(stream)
Promise<Stream>
Decodes a raw stream descriptor string into a structured Stream object.
const stream = await core.transport.decodeStream(rawStreamString);
​
stream
string
required
The raw stream string to decode.
​
analytics(event)
Promise<void>
Sends an analytics event to the core. Also passes location.hash as context.
await core.transport.analytics({ event: 'playerOpen', args: { type: 'movie' } });
​
event
AnalyticsEvent
required
type AnalyticsEvent = {
    event: string;
    args: object;
};
​
on(name, listener)
void
Subscribe to transport-level events ('init', 'error', plus any events forwarded from window.onCoreEvent).
​
off(name, listener)
void
Unsubscribe from a transport-level event.
​
removeAllListeners()
void
Removes all listeners. Called internally by Core.stop().

​
Usage example

import Core from 'services/Core';

const core = new Core({ /* stremio-core-web init args */ });

core.on('stateChanged', () => {
    if (core.active) {
        console.log('Core is ready');
    } else if (core.error) {
        console.error('Core failed:', core.error);
    }
});

core.start();

// Later, dispatch an action:
if (core.active) {
    await core.transport.dispatch({
        action: 'Ctx',
        args: { action: 'Authenticate', args: { key: '...' } }
    });
}

// Shutdown:
core.stop();
The Core service is a singleton in practice — only one instance should be created per application session. All components that need to interact with the core access it through the shared instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us