From df73965b74980b3eecfd787bd972689884addbe2 Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Mon, 15 Jun 2026 03:53:20 +0100 Subject: [PATCH 1/6] docs: Update upgrade guide to 4.0 --- docs/11-upgrading/01-upgrade-to-three-five.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index 04b73831..4a15817b 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -1,13 +1,13 @@ --- -title: Upgrade to 3.5 -description: Upgrade your Serverpod 3.4 project to 3.5 (Jetstream) by adopting serverpod start, the embedded Postgres option, and the new agent skills. +title: Upgrade to 4.0 +description: Upgrade your Serverpod 3.4 project to 4.0 (Jetstream) by adopting serverpod start, the embedded Postgres option, and the new agent skills. --- -# Upgrade to 3.5 +# Upgrade to 4.0 -Serverpod 3.5 (Jetstream) brings a unified `serverpod start` command with hot reload that runs your server, database, and Flutter app together. The release also includes an embedded Postgres option and optional AI agent skills for your editor. The changes are mostly opt-in: your existing 3.4 project keeps working with small updates. +Serverpod 4.0 (Jetstream) brings a unified `serverpod start` command with hot reload that runs your server, database, and Flutter app together. The release also includes an embedded Postgres option and optional AI agent skills for your editor. The changes are mostly opt-in: your existing 3.4 project keeps working with small updates. This guide walks through the upgrade and should take about 15 minutes. @@ -19,10 +19,10 @@ This guide walks through the upgrade and should take about 15 minutes. ## Update the Serverpod CLI -Install the 3.5 CLI: +Install the 4.0 CLI: ```bash -$ dart install serverpod_cli 3.5.0-beta.9 +$ dart install serverpod_cli 4.0.0 ``` Verify the version: @@ -33,16 +33,16 @@ $ serverpod version ## Update your project dependencies -In each package's `pubspec.yaml` (`_server`, `_client`, `_flutter`), bump the Serverpod packages to 3.5. Serverpod prefers an exact version pin over a caret range to keep the CLI and the packages in sync: +In each package's `pubspec.yaml` (`_server`, `_client`, `_flutter`), bump the Serverpod packages to 4.0. Serverpod prefers an exact version pin over a caret range to keep the CLI and the packages in sync: ```yaml dependencies: - serverpod: 3.5.0-beta.9 - serverpod_client: 3.5.0-beta.9 # in the client and Flutter packages - serverpod_flutter: 3.5.0-beta.9 # in the Flutter package + serverpod: 4.0.0 + serverpod_client: 4.0.0 # in the client and Flutter packages + serverpod_flutter: 4.0.0 # in the Flutter package ``` -Also bump the Dart SDK constraint in the root `pubspec.yaml` and `_server/pubspec.yaml` to match the 3.5 minimum: +Also bump the Dart SDK constraint in the root `pubspec.yaml` and `_server/pubspec.yaml` to match the 4.0 minimum: ```yaml environment: @@ -63,19 +63,19 @@ Then refresh the generated server and client code: $ serverpod generate ``` -## Generate the 3.5 migration +## Generate the 4.0 migration -Version 3.5 adds a few new internal Serverpod tables and updates some indexes to greatly improve logs performance on Insights. Create a migration that captures these schema deltas so your database can be brought up to date: +Version 4.0 adds a few new internal Serverpod tables and updates some indexes to greatly improve logs performance on Insights. Create a migration that captures these schema deltas so your database can be brought up to date: ```bash -$ serverpod create-migration --tag "upgrade-3.5" +$ serverpod create-migration --tag "upgrade-4.0" ``` This writes a new migration to `_server/migrations/`. It will be applied to your database in the next step. ## Adopt the new development workflow -Version 3.5 introduces a faster, integrated development workflow. The new `serverpod start` command runs your server, your Flutter app, and (optionally) your database in a single watch process with hot reload, replacing the manual `docker compose up` + `dart bin/main.dart` + `flutter run` triad. The result is a tighter edit-save-see-result loop and built-in tooling for migrations, hot restart, and agent skills. +Version 4.0 introduces a faster, integrated development workflow. The new `serverpod start` command runs your server, your Flutter app, and (optionally) your database in a single watch process with hot reload, replacing the manual `docker compose up` + `dart bin/main.dart` + `flutter run` triad. The result is a tighter edit-save-see-result loop and built-in tooling for migrations, hot restart, and agent skills. Before running it, choose how to handle the database. @@ -95,7 +95,7 @@ With `--docker`, `serverpod start` brings up Docker if it isn't running, and tea #### Switch to the embedded Postgres (recommended for new development) -Version 3.5 ships a built-in Postgres that runs as a child process of your Dart server, using the same Postgres dialect as production. It has practical advantages over Docker for day-to-day development: +Version 4.0 ships a built-in Postgres that runs as a child process of your Dart server, using the same Postgres dialect as production. It has practical advantages over Docker for day-to-day development: **Pros:** @@ -139,11 +139,11 @@ If you've added `dataPath` to your config and also pass `--docker`, the server c The first run compiles the native build hooks (this can take about 30 seconds) and applies the migration you generated above. The server then starts and watches your project; saving a file hot-reloads the code. -Beyond the server, `serverpod start` also launches the project's Flutter app. By default it uses Flutter's `web-server` device and opens your browser. Pass `--flutter-device ` to target a specific device. For IDE debugging, projects scaffolded with 3.5 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 3.5 scaffold if you want the same setup. +Beyond the server, `serverpod start` also launches the project's Flutter app. By default it uses Flutter's `web-server` device and opens your browser. Pass `--flutter-device ` to target a specific device. For IDE debugging, projects scaffolded with 4.0 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 4.0 scaffold if you want the same setup. ## Add the agent skills (optional) -Version 3.5 ships AI agent skills (for editors like Claude Code and Cursor) and an MCP server. Install them with: +Version 4.0 ships AI agent skills (for editors like Claude Code and Cursor) and an MCP server. Install them with: ```bash $ dart install skills @@ -159,11 +159,11 @@ Replace `cursor` with the editor you use: `antigravity`, `claude`, `cline`, `cod ## Production deployment notes -Your production build needs to switch from `dart compile exe` to `dart build cli`. The 3.5 server includes native build hooks that `dart compile` doesn't support, and produces a bundle (executable plus its native libraries) rather than a single static binary, so your Dockerfile needs a few updates. +Your production build needs to switch from `dart compile exe` to `dart build cli`. The 4.0 server includes native build hooks that `dart compile` doesn't support, and produces a bundle (executable plus its native libraries) rather than a single static binary, so your Dockerfile needs a few updates. -Copy the updated Dockerfile from the [3.5 framework template](https://github.com/serverpod/serverpod/blob/main/templates/serverpod_templates/projectname_server/Dockerfile) or a fresh 3.5 project's `_server/Dockerfile`. The key changes vs. the 3.4 pattern: build from the project root (not the server directory), copy the bundle directory, update `ENTRYPOINT` to point at the bundled binary, and bump the Dart SDK base image to 3.10.x or newer. +Copy the updated Dockerfile from the [4.0 framework template](https://github.com/serverpod/serverpod/blob/main/templates/serverpod_templates/projectname_server/Dockerfile) or a fresh 4.0 project's `_server/Dockerfile`. The key changes vs. the 3.4 pattern: build from the project root (not the server directory), copy the bundle directory, update `ENTRYPOINT` to point at the bundled binary, and bump the Dart SDK base image to 3.10.x or newer. -## What's new in 3.5 +## What's new in 4.0 - **`serverpod start` TUI**: hot reload on save, **R** to hot restart, **M** to create a migration, **A** to apply migrations, **P** to apply a repair migration. - **Flutter app spawning** from `serverpod start` so the Flutter app runs alongside the server in the same TUI. @@ -196,4 +196,4 @@ If something here didn't go as expected, reach out on the [community page](../su ## Related - [Migrations](../concepts/database/migrations): how Serverpod's migration system works under the hood. -- [Build your first app](../get-started/creating-endpoints): the hands-on tour of the 3.5 workflow if you want to see `serverpod start` from scratch. +- [Build your first app](../get-started/creating-endpoints): the hands-on tour of the 4.0 workflow if you want to see `serverpod start` from scratch. From 4513d6e3e78c4570e7b47200302f181ee8102d70 Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Mon, 6 Jul 2026 16:54:05 +0100 Subject: [PATCH 2/6] Update docs/11-upgrading/01-upgrade-to-three-five.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/11-upgrading/01-upgrade-to-three-five.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index 4a15817b..d2bb932b 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -22,7 +22,7 @@ This guide walks through the upgrade and should take about 15 minutes. Install the 4.0 CLI: ```bash -$ dart install serverpod_cli 4.0.0 +$ dart install serverpod_cli 4.0.0-beta.0 ``` Verify the version: From 68f604acef65dcf0a5ad1c32a6077e10e299a01f Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Mon, 6 Jul 2026 16:54:11 +0100 Subject: [PATCH 3/6] Update docs/11-upgrading/01-upgrade-to-three-five.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/11-upgrading/01-upgrade-to-three-five.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index d2bb932b..ac95b680 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -37,9 +37,9 @@ In each package's `pubspec.yaml` (`_server`, `_client`, `_server/pubspec.yaml` to match the 4.0 minimum: From 17b2ab54351e0d64793fdb18f592fa9fa009de89 Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Mon, 6 Jul 2026 21:02:17 +0100 Subject: [PATCH 4/6] Update docs/11-upgrading/01-upgrade-to-three-five.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/11-upgrading/01-upgrade-to-three-five.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-three-five.md index ac95b680..d84d03cc 100644 --- a/docs/11-upgrading/01-upgrade-to-three-five.md +++ b/docs/11-upgrading/01-upgrade-to-three-five.md @@ -139,7 +139,7 @@ If you've added `dataPath` to your config and also pass `--docker`, the server c The first run compiles the native build hooks (this can take about 30 seconds) and applies the migration you generated above. The server then starts and watches your project; saving a file hot-reloads the code. -Beyond the server, `serverpod start` also launches the project's Flutter app. By default it uses Flutter's `web-server` device and opens your browser. Pass `--flutter-device ` to target a specific device. For IDE debugging, projects scaffolded with 4.0 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 4.0 scaffold if you want the same setup. +Beyond the server, `serverpod start` also launches the project's Flutter apps configured with `auto_launch: true`. For IDE debugging, projects scaffolded with 4.0 include a `launch.json` that runs `serverpod start` with the debugger attached; you can copy that file into your existing project from a fresh 4.0 scaffold if you want the same setup. ## Add the agent skills (optional) From 0fb274dcbe992767fdf3afd0417d5022c8f16a3e Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Mon, 6 Jul 2026 21:12:52 +0100 Subject: [PATCH 5/6] docs: rename 4.0 upgrade guide to upgrade-to-four and repoint links --- .../{01-upgrade-to-three-five.md => 01-upgrade-to-four.md} | 0 docs/11-upgrading/03-migrate-from-legacy-auth.md | 4 ++-- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/11-upgrading/{01-upgrade-to-three-five.md => 01-upgrade-to-four.md} (100%) diff --git a/docs/11-upgrading/01-upgrade-to-three-five.md b/docs/11-upgrading/01-upgrade-to-four.md similarity index 100% rename from docs/11-upgrading/01-upgrade-to-three-five.md rename to docs/11-upgrading/01-upgrade-to-four.md diff --git a/docs/11-upgrading/03-migrate-from-legacy-auth.md b/docs/11-upgrading/03-migrate-from-legacy-auth.md index 5aab1492..28a3e820 100644 --- a/docs/11-upgrading/03-migrate-from-legacy-auth.md +++ b/docs/11-upgrading/03-migrate-from-legacy-auth.md @@ -9,7 +9,7 @@ This guide is for apps still running `serverpod_auth_server` on Serverpod 3.4 or ## Before you start -- A Serverpod 3.5.x project. If you are still on 3.4 or earlier, follow [Upgrade to 3.5](./upgrade-to-three-five) first. +- A Serverpod 3.5.x project. If you are still on 3.4 or earlier, follow [Upgrade to 4.0](./upgrade-to-four) first. - Dart SDK 3.8.0 or later. - Flutter SDK 3.32.0 or later (only if you are migrating the Flutter app). - Postgres 14 or later, or SQLite3. @@ -294,6 +294,6 @@ Reach out on the [community page](../support). ## Related -- [Upgrade to 3.5](./upgrade-to-three-five): do this first. +- [Upgrade to 4.0](./upgrade-to-four): do this first. - [Authentication setup](../concepts/authentication/setup): modular configuration reference. - [Database migrations](../concepts/database/migrations): creating and applying schema changes safely. From 376753becdff1365ba783e46ea8a1cd5e32ec2ed Mon Sep 17 00:00:00 2001 From: Chiziaruhoma Ogbonda Date: Mon, 6 Jul 2026 21:29:43 +0100 Subject: [PATCH 6/6] docs: lead upgrade guide description with the topic noun --- docs/11-upgrading/01-upgrade-to-four.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index d84d03cc..936a50f2 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -1,6 +1,6 @@ --- title: Upgrade to 4.0 -description: Upgrade your Serverpod 3.4 project to 4.0 (Jetstream) by adopting serverpod start, the embedded Postgres option, and the new agent skills. +description: Upgrading a Serverpod 3.4 project to 4.0 (Jetstream) brings serverpod start, the embedded Postgres option, and the new agent skills. ---