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 397877b6..afe12e11 100644 --- a/docs/04-get-started/02-quickstart.md +++ b/docs/04-get-started/02-quickstart.md @@ -8,81 +8,142 @@ slug: /quickstart import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import CollapsibleCodeBlock from '@site/src/components/CollapsibleCodeBlock'; # 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. +- An AI coding agent, such as Claude Code, Cursor, or Antigravity -:::info -Check your Flutter installation by running the following command in your terminal: +## Install Serverpod -```bash -$ flutter doctor -``` + + -::: +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. -New projects use an embedded PostgreSQL that Serverpod downloads and runs for you, so no database setup is needed. + -## 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. -Serverpod is installed using the Dart package manager. To install Serverpod, run the following command in your terminal: +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. -```txt -$ dart install serverpod_cli -``` +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. -Verify the installation by running: +Already installed +- -```bash -$ serverpod +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 a previous version of Serverpod is already installed with `dart pub global activate`, deactivate it before installing or upgrading: +:::warning +If you installed an earlier version of Serverpod with `dart pub global activate`, remove it before you install: -```txt +```bash $ dart pub global deactivate serverpod_cli ``` ::: -## Create the project +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: -Use Serverpod's `quickstart` command to create a new project. + ```bash + $ dart install serverpod_cli + ``` -```bash -$ serverpod quickstart my_project -``` +3. To make the `serverpod` command available in new terminals, add the Dart install directory to your `PATH`: -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/Library/Application Support/Dart/install/bin"' >> ~/.zshrc + ``` -:::important + + + + ```bash + $ echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc + ``` + + + + + Run this in PowerShell: + + ```powershell + [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Dart\install\bin", "User") + ``` + + + -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. +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: + + ```bash + $ serverpod quickstart my_project + ``` + +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. + +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. ::: -## 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: +From the my_project folder, run [`serverpod start`](./concepts/server-fundamentals/running-your-server): ```bash +$ 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. +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. Enter your name and click Send to get a greeting from the server. + +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: @@ -102,44 +163,48 @@ 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 - -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 your app to Serverpod Cloud to make it publicly accessible. Your first project includes a one-month free trial with no credit card required. -## Deploy the app to the cloud +1. Create an account in the [Serverpod Cloud Console](https://console.serverpod.dev/). -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. +2. From your `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 -``` +3. In the browser window that opens, select your account. -This links your project to Cloud and deploys your backend along with the web build of your app. +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 see what your server is doing. +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/docs/06-concepts/cli/_generated/cloud.md b/docs/06-concepts/cli/_generated/cloud.md deleted file mode 100644 index e69de29b..00000000 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 e69de29b..00000000 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..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,81 +8,140 @@ slug: /quickstart import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import CollapsibleCodeBlock from '@site/src/components/CollapsibleCodeBlock'; # 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. +- An AI coding agent, such as Claude Code, Cursor, or Antigravity -:::info -Check your Flutter installation by running the following command in your terminal: +## Install Serverpod -```bash -$ flutter doctor -``` + + -::: +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. -New projects use an embedded PostgreSQL that Serverpod downloads and runs for you, so no database setup is needed. + -## 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. -Serverpod is installed using the Dart package manager. To install Serverpod, run the following command in your terminal: +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. -```txt -$ dart install serverpod_cli -``` +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. -Verify the installation by running: +Already installed +- -```bash -$ serverpod +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 a previous version of Serverpod is already installed with `dart pub global activate`, deactivate it before installing or upgrading: +:::warning +If you installed an earlier version of Serverpod with `dart pub global activate`, remove it before you install: -```txt +```bash $ dart pub global deactivate serverpod_cli ``` ::: -## Create the project +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: -Use Serverpod's `quickstart` command to create a new project. + ```bash + $ dart install serverpod_cli + ``` -```bash -$ serverpod quickstart my_project -``` +3. To make the `serverpod` command available in new terminals, add the Dart install directory to your `PATH`: -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/Library/Application Support/Dart/install/bin"' >> ~/.zshrc + ``` -:::important + + + + ```bash + $ echo 'export PATH="$PATH:$HOME/.pub-cache/bin"' >> ~/.bashrc + ``` + + + + + ```powershell + [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Pub\Cache\bin", "User") + ``` + + + -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. +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: + + ```bash + $ serverpod quickstart my_project + ``` + +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. + +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. ::: -## 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: +From the my_project folder, run [`serverpod start`](./concepts/server-fundamentals/running-your-server): ```bash +$ 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. +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. Enter your name and click Send to get a greeting from the server. + +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: @@ -102,44 +161,48 @@ 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 - -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 your app to Serverpod Cloud to make it publicly accessible. Your first project includes a one-month free trial with no credit card required. -## Deploy the app to the cloud +1. Create an account in the [Serverpod Cloud Console](https://console.serverpod.dev/). -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. +2. From your `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 -``` +3. In the browser window that opens, select your account. -This links your project to Cloud and deploys your backend along with the web build of your app. +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 see what your server is doing. +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!