---
title: setWorld
description: Override or reset the cached World instance used by the workflow runtime.
type: reference
summary: Use setWorld to inject a custom World instance or reset the cache to the build-injected World.
prerequisites:
  - /docs/api-reference/workflow-runtime/get-world
related:
  - /docs/api-reference/workflow-runtime/create-world
---

Overrides the cached [World](/docs/api-reference/workflow-runtime/world) instance that [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) returns. Use it to inject a World constructed with explicit configuration, or pass `undefined` to clear the cache so the next `getWorld()` call reconstructs the World that was statically injected into the bundle at build time.

```typescript lineNumbers
import { setWorld, getWorld } from "workflow/runtime";
import type { World } from "@workflow/world";
declare const customWorld: World; // @setup

setWorld(customWorld); // [!code highlight]
const world = await getWorld(); // resolves customWorld
```

## API signature

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `world` | `World \| undefined` | The World instance to use, or `undefined` to reset the cache so the next access reconstructs the build-injected World |

### Returns

This function does not return a value.

## Example: inject a specific World

The build selects the target World via `WORKFLOW_TARGET_WORLD` and statically injects it into the bundle. Changing the environment variable at runtime has no effect. To use a different World at runtime, construct it explicitly with the World package's `createWorld()` factory and inject it:

```typescript lineNumbers
import { setWorld } from "workflow/runtime";
import { createWorld } from "@workflow/world-local";

setWorld(createWorld({ dataDir: "/tmp/workflow-test" })); // [!code highlight]
```

Calling `setWorld(undefined)` afterwards restores the build-injected World on the next `getWorld()` call.

## Related functions

- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world): Resolve the cached World instance.
- [`createWorld()`](/docs/api-reference/workflow-runtime/create-world): Construct a fresh instance of the build-injected World.