<!-- Source: https://docs.squirro.com/en/latest/technical/neo/dev-guide/migrating-from-nextgen.html -->
# Migrating from nextgen to neo-ui

> **Warning**
>
> Project Neo is currently in [Technical Preview](../../../a-z/squirro-glossary.md#term-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:

```bash
npm install -g @squirro/neo-ui
```

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

```bash
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.
>
>
>
> ```bash
> 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.

1. Preview the changes without writing anything:

   ```bash
   neo-ui upgrade --dry-run
   ```

   Add `--next` if your project tracks a pre-release line, meaning a version ending in `-next`:

   ```bash
   neo-ui upgrade --next --dry-run
   ```
2. Apply the upgrade:

   ```bash
   neo-ui upgrade          # Latest stable release
   neo-ui upgrade --next   # Latest pre-release
   ```
3. Rebuild to confirm the project compiles against the new version:

   ```bash
   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](cli-reference.md#neo-extensions-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.