fix: ESM world loading for @workflow/world-postgres

[michael-han-dev]

Description

@workflow/world-postgres fails with ERR_REQUIRE_ESM because world.ts used require() to load external worlds, but postgres is ESM-only. fixmade : replace require() with dynamic import() via new Function() to bypass bundler static analysis. Added initWorld() for async world loading. External worlds now need await initWorld() instead of getWorld() - though this was already broken before, so nothing that was working is changing. Built-in worlds (local, vercel) unchanged. updated docs accordingly as well. fixes #812

How did you test your changes?

Added packages/core/src/runtime/world.test.ts with 13 tests
Postgres World Testing
Ran a local postgres container (postgres:18-alpine) on port 5432.

Framework Tests
Built and started each framework with WORKFLOW_TARGET_WORLD=@workflow/world-postgres and the postgres connection string. All four logged "Starting Postgres World..." and started without ESM errors.

• Nitro v3: production build, ran node .output/server/index.mjs, server on localhost:3000
• Nuxt: production build, ran node .output/server/index.mjs, server on localhost:3000
• SvelteKit: production build, ran node build/index.js, server on localhost:3000
• Astro: production build, ran bundled output, server on localhost:4321

The Astro start-with-pg.mjs script fails with ERR_MODULE_NOT_FOUND. Pre-existing issue unrelated to this PR. Bundled output works.

Edge Cases
Tested invalid module path (throws ERR_MODULE_NOT_FOUND), module with wrong exports (throws "Invalid target world module"), external world accessed before init (throws "Call await initWorld() first"), and built-in worlds (still work synchronously).

E2E with Postgres
Pushed the database schema via pnpm db:push in world-postgres. Started Next.js Turbopack with postgres world env vars. Triggered the simple workflow via curl to /api/trigger. Got back a run ID.

Verified in postgres: workflow run created, step created, pg-boss jobs queued and processed. The ESM module loaded correctly and the World instance worked.

Also ran the same workflow with local world to confirm end-to-end execution works. It does.

PR Checklist - Required to merge

• 📦 pnpm changeset was run to create a changelog for this PR
  • During beta, we only use "patch" mode for changes. Don't tag minor/major versions.
  • Use pnpm changeset --empty if you are changing documentation or workbench apps
• 🔒 DCO sign-off passes (run git commit --signoff on your commits)

[changeset-bot]

🦋 Changeset detected

Latest commit: 32de6bf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
workflow	Patch
@workflow/core	Patch
@workflow/cli	Patch
@workflow/ai	Patch
@workflow/docs-typecheck	Patch
@workflow/world-testing	Patch
@workflow/builders	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/web-shared	Patch
@workflow/astro	Patch
@workflow/sveltekit	Patch
@workflow/nuxt	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@michael-han-dev is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The Run class properties and methods throw synchronously when accessing world getter with external worlds, breaking the public API instead of returning rejected Promises