Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Crane04/esem/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through installing esem-bridge, writing a small Python module, and calling it from a Node.js script. By the end you will have a working bridge between JavaScript and Python with zero server setup. You need Node.js 18+ and Python 3.8+ installed on your machine.

​
Using the python() helper

The python() helper is the recommended way to load a Python module. It works in any Node.js ESM script with no extra flags.
1

Install esem-bridge

Add esem-bridge to your project with your preferred package manager.
npm install esem-bridge
2

Write a Python module

Create a file called tools.py in your project directory. This module exposes a greet function, a multiply function, and a Counter class.
tools.py
def greet(name):
    return f"Hello, {name}!"

def multiply(a, b):
    return a * b

class Counter:
    def __init__(self, start=0):
        self.value = start

    def add(self, amount=1):
        self.value += amount
        return self.value
3

Call it from JavaScript

Create index.js. Use python() to load the module, then call its exports like regular async functions. Instantiate Counter by calling it like a function — await Counter(5) returns a live proxy of the Python object.
index.js
import { python, shutdown } from "esem-bridge";

const { greet, multiply, Counter } = await python("./tools.py");

console.log(await greet("Mayowa"));      // Hello, Mayowa!
console.log(await multiply(4, 6));       // 24

const counter = await Counter(5);
console.log(await counter.add(3));       // 8

await counter.release();
4

Run it

Execute the script with Node.js directly — no extra flags needed when using the python() helper.
node index.js
Expected output:
Hello, Mayowa!
24
8
You do not need to call shutdown() in short scripts. esem-bridge automatically unrefs the Python worker when no calls are active, so Node.js exits naturally once your script finishes. In long-running applications the worker stays alive and is reused across all python() calls.

​
Using the python: import syntax

If you prefer static ESM import declarations, esem-bridge provides a Node.js loader hook that intercepts python: specifiers and synthesizes a live module proxy on the fly.
1

Write your JavaScript file using the import syntax

Replace the python() call with a standard import statement using the python: prefix. Everything else — calling functions, instantiating classes, reading constants — works the same way.
index.js
import tools from "python:./tools.py";

console.log(await tools.greet("Mayowa"));    // Hello, Mayowa!
console.log(await tools.multiply(4, 6));     // 24

const counter = await tools.Counter(5);
console.log(await counter.add(3));           // 8
2

Run with the loader hook

The python: syntax requires the esem-bridge loader to be active. Use either the esem CLI or the --experimental-loader flag directly.
npx esem run index.js
To run the CLI without installing the package first, use npx with the --package flag:
npx --package esem-bridge esem run index.js
To use a specific Python binary — such as one inside a virtual environment — set the ESEM_PYTHON environment variable before running your script:
ESEM_PYTHON=.venv/bin/python npx esem run index.js
This is useful when your Python module depends on packages installed in a project-local .venv.

Build docs developers (and LLMs) love

Get started for freeTalk to us