npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@n-dream/builders-sdk

v1.5.0

Published

Builders SDK for app code: app information, sign-in of app users and app data.

Readme

@n-dream/builders-sdk

The SDK for apps on Builders (design 4.5). Apps import it from npm.

import * as builders from "@n-dream/builders-sdk";

const info = await builders.appInfo(); // { appId, slug, environment, version }

const user = await builders.auth.user(); // { id, name, developer } or null
builders.auth.onChange((u) => render(u)); // now and at each change
await builders.auth.signIn(); // leaves the page; comes back signed in
await builders.auth.signOut();
builders.auth.accountPage(); // the Builders page: download or delete my data
  • appInfo() reads /_api/app.json on the app's own host. environment is live, preview or version. version is null on the preview. Without the platform, appInfo() throws a BuildersError.
  • auth (docs/login-and-data.md 4.1, 8.1): sign-in with Google, on the app's own host. user.id is this app's id of the user (another app has another id). The app gets the name, never the email. signIn() goes to the Builders sign-in page and back to the page (or to returnTo, a path of the app). Previews and versions sign in only developers.
  • Who can sign in is set by the app's owner in the portal (anyone, listed domains, or listed emails).
  • BuildersError has code (for example sign-in-required, offline, app-stopped) and status (the HTTP status, 0 when no answer came).

Data

Each collection is declared in builders.data.json in the app folder (docs/login-and-data.md 6.1): "mine" (each user's own, sign-in needed) or "public" (everyone reads; each signed-in user adds and changes only their own items; developers can remove any).

const notes = builders.db.collection<{ text: string; folder: string }>("notes");
const n = await notes.add({ text: "Hi", folder: "work" });
await notes.update(n.id, { text: "Hello" });
const page = await notes.list({ where: { folder: "work" }, limit: 20 });
const stop = notes.watch({ where: { folder: "work" } }, (items) => render(items));
  • get, set, update, remove take an id. A short id (no dot) is always the caller's own item. A public item has the id <user id>.<id>.
  • list and count filter only by equality on the declared filter fields and sort by createdAt, updatedAt or the declared sort field. watch gives the whole current list at once and after each change.
  • Errors are BuildersError with a plain message that says what to do (8.3). There are no transactions, joins or counters; calls such as db.transaction throw a message with the way to do it.
  • db.usage(): the bytes of the signed-in user's items and files, and their limits.
  • The user guard: each request names the user that the page believes is signed in. When the session has another user (a sign-in in another tab), Builders refuses it with user-changed: nothing is read or saved, auth.onChange gets the new user, and watches start again.

Files

A file set is declared in builders.data.json as "files": { "photos": "mine" } (docs/login-and-data.md 7). Only the user who uploads a file can open it, and only when signed in.

const photos = builders.db.files("photos");
const f = await photos.upload(input.files[0]); // a File or a Blob
img.src = f.url; // "/_api/files/photos/<id>": only this user can open it
const { files, next } = await photos.list({ limit: 20 }); // newest first
await photos.remove(f.id);
  • Types: JPEG, PNG, WebP, GIF, AVIF, HEIC; MP3, M4A, OGG, WAV, WebM audio; MP4, MOV (iPhone), WebM video; PDF. The platform reads the first bytes of the file: the content must be the type of the file. No SVG, HTML or scripts. A .mov is served as video/mp4 (Chrome on Android plays it only so); its type stays video/quicktime.
  • At most 10 MB a file, 1,000 files and 200 MB per user. Make photos smaller in the browser before the upload (at most 2,048 pixels, JPEG or WebP).

Local mode

On localhost, 127.0.0.1 and [::1] (vite dev, test:headless) the SDK keeps everything in memory (docs/login-and-data.md 8.4), with the same rules and limits as the platform (the same engine runs there): auth.signIn() signs in "Test user 1" at once. The tabs of one browser share the data. A file's url is a blob: URL there (there is no /_api/files on localhost); <img src> and <audio src> work the same. The Vite plugin puts builders.data.json into the build:

// vite.config.ts
import { builders } from "@n-dream/builders-sdk/vite";
export default defineConfig({ plugins: [builders(), react()] });

Headless tests use:

import { signInAs, signOut, reset, seed, setLoginMode } from "@n-dream/builders-sdk/testing";

signInAs("Ann"); // the same name gives the same user id
signInAs("Dev", { developer: true });
await seed("posts", [{ data: { text: "Hi" } }], { as: "Bob" });
setLoginMode("emails", ["[email protected]"]); // then signInAs takes the email
signOut();
reset(); // no users, no data

The SDK never uses the local mode on other hosts.

Release: the owner publishes with the next dist-tag (Q29). npm pack builds dist/ first.