portablemc-node

A lightweight TypeScript/JavaScript wrapper for the portablemc command-line tool.

It automatically handles downloading and managing the underlying portablemc binary for Windows, Linux, and macOS so you don't have to bundle it or require your users to install it manually.

[!WARNING] Versions 1.0.3 and older are deprecated and no longer work. Please make sure you are using the latest version.

Features

• Cross-Platform: Automatically detects, downloads, and sets permissions for Windows, Linux, and macOS binaries.
• Zero Manual Setup: Downloads the required binary on initialization if it doesn't exist.
• Authentication Support: Seamless Microsoft/Minecraft login handling, exposing the required OAuth device codes directly via code.
• Account Management: List locally cached Microsoft accounts and their UUIDs.
• Flexible Launching: Supports specific vanilla versions, mod loaders (Forge, Fabric, NeoForge, Quilt), custom JVM arguments, and auto-joining servers.

Installation

Install the package via npm:

npm install portablemc-node

Quick Start

Here is a basic example of how to initialize the library and launch a specific Minecraft version.

import { PortableMC } from "portablemc-node";
import path from "path";

async function main() {
  // Define where to store the portablemc binary and Minecraft files
  const storageDir = path.join(process.cwd(), ".minecraft-data");

  const launcher = new PortableMC(storageDir);

  // 1. Initialize (downloads the binary if it's missing)
  console.log("Initializing launcher...");
  await launcher.init();

  // 2. Configure game settings
  launcher
    .setVersion("1.20.4")
    .setLoader("fabric") // Supports: 'neoforge' | 'fabric' | 'forge' | 'quilt'
    .setServer("play.example.com:25565"); // Optional: Auto-join server on launch

  // 3. Start the game
  console.log("Launching Minecraft...");
  launcher.start("PlayerName", {
    auth: false, // Set to true if using an authenticated account
    onClose: () => {
      console.log("Game closed!");
    },
  });
}

main().catch(console.error);

Authentication Flow

To launch the game with an official Microsoft account, you must complete the device login flow.

const launcher = new PortableMC("./mincraft-data");
await launcher.init();

// Start the login process
const code = await launcher.login(() => {
  console.log("Successfully authenticated with Microsoft!");

  // Now you can safely start the game with auth enabled
  launcher.setVersion("1.20.4").start("YourRegisteredUsername", { auth: true });
});

// Display this code to your user so they can link their account
console.log(`Please go to https://microsoft.com/link and enter code: ${code}`);

API Reference

new PortableMC(binDest, dataFolderName?, binFilepath?)

Creates a new instance of the PortableMC wrapper.

| Parameter | Type | Required | Description | | ---------------- | -------- | -------- | ----------------------------------------------------------------------------------- | | binDest | string | Yes | The directory path where the portablemc executable will be downloaded and stored. | | dataFolderName | string | No | The directory path for Minecraft's game data (defaults to binDest). | | binFilepath | string | No | Custom exact path to the binary (auto-generated by default). |

Instance Methods

.init(): Promise<this>

Downloads the correct platform binary to binDest if it doesn't already exist and applies executable permissions (chmod +x) on Unix systems. Returns the class instance for chaining.

.setVersion(version: string): this

Sets the target Minecraft version (e.g., "1.20.4", "1.16.5").

.setLoader(loader: 'neoforge' | 'fabric' | 'forge' | 'quilt'): this

Sets the mod loader to use.

.setServer(address: string): this

Pass a server address (e.g., "localhost:25565" or "mc.hypixel.net"). The game will automatically attempt to connect to this server upon loading.

.start(username: string, options?: LaunchOptions): void

Spawns the Minecraft process. If the binary isn't ready yet, it will queue execution until the ready event fires.

type LaunchOptions = {
  auth?: boolean; // Use Microsoft authentication profile (Default: false)
  jvmArg?: string; // Additional custom JVM arguments
  onClose?: () => void; // Callback function fired when the game process exits
};

.login(authenticatedCallback: () => void): Promise<string>

Triggers the Microsoft device authentication step.

• Returns: A Promise<string> containing the short verification code your user needs to enter on Microsoft's login activation page.
• Callback: authenticatedCallback is executed once the login process detects a successful token receipt.

.getAccounts(): Promise<{ username: string; uuid: string }[]>

Parses and returns an array of all locally saved profiles/accounts currently stored in the data directory.

License

This project wrapper is MIT licensed. The underlying tool portablemc belongs to its respective owners.