@squirro/neo-ui

The neo-ui command-line tool for building custom dashboards on top of the Squirro Neo frontend. Scaffold a bundle, run a local dev server, and produce a production build, all from one CLI.

Install this package globally. It is a CLI, not a library. The npm install snippet shown at the top of this page on npmjs is the generic one. Use the command below.

npm install -g @squirro/neo-ui

Prerequisites

Before installing, make sure the following is in place.

1. Node.js 22.18 or later

node -v

If you need to install or upgrade, use the official installer or nvm.

2. A Squirro instance and refresh token

You need access to a running Squirro instance and a refresh token to authenticate API requests during development.

To get a refresh token:

1. Log in to your Squirro instance
2. Click your profile picture (top-right)
3. Go to My Account → API Access
4. Generate a User Token and copy it — you will paste it during neo-ui create bundle

Install

@squirro/neo-ui and @squirro/neo-core are published on the public npm registry. No registry configuration or token is required.

npm install -g @squirro/neo-ui

Verify:

neo-ui

You should see the CLI welcome message and a list of available commands.

Already have a bundle?

The core package was renamed from @squirro/nextgen-core to @squirro/neo-core in September 2026, and the CLI was renamed from nextgen to neo-ui before that. One command migrates a bundle across both renames, rewriting the dependency, every import and config reference, and refreshing the Claude skills:

neo-ui upgrade

Until it has run, neo-ui dev and neo-ui build stop with a message pointing at upgrade. See Migrating from nextgen for the details and the pre-flight steps for bundles that came from GitHub Packages.

Quick start

Get your first dashboard running in under 10 minutes.

1. Create a bundle

neo-ui create bundle

You will be prompted for:

| Prompt | What to enter | |--------|---------------| | Project name | Letters, digits, hyphens, underscores, dots | | Squirro API endpoint | Your instance URL, e.g. https://your-tenant.squirro.cloud | | Refresh token | The User Token from your Squirro profile | | Ports | Only asked when a default (bundle: 3001, proxy: 5555) is already in use |

The CLI then scaffolds the bundle, installs dependencies (including @squirro/neo-core and @squirro/neo-ui), and writes your credentials to .env.

Skipping the credential prompts

To scaffold non-interactively (in CI, or from a tool that already knows the instance and token), provide the credentials through the environment and the API endpoint / refresh token prompts are skipped:

SQUIRRO_API_URL=https://your-tenant.squirro.cloud SQUIRRO_TOKEN=<refresh-token> neo-ui create bundle my-bundle

Credentials are environment-only — there are no --api-url / --token flags, which keeps the refresh token out of process listings and shell history. The bundle name can still be given as a positional argument or via --name. When both credentials are set this way, they're verified once and — if verification fails — the scaffold continues with a warning instead of blocking on a retry prompt (so it stays non-interactive).

Missing values are prompted for only when a terminal (TTY) is attached. If a value is missing and there's no TTY to answer a prompt, create bundle fails fast with a clear message rather than hanging.

Exit codes (for scripts driving the CLI):

| Code | Meaning | |------|---------| | 0 | Bundle created; credentials verified (or entered/accepted interactively). | | 2 | Bundle created, but credentials supplied via the environment failed verification — the .env may be wrong. Refresh the token and re-run, or fix .env. Non-fatal: the bundle exists. | | 1 | Failed before completion (bad/missing args, missing credentials with no TTY, directory already exists, npm install failed, core package not found). The partially-created directory is cleaned up so a retry isn't blocked. |

2. Start the dev server

cd my-dashboards
neo-ui dev

Two servers start in parallel: the Neo host on http://localhost:5555 (the dev server handles authentication and proxies the API), and your bundle dev server on http://localhost:3001. Open http://localhost:5555 in your browser — authentication is handled automatically by the dev server.

3. Add a dashboard

In a second terminal, inside the bundle directory:

neo-ui create dashboard

You will be prompted for the dashboard name, route, and a Lucide icon (kebab-case). The CLI creates the component file, updates the manifest, and adds a dev route. Refresh your browser — the new dashboard appears in the sidebar.

