serverpod/serverpod-upgrading
packages/serverpod/skills/serverpod-upgrading/SKILL.md
Upgrade Serverpod — minor/patch updates, major upgrade to v3. Use when upgrading Serverpod versions or updating dependencies.
$ install --global
skillsauthnpx skillsauth add serverpod/serverpod serverpod-upgradingInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 14, 2026, 4:53 AM290.9s1 file scanned
SKILL.md
- name:
- serverpod-upgrading
- description:
- Upgrade Serverpod — minor/patch updates, major upgrade to v3. Use when upgrading Serverpod versions or updating dependencies.
Serverpod minor/patch upgrade
Requirements: Dart 3.10.3+, Flutter 3.38.4+.
Use the same pinned Serverpod version across all packages. Use the CLI to do the upgrade. Ask the user to start the server with serverpod start after the upgrade. NEVER update the CLI tooling, instead STOP and ask the user to do it.
- Check the latest version of Serverpod: https://pub.dev/packages/serverpod (unless the user has requested a specific version).
- Run
serverpod versionto verify that the tooling has the correct version. If not, STOP and ask the user to install the correct version (dart install serverpod_clifor latest ordart install serverpod_cli 3.x.xfor specific version). - Update all Serverpod packages in all relevant package pubspec.yaml (server, client, flutter, shared).
- Run
dart pub upgradein all packages. - Run
serverpod generate. - Run
serverpod create-migration. - Run
dart analyzein the root of the project and address any issues. - Ensure that the Dockerfile uses at least
FROM dart:3.10.3 AS build. - Inform the user that the upgrade is complete and they should start the server with
serverpod start.
Major upgrade: Serverpod 2.x to 3.0
After following the regular upgrade process, ensure that the following breaking changes are addressed.
Breaking changes
Web server (Relic):
handleCall:HttpRequest→Request,Future<bool>→FutureOr<Result>, returnResponse.ok(...)instead of writing to responserequest.remoteIpAddress→request.remoteInfo;request.headers.value('name')→request.headers['name']- Widget renames:
AbstractWidget→WebWidget,Widget→TemplateWidget,WidgetList→ListWidget,WidgetJson→JsonWidget,WidgetRedirect→RedirectWidget RouteStaticDirectory(...)→StaticRoute.directory(Directory(...))withcacheControlFactory
Session.request: Optional request property on Session (null for non-HTTP sessions).
Enum serialization: Default now byName. Add serialized: byIndex in YAML to keep old behavior.
Models: SerializableEntity → SerializableModel. YAML: parent=table → relation(parent=table); database → scope=serverOnly; api → !persist.
Auth: session.authenticated is now synchronous. AuthenticationInfo.authId non-nullable, userIdentifier is String. Client: authenticationKeyManager → authKeyProvider. Custom handlers receive unwrapped Bearer token.
Deprecated: Legacy streaming endpoints; use streaming methods.
Related Skills
serverpod/serverpod-flutter-frontend
development
VerifiedTrustedCommunity
Build highly distinctive, production-ready Flutter interfaces with exceptional design fidelity. Include this skill whenever a user requests Flutter widgets, screens, or full apps.
3,192SKILL.mdUpdated Jun 4, 2026
serverpod/serverpod-auth
testing
VerifiedTrustedCommunity
Serverpod Authentication — Signing in users, verify if they are authenticated, assinging scopes (e.g., admin). Use when adding features that require the user to be signed in.
3,192SKILL.mdUpdated May 13, 2026
serverpod/serverpod-webserver
development
VerifiedTrustedCommunity
Serverpod web server (Relic) — REST APIs, webhooks, middleware, static files, server-rendered HTML, SPAs, Flutter web. Use when adding HTTP routes, serving web pages or web apps, intercepting requests, or working with the Relic web server.
3,187SKILL.mdUpdated Apr 15, 2026
serverpod/serverpod-overview
tools
VerifiedTrustedCommunity
Serverpod overview — what it is, project structure, how to work with. Always use at least once when working with projects that use Serverpod.
3,180SKILL.mdUpdated Apr 15, 2026