Migrating from nextgen to neo-ui

Migrating from nextgen to neo-ui#

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

The command-line tool for building Project Neo bundles was renamed from nextgen to neo-ui. The npm package changed from @squirro/nextgen-cli to @squirro/neo-ui, and the binary changed from nextgen to neo-ui. In September 2026 the library package followed: @squirro/nextgen-core became @squirro/neo-core.

The neo-ui upgrade command performs the migration for you, including the dependency and script renames. This page covers moving an existing bundle project.

What Changed#

Before	After
`@squirro/nextgen-cli` (development dependency)	`@squirro/neo-ui`
`nextgen` (binary)	`neo-ui`
`nextgen dev`, `nextgen build` (scripts)	`neo-ui dev`, `neo-ui build`
`@squirro/nextgen-core` (library, until September 2026)	`@squirro/neo-core`
`NEXTGEN_CORE_VERSION` (build-time define)	`NEO_CORE_VERSION`

Before You Start#

The migration is driven by the new CLI. The legacy nextgen binary has no upgrade command, so run the upgrade with neo-ui. Install it globally:

npm install -g @squirro/neo-ui

Alternatively, run it without installing, from inside the project:

npx @squirro/neo-ui upgrade

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

Important

Bundles scaffolded before the move to the public npm registry have a committed .npmrc containing @squirro:registry=https://npm.pkg.github.com, and your ~/.npmrc may carry the same line with a GitHub token. Remove both before running the upgrade. A scoped registry line takes precedence over every other registry setting, so with it in place the upgrade keeps resolving @squirro packages from GitHub Packages, reports that the project is already up to date, and breaks once that token expires.

rm .npmrc   # or delete the @squirro:registry line from it and from ~/.npmrc

neo-ui doctor reports the line, and neo-ui doctor --fix removes it from the project .npmrc. The GitHub token itself is no longer needed for anything. Revoke it.

Migrate an Existing Project#

Run the following steps from the project root.

Preview the changes without writing anything:
```
neo-ui upgrade --dry-run
```
Add --next if your project tracks a pre-release line, meaning a version ending in -next:
```
neo-ui upgrade --next --dry-run
```

Apply the upgrade:

neo-ui upgrade          # Latest stable release
neo-ui upgrade --next   # Latest pre-release

Rebuild to confirm the project compiles against the new version:
```
neo-ui build
```

What the Upgrade Changes#

neo-ui upgrade applies the following in a single run:

Pins @squirro/neo-core and @squirro/neo-ui in package.json to the target version, then runs npm install.
Renames a legacy @squirro/nextgen-cli dependency to @squirro/neo-ui, keeping its position in package.json.
Renames a pre-rename @squirro/nextgen-core dependency to @squirro/neo-core and rewrites every reference to it: imports and require calls, the CSS @import and @source lines, the extends entries in biome.json and tsconfig.json, rsbuild.config.ts, CLAUDE.md, and the NEXTGEN_CORE_VERSION define, which becomes NEO_CORE_VERSION. The Claude Code skills under .claude/skills/ are refreshed from the newly installed core package.
Rewrites package.json scripts that call the old nextgen binary so they call neo-ui instead. For example, nextgen dev becomes neo-ui dev.
Updates the nextgen skill markers in CLAUDE.md to their neo-ui equivalents.
Applies the extension to bundle rename across the bundle source and .env.
Adds src/env.d.ts when the project predates that file, so import.meta.env type-checks.

The migration is idempotent. Running it again on an already-migrated project reports no changes. If npm install fails, package.json is restored to its previous state.

Until the migration has run, neo-ui dev, neo-ui build, and neo-ui translations keys refuse to run in a bundle that has only @squirro/nextgen-core installed, so the two packages cannot be mixed by accident. neo-ui doctor reports the same condition and names the fix.

For the full command reference, see the CLI Reference page.

Troubleshooting#

The Old nextgen Command Has No upgrade Subcommand#

The migration logic ships only in the new CLI. Install @squirro/neo-ui globally, or run the upgrade through npx @squirro/neo-ui upgrade.

A Plain neo-ui upgrade Proposes a Downgrade#

The default upgrade targets the latest stable release. A project on a pre-release line, meaning a version ending in -next, can sit ahead of the latest stable release, so the command offers to downgrade. Pass --next to track the pre-release channel instead.