# Upgrading to Forgekit 3

> What changed in 3.0, why we dropped forge.json, and how to upgrade a project in about ten minutes.

- URL: https://devtool-changelog-example.notra.site/blog/upgrading-to-forgekit-3
- Published: 2026-09-30
- Authors: Ines Varga
- Tags: release, guides

Forgekit 3.0 is out. It’s the first major release in a year, and most projects upgrade with one command.

## Why one config file

Forgekit 2 read settings from `forge.json` and from `forge.config.ts`, and merged them. That merge caused a third of the config bugs filed this year. Two files that can disagree is one too many, so 3.0 reads only `forge.config.ts`.

## Upgrade in four steps

1. Check your Node version

   Run `node --version`. You need 20.11 or later. Bun 1.2 works too.

2. Run the migration

   `npx forgekit@3 migrate` rewrites `forge.json` into `forge.config.ts` and deletes the old file. In a monorepo, add `--workspace`.

3. Rename roles to groups

   The migration renames `ctx.user.roles` for you. Search for `roles` once more in code it can’t see, like shared helpers outside the tool folder.

4. Deploy a preview

   `forge deploy --preview` and click through your most used tools before you promote it.

## Before and after

The old `forge.json`:

```json
{
  "name": "ops-tools",
  "auth": { "provider": "okta", "roles": ["support", "finance"] }
}
```

The same settings in `forge.config.ts`:

```typescript
import { defineConfig } from "forgekit";

export default defineConfig({
  name: "ops-tools",
  auth: { provider: "okta", groups: ["support", "finance"] },
});
```

> **Note**
>
> Forgekit 2.5 keeps getting security fixes until March 2027. You don’t have to upgrade this week.
