Getting Started
Install
devsess needs effect, plus whichever platform you run scripts on — it doesn’t declare a peer on either, so install the one you use directly:
bun add devsess effect @effect/platform-node
bun add devsess effect @effect/platform-bun
Write the script
Create scripts/dev.ts. Build a stock Command and provide devsess’s layers around it, using whichever platform package you installed:
// scripts/dev.ts
import { CurrentSession, DevSessions, getStickyPort, runManagedSubprocess } from 'devsess'
import { NodeRuntime, NodeServices } from '@effect/platform-node'
import { Effect } from 'effect'
import { Command } from 'effect/cli'
const web = Command.make('web', {}, () =>
Effect.gen(function* () {
const session = yield* CurrentSession
console.log(`session: ${session.name}`)
const port = yield* getStickyPort(session)
yield* runManagedSubprocess('bunx', ['vite'], {
env: { PORT: String(port) },
})
}).pipe(Effect.provide(CurrentSession.layer)),
)
Command.run(web, { version: '0.1.0' }).pipe(
Effect.provide(DevSessions.layer),
Effect.provide(NodeServices.layer),
Effect.scoped,
NodeRuntime.runMain,
)
On Bun, the shape is identical — swap the import and the layer:
import { BunRuntime, BunServices } from '@effect/platform-bun'
Command.run(web, { version: '0.1.0' }).pipe(
Effect.provide(DevSessions.layer),
Effect.provide(BunServices.layer),
Effect.scoped,
BunRuntime.runMain,
)
There’s no dir to pass — DevSessions.layer auto-detects your project root by walking up from process.cwd() to the nearest package.json. CurrentSession.layer sits on the handler rather than around Command.run on purpose: a Layer’s build effect runs the moment it’s provided, so putting it around the whole CLI would resolve (and create) a session even for --help. Writing a dev CLI → says more.
This resolves the current session, reads a sticky port for it, and runs vite as a managed subprocess bound to that port.
Run it
bun scripts/dev.ts
You’ll see something like:
session: walrus
[dev] started: bunx vite (pid=41213)
Then whatever vite prints on its own — its output goes straight to your terminal, unchanged.
What just happened
- Session. devsess resolved this checkout’s session — a directory under
.data/sessions/, isolated from any other checkout of this project. It picked whichever session was modified most recently, or created one since none existed yet. Slugs are a single word, likewalrus, not something you name. Writing a dev CLI → - Sticky port. It read the port already stored in that session and asked for it again —
getStickyPort(session)hands back the same port next run, as long as it’s still free. Ports that survive restarts → - Managed subprocess.
viteran under devsess’s control. Ctrl-C the script and devsess kills it too — no orphaned process left behind. Running your dev server → - One scope. All of it runs inside the
Effect.scoped(...)wrapped aroundCommand.run(...)above. That scope closing is what makes the cleanup above possible. Writing a dev CLI →
Where to go next
- A database per session — give each session its own Postgres, seeded from your migrations.
- Wiring services together — let one service read the port another one landed on.
- devsess reference — every export, in full, once you’re past the basics.