tspoonbase

library0.15.0jsnpmunverified

TspoonBase is a TypeScript backend-as-a-service library (v0.15.0) that bundles SQLite, Express, WebSocket, auth (email/password, OAuth2, OTP, MFA/TOTP), realtime subscriptions, file storage, vector search, AI tools, and a React admin UI into one package. It follows a dual-database SQLite architecture (data.db + auxiliary.db) with 14 field types, including vector fields for AI-powered search. Release cadence is frequent (multiple weekly releases). Differentiators: single dependency, TypeScript-native, built-in admin UI, and JavaScript hooks for server-side logic, inspired by PocketBase but fully Node.js/TypeScript. Requires Node >=20.

database

npm install tspoonbase

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TSPOONBASE

tspoonbase

databasejavascriptv0.15.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TspoonBase

✓ import { TspoonBase } from 'tspoonbase'

✗ const TspoonBase = require('tspoonbase')

ESM-only package. CommonJS require() will fail. Use ESM imports.

TspoonBase class (default usage)

✓ import { TspoonBase } from 'tspoonbase' const app = new TspoonBase({ defaultDev: true })

✗ import TspoonBase from 'tspoonbase'

Named export only. Default import returns undefined.

type RecordService

✓ import type { RecordService } from 'tspoonbase'

✗ import { RecordService } from 'tspoonbase'

TypeScript type import. Use 'import type' for runtime-free imports. RecordService is not a value.

AdminUI component (React)

✓ import { AdminUI } from 'tspoonbase/admin'

✗ import { AdminUI } from 'tspoonbase'

AdminUI is exported from a separate subpath 'tspoonbase/admin'. Importing from main fails.

Initializes TspoonBase server, creates a superuser, defines a collection, inserts a record, and queries with filters.

import { TspoonBase } from 'tspoonbase'; const app = new TspoonBase({ defaultDev: true }); await app.start(8090); console.log('Admin UI: http://localhost:8090/_/'); // Create a superuser programmatically import { parse } from 'ts-command-line-args'; // Or use CLI: tspoonbase superuser-create admin@example.com secret123 // Setup a collection const usersCollection = app.collections.create({ name: 'users', type: 'auth', fields: [ { name: 'username', type: 'text', required: true }, { name: 'email', type: 'email', required: true }, { name: 'age', type: 'number' } ] }); // Insert a record await app.records.create('users', { username: 'john_doe', email: 'john@example.com', age: 30 }); // Query with filter const results = await app.records.getList('users', { filter: 'age > 20', sort: '-created', perPage: 10 }); console.log(results.items);

Debug

Known issues

breakingNode.js >= 20.0.0 required. Older versions will throw ERR_REQUIRE_ESM errors.

fix

Upgrade Node.js to version 20 or later.

affects: >=0.0.0

breakingESM-only: CommonJS require() fails with ERR_REQUIRE_ESM.

fix

Use ESM imports (import { ... } from 'tspoonbase') or set type: module in package.json.

affects: >=0.1.0

gotchaAdmin UI subpath import: import { AdminUI } from 'tspoonbase/admin' — NOT from main package.

fix

Always import AdminUI from 'tspoonbase/admin' when using the React admin component.

affects: >=0.10.0

deprecatedapp.start(port) is deprecated in favor of app.listen(port) in v0.14+. Will be removed in v1.

fix

Use app.listen(port) instead of app.start(port).

affects: >=0.14.0 <1.0.0

breakingCollection types changed: 'auth' type now requires a mandatory username field since v0.12.0.

fix

Add a 'username' text field to any collection with type: 'auth'.

affects: >=0.12.0

gotchaVector search requires a vector field in the collection and auxiliary.db must exist. Server initializes it automatically, but manual SQLite file removal breaks it.

fix

Do not delete auxiliary.db manually. Use proper migration commands (tspoonbase migrate).

affects: >=0.8.0

breakingbcrypt dependency was removed in v0.15.0; switched to native crypto scrypt. Existing hashes will not verify.

fix

Rehash all existing passwords using the new scrypt method or migrate users manually.

affects: >=0.15.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/tspoonbase/index.js from /path/to/file.js not supported.

Using CommonJS require() with an ESM-only package.

fix

Replace require() with ESM import: import { TspoonBase } from 'tspoonbase'; or set type: module in your package.json.

TypeError: app.start is not a function

app.start() was renamed to app.listen() in v0.14.0.

fix

Use app.listen(port) instead of app.start(port).

ValidationError: Field 'username' is required for auth collections

Auth collection type requires a 'username' field since v0.12.0.

fix

Add a text field with name 'username' to the collection definition.

Error: Cannot find module 'tspoonbase/admin'

AdminUI subpath is only available in Node >= 16 with ESM. Wrong import path.

fix

Import from 'tspoonbase/admin' (not 'tspoonbase/admin/index.js') and ensure package.json has exports field coverage.

Upgrade

Version history

0.15.0latest on npm

Audit

Dependencies

better-sqlite3requiredSQLite database driver (synchronous API)

expressrequiredHTTP server and routing framework

wsrequiredWebSocket server for realtime subscriptions

bcryptrequiredPassword hashing for authentication

jsonwebtokenrequiredJWT token generation and verification

multerrequiredFile upload handling

Agent activity

22 hits · last 30 days

node