4. Build for production

neo-ui build

Outputs optimized static files to dist/, including mf-manifest.json (the Module Federation manifest the host loads).

To ship it, run neo-ui deploy — it builds, runs a compatibility preflight, uploads the bundle to your Squirro instance, and sets the frontend.ui-bundle configuration for you. (You can also host the dist/ folder yourself and point frontend.ui-bundle at it manually.)

Commands

| Command | Description | |---------|-------------| | neo-ui create bundle | Scaffold a new bundle | | neo-ui create dashboard | Add a dashboard to a bundle (--name/--route/--icon/--groups for non-interactive use) | | neo-ui remove dashboard | Remove a dashboard (--route/--id/--name to select, --yes to skip confirmation) | | neo-ui dev | Start the local development environment (host + bundle); auto-resolves busy ports (--port, --proxy-port, --persist) | | neo-ui build | Preflight-check and build the bundle for production (--no-verify to skip checks locally) | | neo-ui deploy | Build, preflight, and upload the bundle to a Squirro instance | | neo-ui projects | List projects on the configured instance (--json for scripts) | | neo-ui upgrade | Upgrade the @squirro packages (--next for prereleases) | | neo-ui catalog | Serve the component catalog locally (the Storybook bundled with the installed core version) | | neo-ui doctor | Diagnose common bundle issues (--fix to auto-heal, --json for CI) | | neo-ui groups | List the instance user groups (name + id) for allowedGroups | | neo-ui config | Interactively edit .env (API credentials, ports) | | neo-ui info | Print a summary of the current bundle | | neo-ui translations init | Scaffold translation files for the bundle | | neo-ui translations keys | List translation keys available in the host | | neo-ui translations add-locale | Add a language beyond the four built-ins |

Run neo-ui with no arguments to see the full list, or neo-ui --version (short: -v) to print the installed CLI version. See the CLI reference for full details on every command.

What you can build

• Custom dashboards — full-page React components with access to Squirro data, shared UI components, and the active project context. Each dashboard appears automatically in the Neo sidebar.
• Translation overrides — customize any text in the core Neo UI (button labels, placeholders, headings) per language, without modifying host code.

Bundles cannot override built-in widgets, inject global CSS, or modify core application logic. If a use case requires changes to core features, that is a product request — not a bundle.

How it works

A bundle is a standard React/TypeScript project. It installs @squirro/neo-core as a library (build configuration, shared types, UI components) and is wired into the host at runtime via Module Federation.

When a user opens a Squirro project, the Neo host checks for a bundle configured via frontend.ui-bundle. If one is set, the host fetches the bundle's manifest, adds sidebar entries, creates dynamic routes, and lazy-loads each dashboard component on demand. No host redeploy is required to ship new dashboards.

Documentation

Full delivery documentation is published at docs.squirro.com:

• Overview
• Prerequisites
• Quick start
• Project structure
• CLI reference
• The bundle manifest
• Building dashboards
• Styling & components
• Squirro API
• Translations
• Local development
• Building & deploying
• Troubleshooting
• Roadmap
• Neo dev annotations

Related packages

| Package | What it provides | |---------|-----------------| | @squirro/neo-ui | The neo-ui CLI — scaffolding, dev server, build | | @squirro/neo-core | Types, configuration factory, shared UI components, and a typed Squirro API client |

Authentication in bundles

• The dev proxy authenticates every proxied request itself. Your .env token never appears in a browser-visible URL.
• Bundles must not read authentication tokens from cookies or browser storage. Use the SDK's authenticated fetch (useSquirroApi from @squirro/neo-core/api). neo-ui upgrade flags hand-rolled token access in your bundle and adds a migration note to CLAUDE.md.
• The .env token (SQUIRRO_TOKEN) is long-lived. Treat it as a secret: never commit it, and if it leaks, revoke it under My Account → API Access.

Security

Report suspected vulnerabilities in this package privately through your Squirro support contact or account manager, marked as security-sensitive. Do not open a public issue.