libSQL Client (TypeScript)

@libsql/client is the official TypeScript/JavaScript driver for libSQL, the open-source fork of SQLite that powers Turso’s distributed database platform. A single createClient({ url }) call gives you a promise-based API (execute, batch, transaction) that works identically whether you’re pointed at a local SQLite file, a remote Turso database over HTTP/WebSocket, or an offline-first “embedded replica” that syncs periodically with a remote primary.

The client automatically selects the right transport based on the connection URL scheme — native SQLite bindings for local files, WebSocket (Hrana protocol) or HTTP for remote databases — so application code stays the same regardless of deployment target. It’s built on the shared @libsql/core package (config parsing, error types, SQL value conversion) alongside sibling packages for WASM (@libsql/client-wasm) and edge/serverless runtimes.

What You Get

• A unified Client API (execute, batch, transaction) that works the same for local files, remote Turso databases, and in-memory databases
• Embedded Replicas support — a local SQLite file that periodically syncs with a remote Turso primary via syncUrl/syncInterval, enabling offline reads with eventual sync
• Encryption-at-rest support for local database files
• Native integration with Turso’s AI/vector search features for similarity queries directly from SQL
• Runtime-specific entry points (node.ts, web.ts, plus a companion @libsql/client-wasm package) so the same driver works in Node.js, browsers, and edge runtimes like Vercel/Netlify/Lambda

Common Use Cases

• Building serverless/edge applications (Vercel, Netlify, Lambda) that need a lightweight SQL database without managing connection pools
• Multi-tenant SaaS apps that provision one SQLite/Turso database per tenant instead of sharing rows in a single large database
• Offline-first apps that read/write to a local SQLite file via Embedded Replicas while syncing changes to a remote Turso primary in the background
• Adding vector similarity search alongside relational data in the same SQLite-compatible database

Under The Hood

Architecture — createClient (packages/libsql-client/src/node.ts) inspects the config’s URL scheme and dispatches to one of three internal client implementations: _createSqlite3Client for local file:/in-memory databases (native SQLite bindings, sqlite3.ts, ~620 lines), _createWsClient for the Hrana WebSocket protocol (ws.ts/hrana.ts, together ~930 lines), or _createHttpClient for HTTP-based remote access (http.ts, ~340 lines) — all three conform to the same Client interface defined in the shared @libsql/core package, so callers never touch transport-specific code directly.

Tech Stack — TypeScript for the driver logic (65% of the repo) with a Rust/native component underneath for local SQLite file access, plus supporting Python tooling (29%) for the monorepo’s test/CI infrastructure. The workspace splits into @libsql/core (shared config/error/value-conversion types), @libsql/client (this package, Node-oriented), and @libsql/client-wasm (browser/edge-oriented, no native bindings).

Code Quality — Core logic is covered by __tests__/ unit tests (uri.test.ts, config.test.ts, client.test.ts) plus a separate smoke_test/ directory with real deployment smoke tests against Vercel and Cloudflare Workers runtimes — a meaningful signal given the package’s explicit goal of working correctly across multiple JS runtimes, not just Node. Release history is thin on GitHub Releases (only one tagged release) despite frequent npm publishes and ~3 commits/month, suggesting versions are cut more informally than via GitHub’s release flow.

API Design — The single createClient(config) entry point with a uniform execute/batch/transaction API across three different transports is a deliberately low-friction design — switching a project from local SQLite to a remote Turso database (or adding Embedded Replicas) is a config change, not a code rewrite. The trade-off is that Config’s scheme-based dispatch (file:, http(s):, ws(s):) is implicit “magic” that developers need to learn from docs rather than the type system alone.