@nodedistro/nodebase-js

NodeBase JavaScript / TypeScript SDK, Node.js 18+ and modern browsers. No runtime dependencies. This is an independent NodeBase client, not a drop-in replacement for supabase-js.

Install now

From a downloaded/cloned NodeBase repository:

npm install ./packages/nodebase-js

Or run npm pack inside packages/nodebase-js and install the resulting .tgz. The registry command npm install @nodedistro/nodebase-js works only after the owner publishes the package to npm.

Server database client

NODEBASE_PROJECT_URL=https://db.nodedistro.com/rest/YOUR_PROJECT_UUID
NODEBASE_SECRET_KEY=nbk_YOUR_PROJECT_KEY

import { createClient } from '@nodedistro/nodebase-js';
const db = createClient(process.env.NODEBASE_PROJECT_URL, process.env.NODEBASE_SECRET_KEY);
const { data, error } = await db.from('todos').select();
if (error) throw new Error(error.message);
console.log(data);

await db.from('todos').insert({name:'Build something'});
await db.from('todos').update({id:'ROW_UUID'}, {completed:true});
await db.from('todos').delete({id:'ROW_UUID'});
await db.from('todos').select({offset:100});

Use complete primary keys, including all columns of a composite key. select() returns at most 100 rows; paginate with offset. The table client supports whole rows, pagination, insert, keyed update and keyed delete. It does not currently implement Supabase filters, joins, SQL RPC, selected-column expressions, query chaining or automatic table RLS for application users. Check each operation's returned error; creation and updates can fail on constraints or permissions.

Never prefix the secret with NEXT_PUBLIC_, put it in browser code, or expose a server route that blindly forwards arbitrary user table requests. Project keys grant project-wide access. The client refuses initialization in a browser and refuses redirects when sending credentials.

Next.js server page

import 'server-only';
import { createClient } from '@nodedistro/nodebase-js';
export default async function Page() {
  // Protect this page with your application's authorization before making it public.
  const db = createClient(process.env.NODEBASE_PROJECT_URL!, process.env.NODEBASE_SECRET_KEY!);
  const {data, error} = await db.from('todos').select();
  if (error) throw new Error(error.message);
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Install server-only for this optional Next.js example.

Browser application authentication

import { createAppClient } from '@nodedistro/nodebase-js';
const app = createAppClient('https://db.nodedistro.com/rest/YOUR_PROJECT_UUID');
const signedIn = await app.auth.signInWithPassword({email:'[email protected]',password:'my-long-password'});
if (signedIn.error) throw new Error(signedIn.error.message);
const rows = await app.records('items').select();
await app.records('items').insert({name:'My private record'});
await app.auth.refreshSession();
await app.auth.signOut();

Application users are separate from dashboard users. app.records() accesses only the signed-in user's JSON records, not arbitrary relational tables. Configure allowed website origins in Project Settings. signUp() requires application signup enabled. It creates an account, then you must sign in.

Sessions stay in memory; the SDK does not persist cookies, implement SSR middleware or refresh on a timer. Access sessions expire in 30 minutes; call refreshSession() before expiry. Refresh tokens rotate. Concurrent refresh calls on a single client share one request. Use auth.getSession() to obtain a copy; an optional initial {session} restores an already valid app session. Cookie/session persistence is your application's responsibility.

Development and publishing

npm test
npm pack
npm login
npm publish --access public

Publishing requires an npm account with access to the @nodedistro scope. GitHub organization membership does not grant npm permissions. Publishing is handled by the repository’s Publish NodeBase JS GitHub Actions workflow. See setup instructions. NodeBase deployment and Amplify builds do not publish packages.