From ea948ee125b067cc32fcd5665f9bfca35f1cdb28 Mon Sep 17 00:00:00 2001 From: Felix Angelov Date: Fri, 11 Oct 2024 14:29:34 -0500 Subject: [PATCH] docs: consolidate getting started and quickstart guide (#303) --- astro.config.mjs | 5 +- .../docs/guides/code-push-quickstart.mdx | 161 ------------------ .../docs/guides/submitting/app-store.mdx | 2 +- .../docs/guides/submitting/play-store.mdx | 2 +- src/content/docs/index.mdx | 160 ++++++++++++++--- 5 files changed, 139 insertions(+), 191 deletions(-) delete mode 100644 src/content/docs/guides/code-push-quickstart.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 42cf159c..64c1d5c0 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -68,10 +68,6 @@ export default defineConfig({ { label: 'Guides', items: [ - { - label: 'Code Push Quickstart', - link: '/guides/code-push-quickstart', - }, { label: 'Staging Patches', link: '/guides/staging-patches', @@ -180,6 +176,7 @@ export default defineConfig({ 'guides/crash-reporting': 'guides/crash-reporting/uploading-symbols', 'guides/fastlane': 'ci/fastlane', 'guides/flavors': 'guides/flavors/android', + 'guides/code-push-quickstart': '/', 'guides/hybrid-app': 'guides/hybrid-apps/android', 'guides/hybrid-app/android': 'guides/hybrid-apps/android', 'guides/hybrid-app/ios': 'guides/hybrid-apps/ios', diff --git a/src/content/docs/guides/code-push-quickstart.mdx b/src/content/docs/guides/code-push-quickstart.mdx deleted file mode 100644 index 6ed8654a..00000000 --- a/src/content/docs/guides/code-push-quickstart.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Code Push Quickstart -description: Try code push for yourself -sidebar: - order: 1 ---- - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -This guide shows you the fastest way to install Shorebird and try code push. - -This document is a (slightly) condensed version of our [code -push](/code-push/initialize) docs, all on one page. - -## Sign up - -Before you can create a Shorebird app, you will need to sign up for Shorebird. - -### Create an account - -To create an account, head over to the [Shorebird -Console](https://console.shorebird.dev) and authenticate with one of the available authentication methods. - -Once you have logged into the console, follow the instructions to install the -Shorebird CLI on your machine. - -## Create the app - -Once you have registered and installed the CLI, you're ready to use code push! - -Start by creating a new Flutter app: - -```sh -flutter create my_shorebird_app -``` - -As with any Flutter app, you can verify this created the standard Counter app by -following the instructions printed by `flutter create`: - -```sh -cd my_shorebird_app -flutter run -``` - -### Initialize Shorebird - -To make this a Shorebird app, run: - -```sh -shorebird init -``` - -This will create a `shorebird.yaml` file in the root of your project. This file -contains your Shorebird `app_id`. - -This will also run `shorebird doctor` to ensure everything is set up correctly. - -:::note -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](/flutter-version) for more -info. -::: - -### Create a release - -We will create a release using the unmodified Counter app. Run: - - - - - -```sh -shorebird release android -``` - - - - - -```sh -shorebird release ios -``` - - - - -When prompted, use the suggested version number (`1.0.0+1`), and enter `y` when -asked if you would like to continue. - -### Preview the release - -To preview the release with Shorebird (that is, with [Shorebird's fork of the -Flutter engine](/faq#how-does-shorebird-relate-to-flutter)), run: - -```sh -shorebird preview -``` - -Now kill the app on your device or emulator. - -### Create a patch - -We will now make a small change to the Counter app. In `lib/main.dart`, change -the app theme's `primarySwatch` from blue to green: - -```diff -class MyApp extends StatelessWidget { - const MyApp({super.key}); - - // This widget is the root of your application. - @override - Widget build(BuildContext context) { - return MaterialApp( - title: 'Flutter Demo', - theme: ThemeData( - // This is the theme of your application. - // - // Try running your application with "flutter run". You'll see the - // application has a blue toolbar. Then, without quitting the app, try - // changing the primarySwatch below to Colors.green and then invoke - // "hot reload" (press "r" in the console where you ran "flutter run", - // or simply save your changes to "hot reload" in a Flutter IDE). - // Notice that the counter didn't reset back to zero; the application - // is not restarted. -- primarySwatch: Colors.blue, -+ primarySwatch: Colors.green, - ), - home: const MyHomePage(title: 'Flutter Demo Home Page'), - ); - } -} -``` - -After making this change, save the file and run: - - - - - -```sh -shorebird patch android -``` - - - - - -```sh -shorebird patch ios -``` - - - - - -### See the patch in action - -Launch the app from your device or emulator. The app will still have the -original blue theme, but it will be downloading the patch we just created in the -background. Kill and launch the app again, and the app will be green! 🎉 diff --git a/src/content/docs/guides/submitting/app-store.mdx b/src/content/docs/guides/submitting/app-store.mdx index 16e11e3b..31a00504 100644 --- a/src/content/docs/guides/submitting/app-store.mdx +++ b/src/content/docs/guides/submitting/app-store.mdx @@ -16,7 +16,7 @@ The app we will be releasing in this guide is Shorebird Clock, our demo code pus To follow along with this guide, you will need the following: -1. An existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](/guides/code-push-quickstart/) guide. +1. An existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](/) guide. 1. Access to hardware running macOS. This is required to build iOS apps. 1. A valid Apple Developer account. This is required to release iOS apps. 1. An app in [App Store Connect](https://appstoreconnect.apple.com/). See the [official documentation](https://developer.apple.com/help/app-store-connect/create-an-app-record/add-a-new-app) for more information about how to create one. diff --git a/src/content/docs/guides/submitting/play-store.mdx b/src/content/docs/guides/submitting/play-store.mdx index 2cbb7414..5f885019 100644 --- a/src/content/docs/guides/submitting/play-store.mdx +++ b/src/content/docs/guides/submitting/play-store.mdx @@ -12,7 +12,7 @@ The app we will be releasing in this guide is [`Time Shift`](https://play.google ## Prerequisites -This guide assumes that you have an existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](/guides/code-push-quickstart/) guide. +This guide assumes that you have an existing Shorebird app. If you don't have one, you can create one by following the [code push quickstart](/) guide. ## Creating a release diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index c9dd5933..3c45437e 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -6,11 +6,22 @@ template: doc import { Tabs, TabItem } from '@astrojs/starlight/components'; -This guide will walk you through [creating an account](#sign-up), [installing Shorebird](#install), and [logging in](#login). +Welcome to Shorebird! 👋 -## Sign Up +In this guide, we'll walk you through setting up Shorebird and integrating it +into your app in just a few minutes. -To create an account, head over to the [Shorebird Console](https://console.shorebird.dev) and authenticate with your Google account. +## Sign up + +The first thing you'll need to do is sign up for a Shorebird account. This will +allow you to use the Shorebird CLI to manage your apps. + +### Create an account + +To create an account, head over to the [Shorebird +Console](https://console.shorebird.dev) and authenticate with one of the available authentication methods. Once you've authenticated, you will have a free Shorebird account. + +Next, let's install the Shorebird CLI on your machine. ## Install @@ -116,43 +127,144 @@ Engine • revision e81fa131e59506d9f6af2a0cee7de749131f1bf0 No issues detected! ``` -## Login +## Integrate Shorebird -You can login using the `shorebird login` command: +Once you have registered and installed the CLI, you're ready to use code push! + +Start by creating a new Flutter app: ```sh -shorebird login +flutter create my_shorebird_app ``` -Example output: +As with any Flutter app, you can verify this created the standard Counter app by +following the instructions printed by `flutter create`: + +```sh +cd my_shorebird_app +flutter run +``` + +### Initialize Shorebird + +To make this a Shorebird app, run: + +```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. + +:::note +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](/flutter-version) for more +info. +::: + +### Create a release + +We will create a release using the unmodified Counter app. Run: + + + + + +```sh +shorebird release android +``` + + + + +```sh +shorebird release ios ``` -shorebird login -The Shorebird CLI needs your authorization to manage apps, releases, and patches -on your behalf. -In a browser, visit this URL to log in: + + -https://accounts.google.com/o/oauth2/v2/auth... +When prompted, use the suggested version number (`1.0.0+1`), and enter `y` when +asked if you would like to continue. -Waiting for your authorization... +### Preview the release -🎉 Welcome to Shorebird! You are now logged in as . +To preview the release with Shorebird (that is, with [Shorebird's fork of the +Flutter engine](/faq#how-does-shorebird-relate-to-flutter)), run: -🔑 Credentials are stored in ./path/to/credentials.json. -🚪 To logout use: "shorebird logout". +```sh +shorebird preview ``` -That's it 🎉 +Now kill the app on your device or emulator. + +### Create a patch + +We will now make a small change to the Counter app. In `lib/main.dart`, change +the app theme's `primarySwatch` from blue to green: + +```diff +class MyApp extends StatelessWidget { + const MyApp({super.key}); + + // This widget is the root of your application. + @override + Widget build(BuildContext context) { + return MaterialApp( + title: 'Flutter Demo', + theme: ThemeData( + // This is the theme of your application. + // + // Try running your application with "flutter run". You'll see the + // application has a blue toolbar. Then, without quitting the app, try + // changing the primarySwatch below to Colors.green and then invoke + // "hot reload" (press "r" in the console where you ran "flutter run", + // or simply save your changes to "hot reload" in a Flutter IDE). + // Notice that the counter didn't reset back to zero; the application + // is not restarted. +- primarySwatch: Colors.blue, ++ primarySwatch: Colors.green, + ), + home: const MyHomePage(title: 'Flutter Demo Home Page'), + ); + } +} +``` + +After making this change, save the file and run: + + -You now have a Shorebird account, have installed Shorebird CLI on your machine, and are ready to start using Shorebird. + + +```sh +shorebird patch android +``` + + + + + +```sh +shorebird patch ios +``` + + + + + +### See the patch in action + +Launch the app from your device or emulator. The app will still have the +original blue theme, but it will be downloading the patch we just created in the +background. Kill and launch the app again, and the app will be green! 🎉 ## Connect on Discord -Shorebird has an active Discord where we're happy to help you: +Shorebird has an active Discord where we're happy to help you with any questions https://discord.gg/shorebird - -We also offer a private support channel for paying customers. We don't yet have -an automated way to add you to the channel, so please message a member of our -team on Discord and we'll happily add you to the customer support channel. -https://github.com/shorebirdtech/shorebird/issues/308