# gatsby-worker

> Utility to create worker pools

Latest version **2.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-worker
pnpm add gatsby-worker
yarn add gatsby-worker
bun add gatsby-worker
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: no vulnerabilities; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.16.0 |
| Published | 2026-01-26 |
| First published | 2021-06-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18.0.0 <26 |
| Dependencies | 4 |
| Unpacked size | 51 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 55943 |
| Author | Michal Piechowiak |
| Maintainers | pieh, mlgualtieri-gatsby, gatsby_integrations, kathmbeck, seanroberts, serhalp-netlify, wardpeet |
| Keywords | gatsby, worker |

## Links

- npm: https://www.npmjs.com/package/gatsby-worker
- Repository: https://github.com/gatsbyjs/gatsby
- Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-worker#readme
- Issues: https://github.com/gatsbyjs/gatsby/issues
- npm.io page: https://npm.io/package/gatsby-worker

## Dependencies (4)

- [fs-extra](https://npm.io/package/fs-extra.md) ^11.2.0
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.20.12
- [signal-exit](https://npm.io/package/signal-exit.md) ^3.0.7
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13

## Alternatives

- [cron](https://npm.io/package/cron.md) — 4.9M weekly downloads
- [@vercel/queue](https://npm.io/package/@vercel/queue.md) — 731.6K weekly downloads
- [create-sonicjs](https://npm.io/package/create-sonicjs.md) — 1.6K weekly downloads
- [@exellix/jobs-api](https://npm.io/package/@exellix/jobs-api.md) — 941 weekly downloads
- [@forwardimpact/libskill](https://npm.io/package/@forwardimpact/libskill.md) — 575 weekly downloads

## Recent versions

- 2.16.0 (latest) — 2026-01-26
- 2.17.0-next.0 (next) — 2025-11-27
- 0.6.0 (latest-v3) — 2022-12-07
- 1.25.0 (latest-v4) — 2022-12-07
- 2.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22
- 1.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12
- 2.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12
- 1.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08
- 1.23.0-alpha-9689ff.25 (alpha-9689ff) — 2022-08-31
- 1.18.0-alpha-drupal-self-reference.18 (drupal-self-reference) — 2022-07-19
- 1.15.0-alpha-wp-image-cdn-auth.48 (wp-image-cdn-auth) — 2022-05-20
- 1.8.0-alpha-image-service.24 (image-service) — 2022-02-10
- 1.6.0-alpha-ts-jit.48 (alpha-ts-jit) — 2022-01-21
- 0.5.0-alpha-qe-sm.46 (alpha-qe-sm) — 2021-09-13
- 0.1.0-alpha-pqr-debug.18666 (alpha-pqr-debug) — 2021-07-07
- … 158 more at https://npm.io/package/gatsby-worker/versions

## README

# gatsby-worker

Utility to execute tasks in forked processes. Highly inspired by [`jest-worker`](https://www.npmjs.com/package/jest-worker).

## Example

File `worker.ts`:

```ts
export async function heavyTask(param: string): Promise<string> {
  // using workers is ideal for CPU intensive tasks
  return await heavyProcessing(param)
}

export async function setupStep(param: string): Promise<void> {
  await heavySetup(param)
}
```

File `parent.ts`:

```ts
import { WorkerPool } from "gatsby-worker"

const workerPool = new WorkerPool<typeof import("./worker")>(
  require.resolve(`./worker`),
  {
    numWorkers: 5,
    env: {
      CUSTOM_ENV_VAR_TO_SET_IN_WORKER: `foo`,
    },
    silent: false,
  }
)

// queue a task on all workers
const arrayOfPromises = workerPool.all.setupStep(`bar`)

// queue a task on single worker
const singlePromise = workerPool.single.heavyTask(`baz`)
```

## API

### Constructor

```ts
// TypeOfWorkerModule allows to type exposed functions ensuring type safety.
// It will convert sync methods to async and discard/disallow usage of exports
// that are not functions. Recommended to use with `<typeof import("path_to_worker_module")>`.
const workerPool = new WorkerPool<TypeOfWorkerModule>(
  // Absolute path to worker module. Recommended to use with `require.resolve`
  workerPath: string,
  // Not required options
  options?: {
    // Number of workers to spawn. Defaults to `1` if not defined.
    numWorkers?: number
    // Additional env vars to set in worker. Worker will inherit env vars of parent process
    // as well as additional `GATSBY_WORKER_ID` env var (starting with "1" for first worker)
    env?: Record<string, string>,
    // Whether or not the output from forked process should ignored. Defaults to `false` if not defined.
    silent?: boolean,
  }
)
```

### `.single`

```ts
// Exports of the worker module become available under `.single` property of `WorkerPool` instance.
// Calling those will either start executing immediately if there are any idle workers or queue them
// to be executed once a worker become idle.
const singlePromise = workerPool.single.heavyTask(`baz`)
```

### `.all`

```ts
// Exports of the worker module become available under `.all` property of `WorkerPool` instance.
// Calling those will ensure a function is executed on all workers. Best usage for this is performing
// setup/bootstrap of workers.
const arrayOfPromises = workerPool.all.setupStep(`baz`)
```

### `.end`

```ts
// Used to shutdown `WorkerPool`. If there are any in progress or queued tasks, promises for those will be rejected as they won't be able to complete.
const arrayOfPromises = workerPool.end()
```

### `isWorker`

```ts
// Determine if current context is executed in worker context. Useful for conditional handling depending on context.
import { isWorker } from "gatsby-worker"

if (isWorker) {
  // this is executed in worker context
} else {
  // this is NOT executed in worker context
}
```

### Messaging

`gatsby-worker` allows sending messages from worker to main and from main to worker at any time.

#### Sending messages from worker

File `message-types.ts`:

```ts
// `gatsby-worker` supports message types. Creating common module that centralize possible messages
// that is shared by worker and parent will ensure messages type safety.
interface IPingMessage {
  type: `PING`
}

interface IAnotherMessageFromChild {
  type: `OTHER_MESSAGE_FROM_CHILD`
  payload: {
    foo: string
  }
}

export type MessagesFromChild = IPingMessage | IAnotherMessageFromChild

interface IPongMessage {
  type: `PONG`
}

interface IAnotherMessageFromParent {
  type: `OTHER_MESSAGE_FROM_PARENT`
  payload: {
    foo: string
  }
}

export type MessagesFromParent = IPongMessage | IAnotherMessageFromParent
```

File `worker.ts`:

```ts
import { getMessenger } from "gatsby-worker"

import { MessagesFromParent, MessagesFromChild } from "./message-types"

const messenger = getMessenger<MessagesFromParent, MessagesFromChild>()
// messenger might be `undefined` if `getMessenger`
// is called NOT in worker context
if (messenger) {
  // send a message to a parent
  messenger.send({ type: `PING` })
  messenger.send({
    type: `OTHER_MESSAGE_FROM_CHILD`,
    payload: {
      foo: `bar`,
    },
  })

  // following would cause type error as message like that is
  // not part of MessagesFromChild type union
  // messenger.send({ type: `NOT_PART_OF_TYPES` })

  // start listening to messages from parent
  messenger.onMessage(msg => {
    switch (msg.type) {
      case `PONG`: {
        // handle PONG message
        break
      }
      case `OTHER_MESSAGE_FROM_PARENT`: {
        // msg.payload.foo will be typed as `string` here
        // handle
        break
      }

      // following would cause type error as there is no msg with
      // given type as part of MessagesFromParent type union
      // case `NOT_PART_OF_TYPES`: {}
    }
  })
}
```

File `parent.ts`:

```ts
import { getMessenger } from "gatsby-worker"

import { MessagesFromParent, MessagesFromChild } from "./message-types"

const workerPool = new WorkerPool<
  typeof import("./worker"),
  MessagesFromParent,
  MessagesFromChild
>(
  workerPath: require.resolve(`./worker`)
)

// `sendMessage` on WorkerPool instance requires second parameter
// `workerId` to specify to which worker to send message to
// (`workerId` starts at 1 for first worker).
workerPool.sendMessage(
  {
    type: `OTHER_MESSAGE_FROM_PARENT`,
    payload: {
      foo: `baz`
    }
  },
  1
)

// start listening to messages from child
// `onMessage` callback will be called with message sent from worker
// and `workerId` (to identify which worker send this message)
workerPool.onMessage((msg: MessagesFromChild, workerId: number): void => {
  switch(msg.type) {
    case: `PING`: {
      // send message back making sure we send it back to same worker
      // that sent `PING` message
      workerPool.sendMessage({ type: `PONG` }, workerId)
      break
    }
  }
})
```

## Usage with unit tests

If you are working with source files that need transpilation, you will need to make it possible to load untranspiled modules in child processes.
This can be done with `@babel/register` (or similar depending on your build toolchain). Example setup:

```ts
const testWorkerPool = new WorkerPool<WorkerModuleType>(workerModule, {
  numWorkers,
  env: {
    NODE_OPTIONS: `--require ${require.resolve(`./ts-register`)}`,
  },
})
```

This will execute additional module before allowing adding runtime support for new JavaScript syntax or support for TypeScript. Example `ts-register.js`:

```js
// spawned process won't use jest config (or other testing framework equivalent) to support TS, so we need to add support ourselves
require(`@babel/register`)({
  extensions: [`.js`, `.ts`],
  configFile: require.resolve(relativePathToYourBabelConfig),
  ignore: [/node_modules/],
})
```

---
_Source: https://npm.io/package/gatsby-worker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._