From 2992894ad01b2b6cead66ef46c1ad9f0a814e538 Mon Sep 17 00:00:00 2001 From: Brandon DeRosier Date: Wed, 4 Mar 2026 21:53:56 -0800 Subject: [PATCH 1/4] refactor: consolidate Flutter/Dart version numbers into shared constants Add a remark plugin that replaces %flutter_version% and %dart_version% placeholders in MDX files at build time. Version numbers are now defined once in src/consts.ts instead of being hardcoded across 6 files. --- astro.config.mjs | 4 +++ src/consts.ts | 4 +++ src/content/docs/code-push/ci/codemagic.mdx | 12 +++---- src/content/docs/code-push/ci/generic.mdx | 2 +- src/content/docs/code-push/release.mdx | 20 +++++------ .../flutter-sdk-deep-dive.mdx | 4 +-- .../how-to-install-flutter.mdx | 12 +++---- .../docs/getting-started/flutter-version.mdx | 2 +- src/plugins/replace-versions.ts | 33 +++++++++++++++++++ 9 files changed, 67 insertions(+), 26 deletions(-) create mode 100644 src/consts.ts create mode 100644 src/plugins/replace-versions.ts diff --git a/astro.config.mjs b/astro.config.mjs index 3f6d48fc..251bc082 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -11,12 +11,16 @@ import opengraphImages from 'astro-opengraph-images'; import { renderer } from './src/og/renderer.tsx'; import { readFileSync } from 'node:fs'; import starlightLlmsTxt from 'starlight-llms-txt'; +import { remarkReplaceVersions } from './src/plugins/replace-versions.ts'; const site = 'https://docs.shorebird.dev/'; // https://astro.build/config export default defineConfig({ site, + markdown: { + remarkPlugins: [remarkReplaceVersions], + }, vite: { plugins: [tailwindcss()], }, diff --git a/src/consts.ts b/src/consts.ts new file mode 100644 index 00000000..71616d6a --- /dev/null +++ b/src/consts.ts @@ -0,0 +1,4 @@ +export const versions = { + flutter: '3.41.4', + dart: '3.11.1', +}; diff --git a/src/content/docs/code-push/ci/codemagic.mdx b/src/content/docs/code-push/ci/codemagic.mdx index 6adddf8a..7524ce4d 100644 --- a/src/content/docs/code-push/ci/codemagic.mdx +++ b/src/content/docs/code-push/ci/codemagic.mdx @@ -78,12 +78,12 @@ As a preview, our finished `codemagic.yaml` file will look like this: definitions: environment: shared_env: &shared_env - flutter: 3.41.4 + flutter: %flutter_version% groups: - shorebird - play_store vars: - FLUTTER_VERSION: 3.41.4 + FLUTTER_VERSION: %flutter_version% scripts: - &shorebird_install name: Install Shorebird @@ -189,7 +189,7 @@ definitions: # Use &shared_env to allow us to reference this environment in other # parts of the file shared_env: &shared_env - flutter: 3.41.4 + flutter: %flutter_version% groups: # Add the shorebird group to make $SHOREBIRD_TOKEN available to # the Shorebird CLI. @@ -198,7 +198,7 @@ definitions: # available to the Google Play Publishing step. - play_store vars: - FLUTTER_VERSION: 3.41.4 + FLUTTER_VERSION: %flutter_version% scripts: # A step to install Shorebird and add it to the host machine's PATH - &shorebird_install @@ -358,7 +358,7 @@ locally. definitions: environment: shared_env: &shared_env - flutter: 3.41.4 + flutter: %flutter_version% groups: # Export the shorebird group to make $SHOREBIRD_TOKEN available to # the Shorebird CLI. @@ -370,7 +370,7 @@ definitions: # The bundle ID of this example app. # Replace this with your app's bundle id. BUNDLE_ID: dev.shorebird.codemagic-demo - FLUTTER_VERSION: 3.41.4 + FLUTTER_VERSION: %flutter_version% scripts: # Download the Shorebird CLI and add it to the PATH. - &shorebird_install diff --git a/src/content/docs/code-push/ci/generic.mdx b/src/content/docs/code-push/ci/generic.mdx index ed3b72b7..462b878c 100644 --- a/src/content/docs/code-push/ci/generic.mdx +++ b/src/content/docs/code-push/ci/generic.mdx @@ -97,7 +97,7 @@ change. If you'd like to pin your CI to a specific Flutter version you can do this by adding `--flutter-version` to your command, e.g. ``` -shorebird release ios --flutter-version=3.41.4 --dart-define=HERO=Mario -- --enable-impeller +shorebird release ios --flutter-version=%flutter_version% --dart-define=HERO=Mario -- --enable-impeller ``` ### Patching diff --git a/src/content/docs/code-push/release.mdx b/src/content/docs/code-push/release.mdx index 188f295a..c9e82ef2 100644 --- a/src/content/docs/code-push/release.mdx +++ b/src/content/docs/code-push/release.mdx @@ -94,7 +94,7 @@ To release with a different Flutter version, you can specify the version using the `--flutter-version` flag. ``` -shorebird release android --flutter-version 3.41.4 +shorebird release android --flutter-version %flutter_version% ``` @@ -166,7 +166,7 @@ To release with a different Flutter version, you can specify the version using the `--flutter-version` flag. ```sh -shorebird release ios --flutter-version 3.41.4 +shorebird release ios --flutter-version %flutter_version% ``` ### Signing issues @@ -233,7 +233,7 @@ Example output: ``` $ shorebird release linux ✓ Fetching apps (0.3s) -✓ Building app bundle with Flutter 3.41.4 (1e0e5760ee) (18.3s) +✓ Building app bundle with Flutter %flutter_version% (1e0e5760ee) (18.3s) ✓ Fetching releases (0.1s) 🚀 Ready to create a new release! @@ -241,7 +241,7 @@ $ shorebird release linux 📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd) đŸ“Ļ Release Version: 1.0.13+2 đŸ•šī¸ Platform: linux -đŸĻ Flutter Version: 3.41.4 (1e0e5760ee) +đŸĻ Flutter Version: %flutter_version% (1e0e5760ee) Would you like to continue? (y/N) Yes ✓ Fetching releases (0.1s) @@ -266,7 +266,7 @@ Example output: ``` $ shorebird release macos ✓ Fetching apps (0.3s) -✓ Building app bundle with Flutter 3.41.4 (1e0e5760ee) (18.3s) +✓ Building app bundle with Flutter %flutter_version% (1e0e5760ee) (18.3s) ✓ Fetching releases (0.1s) 🚀 Ready to create a new release! @@ -274,7 +274,7 @@ $ shorebird release macos 📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd) đŸ“Ļ Release Version: 1.0.13+2 đŸ•šī¸ Platform: macos -đŸĻ Flutter Version: 3.41.4 (1e0e5760ee) +đŸĻ Flutter Version: %flutter_version% (1e0e5760ee) Would you like to continue? (y/N) Yes ✓ Fetching releases (0.1s) @@ -323,7 +323,7 @@ To release with a different Flutter version, you can specify the version using the `--flutter-version` flag. ``` -shorebird release macos --flutter-version 3.41.4 +shorebird release macos --flutter-version %flutter_version% ``` @@ -339,7 +339,7 @@ Example output: ``` $ shorebird release windows ✓ Fetching apps (0.3s) -✓ Building Windows app with Flutter 3.41.4 (1e0e5760ee) (18.3s) +✓ Building Windows app with Flutter %flutter_version% (1e0e5760ee) (18.3s) ✓ Fetching releases (0.1s) 🚀 Ready to create a new release! @@ -347,7 +347,7 @@ $ shorebird release windows 📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd) đŸ“Ļ Release Version: 1.0.0+1 đŸ•šī¸ Platform: windows -đŸĻ Flutter Version: 3.41.4 (1e0e5760ee) +đŸĻ Flutter Version: %flutter_version% (1e0e5760ee) Would you like to continue? (y/N) Yes ✓ Fetching releases (0.1s) @@ -396,7 +396,7 @@ To release with a different Flutter version, you can specify the version using the `--flutter-version` flag. ``` -shorebird release windows --flutter-version 3.41.4 +shorebird release windows --flutter-version %flutter_version% ``` diff --git a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx index a593e36c..178718ff 100644 --- a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx +++ b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx @@ -323,8 +323,8 @@ modify Dart code (not native code, Flutter engine, or assets). ## Current best practices for Flutter development in 2026 -**Flutter 3.41.4** (March 2026) is the current stable release, bundled with -**Dart 3.11.1**. Key requirements now include Java 17 minimum for Android, iOS +**Flutter %flutter_version%** (March 2026) is the current stable release, bundled with +**Dart %dart_version%**. Key requirements now include Java 17 minimum for Android, iOS 13+ minimum, and Android 16KB page size support for Google Play compliance. Impeller is fully default across iOS and Android API 29+. diff --git a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx index 67d99bcb..33423712 100644 --- a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx +++ b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx @@ -82,7 +82,7 @@ Once downloaded, extract the zip to a development directory: ```bash mkdir -p ~/develop -unzip ~/Downloads/flutter_macos_arm64_3.41.4-stable.zip -d ~/develop/ +unzip ~/Downloads/flutter_macos_arm64_%flutter_version%-stable.zip -d ~/develop/ ``` For manual installs, add Flutter to your PATH. Since macOS defaults to **zsh** @@ -171,7 +171,7 @@ and extract it to a path without spaces or special characters (as a reminder, never use `C:\Program Files\`). A good choice is `%USERPROFILE%\develop\`: ```powershell -Expand-Archive -Path \$env:USERPROFILE\Downloads\flutter_windows_3.41.4-stable.zip -Destination \$env:USERPROFILE\develop\ +Expand-Archive -Path \$env:USERPROFILE\Downloads\flutter_windows_%flutter_version%-stable.zip -Destination \$env:USERPROFILE\develop\ ``` Next, to add Flutter to your path, configure PATH through **System Properties → @@ -220,7 +220,7 @@ If you want to install Flutter, manually, download the `.tar.xz` from the ```bash mkdir -p ~/develop -tar -xf ~/Downloads/flutter_linux_3.41.4-stable.tar.xz -C ~/develop/ +tar -xf ~/Downloads/flutter_linux_%flutter_version%-stable.tar.xz -C ~/develop/ ``` ```bash @@ -436,14 +436,14 @@ line is prefixed with one of three symbols: A fully healthy macOS output looks like: ``` -[✓] Flutter (Channel stable, 3.41.4, on macOS 26.2 25C56 darwin-arm64, locale +[✓] Flutter (Channel stable, %flutter_version%, on macOS 26.2 25C56 darwin-arm64, locale en-IN) [605ms] - â€ĸ Flutter version 3.41.4 on channel stable at + â€ĸ Flutter version %flutter_version% on channel stable at /Users//development/flutter â€ĸ Upstream repository https://github.com/flutter/flutter.git â€ĸ Framework revision 582a0e7c55 (5 days ago), 2026-02-12 17:12:32 -0800 â€ĸ Engine revision 3452d735bd - â€ĸ Dart version 3.11.1 + â€ĸ Dart version %dart_version% â€ĸ DevTools version 2.54.1 â€ĸ Feature flags: enable-web, enable-linux-desktop, enable-macos-desktop, enable-windows-desktop, enable-android, enable-ios, cli-animations, diff --git a/src/content/docs/getting-started/flutter-version.mdx b/src/content/docs/getting-started/flutter-version.mdx index e3daf622..d55499fe 100644 --- a/src/content/docs/getting-started/flutter-version.mdx +++ b/src/content/docs/getting-started/flutter-version.mdx @@ -48,7 +48,7 @@ to create a release with a different version of Flutter, you can use the `--flutter-version` option with the `shorebird release` command: ```sh -shorebird release android --flutter-version=3.41.4 +shorebird release android --flutter-version=%flutter_version% ``` Any patches created with this release will be built with the version of Flutter diff --git a/src/plugins/replace-versions.ts b/src/plugins/replace-versions.ts new file mode 100644 index 00000000..74559ac0 --- /dev/null +++ b/src/plugins/replace-versions.ts @@ -0,0 +1,33 @@ +import { versions } from '../consts'; +import type { Root, RootContent } from 'mdast'; + +const replacements: Record = { + '%flutter_version%': versions.flutter, + '%dart_version%': versions.dart, +}; + +const pattern = /%(?:flutter_version|dart_version)%/g; + +function replaceInString(value: string): string { + return value.replace(pattern, (match) => replacements[match] ?? match); +} + +function walk(node: Root | RootContent) { + if ('value' in node && typeof node.value === 'string') { + node.value = replaceInString(node.value); + } + if ('url' in node && typeof node.url === 'string') { + node.url = replaceInString(node.url); + } + if ('children' in node && Array.isArray(node.children)) { + for (const child of node.children) { + walk(child as RootContent); + } + } +} + +export function remarkReplaceVersions() { + return (tree: Root) => { + walk(tree); + }; +} From 62e48557ad1bfeb4a8319da858ffbaea8e6f5d16 Mon Sep 17 00:00:00 2001 From: Brandon DeRosier Date: Wed, 4 Mar 2026 21:55:20 -0800 Subject: [PATCH 2/4] style: fix prettier formatting in flutter-sdk-deep-dive.mdx --- .../docs/flutter-concepts/flutter-sdk-deep-dive.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx index 178718ff..d806e99e 100644 --- a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx +++ b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx @@ -323,10 +323,11 @@ modify Dart code (not native code, Flutter engine, or assets). ## Current best practices for Flutter development in 2026 -**Flutter %flutter_version%** (March 2026) is the current stable release, bundled with -**Dart %dart_version%**. Key requirements now include Java 17 minimum for Android, iOS -13+ minimum, and Android 16KB page size support for Google Play compliance. -Impeller is fully default across iOS and Android API 29+. +**Flutter %flutter_version%** (March 2026) is the current stable release, +bundled with **Dart %dart_version%**. Key requirements now include Java 17 +minimum for Android, iOS 13+ minimum, and Android 16KB page size support for +Google Play compliance. Impeller is fully default across iOS and Android API +29+. For static analysis, configure `analysis_options.yaml` to include `package:flutter_lints/flutter.yaml` and enable strict mode: From 7a1745de3f2deca387ef58a46471d22ac094f7a6 Mon Sep 17 00:00:00 2001 From: Brandon DeRosier Date: Wed, 4 Mar 2026 22:20:05 -0800 Subject: [PATCH 3/4] refactor: add flutter_release_date shared constant Also replaces the stale partial versions (3.41, 3.11) in how-to-install-flutter.mdx with the shared placeholders. --- src/consts.ts | 1 + .../docs/flutter-concepts/flutter-sdk-deep-dive.mdx | 6 +++--- .../docs/flutter-concepts/how-to-install-flutter.mdx | 11 ++++++----- src/plugins/replace-versions.ts | 3 ++- 4 files changed, 12 insertions(+), 9 deletions(-) diff --git a/src/consts.ts b/src/consts.ts index 71616d6a..25567df1 100644 --- a/src/consts.ts +++ b/src/consts.ts @@ -1,4 +1,5 @@ export const versions = { flutter: '3.41.4', dart: '3.11.1', + flutter_release_date: 'March 2026', }; diff --git a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx index d806e99e..01eaf7b8 100644 --- a/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx +++ b/src/content/docs/flutter-concepts/flutter-sdk-deep-dive.mdx @@ -323,9 +323,9 @@ modify Dart code (not native code, Flutter engine, or assets). ## Current best practices for Flutter development in 2026 -**Flutter %flutter_version%** (March 2026) is the current stable release, -bundled with **Dart %dart_version%**. Key requirements now include Java 17 -minimum for Android, iOS 13+ minimum, and Android 16KB page size support for +**Flutter %flutter_version%** (%flutter_release_date%) is the current stable +release, bundled with **Dart %dart_version%**. Key requirements now include Java +17 minimum for Android, iOS 13+ minimum, and Android 16KB page size support for Google Play compliance. Impeller is fully default across iOS and Android API 29+. diff --git a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx index 33423712..0aae7723 100644 --- a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx +++ b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx @@ -5,11 +5,12 @@ sidebar: order: 4 --- -Flutter 3.41 is the latest stable release as of February 2026, bundled with Dart -3.11, and installing it correctly from day one, alongside -[Shorebird](https://shorebird.dev/) for over-the-air updates, eliminates the -most common developer pain points, such as broken PATH variables, missing -Android SDK command-line tools, and CocoaPods failures on Apple Silicon. +Flutter %flutter_version% is the latest stable release as of +%flutter_release_date%, bundled with Dart %dart_version%, and installing it +correctly from day one, alongside [Shorebird](https://shorebird.dev/) for +over-the-air updates, eliminates the most common developer pain points, such as +broken PATH variables, missing Android SDK command-line tools, and CocoaPods +failures on Apple Silicon. This guide covers exact commands and configuration for macOS, Windows, and Linux, prioritizing the professional workflow used in production teams. macOS diff --git a/src/plugins/replace-versions.ts b/src/plugins/replace-versions.ts index 74559ac0..dff57fdc 100644 --- a/src/plugins/replace-versions.ts +++ b/src/plugins/replace-versions.ts @@ -4,9 +4,10 @@ import type { Root, RootContent } from 'mdast'; const replacements: Record = { '%flutter_version%': versions.flutter, '%dart_version%': versions.dart, + '%flutter_release_date%': versions.flutter_release_date, }; -const pattern = /%(?:flutter_version|dart_version)%/g; +const pattern = /%(?:flutter_version|dart_version|flutter_release_date)%/g; function replaceInString(value: string): string { return value.replace(pattern, (match) => replacements[match] ?? match); From 33079742e52c4ef4a1840da78b43bafb18687db7 Mon Sep 17 00:00:00 2001 From: Brandon DeRosier Date: Wed, 4 Mar 2026 22:22:02 -0800 Subject: [PATCH 4/4] refactor: revert placeholders in example terminal output Example outputs contain commit hashes and dates that aren't updated, so the version numbers in those blocks should stay hardcoded too. --- src/content/docs/code-push/release.mdx | 12 ++++++------ .../docs/flutter-concepts/how-to-install-flutter.mdx | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/docs/code-push/release.mdx b/src/content/docs/code-push/release.mdx index c9e82ef2..1ab7b227 100644 --- a/src/content/docs/code-push/release.mdx +++ b/src/content/docs/code-push/release.mdx @@ -233,7 +233,7 @@ Example output: ``` $ shorebird release linux ✓ Fetching apps (0.3s) -✓ Building app bundle with Flutter %flutter_version% (1e0e5760ee) (18.3s) +✓ Building app bundle with Flutter 3.41.4 (1e0e5760ee) (18.3s) ✓ Fetching releases (0.1s) 🚀 Ready to create a new release! @@ -241,7 +241,7 @@ $ shorebird release linux 📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd) đŸ“Ļ Release Version: 1.0.13+2 đŸ•šī¸ Platform: linux -đŸĻ Flutter Version: %flutter_version% (1e0e5760ee) +đŸĻ Flutter Version: 3.41.4 (1e0e5760ee) Would you like to continue? (y/N) Yes ✓ Fetching releases (0.1s) @@ -266,7 +266,7 @@ Example output: ``` $ shorebird release macos ✓ Fetching apps (0.3s) -✓ Building app bundle with Flutter %flutter_version% (1e0e5760ee) (18.3s) +✓ Building app bundle with Flutter 3.41.4 (1e0e5760ee) (18.3s) ✓ Fetching releases (0.1s) 🚀 Ready to create a new release! @@ -274,7 +274,7 @@ $ shorebird release macos 📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd) đŸ“Ļ Release Version: 1.0.13+2 đŸ•šī¸ Platform: macos -đŸĻ Flutter Version: %flutter_version% (1e0e5760ee) +đŸĻ Flutter Version: 3.41.4 (1e0e5760ee) Would you like to continue? (y/N) Yes ✓ Fetching releases (0.1s) @@ -339,7 +339,7 @@ Example output: ``` $ shorebird release windows ✓ Fetching apps (0.3s) -✓ Building Windows app with Flutter %flutter_version% (1e0e5760ee) (18.3s) +✓ Building Windows app with Flutter 3.41.4 (1e0e5760ee) (18.3s) ✓ Fetching releases (0.1s) 🚀 Ready to create a new release! @@ -347,7 +347,7 @@ $ shorebird release windows 📱 App: sample (d0cf1d8f-e741-4f5d-b280-b794000df1cd) đŸ“Ļ Release Version: 1.0.0+1 đŸ•šī¸ Platform: windows -đŸĻ Flutter Version: %flutter_version% (1e0e5760ee) +đŸĻ Flutter Version: 3.41.4 (1e0e5760ee) Would you like to continue? (y/N) Yes ✓ Fetching releases (0.1s) diff --git a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx index 0aae7723..426e8874 100644 --- a/src/content/docs/flutter-concepts/how-to-install-flutter.mdx +++ b/src/content/docs/flutter-concepts/how-to-install-flutter.mdx @@ -437,14 +437,14 @@ line is prefixed with one of three symbols: A fully healthy macOS output looks like: ``` -[✓] Flutter (Channel stable, %flutter_version%, on macOS 26.2 25C56 darwin-arm64, locale +[✓] Flutter (Channel stable, 3.41.4, on macOS 26.2 25C56 darwin-arm64, locale en-IN) [605ms] - â€ĸ Flutter version %flutter_version% on channel stable at + â€ĸ Flutter version 3.41.4 on channel stable at /Users//development/flutter â€ĸ Upstream repository https://github.com/flutter/flutter.git â€ĸ Framework revision 582a0e7c55 (5 days ago), 2026-02-12 17:12:32 -0800 â€ĸ Engine revision 3452d735bd - â€ĸ Dart version %dart_version% + â€ĸ Dart version 3.11.1 â€ĸ DevTools version 2.54.1 â€ĸ Feature flags: enable-web, enable-linux-desktop, enable-macos-desktop, enable-windows-desktop, enable-android, enable-ios, cli-animations,