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

@unbase-app/cli

v0.6.2

Published

Adds Unbase to an Astro, Vite + React or Next.js site, checks it, takes it out again, and renames, duplicates and deletes its pages: unbase init, doctor, uninstall and page.

Readme

@unbase-app/cli

Adds Unbase to an Astro, Vite + React or Next.js site, checks it, and takes it out again.

npx @unbase-app/cli init       # the framework's package, its line in its config, comment-modus.json
npx @unbase-app/cli doctor     # per feature: on, or what is missing, where, and how to fix it
npx @unbase-app/cli uninstall  # all of it out again; the built pages compared before and after
npx @unbase-app/cli page …     # rename, duplicate or delete a page, as Unbase's editor does

Always with the package's name: the unscoped unbase on npm is another product's package, so a bare npx @unbase-app/cli outside a site that has this CLI installed would fetch that one.

Unbase works on a connected site without any of this: the canvas, comments on the canvas, publishing, and visual editing (on Astro, nothing installed). What has to live in the site's own code is what this adds: comments on the live site (?comment), page management (draft pages kept off Live, page and site settings), and analytics (Unbase's beacon, a pageview from every page of a production build, no cookies). The packages change how the site is edited and built, never how it renders, but for the beacon's script, which renders nothing. The CLI itself never calls Unbase.

Astro, Vite + React with React Router as a library (what Lovable makes: Vite + React, below), and Next.js; each framework's own steps are in agents/<framework>.md. Node 18.17 or newer for the CLI (comment-modus itself needs 22.12). Until 03-11-2026 this was @unbase-app/cli; init moves a site installed with it across (Moving from before 03-11).

For a coding agent

Add Unbase to this site.

1. Run `npx @unbase-app/cli init --yes` and keep its changes.
2. Read node_modules/@unbase-app/cli/AGENTS.md and do the steps it leaves to you.
3. Don't move or rewrite the site's content. Unbase edits text where it is written.
4. Run `npx @unbase-app/cli doctor` until it passes. Commit on a new branch and push it.

AGENTS.md is in the package, so the steps are pinned by the site's lockfile. It points to the framework's own file, agents/astro.md or agents/vite-react.md, which init names.

unbase init

| Flag | | |---|---| | --comments / --no-comments | Comments on the live site, with ?comment (@unbase-app/layer, inside @unbase-app/astro). Default: in, or as the site has it when Unbase is in it already | | --project <id or slug> | Link comment mode and analytics to an Unbase project now (see Linking) | | --pointer[=AGENTS.md\|CLAUDE.md] / --no-pointer | One line in the site's AGENTS.md (or CLAUDE.md) pointing its agent at this package's AGENTS.md. Default: no | | --no-install | Write package.json only; install yourself | | --tarballs <dir> | Install the packages from npm pack tarballs in <dir>, for testing a release before it is on npm | | --yes | The default for every choice not given | | --json, --dir <path> | Output for programs; the site's folder (default: here) |

It adds, with the site's own package manager (npm, pnpm or yarn, from its lockfile), at these versions:

| Package | Version | | |---|---|---| | @unbase-app/astro | 0.5.0 | Unbase in an Astro site, one integration: comment mode (@unbase-app/layer 2.0.0: comments on the live site; it writes the content schemas Unbase reads, and its page list and content map reach a host adapter's copy of the output too), the draft-pages kit (@unbase-app/pages 0.5.0: draft pages kept out of production builds, and the redirects a moved page leaves applied) and the analytics beacon (@unbase-app/analytics 0.1.0) | | @unbase-app/cli | this one | devDependency: AGENTS.md and doctor, pinned |

In astro.config, found and changed through its syntax tree, never by text substitution:

import unbase from "@unbase-app/astro";
import commentModusConfig from "./comment-modus.json";
// …
integrations: [
  // …the site's own
  unbase({ project: commentModusConfig.project, layerUrl: "https://layer.unbase.app/v1/loader.js", edit: true }),
],

unbase() adds comment mode and the kit after every other integration itself, so the kit runs last wherever the line stands. Its options are comment mode's own; --no-comments writes unbase({ comments: false }), and init --comments later turns it on in the same line.

A config it cannot change with certainty (CommonJS, no export default, integrations that is not an array literal, a spread that may hold it) stops the run with the file named and nothing changed. A package that is already there at an older version is moved up to the pinned one, so running init again is also how a site updates; a newer one is kept and reported, never moved down. A second run changes nothing. It touches no content.

Vite + React

One package, @unbase-app/vite (a devDependency, beside vite), at 0.3.0: the draft-pages kit, the analytics beacon and comment mode's loader in one Vite plugin. In vite.config, through its syntax tree (Lovable's defineConfig(({ mode }) => ({ … })) and plugins: [ … ].filter(Boolean) included):

