From a9559a18fe347834b715a626dd8ee5dd0c51fb5c Mon Sep 17 00:00:00 2001 From: Funke Faith Olasupo <55761629+Roxie-32@users.noreply.github.com> Date: Wed, 21 Oct 2026 08:23:42 +0100 Subject: [PATCH 1/6] improve draft --- docs/04-get-started/02-quickstart.md | 133 ++++++++++++------ docs/06-concepts/cli/_generated/cloud.md | 1 + .../cli/commands/runner/_runner.md | 1 + 3 files changed, 89 insertions(+), 46 deletions(-) diff --git a/docs/04-get-started/02-quickstart.md b/docs/04-get-started/02-quickstart.md index 397877b6..62de66f8 100644 --- a/docs/04-get-started/02-quickstart.md +++ b/docs/04-get-started/02-quickstart.md @@ -11,74 +11,115 @@ import TabItem from '@theme/TabItem'; # Quickstart -Build and deploy a full-stack Flutter and Serverpod app, hosted on the web, in 10–15 minutes. We have tested the default setup with Antigravity, Cursor, and Claude Code, but most agentic editors will work. +This quickstart shows you how to build a full-stack Flutter and Serverpod app with an AI coding agent and deploy it to the web in about 15 minutes. ## 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. +- [Flutter](https://flutter.dev/docs/get-started/install) 3.44.4 or later, which includes Dart 3.12.2. +- An AI coding agent like Claude Code, Cursor, or GitHub Copilot. -:::info -Check your Flutter installation by running the following command in your terminal: +To check your Flutter version, run: ```bash -$ flutter doctor +flutter doctor ``` -::: +:::info + +You don't need to install or set up a database. New projects use an embedded PostgreSQL that Serverpod downloads and runs for you. -New projects use an embedded PostgreSQL that Serverpod downloads and runs for you, so no database setup is needed. +::: ## Install Serverpod -Serverpod is installed using the Dart package manager. To install Serverpod, run the following command in your terminal: +1. Install the Serverpod CLI with Dart: -```txt -$ dart install serverpod_cli -``` + ```bash + dart install serverpod_cli + ``` -Verify the installation by running: +2. Verify the installation: + + ```bash + serverpod + ``` + + You should see a list of available commands. + +3. To make the `serverpod` command available in new terminals, add the Dart install directory to your PATH: + + + + + ```bash + echo 'export PATH="$PATH:$HOME/Library/Application Support/Dart/install/bin"' >> ~/.zshrc + ``` + + + + + ```bash + echo 'export PATH="$PATH:$HOME/.local/state/Dart/install/bin"' >> ~/.bashrc + ``` + + + + + Run this in PowerShell: + + ```powershell + [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:APPDATA\Dart\install\bin", "User") + ``` + + + -```bash -$ serverpod -``` :::warning -If a previous version of Serverpod is already installed with `dart pub global activate`, deactivate it before installing or upgrading: +If you installed an earlier version of Serverpod with `dart pub global activate`, remove it before you install: -```txt -$ dart pub global deactivate serverpod_cli +```bash +dart pub global deactivate serverpod_cli ``` ::: -## Create the project -Use Serverpod's `quickstart` command to create a new project. +## Create your project -```bash -$ serverpod quickstart my_project -``` +1. Create a new Serverpod project with the quickstart command: -The command opens an interactive screen where you select the editor or agent you plan to use. Navigate with your mouse or use the arrow keys to move around, press `Space` to select your editor, then press `Enter` to create the project. + ```bash + serverpod quickstart my_project + ``` -Next, open your newly created project with your favorite AI powered editor. Open the _root_ folder of the full project, for example, `my_project`, which includes the server, client, and Flutter app. + Follow the prompts to choose your code agent or editor and configure your project. Navigate with your mouse or arrow keys, press `Space` to select, and press `Enter` to create the project. Serverpod uses your selection to set up the project for your selected agent or editor. -:::important +2. When setup finishes, open the newly created `my_project` folder in the agent or editor you selected. + Serverpod creates a `my_project` folder with three packages: -If you are using Cursor, you will need to **enable the Serverpod and Dart MCP servers**: open **Customize** in the sidebar, click **MCPs**, and turn on both servers. + - `my_project_server` is your backend. + - `my_project_client` is generated code that your app uses to call the server. + - `my_project_flutter` is your Flutter app. +:::important +**If you use Cursor**, you need to turn on the Serverpod and Dart MCP servers. Open **Customize** in the sidebar, click **MCPs**, and turn on both servers. ::: -## Start the server and the app +## Start your server and app -Start the server and the Flutter app by opening up a terminal window and running the [`serverpod start`](./concepts/server-fundamentals/running-your-server) command: +Open the project folder in your terminal and run the [`serverpod start`](./concepts/server-fundamentals/running-your-server) command: ```bash -$ serverpod start +serverpod start ``` -After the server has started and your app has finished building, the app will open in a new browser window. Try it out by entering your name and clicking the send button. +Keep the terminal open while the app is running. The command starts the local development environment, including the server, Flutter app, and local database. The first start takes a few minutes, because Serverpod downloads PostgreSQL and builds the app. + +When it's ready, the sample app opens in your browser. Try it out by entering your name and clicking **Send**. The server sends back a greeting. + +Keep this terminal running. It watches your files and reloads the app every time the agent changes the code. ## Build your app @@ -102,39 +143,39 @@ Instruct your AI agent to build your app. Here are a few simple prompts that you ---- -The agent will start building your app. It will manage your database and perform a hot reload when the app is complete. +The agent writes the server code, creates the database tables, and builds the screens. When it's finished, it reloads the app and displays the new app on the browser. :::tip -If your app uses authentication, the verification code will be displayed as an alert in Serverpod's command line interface. Press the `C` key to copy the code. +- If your app uses authentication, the verification code will be displayed as an alert in Serverpod's CLI. Press the `C` key to copy the code. +- If the app fails to reload, click `R` in the terminal running `serverpod start` to force restart the server and the app. ::: -:::tip - -If the agent fails to reload the app, you can always hit the `R` key to force a restart of the server and the app. -::: +## Deploy your app to Serverpod Cloud -## Deploy the app to the cloud +To share your app with others, deploy it to **[Serverpod Cloud](/cloud)**. Serverpod Cloud hosts your backend, database, and web app, and gives you a public URL that anyone can access. Your first project includes a one-month free trial, and you don't need a credit card. -Deploy your web app and backend to **[Serverpod Cloud](/cloud)**, a fully managed platform built by the Serverpod team. Your first project includes a one-month free trial, with no credit card required. +1. Create an account on the **[Serverpod Cloud Console](https://console.serverpod.dev/)**. +2. Create a project and turn on the database. +3. In the `my_project` folder, run: -Create your Cloud account and create a project on the **[Serverpod Cloud Console](https://console.serverpod.dev/)**. Enable the database when you create the project if your server uses one. Then launch your app: + ```bash + serverpod cloud launch + ``` -```bash -$ serverpod cloud launch -``` +4. Follow the prompts to authenticate in the browser and select your Cloud account. +5. Back in the terminal, select the project you want to deploy -This links your project to Cloud and deploys your backend along with the web build of your app. +This links your project to Cloud and deploys your backend along with your web app. Wait for the deployment to finish, then use the deployed app URL provided by the CLI or Cloud Console to open your app publicly. After the first launch, you redeploy any changes by running `serverpod cloud launch` again. :::tip -In the **[Serverpod Cloud Console](https://console.serverpod.dev/)**, open your project and use the **Logs**, **Sessions**, and **Metrics** tabs to see what your server is doing. +In the **[Serverpod Cloud Console](https://console.serverpod.dev/)**, open your project and use the **Logs**, **Sessions**, and **Metrics** tabs to monitor your app. See **[Serverpod Cloud guide](/cloud_docs/)** to learn more. ::: diff --git a/docs/06-concepts/cli/_generated/cloud.md b/docs/06-concepts/cli/_generated/cloud.md index e69de29b..8b137891 100644 --- a/docs/06-concepts/cli/_generated/cloud.md +++ b/docs/06-concepts/cli/_generated/cloud.md @@ -0,0 +1 @@ + diff --git a/docs/06-concepts/cli/commands/runner/_runner.md b/docs/06-concepts/cli/commands/runner/_runner.md index e69de29b..8b137891 100644 --- a/docs/06-concepts/cli/commands/runner/_runner.md +++ b/docs/06-concepts/cli/commands/runner/_runner.md @@ -0,0 +1 @@ + From 3869780de077330719d4a162f2b8b30b4b1f72be Mon Sep 17 00:00:00 2001 From: Funke Faith Olasupo <55761629+Roxie-32@users.noreply.github.com> Date: Wed, 21 Oct 2026 10:49:44 +0100 Subject: [PATCH 2/6] Improve quickstart onboarding --- .../04-get-started/02-quickstart.md | 152 +++++++++++------- 1 file changed, 95 insertions(+), 57 deletions(-) diff --git a/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md b/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md index 397877b6..84c3ca51 100644 --- a/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md +++ b/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md @@ -11,78 +11,113 @@ import TabItem from '@theme/TabItem'; # Quickstart -Build and deploy a full-stack Flutter and Serverpod app, hosted on the web, in 10–15 minutes. We have tested the default setup with Antigravity, Cursor, and Claude Code, but most agentic editors will work. +This quickstart shows you how to build a full-stack Flutter and Serverpod app with an AI coding agent and deploy it to the web, all in about 15 minutes. ## 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. +- [Flutter](https://flutter.dev/docs/get-started/install) 3.44.4 or later, which includes Dart 3.12.2 +- An AI coding agent, such as Claude Code, Cursor, or Antigravity -:::info -Check your Flutter installation by running the following command in your terminal: +To check your Flutter version, run: ```bash -$ flutter doctor +flutter doctor ``` +:::info +You don't need to install or set up a database. New projects use an embedded PostgreSQL database that Serverpod downloads and runs for you. ::: -New projects use an embedded PostgreSQL that Serverpod downloads and runs for you, so no database setup is needed. - ## Install Serverpod -Serverpod is installed using the Dart package manager. To install Serverpod, run the following command in your terminal: +:::warning +If you installed an earlier version of Serverpod with `dart pub global activate`, remove it before you install: -```txt -$ dart install serverpod_cli +```bash +dart pub global deactivate serverpod_cli ``` -Verify the installation by running: +::: -```bash -$ serverpod -``` +1. Install the Serverpod CLI with Dart: -:::warning + ```bash + dart install serverpod_cli + ``` -If a previous version of Serverpod is already installed with `dart pub global activate`, deactivate it before installing or upgrading: +2. Verify the installation: -```txt -$ dart pub global deactivate serverpod_cli -``` + ```bash + serverpod + ``` -::: + You'll see a list of Serverpod commands. -## Create the project +3. To make the `serverpod` command available in new terminals, add the Dart install directory to your `PATH`: -Use Serverpod's `quickstart` command to create a new project. + + -```bash -$ serverpod quickstart my_project -``` + ```bash + echo 'export PATH="$PATH:$HOME/Library/Application Support/Dart/install/bin"' >> ~/.zshrc + ``` -The command opens an interactive screen where you select the editor or agent you plan to use. Navigate with your mouse or use the arrow keys to move around, press `Space` to select your editor, then press `Enter` to create the project. + + -Next, open your newly created project with your favorite AI powered editor. Open the _root_ folder of the full project, for example, `my_project`, which includes the server, client, and Flutter app. + ```bash + echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashr + source ~/.bashrc + ``` -:::important + + + + ```powershell + [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:LOCALAPPDATA\Pub\Cache\bin", "User") + ``` + + + + +## Create your project -If you are using Cursor, you will need to **enable the Serverpod and Dart MCP servers**: open **Customize** in the sidebar, click **MCPs**, and turn on both servers. +1. Create a new Serverpod project with the `quickstart` command: + ```bash + serverpod quickstart my_project + ``` + +2. Follow the prompts to choose your code editor or agent and configure your project. Navigate with your mouse or arrow keys, press `Space` to select, and press `Enter` to create the project. Serverpod configures the project for that editor or agent. + +3. Open the `my_project` folder in the editor you selected. It's already set up with Serverpod skills and MCP servers for your agent, and it contains three packages: + + - `my_project_server` is your backend. + - `my_project_client` is generated code that your app uses to call the server. + - `my_project_flutter` is your Flutter app. + +:::important +**If you use Cursor**, turn on the Serverpod and Dart MCP servers. Open **Customize** in the sidebar, click **MCPs**, and turn on both servers. ::: -## Start the server and the app +## Start your server and app -Start the server and the Flutter app by opening up a terminal window and running the [`serverpod start`](./concepts/server-fundamentals/running-your-server) command: +In your terminal, go to the `my_project` folder and run the [`serverpod start`](./concepts/server-fundamentals/running-your-server) command: ```bash -$ serverpod start +cd my_project +serverpod start ``` -After the server has started and your app has finished building, the app will open in a new browser window. Try it out by entering your name and clicking the send button. +The command starts the local development environment, including the server, Flutter app, and database. The first start takes a few minutes because Serverpod downloads PostgreSQL and builds the app. + +When it's ready, the sample app opens in your browser. Try it out by entering your name and clicking **Send**. The server sends back a greeting. + +Keep this terminal running. It watches your files and reloads the app every time the code changes. ## Build your app -Instruct your AI agent to build your app. Here are a few simple prompts that you can try: +Instruct your agent to build your app. Here are a few prompts that you can try: @@ -102,44 +137,47 @@ Instruct your AI agent to build your app. Here are a few simple prompts that you ---- - -The agent will start building your app. It will manage your database and perform a hot reload when the app is complete. +The agent writes the server code, creates the database tables, and builds the screens. When it's finished, it reloads the app in your browser. :::tip -If your app uses authentication, the verification code will be displayed as an alert in Serverpod's command line interface. Press the `C` key to copy the code. +- If your app uses authentication, the terminal running `serverpod start` shows the verification code. Press the `C` key to copy the code. +- If the app fails to reload, press the `R` key in the terminal running `serverpod start` to force a restart of the server and the app. ::: -:::tip +## Deploy your app to Serverpod Cloud -If the agent fails to reload the app, you can always hit the `R` key to force a restart of the server and the app. +To share your app with others, deploy it to [Serverpod Cloud](/cloud). Serverpod Cloud hosts your backend, database, and web app, and gives you a public URL that anyone can access. Your first project includes a one-month free trial, with no credit card required. -::: +1. Create an account on the [Serverpod Cloud Console](https://console.serverpod.dev/). +2. Create a new project on the Cloud Console. +3. From the `my_project` folder, run: -## Deploy the app to the cloud + ```bash + scloud launch + ``` -Deploy your web app and backend to **[Serverpod Cloud](/cloud)**, a fully managed platform built by the Serverpod team. Your first project includes a one-month free trial, with no credit card required. +4. Follow the prompts to sign in from the browser and select your Serverpod Cloud account. +5. Back in the terminal, select the Serverpod Cloud project you just created. -Create your Cloud account and create a project on the **[Serverpod Cloud Console](https://console.serverpod.dev/)**. Enable the database when you create the project if your server uses one. Then launch your app: +`scloud launch` links your project to Cloud and deploys your backend along with your web app. When the launch completes, the terminal displays the URLs for your deployed app and server: -```bash -$ serverpod cloud launch +```text +When the server has started, you can access it at: + Web: https://my-project.serverpod.space/ + API: https://my-project.api.serverpod.space/ + Insights: https://my-project.insights.serverpod.space/ ``` -This links your project to Cloud and deploys your backend along with the web build of your app. - -After the first launch, you redeploy any changes by running `serverpod cloud launch` again. +- **Web:** Your Flutter web app. Open this URL to try your app or share it with others. +- **API:** Your backend endpoint. Your app uses this URL to communicate with the server. +- **Insights:** The endpoint used to connect Serverpod Insights and monitor your server. -:::tip - -In the **[Serverpod Cloud Console](https://console.serverpod.dev/)**, open your project and use the **Logs**, **Sessions**, and **Metrics** tabs to see what your server is doing. - -::: +After the first launch, you can deploy any changes by running `scloud launch` again. -## Get help +To monitor your app, use the **Logs**, **Sessions**, and **Metrics** tabs in the [Serverpod Cloud Console](https://console.serverpod.dev/). To learn more, see the [Serverpod Cloud guide](/cloud). -We welcome feedback on agent skills, MCP servers, and the `serverpod start` workflow. If you run into issues, reach out on **[Discord](https://serverpod.dev/discord)** or file an issue on **[GitHub](https://github.com/serverpod/serverpod)**. Pull requests are welcome. +Your full-stack app is now live on the web. Have feedback on the agent skills, MCP servers, or the `serverpod start` workflow? Tell us on [Discord](https://serverpod.dev/discord) or open an issue on [GitHub](https://github.com/serverpod/serverpod). -Happy building with Serverpod 4. +Happy building with Serverpod 4! From ec42efe438c72e2a73c82c2ab9681e4eb65d6a07 Mon Sep 17 00:00:00 2001 From: Funke Faith Olasupo <55761629+Roxie-32@users.noreply.github.com> Date: Wed, 28 Oct 2026 09:26:32 +0100 Subject: [PATCH 3/6] Delete docs/06-concepts/cli/_generated/cloud.md --- docs/06-concepts/cli/_generated/cloud.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 docs/06-concepts/cli/_generated/cloud.md diff --git a/docs/06-concepts/cli/_generated/cloud.md b/docs/06-concepts/cli/_generated/cloud.md deleted file mode 100644 index 8b137891..00000000 --- a/docs/06-concepts/cli/_generated/cloud.md +++ /dev/null @@ -1 +0,0 @@ - From 32142a1bf26cb80666371dbbd83baa3456b19a7a Mon Sep 17 00:00:00 2001 From: Funke Faith Olasupo <55761629+Roxie-32@users.noreply.github.com> Date: Wed, 28 Oct 2026 09:27:09 +0100 Subject: [PATCH 4/6] Delete docs/06-concepts/cli/commands/runner/_runner.md --- docs/06-concepts/cli/commands/runner/_runner.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 docs/06-concepts/cli/commands/runner/_runner.md diff --git a/docs/06-concepts/cli/commands/runner/_runner.md b/docs/06-concepts/cli/commands/runner/_runner.md deleted file mode 100644 index 8b137891..00000000 --- a/docs/06-concepts/cli/commands/runner/_runner.md +++ /dev/null @@ -1 +0,0 @@ - From 07162e861a6a77c82e55375d27fef3933f656e62 Mon Sep 17 00:00:00 2001 From: Funke Faith Olasupo <55761629+Roxie-32@users.noreply.github.com> Date: Wed, 28 Oct 2026 09:28:02 +0100 Subject: [PATCH 5/6] Apply batched suggestions from code review Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/04-get-started/02-quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/04-get-started/02-quickstart.md b/docs/04-get-started/02-quickstart.md index 62de66f8..6bac3835 100644 --- a/docs/04-get-started/02-quickstart.md +++ b/docs/04-get-started/02-quickstart.md @@ -68,7 +68,7 @@ You don't need to install or set up a database. New projects use an embedded Pos Run this in PowerShell: ```powershell - [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:APPDATA\Dart\install\bin", "User") + [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Dart\install\bin", "User") ``` @@ -175,7 +175,7 @@ After the first launch, you redeploy any changes by running `serverpod cloud lau :::tip -In the **[Serverpod Cloud Console](https://console.serverpod.dev/)**, open your project and use the **Logs**, **Sessions**, and **Metrics** tabs to monitor your app. See **[Serverpod Cloud guide](/cloud_docs/)** to learn more. +In the **[Serverpod Cloud Console](https://console.serverpod.dev/)**, open your project and use the **Logs**, **Sessions**, and **Metrics** tabs to monitor your app. See **[Serverpod Cloud guide](/cloud)** to learn more. ::: From d44e4f5dd5e031dc05b5ab43d6408f1f10540902 Mon Sep 17 00:00:00 2001 From: Funke Faith Olasupo <55761629+Roxie-32@users.noreply.github.com> Date: Thu, 29 Oct 2026 08:14:03 +0100 Subject: [PATCH 6/6] Resolve installation conflicts --- cloud_docs/getting-started/launch.md | 2 +- docs/04-get-started/02-quickstart.md | 184 ++++++++++-------- .../04-get-started/02-quickstart.md | 161 ++++++++------- 3 files changed, 197 insertions(+), 150 deletions(-) diff --git a/cloud_docs/getting-started/launch.md b/cloud_docs/getting-started/launch.md index 70c337a7..0fd38f48 100644 --- a/cloud_docs/getting-started/launch.md +++ b/cloud_docs/getting-started/launch.md @@ -14,7 +14,7 @@ Get your Serverpod app live on Cloud in a few minutes. You need: - The Serverpod Cloud CLI set up and authenticated. See [Set up the Cloud CLI](/cloud/getting-started/installation). -- A Serverpod project on your machine. See [Creating a new project](/quickstart#create-the-project) in the Serverpod installation guide. +- A Serverpod project on your machine. See [Creating a new project](/quickstart#create-your-project) in the Serverpod installation guide. ## Launch your project diff --git a/docs/04-get-started/02-quickstart.md b/docs/04-get-started/02-quickstart.md index 62de66f8..e28bc912 100644 --- a/docs/04-get-started/02-quickstart.md +++ b/docs/04-get-started/02-quickstart.md @@ -8,122 +8,140 @@ slug: /quickstart import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import CollapsibleCodeBlock from '@site/src/components/CollapsibleCodeBlock'; # Quickstart -This quickstart shows you how to build a full-stack Flutter and Serverpod app with an AI coding agent and deploy it to the web in about 15 minutes. +This quickstart shows you how to build a full-stack Flutter and Serverpod app with an AI coding agent and deploy it to the web, all in about 15 minutes. ## Prerequisites -- [Flutter](https://flutter.dev/docs/get-started/install) 3.44.4 or later, which includes Dart 3.12.2. -- An AI coding agent like Claude Code, Cursor, or GitHub Copilot. +- An AI coding agent, such as Claude Code, Cursor, or Antigravity -To check your Flutter version, run: +## Install Serverpod -```bash -flutter doctor -``` + + -:::info +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. -You don't need to install or set up a database. New projects use an embedded PostgreSQL that Serverpod downloads and runs for you. + -::: +```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. -## Install Serverpod +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. -1. Install the Serverpod CLI with Dart: +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. - ```bash - dart install serverpod_cli - ``` +Already installed +- -2. Verify the installation: +Installed +- - ```bash - serverpod - ``` +Optional, not set up +- () - You should see a list of available commands. +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. -3. To make the `serverpod` command available in new terminals, add the Dart install directory to your PATH: +Then ask me: "Do you want me to create a new Serverpod project?" and show the command to do it manually: `serverpod create `. +``` - - + + + - ```bash - echo 'export PATH="$PATH:$HOME/Library/Application Support/Dart/install/bin"' >> ~/.zshrc - ``` +:::warning +If you installed an earlier version of Serverpod with `dart pub global activate`, remove it before you install: - - +```bash +$ dart pub global deactivate serverpod_cli +``` - ```bash - echo 'export PATH="$PATH:$HOME/.local/state/Dart/install/bin"' >> ~/.bashrc - ``` +::: - - +1. Install [Flutter](https://docs.flutter.dev/get-started/install) 3.44.4 or later (which includes Dart 3.12.2 or later). To check your version, run `flutter doctor`. +2. Install the Serverpod CLI: - Run this in PowerShell: + ```bash + $ dart install serverpod_cli + ``` - ```powershell - [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:APPDATA\Dart\install\bin", "User") - ``` +3. To make the `serverpod` command available in new terminals, add the Dart install directory to your `PATH`: - - + + + ```bash + $ echo 'export PATH="$PATH:$HOME/Library/Application Support/Dart/install/bin"' >> ~/.zshrc + ``` -:::warning + + -If you installed an earlier version of Serverpod with `dart pub global activate`, remove it before you install: + ```bash + $ echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc + ``` -```bash -dart pub global deactivate serverpod_cli -``` + + -::: + ```powershell + [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Pub\Cache\bin", "User") + ``` + + + +4. Open a new terminal and verify the installation: + + ```bash + $ serverpod + ``` + + You'll see a list of Serverpod commands. + + + ## Create your project -1. Create a new Serverpod project with the quickstart command: +1. Create a new Serverpod project: ```bash - serverpod quickstart my_project + $ serverpod quickstart my_project ``` - Follow the prompts to choose your code agent or editor and configure your project. Navigate with your mouse or arrow keys, press `Space` to select, and press `Enter` to create the project. Serverpod uses your selection to set up the project for your selected agent or editor. - -2. When setup finishes, open the newly created `my_project` folder in the agent or editor you selected. - Serverpod creates a `my_project` folder with three packages: +2. Follow the prompts to choose your code editor or agent. Navigate with your mouse or arrow keys, press `Space` to select, and press `Enter` to create the project. - - `my_project_server` is your backend. - - `my_project_client` is generated code that your app uses to call the server. - - `my_project_flutter` is your Flutter app. +3. Open the `my_project` folder in your selected agent or editor. It’s already set up with Serverpod skills and MCP servers for your agent :::important -**If you use Cursor**, you need to turn on the Serverpod and Dart MCP servers. Open **Customize** in the sidebar, click **MCPs**, and turn on both servers. +**If you use Cursor**, turn on the Serverpod and Dart MCP servers. Open **Customize** in the sidebar, click **MCPs**, and turn on both servers. ::: ## Start your server and app -Open the project folder in your terminal and run the [`serverpod start`](./concepts/server-fundamentals/running-your-server) command: +From the my_project folder, run [`serverpod start`](./concepts/server-fundamentals/running-your-server): ```bash -serverpod start +$ cd my_project +$ serverpod start ``` -Keep the terminal open while the app is running. The command starts the local development environment, including the server, Flutter app, and local database. The first start takes a few minutes, because Serverpod downloads PostgreSQL and builds the app. +This starts your server, Flutter app, and database. The first start takes a few minutes while Serverpod downloads PostgreSQL and builds the app. -When it's ready, the sample app opens in your browser. Try it out by entering your name and clicking **Send**. The server sends back a greeting. +When it's ready, the sample app opens in your browser. Enter your name and click Send to get a greeting from the server. -Keep this terminal running. It watches your files and reloads the app every time the agent changes the code. +Keep this terminal running. It reloads the app whenever your code changes. ## Build your app -Instruct your AI agent to build your app. Here are a few simple prompts that you can try: +Instruct your agent to build your app. Here are a few prompts that you can try: @@ -143,44 +161,48 @@ Instruct your AI agent to build your app. Here are a few simple prompts that you - -The agent writes the server code, creates the database tables, and builds the screens. When it's finished, it reloads the app and displays the new app on the browser. +The agent writes the server code, creates the database tables, and builds the screens. When it's finished, it reloads the app in your browser. :::tip -- If your app uses authentication, the verification code will be displayed as an alert in Serverpod's CLI. Press the `C` key to copy the code. -- If the app fails to reload, click `R` in the terminal running `serverpod start` to force restart the server and the app. +- If your app uses authentication, the terminal running `serverpod start` shows the verification code. Press the `C` key to copy the code. +- If the app fails to reload, press the `R` key in the terminal running `serverpod start` to force a restart of the server and the app. ::: - ## Deploy your app to Serverpod Cloud -To share your app with others, deploy it to **[Serverpod Cloud](/cloud)**. Serverpod Cloud hosts your backend, database, and web app, and gives you a public URL that anyone can access. Your first project includes a one-month free trial, and you don't need a credit card. +Deploy your app to Serverpod Cloud to make it publicly accessible. Your first project includes a one-month free trial with no credit card required. + +1. Create an account in the [Serverpod Cloud Console](https://console.serverpod.dev/). -1. Create an account on the **[Serverpod Cloud Console](https://console.serverpod.dev/)**. -2. Create a project and turn on the database. -3. In the `my_project` folder, run: +2. From your `my_project` folder, run: ```bash - serverpod cloud launch + $ serverpod cloud launch ``` -4. Follow the prompts to authenticate in the browser and select your Cloud account. -5. Back in the terminal, select the project you want to deploy +3. In the browser window that opens, select your account. -This links your project to Cloud and deploys your backend along with your web app. Wait for the deployment to finish, then use the deployed app URL provided by the CLI or Cloud Console to open your app publicly. +4. Back in the terminal, select **Open the browser and create a new project**. Your browser opens the project creation page. Enter a project name and click **Launch Project**. -After the first launch, you redeploy any changes by running `serverpod cloud launch` again. +5. When deployment finishes, the terminal shows your app's URLs: -:::tip + ```text + When the server has started, you can access it at: + Web: https://my-project.serverpod.space/ + API: https://my-project.api.serverpod.space/ + Insights: https://my-project.insights.serverpod.space/ + ``` -In the **[Serverpod Cloud Console](https://console.serverpod.dev/)**, open your project and use the **Logs**, **Sessions**, and **Metrics** tabs to monitor your app. See **[Serverpod Cloud guide](/cloud_docs/)** to learn more. +Your app is now live on the web. Open the **Web** URL to try it, and send the link to anyone you want to share it with. -::: +To deploy later changes, run `serverpod cloud launch` again. -## Get help +## Next steps -We welcome feedback on agent skills, MCP servers, and the `serverpod start` workflow. If you run into issues, reach out on **[Discord](https://serverpod.dev/discord)** or file an issue on **[GitHub](https://github.com/serverpod/serverpod)**. Pull requests are welcome. +- [Learn how Serverpod works](./03-how-it-works.md): See how your agent builds with Serverpod, and how endpoints, data models, and the database fit together. +- [Monitor your app](/cloud): Use the Logs, Sessions, and Metrics tabs in the [Serverpod Cloud Console](https://console.serverpod.dev/). +- Have feedback or questions? Tell us on [Discord](https://serverpod.dev/discord) or open an issue on [GitHub](https://github.com/serverpod/serverpod). -Happy building with Serverpod 4. +Happy building with Serverpod 4! diff --git a/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md b/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md index 84c3ca51..e28bc912 100644 --- a/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md +++ b/versioned_docs/version-4.0.0/04-get-started/02-quickstart.md @@ -8,6 +8,7 @@ slug: /quickstart import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import CollapsibleCodeBlock from '@site/src/components/CollapsibleCodeBlock'; # Quickstart @@ -15,86 +16,109 @@ This quickstart shows you how to build a full-stack Flutter and Serverpod app wi ## Prerequisites -- [Flutter](https://flutter.dev/docs/get-started/install) 3.44.4 or later, which includes Dart 3.12.2 - An AI coding agent, such as Claude Code, Cursor, or Antigravity -To check your Flutter version, run: +## Install Serverpod -```bash -flutter doctor -``` + + -:::info -You don't need to install or set up a database. New projects use an embedded PostgreSQL database that Serverpod downloads and runs for you. -::: +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. -## Install Serverpod + + +```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 `. +``` + + + + :::warning If you installed an earlier version of Serverpod with `dart pub global activate`, remove it before you install: ```bash -dart pub global deactivate serverpod_cli +$ dart pub global deactivate serverpod_cli ``` ::: -1. Install the Serverpod CLI with Dart: +1. Install [Flutter](https://docs.flutter.dev/get-started/install) 3.44.4 or later (which includes Dart 3.12.2 or later). To check your version, run `flutter doctor`. +2. Install the Serverpod CLI: ```bash - dart install serverpod_cli + $ dart install serverpod_cli ``` -2. Verify the installation: +3. To make the `serverpod` command available in new terminals, add the Dart install directory to your `PATH`: + + + ```bash - serverpod + $ echo 'export PATH="$PATH:$HOME/Library/Application Support/Dart/install/bin"' >> ~/.zshrc ``` - You'll see a list of Serverpod commands. + + -3. To make the `serverpod` command available in new terminals, add the Dart install directory to your `PATH`: + ```bash + $ echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc + ``` - - + + - ```bash - echo 'export PATH="$PATH:$HOME/Library/Application Support/Dart/install/bin"' >> ~/.zshrc - ``` + ```powershell + [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Pub\Cache\bin", "User") + ``` - - + + - ```bash - echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashr - source ~/.bashrc - ``` +4. Open a new terminal and verify the installation: - - + ```bash + $ serverpod + ``` - ```powershell - [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:LOCALAPPDATA\Pub\Cache\bin", "User") - ``` + You'll see a list of Serverpod commands. - - + + ## Create your project -1. Create a new Serverpod project with the `quickstart` command: +1. Create a new Serverpod project: ```bash - serverpod quickstart my_project + $ serverpod quickstart my_project ``` -2. Follow the prompts to choose your code editor or agent and configure your project. Navigate with your mouse or arrow keys, press `Space` to select, and press `Enter` to create the project. Serverpod configures the project for that editor or agent. - -3. Open the `my_project` folder in the editor you selected. It's already set up with Serverpod skills and MCP servers for your agent, and it contains three packages: +2. Follow the prompts to choose your code editor or agent. Navigate with your mouse or arrow keys, press `Space` to select, and press `Enter` to create the project. - - `my_project_server` is your backend. - - `my_project_client` is generated code that your app uses to call the server. - - `my_project_flutter` is your Flutter app. +3. Open the `my_project` folder in your selected agent or editor. It’s already set up with Serverpod skills and MCP servers for your agent :::important **If you use Cursor**, turn on the Serverpod and Dart MCP servers. Open **Customize** in the sidebar, click **MCPs**, and turn on both servers. @@ -102,18 +126,18 @@ dart pub global deactivate serverpod_cli ## Start your server and app -In your terminal, go to the `my_project` folder and run the [`serverpod start`](./concepts/server-fundamentals/running-your-server) command: +From the my_project folder, run [`serverpod start`](./concepts/server-fundamentals/running-your-server): ```bash -cd my_project -serverpod start +$ cd my_project +$ serverpod start ``` -The command starts the local development environment, including the server, Flutter app, and database. The first start takes a few minutes because Serverpod downloads PostgreSQL and builds the app. +This starts your server, Flutter app, and database. The first start takes a few minutes while Serverpod downloads PostgreSQL and builds the app. -When it's ready, the sample app opens in your browser. Try it out by entering your name and clicking **Send**. The server sends back a greeting. +When it's ready, the sample app opens in your browser. Enter your name and click Send to get a greeting from the server. -Keep this terminal running. It watches your files and reloads the app every time the code changes. +Keep this terminal running. It reloads the app whenever your code changes. ## Build your app @@ -148,36 +172,37 @@ The agent writes the server code, creates the database tables, and builds the sc ## Deploy your app to Serverpod Cloud -To share your app with others, deploy it to [Serverpod Cloud](/cloud). Serverpod Cloud hosts your backend, database, and web app, and gives you a public URL that anyone can access. Your first project includes a one-month free trial, with no credit card required. +Deploy your app to Serverpod Cloud to make it publicly accessible. Your first project includes a one-month free trial with no credit card required. -1. Create an account on the [Serverpod Cloud Console](https://console.serverpod.dev/). -2. Create a new project on the Cloud Console. -3. From the `my_project` folder, run: +1. Create an account in the [Serverpod Cloud Console](https://console.serverpod.dev/). + +2. From your `my_project` folder, run: ```bash - scloud launch + $ serverpod cloud launch ``` -4. Follow the prompts to sign in from the browser and select your Serverpod Cloud account. -5. Back in the terminal, select the Serverpod Cloud project you just created. +3. In the browser window that opens, select your account. -`scloud launch` links your project to Cloud and deploys your backend along with your web app. When the launch completes, the terminal displays the URLs for your deployed app and server: +4. Back in the terminal, select **Open the browser and create a new project**. Your browser opens the project creation page. Enter a project name and click **Launch Project**. -```text -When the server has started, you can access it at: - Web: https://my-project.serverpod.space/ - API: https://my-project.api.serverpod.space/ - Insights: https://my-project.insights.serverpod.space/ -``` +5. When deployment finishes, the terminal shows your app's URLs: + + ```text + When the server has started, you can access it at: + Web: https://my-project.serverpod.space/ + API: https://my-project.api.serverpod.space/ + Insights: https://my-project.insights.serverpod.space/ + ``` -- **Web:** Your Flutter web app. Open this URL to try your app or share it with others. -- **API:** Your backend endpoint. Your app uses this URL to communicate with the server. -- **Insights:** The endpoint used to connect Serverpod Insights and monitor your server. +Your app is now live on the web. Open the **Web** URL to try it, and send the link to anyone you want to share it with. -After the first launch, you can deploy any changes by running `scloud launch` again. +To deploy later changes, run `serverpod cloud launch` again. -To monitor your app, use the **Logs**, **Sessions**, and **Metrics** tabs in the [Serverpod Cloud Console](https://console.serverpod.dev/). To learn more, see the [Serverpod Cloud guide](/cloud). +## Next steps -Your full-stack app is now live on the web. Have feedback on the agent skills, MCP servers, or the `serverpod start` workflow? Tell us on [Discord](https://serverpod.dev/discord) or open an issue on [GitHub](https://github.com/serverpod/serverpod). +- [Learn how Serverpod works](./03-how-it-works.md): See how your agent builds with Serverpod, and how endpoints, data models, and the database fit together. +- [Monitor your app](/cloud): Use the Logs, Sessions, and Metrics tabs in the [Serverpod Cloud Console](https://console.serverpod.dev/). +- Have feedback or questions? Tell us on [Discord](https://serverpod.dev/discord) or open an issue on [GitHub](https://github.com/serverpod/serverpod). Happy building with Serverpod 4!