From 2fa34bbefa1b42d40adc45e2020c9307e379f597 Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 2 Oct 2026 15:22:17 +0200 Subject: [PATCH 1/6] docs: Add an agent setup prompt to the installation page Adds a copyable prompt that tells a coding agent to check for and install only the missing tooling (Flutter and the Serverpod CLI), then verify it. Code block copies are now reported to Google Analytics as a `copy_code_block` event. Co-Authored-By: Claude Opus 5.5 --- docs/04-get-started/01-installation.md | 15 ++++++++++++++ .../CodeBlock/Buttons/CopyButton/index.js | 20 +++++++++++++++++-- 2 files changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/04-get-started/01-installation.md b/docs/04-get-started/01-installation.md index 4e3afa4c..b5a852ea 100644 --- a/docs/04-get-started/01-installation.md +++ b/docs/04-get-started/01-installation.md @@ -6,6 +6,21 @@ slug: /installation # Installation +### Set up with an AI agent + +If you use a coding agent such as Claude Code, Cursor, or Codex, paste this prompt into it. The agent checks what is already installed, installs only what is missing, and verifies the result. To install manually, follow the steps below instead. + +```text title="Agent setup prompt" +Set up this machine for Serverpod development. Check what is already installed first and only install what is missing. Do not reinstall or upgrade anything without asking me. + +1. Flutter: run `flutter --version`. If Flutter is missing, install the latest stable release for this OS following https://docs.flutter.dev/get-started/install. Use the Dart SDK bundled with Flutter, not a separate one. +2. Serverpod CLI: run `serverpod version`. If it is missing, run `dart install serverpod_cli` (if it was previously installed with `dart pub global activate`, run `dart pub global deactivate serverpod_cli` first). If the install fails because the installed Flutter is too old, stop and ask me whether to upgrade Flutter. +3. Make sure `flutter`, `dart`, and `serverpod` are on the PATH for new terminal sessions, including non-interactive shells. +4. Verify by running `flutter doctor`, `dart --version`, and `serverpod version`. Do not install the platform toolchains flutter doctor reports as missing (Android Studio, Xcode, Chrome) unless I ask. + +Finish with a short summary: what was already installed, what you installed, and the output of the verification commands. +``` + ### Prerequisites Serverpod is tested on Mac, Windows, and Linux. Before you can install Serverpod, you need to have **[Flutter](https://flutter.dev/docs/get-started/install)** installed. Serverpod 4 requires Flutter 3.44.4 or later, which includes Dart 3.12.2. diff --git a/src/theme/CodeBlock/Buttons/CopyButton/index.js b/src/theme/CodeBlock/Buttons/CopyButton/index.js index 8399edd1..2a355a2c 100644 --- a/src/theme/CodeBlock/Buttons/CopyButton/index.js +++ b/src/theme/CodeBlock/Buttons/CopyButton/index.js @@ -2,6 +2,7 @@ * Swizzled from @docusaurus/theme-classic to strip leading shell prompts * (`$ `) from text written to the clipboard. The prompt remains visible * in the rendered code block, but the copied text is the runnable command. + * Also reports each copy to Google Analytics as a `copy_code_block` event. */ import React, {useCallback, useState, useRef, useEffect} from 'react'; import clsx from 'clsx'; @@ -62,20 +63,35 @@ async function copyToClipboard(text) { return copy(text); } +function reportCopyEvent(params) { + // gtag is absent on the dev server and behind ad blockers. + if (typeof window === 'undefined' || typeof window.gtag !== 'function') { + return; + } + try { + window.gtag('event', 'copy_code_block', params); + } catch {} +} + function useCopyButton() { const { - metadata: {code}, + metadata: {code, language, title: blockTitle}, } = useCodeBlockContext(); const [isCopied, setIsCopied] = useState(false); const copyTimeout = useRef(undefined); const copyCode = useCallback(() => { copyToClipboard(stripShellPrompts(code)).then(() => { setIsCopied(true); + reportCopyEvent({ + page_path: window.location.pathname, + language, + block_title: typeof blockTitle === 'string' ? blockTitle : undefined, + }); copyTimeout.current = window.setTimeout(() => { setIsCopied(false); }, 1000); }); - }, [code]); + }, [code, language, blockTitle]); useEffect(() => () => window.clearTimeout(copyTimeout.current), []); return {copyCode, isCopied}; } From 2e7843ab30c5889832ca239168aae427f12ac257 Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 2 Oct 2026 15:29:30 +0200 Subject: [PATCH 2/6] docs: Offer to create a project at the end of the agent setup prompt Co-Authored-By: Claude Opus 5.5 --- docs/04-get-started/01-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-get-started/01-installation.md b/docs/04-get-started/01-installation.md index b5a852ea..8411eb84 100644 --- a/docs/04-get-started/01-installation.md +++ b/docs/04-get-started/01-installation.md @@ -18,7 +18,7 @@ Set up this machine for Serverpod development. Check what is already installed f 3. Make sure `flutter`, `dart`, and `serverpod` are on the PATH for new terminal sessions, including non-interactive shells. 4. Verify by running `flutter doctor`, `dart --version`, and `serverpod version`. Do not install the platform toolchains flutter doctor reports as missing (Android Studio, Xcode, Chrome) unless I ask. -Finish with a short summary: what was already installed, what you installed, and the output of the verification commands. +Finish with a short summary: what was already installed, what you installed, and the output of the verification commands. Then ask me: "Do you want me to create a new Serverpod project?" and show the command to do it manually: `serverpod create `. ``` ### Prerequisites From ddc80349250b4b20b947318d771df2fd5bd4566c Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 2 Oct 2026 15:32:56 +0200 Subject: [PATCH 3/6] docs: Tighten the summary format in the agent setup prompt Co-Authored-By: Claude Opus 5.5 --- docs/04-get-started/01-installation.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/04-get-started/01-installation.md b/docs/04-get-started/01-installation.md index 8411eb84..c7b619b6 100644 --- a/docs/04-get-started/01-installation.md +++ b/docs/04-get-started/01-installation.md @@ -18,7 +18,12 @@ Set up this machine for Serverpod development. Check what is already installed f 3. Make sure `flutter`, `dart`, and `serverpod` are on the PATH for new terminal sessions, including non-interactive shells. 4. Verify by running `flutter doctor`, `dart --version`, and `serverpod version`. Do not install the platform toolchains flutter doctor reports as missing (Android Studio, Xcode, Chrome) unless I ask. -Finish with a short summary: what was already installed, what you installed, and the output of the verification commands. Then ask me: "Do you want me to create a new Serverpod project?" and show the command to do it manually: `serverpod create `. +Finish with a short summary in this format, with no other commentary: +- Already installed: each tool with its version, or "nothing". +- Installed: each tool or package you installed, with its version. +- Optional, not set up: only the items flutter doctor reports as missing, each with what it is for: Android toolchain (Android apps), Xcode (iOS and macOS apps), Chrome (web apps), Linux toolchain (Linux desktop apps), Visual Studio (Windows desktop apps). Ask if I want any of them installed. + +Then ask me: "Do you want me to create a new Serverpod project?" and show the command to do it manually: `serverpod create `. ``` ### Prerequisites From 10ebfa7f2edb317bd31390a33572b8a506c22de0 Mon Sep 17 00:00:00 2001 From: Isak Date: Fri, 2 Oct 2026 15:34:21 +0200 Subject: [PATCH 4/6] Update docs/04-get-started/01-installation.md Co-authored-by: Alexander Sandor <137198655+SandPod@users.noreply.github.com> --- docs/04-get-started/01-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-get-started/01-installation.md b/docs/04-get-started/01-installation.md index c7b619b6..51a4a78f 100644 --- a/docs/04-get-started/01-installation.md +++ b/docs/04-get-started/01-installation.md @@ -8,7 +8,7 @@ slug: /installation ### Set up with an AI agent -If you use a coding agent such as Claude Code, Cursor, or Codex, paste this prompt into it. The agent checks what is already installed, installs only what is missing, and verifies the result. To install manually, follow the steps below instead. +If you use a coding agent such as Claude Code, Cursor, or Codex, you can configure your development environment with it. Give it this prompt, and the agent will install only what is missing and verify the results. ```text title="Agent setup prompt" Set up this machine for Serverpod development. Check what is already installed first and only install what is missing. Do not reinstall or upgrade anything without asking me. From c4ab7d442f9ddc47108af1ed9e925eb662462b6e Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 2 Oct 2026 15:36:53 +0200 Subject: [PATCH 5/6] docs: Use a sectioned list for the agent setup summary Co-Authored-By: Claude Opus 5.5 --- docs/04-get-started/01-installation.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/04-get-started/01-installation.md b/docs/04-get-started/01-installation.md index 51a4a78f..470133ac 100644 --- a/docs/04-get-started/01-installation.md +++ b/docs/04-get-started/01-installation.md @@ -18,10 +18,18 @@ Set up this machine for Serverpod development. Check what is already installed f 3. Make sure `flutter`, `dart`, and `serverpod` are on the PATH for new terminal sessions, including non-interactive shells. 4. Verify by running `flutter doctor`, `dart --version`, and `serverpod version`. Do not install the platform toolchains flutter doctor reports as missing (Android Studio, Xcode, Chrome) unless I ask. -Finish with a short summary in this format, with no other commentary: -- Already installed: each tool with its version, or "nothing". -- Installed: each tool or package you installed, with its version. -- Optional, not set up: only the items flutter doctor reports as missing, each with what it is for: Android toolchain (Android apps), Xcode (iOS and macOS apps), Chrome (web apps), Linux toolchain (Linux desktop apps), Visual Studio (Windows desktop apps). Ask if I want any of them installed. +Finish with a summary in exactly this format, one item per line and no other commentary. Leave out a section if it would be empty. + +Already installed +- + +Installed +- + +Optional, not set up +- () + +Use these descriptions for the optional items: Android toolchain (Android apps), Xcode (iOS and macOS apps), Chrome (web apps), Linux toolchain (Linux desktop apps), Visual Studio (Windows desktop apps). After the list, ask if I want any of them installed. Then ask me: "Do you want me to create a new Serverpod project?" and show the command to do it manually: `serverpod create `. ``` From 8f260c3b6185c3f7758c8139ef161fc17b1e196b Mon Sep 17 00:00:00 2001 From: Isakdl Date: Fri, 2 Oct 2026 15:43:19 +0200 Subject: [PATCH 6/6] docs: Add the agent setup prompt to the 4.0.0 docs Co-Authored-By: Claude Opus 5.5 --- .../04-get-started/01-installation.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/versioned_docs/version-4.0.0/04-get-started/01-installation.md b/versioned_docs/version-4.0.0/04-get-started/01-installation.md index 4e3afa4c..470133ac 100644 --- a/versioned_docs/version-4.0.0/04-get-started/01-installation.md +++ b/versioned_docs/version-4.0.0/04-get-started/01-installation.md @@ -6,6 +6,34 @@ slug: /installation # Installation +### Set up with an AI agent + +If you use a coding agent such as Claude Code, Cursor, or Codex, you can configure your development environment with it. Give it this prompt, and the agent will install only what is missing and verify the results. + +```text title="Agent setup prompt" +Set up this machine for Serverpod development. Check what is already installed first and only install what is missing. Do not reinstall or upgrade anything without asking me. + +1. Flutter: run `flutter --version`. If Flutter is missing, install the latest stable release for this OS following https://docs.flutter.dev/get-started/install. Use the Dart SDK bundled with Flutter, not a separate one. +2. Serverpod CLI: run `serverpod version`. If it is missing, run `dart install serverpod_cli` (if it was previously installed with `dart pub global activate`, run `dart pub global deactivate serverpod_cli` first). If the install fails because the installed Flutter is too old, stop and ask me whether to upgrade Flutter. +3. Make sure `flutter`, `dart`, and `serverpod` are on the PATH for new terminal sessions, including non-interactive shells. +4. Verify by running `flutter doctor`, `dart --version`, and `serverpod version`. Do not install the platform toolchains flutter doctor reports as missing (Android Studio, Xcode, Chrome) unless I ask. + +Finish with a summary in exactly this format, one item per line and no other commentary. Leave out a section if it would be empty. + +Already installed +- + +Installed +- + +Optional, not set up +- () + +Use these descriptions for the optional items: Android toolchain (Android apps), Xcode (iOS and macOS apps), Chrome (web apps), Linux toolchain (Linux desktop apps), Visual Studio (Windows desktop apps). After the list, ask if I want any of them installed. + +Then ask me: "Do you want me to create a new Serverpod project?" and show the command to do it manually: `serverpod create `. +``` + ### Prerequisites Serverpod is tested on Mac, Windows, and Linux. Before you can install Serverpod, you need to have **[Flutter](https://flutter.dev/docs/get-started/install)** installed. Serverpod 4 requires Flutter 3.44.4 or later, which includes Dart 3.12.2.