import { unbase } from "@unbase-app/vite";
// …
plugins: [react(), mode === "development" && componentTagger(), unbase()].filter(Boolean),

--no-comments writes unbase({ comments: false }); init --comments later takes that option out again. A config with the kit's own Vite plugin (unbasePages() from @jens4m/unbase-pages/vite) gets unbase() in its place. The plugin reads comment-modus.json itself, so the config does not import it. A Vite app keeps its site settings in index.html, which Unbase reads and writes as it is; it has no page settings, so nothing is written for them.

Next.js

On a Next.js site init adds @unbase-app/next (0.3.0) and wraps the config next.config hands Next.js in withUnbase(…) (through its syntax tree; a CommonJS config gets the require), writes comment-modus.json, and on a Next.js from 15.3 to 16.2 imports the comments' loader in instrumentation-client.ts (from 16.3 withUnbase injects it). doctor builds with next build into the site's own .next and reads it; page settings need nothing installed (each page's export const metadata), so it lists which pages Unbase can set and why not the others. uninstall takes it all out and compares the prerendered pages, with Next.js's scripts and hashed asset names left out. The steps: agents/next.md.

Analytics

The beacon comes with the framework's package, on by default (@unbase-app/analytics): every page of a production build sends a pageview to Unbase once the site is linked, never in a dev server. analytics: false in the package's call (unbase({ … }), withUnbase(nextConfig, { … })) leaves it out; init never writes that, and keeps it when a site has it.

What init adds for it is the collector's origin, https://unbase.app, in connect-src wherever the site sets a Content-Security-Policy it can edit safely: vercel.json's headers and public/_headers (Netlify, Cloudflare Pages), each value changed in place and the rest of the file as it was; with no connect-src, one made of default-src's sources and the origin. A CSP set anywhere else (next.config's headers(), a middleware, a <meta http-equiv>, netlify.toml, Astro's csp option) is named in next and csp.elsewhere, never edited. uninstall takes the origin out of the two files again, to the letter. The reading and the editing are Unbase's own (lib/readers.mjs, csp), the same code read_install uses for its Analytics row.

On Astro and Vite the package reads comment-modus.json itself, so --no-comments still writes it for analytics, and --project links analytics alone. On Next.js the beacon comes with the comments' client module: one link for both, and --no-comments leaves both out.

Linking

comment mode and analytics need the site's Unbase project, which a site added before Unbase knows it does not have yet. So init writes comment-modus.json with "project": null, and the config only turns comment mode (and analytics) on once that file names the project: until then the site builds and renders as before. Unbase fills the value in when the site is connected (one JSON value, never a change to the config), or init --project <id> does. comment-modus.json is the same file comment-modus's own CLI reads.

A config that sets comment mode up itself, with its own project (a site that had comment mode before init existed), keeps it: init --project with that same project changes nothing there and writes no comment-modus.json; another project is refused, to be changed in the config by a person.

Moving from before 03-11

A site installed before 03-11-2026 has the pair, @jens4m/comment-modus and @jens4m/unbase-pages with commentModus() and unbasePages() in its config, and the CLI as @unbase-app/cli. init moves it across, and it is how Unbase's Update does it:

  • @unbase-app/astro and @unbase-app/cli in; @jens4m/unbase-pages and @unbase-app/cli out (removed, with replacedBy, in --json): written to package.json together and installed in one run, so the unbase bin both CLIs have is the new one's. A failed install puts package.json back, and nothing else has changed yet.
  • unbase() takes commentModus()'s place with its options as they are (a site's own project, titles, language…); the commentModusConfig.project ? … : null init wrote around it goes, since unbase() waits for the project itself. unbasePages() and its import go.
  • Comment mode's own package goes too, under either name (@unbase-app/layer, or @jens4m/comment-modus before 2.0), unless the site uses it for itself: a name its config still imports from it, the package named in its code or a workflow, or the layer's CLI in a script. The layer then stays, moved to the version @unbase-app/astro brings, so there is one; @jens4m/comment-modus stays as it is, as the layer has no release under that name. Its CLI alone keeps neither: the layer answers to comment-modus too.
  • The pointer line moves to node_modules/@unbase-app/cli/AGENTS.md.
  • With --yes, a site keeps its choice of comments. A second run changes nothing.

