feat: app bundle, DMG and App Store (macOS & iOS) distribution docs

src/content/docs/distribute/app-store.mdx

@@ -2,11 +2,317 @@
 title: App Store
 sidebar:
   order: 1
-  badge:
-    text: Stub
-    variant: caution
 ---
 
-import Stub from '@components/Stub.astro';
+import CommandTabs from '@components/CommandTabs.astro';
 
-<Stub />
+The [Apple App Store] is the app marketplace maintained by Apple.
+You can distribute your Tauri app targeting macOS and iOS via this App Store.
+
+This guide only covers details for distributing apps directly to the App Store.
+See the general [App Bundle][App Bundle distribution guide] for more information on macOS distribution options and configurations.
+
+## Requirements
+
+Distributing iOS and macOS apps requires enrolling to the [Apple Developer] program.
+
+Additionally, you must setup code signing for [macOS][macOS code signing] and [iOS][iOS code signing].
+
+## Changing App Icon
+
+After running `tauri ios init` to setup the Xcode project, you can use the `tauri icon` command to update the app icons.
+
+<CommandTabs
+  npm="npm run tauri icon /path/to/app-icon.png --ios-color #fff"
+  yarn="yarn tauri icon /path/to/app-icon.png --ios-color #fff"
+  pnpm="pnpm tauri icon /path/to/app-icon.png --ios-color #fff"
+  cargo="cargo tauri icon /path/to/app-icon.png --ios-color #fff"
+/>
+
+The `--ios-color` argument defines the background color for the iOS icons.
+
+## Setting up
+
+After enrolling to the Apple Developer program, the first step to distribute your Tauri app in the App Store
+is to register your app in the [App Store Connect][app-store-connect-apps].
+
+:::note
+The value provided in the _Bundle ID_ field **must** match the identifier defined in [`tauri.conf.json > identifier`].
+:::
+
+## Build and upload
+
+The Tauri CLI can package your app for macOS and iOS. Running on a macOS machine is a requirement.
+
+:::caution
+Code signing is required. See the documentation for [macOS][macOS code signing] and [iOS][iOS code signing].
+:::
+
+Note that Tauri leverages Xcode for the iOS app so you can use Xcode to archive and distribute for iOS instead of the Tauri CLI.
+To open the iOS project in Xcode for building you must run the following command:
+
+<CommandTabs
+  npm="npm run tauri ios build --open"
+  yarn="yarn tauri ios build --open"
+  pnpm="pnpm tauri ios build --open"
+  cargo="cargo tauri ios build --open"
+/>
+
+### macOS
+
+To upload your app to the App Store, first you must ensure all required configuration options are set
+so you can package the App Bundle, create a signed `.pkg` file and upload it.
+
+The following sections will guide you through the process.
+
+#### Setup
+
+Your app must include some configurations to be accepted by the App Store verification system.
+
+:::tip
+The following sections guides you through configuring your app for App Store submissions.
+
+To apply the following config changes only when building for App Store, you can create a separate Tauri configuration file:
+
+```json title="src-tauri/tauri.appstore.conf.json
+{
+  "bundle": {
+    "macOS": {
+      "entitlements": "./Entitlements.plist",
+      "files": {
+        "embedded.provisionprofile": "path/to/profile-name.provisionprofile"
+      }
+    }
+  }
+}
+```
+
+Then merge that config file with the main one when bundling your Tauri app for App Store:
+
+<CommandTabs
+  npm="npm run tauri build --no-bundle
+npm run tauri bundle --bundles app --target universal-apple-darwin --config src-tauri/tauri.appstore.conf.json"
+  yarn="yarn tauri build --no-bundle
+yarn tauri bundle --bundles app --target universal-apple-darwin --config src-tauri/tauri.appstore.conf.json"
+  pnpm="pnpm tauri build --no-bundle
+pnpm tauri bundle --bundles app --target universal-apple-darwin --config src-tauri/tauri.appstore.conf.json"
+  cargo="cargo tauri build --no-bundle
+cargo tauri bundle --bundles app --target universal-apple-darwin --config src-tauri/tauri.appstore.conf.json"
+/>
+
+This is particularly useful when setting up your CI/CD to upload your app to the App Store while not requiring the provision profile locally or
+when compiling the app for distribution outside the App Store.
+
+:::
+
+- Category
+
+Your app must define its [`tauri.conf.json > bundle > category`] to be displayed in the App Store:
+
+```json title="tauri.conf.json" ins={3}
+{
+  "bundle": {
+    "category": "Utility"
+  }
+}
+```
+
+- Provisioning profile
+
+You must also create a provisioning profile for your app to be accepted by Apple.
+
+In the [Identifiers](https://developer.apple.com/account/resources/identifiers/list) page,
+create a new App ID and make sure its "Bundle ID" value matches the identifier set in [`tauri.conf.json > identifier`].
+
+Navigate to the [Profiles](https://developer.apple.com/account/resources/profiles/list) page to create a new provisioning profile.
+For App Store macOS distribution, it must be a "Mac App Store Connect" profile.
+Select the appropriate App ID and link the certificate you are using for code signing.
+
+After creating the provisioning profile, download it and save it to a known location and configure Tauri to include it in your app bundle:
+
+```json title="tauri.conf.json" ins={4-6}
+{
+  "bundle": {
+    "macOS": {
+      "files": {
+        "embedded.provisionprofile": "path/to/profile-name.provisionprofile"
+      }
+    }
+  }
+}
+```
+
+- Info.plist
+
+Your app must comply with encryption export regulations.
+See the [official documentation](https://developer.apple.com/documentation/security/complying-with-encryption-export-regulations?language=objc)
+for more information.
+
+Create a Info.plist file in the src-tauri folder:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>ITSAppUsesNonExemptEncryption</key>
+	<false/> # or `true` if your app uses encryption
+</dict>
+</plist>
+```
+
+- Entitlements
+
+Your app must include the App Sandbox capability to be distributed in the App Store.
+Additionally, you must also set your App ID and Team ID in the code signing entitlements.
+
+Create a `Entitlements.plist` file in the `src-tauri` folder:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.app-sandbox</key>
+    <true/>
+    <key>com.apple.application-identifier</key>
+    <string>$TEAM_ID.$IDENTIFIER</string>
+    <key>com.apple.developer.team-identifier</key>
+    <string>$TEAM_ID</string>
+</dict>
+</plist>
+```
+
+Note that you must replace `$IDENTIFIER` with the [`tauri.conf.json > identifier`] value
+and `$TEAM_ID` with your Apple Developer team ID, which can be found in the `App ID Prefix` section in the
+[Identifier](https://developer.apple.com/account/resources/identifiers/list) you created for the provisioning profile.
+
+And reference that file in the macOS bundle configuration [`tauri.conf.json > bundle > macOS > entitlements`]:
+
+```json title="tauri.conf.json" ins={4}
+{
+  "bundle": {
+    "macOS": {
+      "entitlements": "./Entitlements.plist"
+    }
+  }
+}
+```
+
+You now must build your application with code signing enabled for the entitlements to apply.
+
+Make sure your app works when running in an App Sandbox context.
+
+#### Build
+
+You must upload your macOS application as a `.pkg` file to the App Store.
+Run the following command to package your app as a macOS App Bundle (`.app` extension):
+
+```
+tauri build --bundles app --target universal-apple-darwin
+```
+
+:::note
+The above command creates an Universal App Binary application, supporting both Apple Silicon and Intel processors.
+
+If you prefer to only support Apple Silicon instead, you must change [`tauri.conf.json > bundle > macOS > minimumSystemVersion`] to `12.0`:
+
+```json title="tauri.conf.json" ins={4}
+{
+  "bundle": {
+    "macOS": {
+      "minimumSystemVersion": "12.0"
+    }
+  }
+}
+```
+
+And change the CLI command and output path based on the Mac system you are running:
+
+- if your build system uses an Apple Silicon chip, remove the `--target universal-apple-darwin` arguments and use `target/release`
+  instead of `target/universal-apple-darwin/release` in the paths referenced below.
+- if your build system uses an Intel chip:
+  - install the Rust Apple Silicon target:
+    ```
+    rustup target add aarch64-apple-darwin
+    ```
+  - change the `universal-apple-darwin` argument to `aarch64-apple-darwin`
+    and use `target/aarch64-apple-darwin/release` instead of `target/universal-apple-darwin/release` in the paths referenced below.
+
+:::
+
+See the [App Bundle distribution guide] for more information on configuration options.
+
+To generate a signed `.pkg` from your app bundle, run the following command:
+
+```
+xcrun productbuild --sign "<certificate signing identity>" --component "target/universal-apple-darwin/release/bundle/macos/$APPNAME.app" /Applications "$APPNAME.pkg"
+```
+
+Note that you must replace _$APPNAME_ with your app name.
+
+:::note
+You must sign the PKG with a _Mac Installer Distribution_ signing certificate.
+:::
+
+#### Upload
+
+Now you can use the [`altool`] CLI to upload your app PKG to the App Store:
+
+```
+xcrun altool --upload-app --type macos --file "$APPNAME.pkg" --apiKey $APPLE_API_KEY_ID --apiIssuer $APPLE_API_ISSUER
+```
+
+Note that `altool` requires an App Store Connect API key to upload your app.
+See the [authentication section] for more information.
+
+Your app will then be validated by Apple and available in TestFlight if approved.
+
+### iOS
+
+To build your iOS app, run the `tauri ios build` command:
+
+<CommandTabs
+  npm="npm run tauri ios build --export-method app-store-connect"
+  yarn="yarn tauri ios build --export-method app-store-connect"
+  pnpm="pnpm tauri ios build --export-method app-store-connect"
+  cargo="cargo tauri ios build --export-method app-store-connect"
+/>
+
+The generated IPA file can be found in `src-tauri/gen/apple/build/arm64/$APPNAME.ipa`.
+
+Note that you must replace _$APPNAME_ with your app name.
+
+Now you can use the `altool` CLI to upload your iOS app to the App Store:
+
+```
+xcrun altool --upload-app --type ios --file "src-tauri/gen/apple/build/arm64/$APPNAME.ipa" --apiKey $APPLE_API_KEY_ID --apiIssuer $APPLE_API_ISSUER
+```
+
+Note that `altool` requires an App Store Connect API key to upload your app.
+See the [authentication section] for more information.
+
+Your app will then be validated by Apple and available in TestFlight if approved.
+
+### Authentication
+
+The iOS and macOS apps are uploaded using `altool`, which uses an App Store Connect API key to authenticate.
+
+To create a new API key, open the [App Store Connect's Users and Access page], select the Keys tab, click on the Add button and select a name and the Developer access.
+The `APPLE_API_ISSUER` (Issuer ID) is presented above the keys table, and the `APPLE_API_KEY_ID` is the value on the Key ID column on that table.
+You also need to download the private key, which can only be done once and is only visible after a page reload (the button is shown on the table row for the newly created key).
+The private key file path must be saved as `AuthKey\_<APPLE_API_KEY_ID>.p8` in one of these directories:`<current-working-directory>/private_keys`, `~/private_keys`, `~/.private_keys`or`~/.appstoreconnect/private_keys`.
+
+[App Bundle distribution guide]: /distribute/macos-application-bundle
+[Apple Developer]: https://developer.apple.com
+[Apple App Store]: https://www.apple.com/store
+[`altool`]: https://help.apple.com/itc/apploader/#/apdATD1E53-D1E1A1303-D1E53A1126
+[macOS code signing]: /distribute/signing/macos
+[iOS code signing]: /distribute/signing/ios
+[app-store-connect-apps]: https://appstoreconnect.apple.com/apps
+[`tauri.conf.json > identifier`]: /reference/config/#identifier
+[`tauri.conf.json > bundle > category`]: /reference/config/#category
+[`tauri.conf.json > bundle > macOS > entitlements`]: /reference/config/#entitlements
+[`tauri.conf.json > bundle > macOS > minimumSystemVersion`]: /reference/config/#minimumsystemversion
+[App Store Connect's Users and Access page]: https://appstoreconnect.apple.com/access/users
+[authentication section]: #authentication