Your first TypeScript program

This program creates a ready bot from a Minecraft server address and username. The SDK downloads SoulFire and Java when needed and manages setup and cleanup.

Prepare the Minecraft serverCopy Anchor Link

Start a Minecraft server that accepts offline accounts at localhost:25565. Change server in the program if your server uses another address. The default authentication is "offline". For a server that requires a Microsoft account, see account authentication.

Install the SDKCopy Anchor Link

Complete the Bun installation. Run the program from that application directory.

Save the complete programCopy Anchor Link

Create first-bot.ts:

import { Effect } from "effect";
import { SoulFire } from "@soulfiremc/sdk/bun";

const program = Effect.scoped(
  Effect.gen(function* () {
    const bot = yield* SoulFire.createBot({
      server: "localhost:25565",
      username: "DocsBot_1",
      installation: { version: "2.10.2" },
    });

    yield* bot.chat.send("Hello from SoulFire");
    yield* Effect.logInfo(`Health: ${bot.state.player?.health}`);
  }),
);

await Effect.runPromise(program);

server is the Minecraft address. The SDK supplies the local SoulFire API URL and token and creates or finds the instance and account.

Run and check the resultCopy Anchor Link

bun run first-bot.ts

The first run downloads a dedicated backend and Java into .soulfire under the working directory. Later runs reuse those files and the saved account. Expect Hello from SoulFire in Minecraft chat and a health value in the program log. The scope closes subscriptions and the managed backend when the program finishes.

Use installation.directory to choose another data directory. The example pins the backend to 2.10.2; omit installation.version to select the latest release.

Read the codeCopy Anchor Link

SoulFire.createBot installs a local backend and returns a ready, observed bot. It waits for the initial player snapshot, with a default 30-second deadline. Set readyTimeoutMs to change that deadline. bot.state contains the latest synchronized state.

yield* runs each operation inside Effect.gen. Effect.scoped owns the connection, subscriptions, and managed process. Effect.runPromise runs the complete workflow at the application boundary. Constructing an Effect alone does not send a request.

Use Node.jsCopy Anchor Link

Install the Node.js dependencies. Import SoulFire from @soulfiremc/sdk/node instead of @soulfiremc/sdk/bun. Run the file with npx tsx first-bot.ts on Node.js 22 or newer. For a standalone Node application, NodeRuntime.runMain(program) also handles process interruption and scoped cleanup.

Next stepCopy Anchor Link

Use named instances and bots to reuse one backend for several accounts or connect to an existing server. Try replying to chat, or read the runtime guide for layers and streams. Read task ownership before submitting work that can outlive your program.