diff --git a/astro.config.mjs b/astro.config.mjs index b6c7e9de..badb5407 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -70,7 +70,6 @@ export default defineConfig({ }, customCss: ['./src/styles/custom.css'], sidebar: [ - { label: 'Welcome', link: '/' }, { label: 'Getting Started', collapsed: true, diff --git a/src/content/docs/getting-started/index.mdx b/src/content/docs/getting-started/index.mdx index b7d82cd7..17c853b3 100644 --- a/src/content/docs/getting-started/index.mdx +++ b/src/content/docs/getting-started/index.mdx @@ -1,6 +1,6 @@ --- title: Quick Start -description: The easy way to get started with Shorebird +description: Install Shorebird and create your first release. sidebar: order: 1 --- @@ -10,216 +10,181 @@ import { LinkButton, LinkCard, } from 'starlight-theme-nova/components'; +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; -Welcome to Shorebird! πŸ‘‹ +{/* TODO: Add 2-minute installation walkthrough video */} -In this guide, we'll walk you through setting up Shorebird and integrating it -into your app in just a few minutes. +This guide walks you through installing Shorebird and integrating it into your +Flutter app. -## Sign up +## Prerequisites -The first thing you'll need to do is sign up for a Shorebird account. It's free -to do and you can sign up in a matter of seconds. +- Flutter 3.24.0 or later + ([install Flutter](https://docs.flutter.dev/get-started/install)) +- `git` installed locally - - Create an Account - +## Installation -## Install + -While a full install may not be required to access and use all of our product -offerings, we recommend installing everything locally to make debugging easier -as you continue using our services. +1. **Sign up** for a free Shorebird account. -### Using install script + + Create an Account + -To install the Shorebird command line interface (CLI): +2. **Install Shorebird.** - -```bash title="Mac/Linux" -curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash -``` + -```powershell title="Windows" -Set-ExecutionPolicy RemoteSigned -scope CurrentUser # Needed to execute remote scripts -iwr -UseBasicParsing 'https://raw.githubusercontent.com/shorebirdtech/install/main/install.ps1'|iex -``` + - + Paste the following into any AI assistant (Claude, ChatGPT, etc.) for guided + installation: -:::note + ``` + Install Shorebird on my machine. Shorebird is a Flutter code push tool. -Installing Shorebird CLI requires `git`. + Mac/Linux: + curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash -::: + Windows: + Set-ExecutionPolicy RemoteSigned -scope CurrentUser + iwr -UseBasicParsing 'https://raw.githubusercontent.com/shorebirdtech/install/main/install.ps1' | iex -This installs `shorebird` into `~/.shorebird/bin` (or -`%USERPROFILE%\.shorebird\bin` on Windows) and adds it to your `PATH`. It also -installs a copy of Flutter and Dart inside `~/.shorebird/bin/cache/flutter` (or -`%USERPROFILE%\.shorebird\bin\cache\flutter` on Windows). The copy of Flutter is -slightly modified to add Shorebird code push and is not intended to be added to -your `PATH`. You can continue to use the versions of Flutter and Dart you -already have installed. + After installing, run `shorebird doctor` to verify and help me fix any issues. + ``` -### Manually installing + -Shorebird can also be manually installed, allowing users to choose where the -installation will be placed. + -In order to do so, in a terminal, inside the folder where Shorebird should be -installed at, run: + Run the install script for your platform: -```bash -git clone -b stable https://github.com/shorebirdtech/shorebird.git -``` + + ```bash title="Mac/Linux" + curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash + ``` -Add the `bin` folder from the repository you just cloned into your `PATH`. For -example: + ```powershell title="Windows" + Set-ExecutionPolicy RemoteSigned -scope CurrentUser + iwr -UseBasicParsing 'https://raw.githubusercontent.com/shorebirdtech/install/main/install.ps1' | iex + ``` + - -```bash title="Bash/Zsh" -# Add to shell profile (e.g., ~/.zshrc or ~/.bashrc) -export PATH="$PATH:/path/to/cloned/shorebird/bin" -``` + This installs `shorebird` into `~/.shorebird/bin` and adds it to your `PATH`. + It also installs a bundled copy of Flutter at + `~/.shorebird/bin/cache/flutter` β€” modified to support code push and separate + from your existing Flutter install. -```powershell title="Windows PowerShell" -# Add to User PATH variable -[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\path\to\cloned\shorebird\bin", "User") -``` + - + -:::note + Clone the repository into the directory where you want Shorebird installed: -The total installation is about 300mb. + ```bash + git clone -b stable https://github.com/shorebirdtech/shorebird.git + ``` -::: + Add the `bin` folder to your `PATH`, for example: -Once the installation has completed, `shorebird` should be available in your -terminal: + + ```bash title="Bash/Zsh" + # Add to shell profile (e.g., ~/.zshrc or ~/.bashrc) + export PATH="$PATH:/path/to/cloned/shorebird/bin" + ``` -``` -$ shorebird -The shorebird command-line tool - -Usage: shorebird [arguments] - -Global options: --h, --help Print this usage information. - --version Print the current version. - --json Output results in JSON format (implies non-interactive mode). --v, --[no-]verbose Noisy logging, including all shell commands executed. - -Available commands: - account Manage your Shorebird account. - cache Manage the Shorebird cache. - create Create a new Flutter project with Shorebird. - doctor Show information about the installed tooling. - flutter Manage your Shorebird Flutter installation. - init Initialize Shorebird. - login Login as a new Shorebird user. - logout Logout of the current Shorebird user. - patch Creates a shorebird patch for the provided target platforms. - patches Manage Shorebird patches. - preview Preview a specific release on a device. - release Creates a shorebird release for the provided target platforms. - releases Manage Shorebird releases. - upgrade Upgrade your copy of Shorebird. - -Run "shorebird help " for more information about a command. -``` + ```powershell title="Windows PowerShell" + # Add to User PATH variable + [Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\path\to\cloned\shorebird\bin", "User") + ``` + -:::tip[`--json` flag for CI scripting] + -All Shorebird commands accept a global `--json` flag that switches output to -structured JSON instead of human-readable text. This is useful for parsing CLI -results in shell scripts or CI pipelines: + -```sh -shorebird account apps --json -shorebird releases list --json -shorebird patches list --json -``` + Run `shorebird --help` to see all available commands. -::: +3. **Verify** your setup. -You can use `shorebird doctor` to ensure things are set up correctly: + Restart your terminal to reload your `PATH`, then verify your setup by + running the following command: -```sh -shorebird doctor -``` + ```sh + shorebird doctor + ``` -Example output: + Example output: -``` -$ shorebird doctor -Shorebird 1.5.1 β€’ git@github.com:shorebirdtech/shorebird.git -Flutter 3.27.0 β€’ revision 1e0e5760eeaf534c280cf59ee0504d0e2ba12a7b -Engine β€’ revision 59571a1190752bc1740bff652ce5f0ba7c9413f8 - -URL Reachability -βœ“ https://api.shorebird.dev OK (0.1s) -βœ“ https://console.shorebird.dev OK (0.1s) -βœ“ https://oauth2.googleapis.com OK (60ms) -βœ“ https://storage.googleapis.com OK (0.2s) -βœ“ https://cdn.shorebird.cloud OK (0.1s) - -βœ“ Shorebird is up-to-date (1.4s) -βœ“ Flutter install is correct (0.4s) - -No issues detected! -``` + ``` + $ shorebird doctor + Shorebird 1.5.1 β€’ git@github.com:shorebirdtech/shorebird.git + Flutter 3.27.0 β€’ revision 1e0e5760eeaf534c280cf59ee0504d0e2ba12a7b + Engine β€’ revision 59571a1190752bc1740bff652ce5f0ba7c9413f8 -:::tip[Useful `doctor` flags] + URL Reachability + βœ“ https://api.shorebird.dev OK (0.1s) + βœ“ https://console.shorebird.dev OK (0.1s) + βœ“ https://oauth2.googleapis.com OK (60ms) + βœ“ https://storage.googleapis.com OK (0.2s) + βœ“ https://cdn.shorebird.cloud OK (0.1s) -- **`shorebird doctor -v`** β€” verbose mode, also prints Android toolchain info - (Android Studio, SDK, ADB, Java version, Gradle) and runs a GCP network speed - test. -- **`shorebird doctor -f`** β€” attempts to auto-fix any detected issues (e.g., - adding missing `INTERNET` permission to `AndroidManifest.xml`). + βœ“ Shorebird is up-to-date (1.4s) + βœ“ Flutter install is correct (0.4s) -::: + No issues detected! + ``` -Finally, you can log in to your Shorebird account on your machine: +4. **Log in** to your Shorebird account. -```sh -shorebird login -``` + `shorebird login` opens a browser window for authentication. Return to your + terminal after logging in. -## Integrate Shorebird + ```sh + shorebird login + ``` -You're now ready to add Shorebird to your app. +5. **Integrate Shorebird** into your Flutter app. -You can start by creating a new Flutter app or navigating to the directory of -your already created Flutter app. + -To create a new Flutter app: + -```sh -shorebird create my_shorebird_app -cd my_shorebird_app -``` + Create a new Flutter app with Shorebird: -Or, to enable Shorebird for an existing Flutter app, run: + ```sh + shorebird create my_shorebird_app + cd my_shorebird_app + ``` -```sh -shorebird init -``` + -This will create a `shorebird.yaml` file in the root of your project. This file -contains your Shorebird `app_id`. Your `app_id` is not secret and can be checked -into source control and freely shared. + -This will also run `shorebird doctor` to ensure everything is set up correctly. + In your Flutter app's root directory, run: -:::note + ```sh + shorebird init + ``` -Shorebird expects to find the latest stable `flutter` installed on your machine. -Shorebird can be configured to work with older versions of Flutter (back to -3.10.0). See [Flutter Version Management](/getting-started/flutter-version) for -more info. + This creates a `shorebird.yaml` file containing your `app_id`. Your `app_id` + is not secret and can be committed to source control. -::: + + + + + :::note + + Shorebird supports Flutter 3.24.0 and later. See + [Flutter Version Management](/getting-started/flutter-version) to configure + an older version. + + ::: + + ## Keeping Shorebird Up To Date @@ -253,9 +218,6 @@ out our samples: ## Next Steps -Now that your account is set up and your app is initialized, you're all set to -begin. - Quick Start +## Explore the Docs + + + + + ## Contact Us -Still have questions? We are here to help and can be contacted in a variety of -ways. +Still have questions? Reach us through any of these channels.