doctor passes on a site from before as it is, and says the move is there (moved, info).

unbase doctor

Builds the site once (production, into a folder of its own), then reads it with Unbase's own readers, the code the Edge Functions run, bundled into this package. Per feature it gives a state and per check what is missing, the file, and the step in agents/astro.md that fixes it.

| Check state | | |---|---| | ok | Works | | missing | The site has to change. Fails the run | | waiting | Outside this repository: Unbase linking the project, or a package release. Named, does not fail the run | | info | Worth knowing | | skipped | Not checked (--no-build, or a build that failed) |

Features: Visual editing (Astro, the site builds), Comments on the site (the package, its line, the link, the markers, the loader), Page management (the kit, the drafts in unbase.pages.json, the kit running in a production build, the content schemas, the route files and the site settings and that the layout reads them), Analytics (the package at a version that brings it, not analytics: false, the link, before Next.js 16.3 the client module's import, and the CSP of vercel.json and public/_headers allowing https://unbase.app; a CSP set elsewhere is named as info). --no-build skips the build and what needs it.

The markers are comment mode's data-c: a pin on the live site takes its title and source file from them, so with comments they belong in the production build. A site without comment mode, or whose unbase() says componentMarker: "preview" (comment-modus 1.9.0: markers in the dev server and previews only) or false, must have none there; doctor fails when it does, and names an older comment-modus that ignores "preview".

unbase uninstall

Refuses while unbase.pages.json holds a draft, and lists them: without the kit a draft is built and goes live, so each is published or deleted in Unbase first. It refuses too while the file sends old addresses on (redirects, left by renaming or deleting a live page), and lists them: only the package applies them, so they go into the site's own redirects first. Then it builds the site, removes the packages, their lines in astro.config, comment-modus.json, unbase.pages.json, src/content/.schemas/, the collector in the CSP of vercel.json and public/_headers, and the pointer line, builds again, and compares every page's HTML. Taken out first: comment mode's markers and loader, the analytics beacon, and what differs between any two builds (asset hashes, Astro's ids, white space, attribute order). When pages still differ it builds the after state once more, and what differs between those two builds (an id a component makes at random on every render) is noise, not a change. "No differences in the built pages" is the pass. --yes without a terminal; --no-build skips the comparison; --no-install writes package.json only.

The route files, the settings file and the layout's reads stay: they are the site's own code.

unbase page

Makes, renames, moves, duplicates and deletes a page by the kit's own rule (planPage in @unbase-app/pages's core, bundled here), so the files change exactly as they do when Unbase's editor does it: the same files always give the same changes. It writes them in the working tree and commits nothing; review them with git diff and commit them yourself. A page's name and its address are apart: rename changes the name, move the address.

npx @unbase-app/cli page create /prijzen --name Prijzen
npx @unbase-app/cli page rename /funding --name Financiering
npx @unbase-app/cli page move /funding /financiering
npx @unbase-app/cli page duplicate /pricing /pricing-2027
npx @unbase-app/cli page delete /old-offer --redirect /pricing
npx @unbase-app/cli page list

