$ pip install ephaptic

from fastapi import FastAPI # or `from quart import Quart`
from ephaptic import Ephaptic

app = FastAPI() # or `app = Quart(__name__)`

ephaptic = Ephaptic.from_app(app) # Finds which framework you're using, and creates an ephaptic server.

You can also specify a custom path:

ephaptic = Ephaptic.from_app(app, path="/websocket")

And you can even use Redis for horizontal scaling!

ephaptic = Ephaptic.from_app(app, redis_url="redis://my-redis-container:6379/0")

Now, how do you expose your function to the frontend?

@ephaptic.expose
async def add(num1: int, num2: int) -> int:
    return num1 + num2

If you're trying to expose functions statelessly, e.g. in a different file, feel free to instead import and use the expose function from the library instead of the instance. Please note that if you do this, you must define all exposed functions before creating the ephaptic instance - easily done by simply placing your import line above the ephaptic constructor. The same thing can be done with the global identity_loader decorator.

Yep, it's really that simple.

But what if your code throws an error? No sweat — it surfaces on the frontend as a typed error you can catch. Raise a ServiceError for structured, typed errors (carrying a code, message, and data), or let ephaptic turn unexpected exceptions into a safe, generic error (details stay on the server unless you opt into debug mode). See the error handling docs.

And, want to say something to the frontend?

class Notification(BaseModel):
    message: str
    priority: Literal["high", "low", "default"]

await ephaptic.to(user1, user2).emit(Notification(message="Hello, world!", priority="high"))

To create a schema of your RPC endpoints (pass --watch to auto-regenerate on file changes):

$ ephaptic generate src.app:ephaptic -o schema.json

Or output TypeScript directly, skipping the JSON layer:

$ ephaptic generate src.app:ephaptic -o ephaptic.d.ts

Pydantic is entirely supported. It's validated for arguments, it's auto-serialized when you return a pydantic model, and your models receive type definitions in the schema.

To receive authentication objects and handle them:

from ephaptic import identity_loader

@identity_loader
async def load_identity(auth): # You can use synchronous functions here too.
    jwt = auth.get("token")
    if not jwt: return None # unauthorized
    ... # app logic to retrieve user ID
    return user_id

From here, you can use ephaptic.active_user() within any exposed function, and it will give you the current active user ID / whatever else your identity loading function returns. (This is also how ephaptic.to works.)

To use with a framework / Vite:

$ npm install @ephaptic/client

Then:

import { connect } from "@ephaptic/client";

const client = connect(); // Defaults to `/_ephaptic`.

Or, you can use it with a custom URL:

const client = connect({ url: '/ws' });

const client = connect({ url: 'wss://my-backend.deployment/ephaptic' });

You can even send auth objects to the server for identity loading.

const client = connect({ url: '...', auth: { token: window.localStorage.getItem('jwtToken') } })

And you can load types, too (pass --watch to auto-reload on changes):

$ ephaptic generate ./schema.json -o schema.d.ts

import { connect } from "@ephaptic/client";
import { type EphapticService } from './schema';

const client = connect(...) as EphapticService;

Or, to use in your browser:

<script type="module">
import { connect } from 'https://cdn.jsdelivr.net/npm/@ephaptic/client@latest/+esm';

const client = connect(...);
</script>