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.

esem-bridge is a runtime bridge between JavaScript and Python. Install it from npm, call python("./your_module.py"), and every function, class, and constant in that module becomes an awaitable JavaScript value — no FastAPI server, no HTTP endpoints, no subprocess boilerplate.

Quickstart

Get from npm install to your first Python function call in under two minutes.

How It Works

Learn how the JSON-RPC bridge, Python worker, and proxy system fit together.

API Reference

Full reference for python(), shutdown(), PythonError, and more.

CLI Reference

Run JS files with python: import syntax using the esem run command.

​
Why esem-bridge?

Connecting Python and JavaScript typically means standing up a FastAPI or Flask server, writing HTTP routes, handling serialization, and managing two separate processes. esem-bridge collapses all of that into a single function call. 
// Two processes. An HTTP server. JSON serialization by hand.
const res = await fetch("http://localhost:8000/predict", {
  method: "POST",
  body: JSON.stringify({ age: 22, country: "NG" }),
});
const result = await res.json();

​
Key features

Two import styles

Use the python() helper or the python: import syntax — whichever fits your workflow.

Classes & instances

Instantiate Python classes from JavaScript. Instance methods are callable proxies.

Full type bridge

None, bool, int, float, str, list, and dict map cleanly across the boundary.

Rich error handling

Python exceptions cross the bridge with the original message, type name, and full traceback.

No servers

Communication is JSON-RPC over stdin/stdout — zero network overhead, no open ports.

Virtualenv support

Point ESEM_PYTHON at any interpreter — system Python, a venv, or conda.

​
Get started

1

Install esem-bridge

npm install esem-bridge
Requires Node.js 18+ and Python 3.8+.
2

Write a Python module

tools.py
def greet(name):
    return f"Hello, {name}!"

def add(a, b):
    return a + b
3

Call it from JavaScript

index.js
import { python } from "esem-bridge";

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

console.log(await greet("world")); // Hello, world!
console.log(await add(2, 3));      // 5
4

Run your script

node index.js
The Python worker starts automatically and shuts down when Node exits.

Build docs developers (and LLMs) love

Get started for freeTalk to us