From 7341fcc425ff8e44ce666da1a6f3c8a06931a7d7 Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 14 Aug 2026 11:56:45 +0200 Subject: [PATCH 1/5] docs: Render the Cloud Dart SDK versions from a data file --- cloud_docs/guides/dart-sdk-versions.json | 9 ++ cloud_docs/guides/dart-sdk-versions.mdx | 78 +++++++++ cloud_docs/reference/dart-sdk-versions.md | 179 --------------------- cloud_docs/reference/scloud-yaml-schema.md | 4 +- docusaurus.config.js | 7 +- 5 files changed, 94 insertions(+), 183 deletions(-) create mode 100644 cloud_docs/guides/dart-sdk-versions.json create mode 100644 cloud_docs/guides/dart-sdk-versions.mdx delete mode 100644 cloud_docs/reference/dart-sdk-versions.md diff --git a/cloud_docs/guides/dart-sdk-versions.json b/cloud_docs/guides/dart-sdk-versions.json new file mode 100644 index 00000000..c954cbde --- /dev/null +++ b/cloud_docs/guides/dart-sdk-versions.json @@ -0,0 +1,9 @@ +{ + "supportedVersions": [ + "3.8", + "3.9", + "3.10", + "3.11" + ], + "defaultVersion": "3.8" +} diff --git a/cloud_docs/guides/dart-sdk-versions.mdx b/cloud_docs/guides/dart-sdk-versions.mdx new file mode 100644 index 00000000..21defef5 --- /dev/null +++ b/cloud_docs/guides/dart-sdk-versions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 5 +sidebar_label: Select a Dart SDK version +slug: /guides/deployment/dart-sdk-versions +description: Which Dart SDK versions Serverpod Cloud supports, and how to select the version your deploy builds with using the --dart-version flag, scloud.yaml, .tool-versions, or your pubspec constraint. +--- + +import versionData from './dart-sdk-versions.json'; + +# Select a Dart SDK version + +Serverpod Cloud builds your server with one of a fixed set of Dart SDK versions. This page lists the supported versions and shows how to select the one your deploy uses. + +## Supported versions + + + +This list updates automatically when Serverpod Cloud rolls out support for a new Dart release. + +## How the version is selected + +`scloud deploy` reads the Dart SDK version from the first of these sources that sets one: + +1. The `--dart-version` flag. +2. The `dartSdk` field in `scloud.yaml`. +3. The `dart` entry in a `.tool-versions` file, in the project directory first and then the workspace root. +4. The `environment.sdk` constraint in `pubspec.yaml`. + +Every source accepts an exact version or a pub-style version constraint, such as `3.10`, `^3.9.0`, or `>=3.9.0 <4.0.0`. Serverpod Cloud builds with the highest supported version the constraint allows. If the constraint allows no supported version, the deploy fails with an error that lists the supported versions. + +When no source sets a version, your server builds with Dart {versionData.defaultVersion}. + +### Pass the flag + +```bash +# Deploy with a one-off Dart SDK version override +scloud deploy --dart-version 3.10 +``` + +### Set the version in scloud.yaml + +```yaml title="scloud.yaml" +project: + projectId: "my-app" + dartSdk: "3.10" +``` + +### Use your version manager's pin + +Version managers such as mise and asdf pin tool versions in a `.tool-versions` file. Serverpod Cloud reads the `dart` entry: + +```text title=".tool-versions" +dart 3.10.4 +``` + +### Use the pubspec constraint + +Without any of the sources above, the SDK constraint in your `pubspec.yaml` decides: + +```yaml title="pubspec.yaml" +environment: + sdk: ">=3.9.0 <4.0.0" +``` + +This example builds with the highest supported version, since the constraint allows all of them from 3.9 up. + +## Related documentation + +- [scloud.yaml schema](/cloud/reference/scloud-yaml-schema) - The `dartSdk` field and how scloud commands preserve it. +- [Deployments](/cloud/concepts/deployments) - Deploy operations, status checks, and package validation. +- [`scloud deploy`](/cloud/reference/cli/commands/deploy) - The deploy command and its flags. diff --git a/cloud_docs/reference/dart-sdk-versions.md b/cloud_docs/reference/dart-sdk-versions.md deleted file mode 100644 index 647875d8..00000000 --- a/cloud_docs/reference/dart-sdk-versions.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -sidebar_position: 1 -title: Dart SDK versions -description: Which Dart SDK versions Serverpod Cloud supports, how the SDK version is selected for your build, and how to pin a version in pubspec.yaml. ---- - -# Dart SDK versions - -Serverpod Cloud supports specific Dart SDK versions for building and deploying your applications. Understanding how SDK versions are determined and used is important for configuring your project correctly. - -## Supported Dart SDK versions - -Serverpod Cloud supports the following Dart SDK versions: - -- **3.8.x** -- **3.9.x** -- **3.10.x** - -The supported version range is `>=3.8.0 <3.11.0`. This means your project's SDK constraint must overlap with this range to be deployable. - -## How SDK version is determined - -The SDK version used for building your application is determined from your project's `pubspec.yaml` file. Serverpod Cloud reads the `environment.sdk` constraint from your `pubspec.yaml` and uses **the lowest allowed version** from that constraint that falls within the supported range. - -### Version selection logic - -1. Serverpod Cloud reads the `sdk` constraint from your `pubspec.yaml` -2. It validates that your constraint overlaps with the supported range (`>=3.8.0 <3.11.0`) -3. It selects the **lowest version** that satisfies both: - - Your project's SDK constraint - - The supported version range - -This ensures compatibility while using the most conservative version that meets your requirements. - -## Configuring your pubspec.yaml - -Your `pubspec.yaml` must include an `environment.sdk` constraint. Here are examples of valid configurations: - -### Example 1: Minimum version constraint - -```yaml -name: my_serverpod_app - -environment: - sdk: ">=3.8.0 <4.0.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.8.0** (the lowest version in the supported range) - -### Example 2: Specific minimum version - -```yaml -name: my_serverpod_app - -environment: - sdk: ">=3.9.0 <4.0.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.9.0** (the lowest version that satisfies your constraint) - -### Example 3: Version range - -```yaml -name: my_serverpod_app - -environment: - sdk: ">=3.9.0 <3.11.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.9.0** (the lowest version in your range) - -### Example 4: Caret constraint - -```yaml -name: my_serverpod_app - -environment: - sdk: "^3.10.0" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.10.0** (the lowest version that satisfies `^3.10.0`, which is `>=3.10.0 <4.0.0`) - -### Example 5: Exact version (not recommended) - -```yaml -name: my_serverpod_app - -environment: - sdk: "3.9.5" - -dependencies: - serverpod: ^2.9.0 -``` - -**Result:** Uses Dart SDK **3.9.5** (if available, otherwise the closest supported version) - -## Invalid SDK constraints - -The following constraints will cause deployment to fail: - -### Too old - -```yaml -environment: - sdk: ">=3.7.0 <4.0.0" # ❌ 3.7.0 is below the minimum supported version -``` - -### Too new - -```yaml -environment: - sdk: ">=3.11.0 <4.0.0" # ❌ 3.11.0 is above the maximum supported version -``` - -### No overlap - -```yaml -environment: - sdk: ">=3.0.0 <3.8.0" # ❌ No overlap with supported range (>=3.8.0 <3.11.0) -``` - -## Best practices - -1. **Use a range that includes supported versions**: Specify `>=3.8.0 <4.0.0` or a narrower range like `>=3.9.0 <3.11.0` to ensure compatibility - -2. **Be specific about minimum requirements**: If your code requires features from Dart 3.9, use `>=3.9.0` to ensure the correct version is used - -3. **Avoid overly restrictive constraints**: Using exact versions like `3.9.5` can cause issues if that specific patch version isn't available - -4. **Keep constraints up to date**: As Serverpod Cloud adds support for newer Dart versions, you can update your constraints accordingly - -## Troubleshooting - -### Deployment fails with "Unsupported SDK Version" - -If you see an error like: - -``` -Unsupported sdk version constraint in package my_app: >=3.7.0 <4.0.0 -``` - -Update your `pubspec.yaml` to use a supported SDK version: - -```yaml -environment: - sdk: ">=3.8.0 <4.0.0" -``` - -### Missing SDK constraint - -If you see an error like: - -``` -No sdk constraint found in package my_app -``` - -Add an `environment.sdk` field to your `pubspec.yaml`: - -```yaml -environment: - sdk: ">=3.8.0 <4.0.0" -``` - -## Related documentation - -- [Deployments](/cloud/concepts/deployments) - Deploy operations, status checks, package validation, and `.scloudignore` configuration. -- [Private dependencies](/cloud/reference/private-dependencies) for managing workspace dependencies. diff --git a/cloud_docs/reference/scloud-yaml-schema.md b/cloud_docs/reference/scloud-yaml-schema.md index 74dfa63a..52e38b2f 100644 --- a/cloud_docs/reference/scloud-yaml-schema.md +++ b/cloud_docs/reference/scloud-yaml-schema.md @@ -50,7 +50,7 @@ project: **Type:** string. **Optional.** -Pins the Dart SDK version used for builds. When unset, scloud reads `environment.sdk` from your `pubspec.yaml` and uses the lowest version in the supported range. See [Dart SDK versions](/cloud/reference/dart-sdk-versions) for the supported versions. +Pins the Dart SDK version used for builds. When unset, scloud falls back to your `.tool-versions` file and then the `environment.sdk` constraint in your `pubspec.yaml`. See [Select a Dart SDK version](/cloud/guides/deployment/dart-sdk-versions) for the supported versions and the full selection order. ```yaml title="scloud.yaml" project: @@ -172,6 +172,6 @@ The `pre_deploy` or `post_deploy` value is neither a string nor a list of string ## Related - [Project identifier rules](/cloud/reference/project-id-rules) -- [Dart SDK versions](/cloud/reference/dart-sdk-versions) +- [Select a Dart SDK version](/cloud/guides/deployment/dart-sdk-versions) - [Deployment hooks](/cloud/concepts/deployment-hooks) - [scloud project](/cloud/reference/cli/commands/project) diff --git a/docusaurus.config.js b/docusaurus.config.js index 70112c00..296905ab 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -258,8 +258,11 @@ const config = { to: '/cloud/reference/private-dependencies', }, { - from: ['/cloud/reference/deployment/dart-sdk-versions'], - to: '/cloud/reference/dart-sdk-versions', + from: [ + '/cloud/reference/deployment/dart-sdk-versions', + '/cloud/reference/dart-sdk-versions', + ], + to: '/cloud/guides/deployment/dart-sdk-versions', }, { from: ['/cloud/reference/project-id'], From 9890db4c8797f334fd4f67d8f370564f26bb8a3e Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 14 Aug 2026 12:11:07 +0200 Subject: [PATCH 2/5] ci: Auto-approve Dart version sync PRs --- .github/workflows/auto-approve-docs-sync.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/auto-approve-docs-sync.yml b/.github/workflows/auto-approve-docs-sync.yml index 178d4867..66fd93cf 100644 --- a/.github/workflows/auto-approve-docs-sync.yml +++ b/.github/workflows/auto-approve-docs-sync.yml @@ -16,10 +16,10 @@ jobs: runs-on: ubuntu-latest if: > github.event.pull_request.user.login == 'serverpod-cloud-docs-sync[bot]' && - contains(fromJSON('["auto/cli-docs-sync", "auto/framework-cli-docs-sync"]'), github.event.pull_request.head.ref) + contains(fromJSON('["auto/cli-docs-sync", "auto/framework-cli-docs-sync", "auto/dart-versions-sync"]'), github.event.pull_request.head.ref) steps: - name: Approve PR - run: gh pr review "$PR_URL" --approve --body 'Auto-approved CLI reference docs sync PR.' + run: gh pr review "$PR_URL" --approve --body 'Auto-approved docs sync PR.' env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_URL: ${{ github.event.pull_request.html_url }} From 9f9ccb9aa2d4437fd3f3de16a574de564f7b7cc2 Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 14 Aug 2026 12:46:50 +0200 Subject: [PATCH 3/5] docs: Drop the automatic update note from the Dart SDK versions page --- cloud_docs/guides/dart-sdk-versions.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/cloud_docs/guides/dart-sdk-versions.mdx b/cloud_docs/guides/dart-sdk-versions.mdx index 21defef5..27f57151 100644 --- a/cloud_docs/guides/dart-sdk-versions.mdx +++ b/cloud_docs/guides/dart-sdk-versions.mdx @@ -22,8 +22,6 @@ Serverpod Cloud builds your server with one of a fixed set of Dart SDK versions. ))} -This list updates automatically when Serverpod Cloud rolls out support for a new Dart release. - ## How the version is selected `scloud deploy` reads the Dart SDK version from the first of these sources that sets one: From 7f595825eaabbee39f53f8f991306d552137822c Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 14 Aug 2026 13:01:23 +0200 Subject: [PATCH 4/5] docs: Keep the Dart SDK versions page at its reference URL --- cloud_docs/{guides => reference}/dart-sdk-versions.json | 0 cloud_docs/{guides => reference}/dart-sdk-versions.mdx | 7 +++---- cloud_docs/reference/scloud-yaml-schema.md | 4 ++-- docusaurus.config.js | 7 ++----- 4 files changed, 7 insertions(+), 11 deletions(-) rename cloud_docs/{guides => reference}/dart-sdk-versions.json (100%) rename cloud_docs/{guides => reference}/dart-sdk-versions.mdx (94%) diff --git a/cloud_docs/guides/dart-sdk-versions.json b/cloud_docs/reference/dart-sdk-versions.json similarity index 100% rename from cloud_docs/guides/dart-sdk-versions.json rename to cloud_docs/reference/dart-sdk-versions.json diff --git a/cloud_docs/guides/dart-sdk-versions.mdx b/cloud_docs/reference/dart-sdk-versions.mdx similarity index 94% rename from cloud_docs/guides/dart-sdk-versions.mdx rename to cloud_docs/reference/dart-sdk-versions.mdx index 27f57151..ab73896a 100644 --- a/cloud_docs/guides/dart-sdk-versions.mdx +++ b/cloud_docs/reference/dart-sdk-versions.mdx @@ -1,13 +1,12 @@ --- -sidebar_position: 5 -sidebar_label: Select a Dart SDK version -slug: /guides/deployment/dart-sdk-versions +sidebar_position: 1 +title: Dart SDK versions description: Which Dart SDK versions Serverpod Cloud supports, and how to select the version your deploy builds with using the --dart-version flag, scloud.yaml, .tool-versions, or your pubspec constraint. --- import versionData from './dart-sdk-versions.json'; -# Select a Dart SDK version +# Dart SDK versions Serverpod Cloud builds your server with one of a fixed set of Dart SDK versions. This page lists the supported versions and shows how to select the one your deploy uses. diff --git a/cloud_docs/reference/scloud-yaml-schema.md b/cloud_docs/reference/scloud-yaml-schema.md index 52e38b2f..faa9c2d5 100644 --- a/cloud_docs/reference/scloud-yaml-schema.md +++ b/cloud_docs/reference/scloud-yaml-schema.md @@ -50,7 +50,7 @@ project: **Type:** string. **Optional.** -Pins the Dart SDK version used for builds. When unset, scloud falls back to your `.tool-versions` file and then the `environment.sdk` constraint in your `pubspec.yaml`. See [Select a Dart SDK version](/cloud/guides/deployment/dart-sdk-versions) for the supported versions and the full selection order. +Pins the Dart SDK version used for builds. When unset, scloud falls back to your `.tool-versions` file and then the `environment.sdk` constraint in your `pubspec.yaml`. See [Dart SDK versions](/cloud/reference/dart-sdk-versions) for the supported versions and the full selection order. ```yaml title="scloud.yaml" project: @@ -172,6 +172,6 @@ The `pre_deploy` or `post_deploy` value is neither a string nor a list of string ## Related - [Project identifier rules](/cloud/reference/project-id-rules) -- [Select a Dart SDK version](/cloud/guides/deployment/dart-sdk-versions) +- [Dart SDK versions](/cloud/reference/dart-sdk-versions) - [Deployment hooks](/cloud/concepts/deployment-hooks) - [scloud project](/cloud/reference/cli/commands/project) diff --git a/docusaurus.config.js b/docusaurus.config.js index 296905ab..70112c00 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -258,11 +258,8 @@ const config = { to: '/cloud/reference/private-dependencies', }, { - from: [ - '/cloud/reference/deployment/dart-sdk-versions', - '/cloud/reference/dart-sdk-versions', - ], - to: '/cloud/guides/deployment/dart-sdk-versions', + from: ['/cloud/reference/deployment/dart-sdk-versions'], + to: '/cloud/reference/dart-sdk-versions', }, { from: ['/cloud/reference/project-id'], From 7916c8248dd1c3c61bdd9ab021443cad92178d3c Mon Sep 17 00:00:00 2001 From: Isak Date: Fri, 14 Aug 2026 16:32:31 +0200 Subject: [PATCH 5/5] Update cloud_docs/reference/dart-sdk-versions.mdx Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- cloud_docs/reference/dart-sdk-versions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloud_docs/reference/dart-sdk-versions.mdx b/cloud_docs/reference/dart-sdk-versions.mdx index ab73896a..0d799b42 100644 --- a/cloud_docs/reference/dart-sdk-versions.mdx +++ b/cloud_docs/reference/dart-sdk-versions.mdx @@ -23,7 +23,7 @@ Serverpod Cloud builds your server with one of a fixed set of Dart SDK versions. ## How the version is selected -`scloud deploy` reads the Dart SDK version from the first of these sources that sets one: +The `scloud deploy` command reads the Dart SDK version from the first of these sources that sets one: 1. The `--dart-version` flag. 2. The `dartSdk` field in `scloud.yaml`.