Upgrading to Forgekit 3
What changed in 3.0, why we dropped forge.json, and how to upgrade a project in about ten minutes.
On this page3 sections
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
Check your Node version
Run
node --version. You need 20.11 or later. Bun 1.2 works too.Run the migration
npx forgekit@3 migraterewritesforge.jsonintoforge.config.tsand deletes the old file. In a monorepo, add--workspace.Rename roles to groups
The migration renames
ctx.user.rolesfor you. Search forrolesonce more in code it can’t see, like shared helpers outside the tool folder.Deploy a preview
forge deploy --previewand click through your most used tools before you promote it.
Before and after
The old forge.json:
{
"name": "ops-tools",
"auth": { "provider": "okta", "roles": ["support", "finance"] }
}
The same settings in forge.config.ts:
import { defineConfig } from "forgekit";
export default defineConfig({
name: "ops-tools",
auth: { provider: "okta", groups: ["support", "finance"] },
});