Getting started

From zero to a job that survives airplane mode, in about ten minutes. This page covers installation, the native pieces, creating the queue, defining a job and showing its status.

Requirements

• React Native 0.76 or newer (required by react-native-mmkv 4).
• Expo users need a development build. react-native-mmkv is a native module, so Expo Go cannot run it.
• React 18 or newer if you use the hooks from @nijatk/react-native-queuekit/react.
• TypeScript is optional but recommended. Types ship with the package.

Install

Create the queue

Create it once, in its own module, and import it wherever you need it.

That is a complete configuration. Everything else is optional: concurrency (default 3), the per-attempt timeout (default 30 seconds), the retry policy, per-type limits and payload migrations. See createQueue for all options.

A react-native-mmkv instance is passed straight in as storage. It already has the four synchronous methods the queue needs.

Define your first job

queue.define(type, handler) registers the handler and returns a function that enqueues the job. The payload type is taken from the handler's first parameter.

Enqueue it

The call is synchronous and returns the stored Job. If the device is online the job starts right away. If not, it waits.

Register handlers at startup

Handlers must be registered before a saved job can run. Jobs without a handler simply stay pending, so late registration is safe, but a job whose module is never imported never runs. Import all your job modules once at startup, for example from your app entry file:

Show status in the UI

More in React hooks.

Try it

1. Turn on airplane mode.
2. Enqueue a job. It appears as pending and nothing is sent.
3. Force-quit the app and reopen it. The job is still there.
4. Turn airplane mode off. The job runs and disappears.

If something does not run, see the checklist in FAQ.

Optional: decorators setup

Class-method decorators (@queue.handler) use the standard TC39 syntax. Skip this section if you use queue.define().

In tsconfig.json leave experimentalDecorators off. Do not enable it: those are the older, incompatible decorators. Expo projects use babel-preset-expo instead of the preset above; add the same plugin to the plugins array.

Suggested project layout

Keeping one job per feature file means no central list of handlers to maintain, and the queue module never imports feature code.