| Command | | |---|---| | page create <address> [--name <name>] | A new page in the site's layout, with a heading of its name, made the way the site makes its pages (a file on Astro and Next.js, a route and its file on React Router, a file from the home page's shell on plain HTML); a draft where the kit is installed. The name defaults to the address's last part in words | | page rename <path> --name <name> | Its name in Unbase only (unbase.pages.json); the address stays | | page move <from> <to> [--not-live] | A new address: the page's files move (on Next.js its folder, on React Router the route's path, on plain HTML the file), every link to it or below it in code and content follows (code samples in text are left alone), its route file's pad too, and the pages under it come along | | page rename <from> <to> [--name <name>] [--not-live] | Both at once, as before move existed | | page duplicate <path> [<to>] [--name <name>] | A copy, by default at the first free <path>-copy, with its own copy of what only the page owns (its modules and content); a draft where the kit is installed. Named "… (copy)" when the original has a name | | page delete <path> [--redirect <to> \| --not-found] [--not-live] | Its file and what only it owns; shared parts stay. The links to it are listed, not changed. Visitors to the old address go to the page above it, --redirect's page, or with --not-found nowhere | | page list [--not-live] | Per page: whether it can be renamed, duplicated and deleted here, and if not, why |

Every one takes --dry-run (print the changes, write nothing), --json and --dir.

Live pages. A page counts as live unless --not-live says it was never on the live site. A live page renamed or deleted leaves a redirect in unbase.pages.json (old address → new), which the framework's package applies at build from @unbase-app/astro 0.3.0, @unbase-app/vite 0.3.0 and @unbase-app/next 0.3.0 on (@unbase-app/pages 0.4.0). On a site with an older one, or none, a live rename or delete is refused (no_redirects) instead of breaking the old address: run unbase init to update, or pass --not-live for a page that never was live.

Refusals exit 1 with the reason and what it means (--json: reason, detail, message):

| Reason | | |---|---| | home | Home can be duplicated, not renamed or deleted | | nested | Delete: pages are under it; delete those first | | taken | The new address is a page already, or the site's own redirects send it on | | address | Not an address the page can have (plain segments, not under itself), or --redirect is not a page | | no_redirects | A live page leaves a redirect, and this site's build does not apply them (above) | | content_bound | Duplicate: its content is a collection of its own, and a copy needs code the kit does not write. Unbase's Operator can do it | | content_unregistered | It reads content by a name no content file goes by | | template | The page is made by a dynamic route: change it where its data is | | unparsed | The kit cannot trace the page's route to its file | | missing | The code makes no page at this address | | same | Nothing to change | | invalid | unbase.pages.json is not valid | | framework | Not Astro, Next.js or Vite + React Router |

For programs

  • Never asks without a terminal. A choice without its flag is an error (exit 2) naming the flags; --json never asks.
  • --json on every command. init: packages (name, the pinned version, dev, and action: added, updated with from and to, or kept, with a note when the one there is newer) and files (file, created, changed or removed, and the changes; the lockfile too when the package manager ran); analytics (on, unless the config says analytics: false) and csp (files it allowed the collector in, invalid ones it could not read, and elsewhere: each { file, why } that may set a CSP it does not edit). doctor: features, each with state (on, off, waiting, not-installed) and checks (id, state, message, and for a missing or waiting check missing, file, step). uninstall: files (every file it touched, the lockfile included), packages, comparison (pages, differences, secondBuild), or refused: "drafts" with drafts, or refused: "redirects" with redirects. page: files (each path and action: created, changed, moved or copied with from, or deleted), links (files whose links it rewrote), unlinked (files that still name the old address), redirects (what changed in unbase.pages.json: source → destination, null for one that went), moves (the addresses), dryRun; refused: reason, detail, message. page list: pages, each with rename, duplicate and delete as { ok } or { ok: false, reason }, and redirects (whether the site's build applies them). An error: { ok: false, exitCode: 2, error: { code, message, file? } }.
  • Exit codes: 0 passed, 1 failed (doctor found something missing; uninstall refused or found a difference; a page action refused), 2 could not run (usage, no Astro site, a config it cannot edit safely, an install that failed).
  • No login, no project, no network beyond the package manager's install: it never calls Unbase, and the versions are pinned.

Developing

Part of the kit (kit/ in Unbase's repository; see its README): npm test there runs every package's tests. lib/readers.mjs is generated from the Edge Functions' readers (detect.ts, settings.ts, pages.ts, the kit's core), which live in Unbase's repository: after changing one of them, node kit/cli/scripts/readers.mjs; the tests fail there while it is out of date. In the kit on its own the file ships as it was generated.

MIT licence.