> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel/workflow/llms.txt
> Use this file to discover all available pages before exploring further.

# createWorld

> Create a workflow runtime world instance

## Overview

`createWorld()` creates a workflow runtime instance that handles state management, event sourcing, and infrastructure integration. The world abstraction allows workflows to run on different backends (Vercel, local development, or custom implementations).

## Usage

```typescript theme={null}
import { createWorld } from 'workflow/runtime';

const world = createWorld();
```

The world is automatically created based on environment variables and typically doesn't need to be manually instantiated in application code. Use `getWorld()` to access the current world instance instead.

## Signature

```typescript theme={null}
function createWorld(): World
```

**Returns:** `World` - A world instance configured for the current environment

## Environment Detection

The world type is automatically determined by:

1. **`WORKFLOW_TARGET_WORLD`** environment variable (explicit override)
2. **`VERCEL_DEPLOYMENT_ID`** presence (automatic Vercel detection)
3. **Default**: Local development mode

### Vercel World

Automatically used when deployed to Vercel or when `WORKFLOW_TARGET_WORLD=vercel`.

**Environment Variables:**

<ParamField path="WORKFLOW_VERCEL_AUTH_TOKEN" type="string">
  Vercel API authentication token
</ParamField>

<ParamField path="WORKFLOW_VERCEL_PROJECT" type="string">
  Vercel project ID (e.g., `prj_xxx`)
</ParamField>

<ParamField path="WORKFLOW_VERCEL_PROJECT_NAME" type="string">
  Vercel project slug (e.g., `my-app`)
</ParamField>

<ParamField path="WORKFLOW_VERCEL_ENV" type="string">
  Target environment: `production`, `preview`, or `development`
</ParamField>

<ParamField path="WORKFLOW_VERCEL_TEAM" type="string">
  Vercel team ID (optional, for team projects)
</ParamField>

### Local World

Used for local development when `WORKFLOW_TARGET_WORLD=local` or when no Vercel environment is detected.

**Environment Variables:**

<ParamField path="WORKFLOW_LOCAL_DATA_DIR" type="string">
  Directory for storing workflow state (defaults to `.workflow-data`)
</ParamField>

### Custom World

You can implement a custom world by setting `WORKFLOW_TARGET_WORLD` to a module path:

```bash theme={null}
WORKFLOW_TARGET_WORLD=./my-custom-world.js
```

The module must export one of:

* Default function returning a `World` instance
* Named `createWorld` function

## World Interface

The `World` interface provides access to workflow infrastructure:

```typescript theme={null}
interface World {
  // Event sourcing
  events: {
    create(runId: string, event: Event): Promise<{ event: Event; run: WorkflowRun }>;
  };

  // Run management
  runs: {
    get(runId: string): Promise<WorkflowRun>;
  };

  // Queue operations
  queue(queueName: string, payload: unknown, options?: QueueOptions): Promise<void>;
  createQueueHandler(prefix: string, handler: Function): Function;

  // Deployment info
  getDeploymentId(): Promise<string>;

  // Encryption (optional)
  getEncryptionKeyForRun?(run: WorkflowRun | string, context?: any): Promise<Uint8Array | undefined>;
}
```

## Related Functions

### getWorld()

Retrieves the singleton world instance, creating it if necessary.

```typescript theme={null}
import { getWorld } from 'workflow/runtime';

const world = getWorld();
```

### setWorld()

Replaces the cached world instance. Useful for testing.

```typescript theme={null}
import { setWorld } from 'workflow/runtime';

setWorld(customWorld);
```

<ParamField path="world" type="World | undefined">
  The world instance to use, or `undefined` to clear the cache
</ParamField>

### getWorldHandlers()

Retrieves world handlers needed at build time without full initialization.

```typescript theme={null}
import { getWorldHandlers } from 'workflow/runtime';

const handlers = getWorldHandlers();
const queueHandler = handlers.createQueueHandler('__prefix_', async (msg) => {
  // Handle message
});
```

## Examples

### Basic Usage

```typescript theme={null}
import { getWorld } from 'workflow/runtime';

// Get the current world (auto-created if needed)
const world = getWorld();

// Access run information
const run = await world.runs.get('wrun_123');
console.log('Status:', run.status);
```

### Testing with Custom World

```typescript theme={null}
import { setWorld } from 'workflow/runtime';
import { createLocalWorld } from '@workflow/world-local';

// Use local world for testing
const testWorld = createLocalWorld({
  dataDir: './test-data',
});

setWorld(testWorld);

// Run tests...

// Clean up
setWorld(undefined);
```

### Vercel Deployment

```bash theme={null}
# .env.production
WORKFLOW_VERCEL_AUTH_TOKEN=your-token
WORKFLOW_VERCEL_PROJECT=prj_xxx
WORKFLOW_VERCEL_PROJECT_NAME=my-app
WORKFLOW_VERCEL_ENV=production
```

```typescript theme={null}
// Automatically uses Vercel world when deployed
import { getWorld } from 'workflow/runtime';

const world = getWorld(); // Returns Vercel world
```

### Custom World Implementation

```typescript theme={null}
// custom-world.ts
import type { World } from '@workflow/world';

export function createWorld(): World {
  return {
    events: {
      async create(runId, event) {
        // Custom event storage
        const stored = await myDatabase.insertEvent(runId, event);
        const run = await this.runs.get(runId);
        return { event: stored, run };
      },
    },
    runs: {
      async get(runId) {
        return await myDatabase.getRun(runId);
      },
    },
    async queue(queueName, payload) {
      await myQueue.enqueue(queueName, payload);
    },
    createQueueHandler(prefix, handler) {
      return myQueue.createHandler(prefix, handler);
    },
    async getDeploymentId() {
      return process.env.DEPLOYMENT_ID || 'local';
    },
  };
}
```

```bash theme={null}
# Use custom world
WORKFLOW_TARGET_WORLD=./custom-world.js
```

## Type Definitions

### WorkflowRun

```typescript theme={null}
interface WorkflowRun {
  runId: string;
  workflowName: string;
  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
  createdAt: Date;
  startedAt?: Date;
  completedAt?: Date;
  output?: any;
  error?: {
    message: string;
    stack?: string;
  };
}
```

### Event

```typescript theme={null}
type Event = 
  | { eventType: 'run_created'; eventData: { workflowName: string; input: any; ... } }
  | { eventType: 'run_started'; specVersion: number }
  | { eventType: 'run_completed'; eventData: { output: any } }
  | { eventType: 'run_failed'; eventData: { error: { message: string; stack?: string } } }
  | { eventType: 'run_cancelled'; specVersion: number }
  | { eventType: 'wait_created'; correlationId: string; eventData: { resumeAt: Date } }
  | { eventType: 'wait_completed'; correlationId: string }
  // ... and more event types
```

## Best Practices

1. **Use getWorld() instead of createWorld()**: The singleton pattern ensures consistency

2. **Environment-specific configuration**: Use environment variables for different deployments

3. **Don't cache world references**: Always call `getWorld()` to get the current instance

4. **Test with local world**: Use local world for development and testing

5. **Custom worlds for special cases**: Implement custom worlds for unique infrastructure needs

## See Also

* [start()](/api-reference/workflow-api/start-workflow)
* [getRun()](/api-reference/workflow-api/get-workflow-state)
* [@workflow/world-vercel](https://www.npmjs.com/package/@workflow/world-vercel)
* [@workflow/world-local](https://www.npmjs.com/package/@workflow/world-local)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.