From 218a671acf4d882b1b543606d1d5006d5eb09d19 Mon Sep 17 00:00:00 2001
From: Justin Poliachik <jpoliachik@gmail.com>
Date: Fri, 16 Feb 2024 14:56:24 -0500
Subject: [PATCH] feat(docs): Add docs for ignite boilerplate files (#2634)

* boilerplate structure work

* devtools doc

* boilerplate formatting

* add several missing docs with initial content

* add maestro

* update naming and sidebar positioning

* change ordering to be alphabetical

* docs cleanup

* style nits
---
 docs/boilerplate/App.tsx.md                   |  13 +++
 docs/boilerplate/Boilerplate.md               | 101 ++++++++----------
 docs/boilerplate/android.md                   |   2 +-
 docs/boilerplate/app.json.md                  |  16 +++
 docs/boilerplate/app/_category_.json          |   4 +-
 docs/boilerplate/app/app.md                   |   2 +-
 docs/boilerplate/app/devtools/Devtools.md     |  38 +++++++
 docs/boilerplate/app/devtools/_category_.json |   8 ++
 docs/boilerplate/assets.md                    |  16 +++
 docs/boilerplate/eas.json.md                  |  45 ++++++++
 docs/boilerplate/ignite.md                    |  11 ++
 docs/boilerplate/ios.md                       |   2 +-
 docs/boilerplate/maestro.md                   |  22 ++++
 docs/boilerplate/plugins/Plugins.md           |  25 +++++
 docs/boilerplate/plugins/_category_.json      |   8 ++
 docs/boilerplate/plugins/withSplashScreen.md  |  15 +++
 docs/boilerplate/test/Test.md                 |  10 ++
 docs/boilerplate/test/_category_.json         |   8 ++
 18 files changed, 287 insertions(+), 59 deletions(-)
 create mode 100644 docs/boilerplate/App.tsx.md
 create mode 100644 docs/boilerplate/app.json.md
 create mode 100644 docs/boilerplate/app/devtools/Devtools.md
 create mode 100644 docs/boilerplate/app/devtools/_category_.json
 create mode 100644 docs/boilerplate/assets.md
 create mode 100644 docs/boilerplate/eas.json.md
 create mode 100644 docs/boilerplate/ignite.md
 create mode 100644 docs/boilerplate/maestro.md
 create mode 100644 docs/boilerplate/plugins/Plugins.md
 create mode 100644 docs/boilerplate/plugins/_category_.json
 create mode 100644 docs/boilerplate/plugins/withSplashScreen.md
 create mode 100644 docs/boilerplate/test/Test.md
 create mode 100644 docs/boilerplate/test/_category_.json

diff --git a/docs/boilerplate/App.tsx.md b/docs/boilerplate/App.tsx.md
new file mode 100644
index 000000000..4d9f74b55
--- /dev/null
+++ b/docs/boilerplate/App.tsx.md
@@ -0,0 +1,13 @@
+---
+title: App.tsx
+sidebar_position: 65
+---
+
+# App.tsx
+
+`App.tsx` is the entry point for Expo / React Native itself. It is minimal on purpose - its only responsibiliy is to:
+
+- Setup the Splash Screen
+- Immediately load our app's root component
+
+Not to be confused with [app/app.tsx](./app/app.tsx.md), which is the main root component that gets rendered.
diff --git a/docs/boilerplate/Boilerplate.md b/docs/boilerplate/Boilerplate.md
index 9b475405f..1bfbf78bd 100644
--- a/docs/boilerplate/Boilerplate.md
+++ b/docs/boilerplate/Boilerplate.md
@@ -20,9 +20,10 @@ A new Ignite boilerplate project's structure looks similar to this:
 your-project
 ├── .maestro
 ├── android
-├── ios
 ├── app
 │   ├── components
+│   ├── config
+│   ├── devtools
 │   ├── i18n
 │   ├── models
 │   ├── navigators
@@ -31,16 +32,17 @@ your-project
 │   ├── theme
 │   ├── utils
 │   ├── app.tsx
-|   ├── assets/fonts/
-├── test
-│   ├── __snapshots__
-│   ├── mock-i18n.ts
-│   ├── mock-reactotron.ts
-│   ├── setup.ts
+├── assets
 ├── ignite
 │   └── templates
+├── ios
 ├── plugins
 │   └── withSplashScreen.ts
+├── test
+│   ├── i18n.test.ts
+│   ├── mockFile.ts
+│   ├── setup.ts
+│   ├── test-tsconfig.json
 ├── app.config.ts
 ├── app.json
 ├── App.tsx
@@ -51,85 +53,76 @@ your-project
 
 ### ./app directory
 
-Included in an Ignite boilerplate project is the `app` directory. This is a directory you would normally have to create when using vanilla React Native.
+The vast majority of your code will live in the [/app folder](./app/app.md). This is where you'll spend most of your time.
 
-The inside of the `app` directory looks similar to the following:
+**[components](./app/components/Components.md)**
 
-```
-app
-│── components
-│── i18n
-├── models
-├── navigators
-├── screens
-├── services
-├── theme
-├── utils
-├── app.tsx
-```
+This is where your components will live, the reusable building blocks to create your screens. A handful of built-in components come with Ignite that are adaptable to any custom design system you wish to implement.
 
-**components**
+**[config](./app/config/Config.md)**
 
-This is where your components will live, the reusable building blocks to create your screens. A handful of built-in components come with Ignite that are adaptable to any custom design system you wish to implement. Below are links to further documentation about each component:
+This contains configuration for your app that might vary depending if you're running in development or production.
 
-- [Component Overview](../)
-- [AutoImage](../boilerplate/app/components/AutoImage.md)
-- [Button](../boilerplate/app/components/Button.md)
-- [Card](../boilerplate/app/components/Card.md)
-- [EmptyState](../boilerplate/app/components/EmptyState.md)
-- [Header](../boilerplate/app/components/Header.md)
-- [Icon](../boilerplate/app/components/Icon.md)
-- [ListItem](../boilerplate/app/components/ListItem.md)
-- [ListView](../boilerplate/app/components/ListView.md)
-- [Screen](../boilerplate/app/components/Screen.md)
-- [Text](../boilerplate/app/components/Text.md)
-- [TextField](../boilerplate/app/components/TextField.md)
-- [Toggle](../boilerplate/app/components/Toggle.md)
+**[devtools](./app/devtools/Devtools.md)**
 
-**i18n**
+This is where setup and configuration of devtools like Reactotron occurs.
+
+**[i18n (Internationalization)](./app/i18n/Internationalization.md)**
 
 This is where your translations will live if you are using the included `react-native-i18n`.
 
-**models**
+**[models](./app/models/Models.md)**
 
 This is where your app's models will live. Each model has a directory which will contain the `mobx-state-tree` model file, test file, and any other supporting files like actions, types, etc. In addition, a helpers directory contains utility functions such as `getRootStore` to access the root store.
 
-**navigators**
+**[navigators](./app/navigators/Navigation.md)**
 
 This is where your `react-navigation` navigators will live.
 
-**screens**
+**[screens](./app/screens/Screens.md)**
 
 This is where your screen components will live. A screen is a React component which will take up the entire screen and be part of the navigation hierarchy. Each screen will have a directory containing the `.tsx` file, along with any assets or other helper files.
 
-**services**
+**[services](./app/services/Services.md)**
 
 Any services that interface with the outside world will live here (think REST APIs, Push Notifications, etc.).
 
-**theme**
+**[theme](./app/theme/Theming.md)**
+
+Here lives the theme for your application, including spacing, colors, and typography.
 
-Here lives the theme for your application, including spacing, colors, and typography. For help with adding custom fonts to your application, [check out the readme in Fonts & Typography/](../boilerplate/app/theme/typography.ts.md).
+- For help with adding custom fonts to your application, check out [Fonts & Typography](../boilerplate/app/theme/typography.ts.md).
 
-**utils**
+**[utils](./app/utils/Utils.md)**
 
 This is a great place to put miscellaneous helpers and utilities. Things like date helpers, formatters, etc. are often found here. However, it should only be used for things that are truely shared across your application. If a helper or utility is only used by a specific component or model, consider co-locating your helper with that component or model.
 
-**app.json/app.config.ts**
+**[app.tsx](./app/app.tsx.md)**
+
+The main entry point for your app!
+
+### Root Directory
+
+#### Directories
+
+**[.maestro](./maestro.md)** - Maestro e2e tests
+
+**[android](./android.md)** - Native Android / Android Studio project files for DIY workflows (non-Expo)
 
-These are the configuration files for your application. `app.json` contains the static configuration which will be fed into the dynamic configuration in `app.config.ts`, where Expo builds it's final configuration for the app.
+**[assets](./assets.md)** - icons and images
 
-**App.tsx**
+**[ignite](./ignite.md)** - all things Ignite, including generator templates.
 
-This is the entry point to your app. This is where you will find the main App component which renders the rest of the application.
+**[ios](./ios.md)** - Native iOS / Xcode project files for DIY workflows (non-Expo)
 
-### ./ignite directory
+**[plugins](./plugins/Plugins.md)** - any custom Expo Config Plugins to be applied during the prebuild process when generating the native code for the project.
 
-The `ignite` directory stores all things Ignite, including generator templates.
+**[test](./test/Test.md)** - Jest configs and mocks
 
-### ./plugins directory
+#### Files
 
-The `plugins` directory stores any custom Expo Config Plugins you want to be applied during the prebuild process when generating the native code for the project.
+**[app.json/app.config.ts](./app.json.md)** - configuration files for your app. `app.json` contains the static configuration which will be fed into the dynamic configuration in `app.config.ts`, where Expo builds it's final configuration for the app.
 
-### ./test directory
+**[App.tsx](./App.tsx.md)** - entry point to your app. This is where you will find the main App component which renders the rest of the application.
 
-This directory will hold your Jest configs and mocks.
+**[eas.json](./eas.json.md)** - build configurations for Expo EAS builds
diff --git a/docs/boilerplate/android.md b/docs/boilerplate/android.md
index 8a62cd7ee..77d73b156 100644
--- a/docs/boilerplate/android.md
+++ b/docs/boilerplate/android.md
@@ -1,6 +1,6 @@
 ---
 title: android
-sidebar_position: 20
+sidebar_position: 5
 ---
 
 # `android`
diff --git a/docs/boilerplate/app.json.md b/docs/boilerplate/app.json.md
new file mode 100644
index 000000000..268db36e5
--- /dev/null
+++ b/docs/boilerplate/app.json.md
@@ -0,0 +1,16 @@
+---
+title: app.json / app.config.js
+sidebar_position: 60
+---
+
+# app.json / app.config.js
+
+The app.json & app.config.js files are used to configure your React Native / Expo project.
+
+Ignite has already configured several things for us:
+
+- App Icons - configured for iOS, Android, and Web. Check out [App Icon Generators](../concept/Generators/#app-icon-generator) to update your App Icon.
+- Splash Screen colors and images - configured for iOS, Android, and Web. Check out [Splash Screen Generators](../concept/Generators/#splash-screen-generator) to update your Splash Screen.
+- Expo plugins for things like localization and splash screens
+
+See [Expo's Documentation on App.json Configuration](https://docs.expo.dev/workflow/configuration/) for more details.
diff --git a/docs/boilerplate/app/_category_.json b/docs/boilerplate/app/_category_.json
index dc9861bed..9583cb9d5 100644
--- a/docs/boilerplate/app/_category_.json
+++ b/docs/boilerplate/app/_category_.json
@@ -1,9 +1,9 @@
 {
   "label": "app",
-  "position": 5,
+  "position": 10,
   "link": {
     "type": "doc",
     "id": "app"
   },
-  "collapsed": true
+  "collapsed": false
 }
diff --git a/docs/boilerplate/app/app.md b/docs/boilerplate/app/app.md
index 1d7af96be..0329b49a4 100644
--- a/docs/boilerplate/app/app.md
+++ b/docs/boilerplate/app/app.md
@@ -11,7 +11,7 @@ In this folder, there's only one file ([app.tsx](./app.tsx.md)). The rest are fo
 - [app.tsx](./app.tsx.md) - The main entry point for your app
 - [components](./components/Components.md) - Reusable components
 - [config](./config/Config.md) - Configuration files
-- devtools - Configuration/setup for Reactotron and other dev tools
+- [devtools](./devtools/Devtools.md) - Configuration/setup for Reactotron and other dev tools
 - [i18n](./i18n/Internationalization.md) - Internationalization setup
 - [models](./models/Models.md) - MobX-State-Tree models
 - [navigators](./navigators/Navigation.md) - React Navigation navigators
diff --git a/docs/boilerplate/app/devtools/Devtools.md b/docs/boilerplate/app/devtools/Devtools.md
new file mode 100644
index 000000000..4b08c1982
--- /dev/null
+++ b/docs/boilerplate/app/devtools/Devtools.md
@@ -0,0 +1,38 @@
+# Devtools Folder
+
+## Reactotron
+
+Ignite comes with Reactotron support for debugging your app.
+By default, Reactotron is configured to work with web and mobile apps and is configured with a few plugins and commands we think are useful.
+
+### ReactotronConfig.ts
+
+The `reactotron-mst` plugin is included for MobX-State-Tree support.
+
+```typescript
+import { mst } from "reactotron-mst"
+const reactotron = Reactotron.configure({
+    ...
+}).use(
+  mst({
+    /** ignore some chatty `mobx-state-tree` actions  */
+    filter: (event) => /postProcessSnapshot|@APPLY_SNAPSHOT/.test(event.name) === false,
+  }),
+)
+```
+
+There are also a few custom commands included. You can use `reactotron.onCustomCommand` to add your own own custom debugging tools to Reactotron. Here is an example:
+
+```typescript
+reactotron.onCustomCommand({
+  title: "Reset Navigation State",
+  description: "Resets the navigation state",
+  command: "resetNavigation",
+  handler: () => {
+    Reactotron.log("resetting navigation state")
+    resetRoot({ index: 0, routes: [] })
+  },
+})
+```
+
+For more info check out the [Reactotron Documentation](https://docs.infinite.red/reactotron/)
diff --git a/docs/boilerplate/app/devtools/_category_.json b/docs/boilerplate/app/devtools/_category_.json
new file mode 100644
index 000000000..d84446ca0
--- /dev/null
+++ b/docs/boilerplate/app/devtools/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "devtools",
+  "position": 50,
+  "link": {
+    "type": "doc",
+    "id": "Devtools"
+  }
+}
diff --git a/docs/boilerplate/assets.md b/docs/boilerplate/assets.md
new file mode 100644
index 000000000..e699cf4ae
--- /dev/null
+++ b/docs/boilerplate/assets.md
@@ -0,0 +1,16 @@
+---
+title: assets
+sidebar_position: 20
+---
+
+# Assets Folder
+
+The `assets` folder is for icons, images, fonts, and other static assets used in your app.
+
+### App Icons
+
+For your App Icon, use [Ignite's App Icon Generator](../concept/Generators/#app-icon-generator) to automatically generate image assets, which get put in `assets/images`.
+
+### Splash Screen
+
+To update your Splash Screen, use [Ignite's Splash Screen Generator](../concept/Generators/#splash-screen-generator) to generate images and update `assets/images`.
diff --git a/docs/boilerplate/eas.json.md b/docs/boilerplate/eas.json.md
new file mode 100644
index 000000000..82b5e700c
--- /dev/null
+++ b/docs/boilerplate/eas.json.md
@@ -0,0 +1,45 @@
+---
+title: eas.json
+sidebar_position: 70
+---
+
+# eas.json
+
+`eas.json` is the configuration file for [Expo Application Service (EAS)](https://docs.expo.dev/eas/). It allows you to create profiles for building and distributing your app.
+
+Ignite includes a few default build profiles for common scenarios, but you can customize or add your own profiles too!
+
+- `development` - internal debug build for testing on simulators
+- `development:device` - internal debug build for testing on physical devices
+- `preview` - internal production build for testing on simulators
+- `preview:device` - internal production build for testing on physical devices
+- `production` - default production profile intended for external distribution
+
+Note how profiles can share settings via `extends`:
+
+```json
+"development": {
+    "extends": "production",
+    "distribution": "internal",
+    "android": {
+        "gradleCommand": ":app:assembleDebug"
+    },
+    "ios": {
+        "buildConfiguration": "Debug",
+        "simulator": true
+    }
+},
+"development:device": {
+    "extends": "development",
+    "distribution": "internal",
+    "ios": {
+        "buildConfiguration": "Debug",
+        "simulator": false
+    }
+},
+"production": {}
+```
+
+In this example, `development:device` inherits the settings from `development`, but changes the `ios` setting to `simulator: false`. You can use `extends` to create a set of profiles to fit your needs without duplicating configuration.
+
+View [Expo's eas.json Documentation](https://docs.expo.dev/build/eas-json/) for more info.
diff --git a/docs/boilerplate/ignite.md b/docs/boilerplate/ignite.md
new file mode 100644
index 000000000..8f63de795
--- /dev/null
+++ b/docs/boilerplate/ignite.md
@@ -0,0 +1,11 @@
+---
+title: ignite
+sidebar_position: 25
+---
+
+# Ignite Folder
+
+The `ignite` directory contains an initial set of generator templates to help scaffold new screens, components, models, app icons, and more.
+
+Generators are the true gem of Ignite! They can save you countless hours as you build your app - we strongly recommend you give it a try!
+Learn more about [Ignite Generators](../concept/Generators.md) and how to create your own [Ignite Generator Templates](../concept/Generator-Templates.md)
diff --git a/docs/boilerplate/ios.md b/docs/boilerplate/ios.md
index 14fd3eb41..cdde19105 100644
--- a/docs/boilerplate/ios.md
+++ b/docs/boilerplate/ios.md
@@ -1,6 +1,6 @@
 ---
 title: ios
-sidebar_position: 20
+sidebar_position: 30
 ---
 
 # `ios` folder
diff --git a/docs/boilerplate/maestro.md b/docs/boilerplate/maestro.md
new file mode 100644
index 000000000..6d2954914
--- /dev/null
+++ b/docs/boilerplate/maestro.md
@@ -0,0 +1,22 @@
+---
+title: .maestro
+sidebar_position: 2
+---
+
+# Maestro
+
+Ignite's demo project includes a `.maestro` directory with a few example test flows. [Maestro](https://maestro.mobile.dev/) is Ignite's default end-to-end testing solution.
+
+If you have Maestro setup, you can run your tests via
+
+```bash
+maestro test .maestro/MyTestFile.yaml
+```
+
+This command is also setup as a npm script in `package.json`, which you can customize to your liking:
+
+```bash
+yarn run test:maestro
+```
+
+You can learn how to run and create Maestro tests by following the [Ignite Cookbook Recipe](https://ignitecookbook.com/docs/recipes/MaestroSetup) or by visiting [Maestro's Documentation](https://maestro.mobile.dev/)
diff --git a/docs/boilerplate/plugins/Plugins.md b/docs/boilerplate/plugins/Plugins.md
new file mode 100644
index 000000000..aee851a86
--- /dev/null
+++ b/docs/boilerplate/plugins/Plugins.md
@@ -0,0 +1,25 @@
+## `app/plugins` Directory in Ignite Apps
+
+The `app/plugins` directory is a dedicated space within the Ignite boilerplate for managing Expo Config Plugins. These plugins are used to customize the native configuration of your app without altering the native code directly.
+
+### Adding Custom Plugins
+
+To add a custom plugin:
+
+1. **Create a Plugin**: In `app/plugins`, define your plugin in a TypeScript file, exporting a function that modifies the ExpoConfig.
+2. **Integrate the Plugin**: In `app.config.ts`, import your plugin and add it to the `plugins` array.
+
+Example:
+
+```typescript
+// In app.config.ts
+plugins: [...existingPlugins, require("./plugins/yourCustomPlugin").yourCustomPlugin]
+```
+
+## Key Points
+
+- Config plugins extend app configuration, automating native module integration.
+- Create plugins in `app/plugins` and add them to `app.config.ts`.
+- For complex setups, refer to mods but use them with caution.
+
+For detailed information on creating and using config plugins, refer to [Expo's Config Plugins documentation](https://docs.expo.dev/config-plugins/introduction/).
diff --git a/docs/boilerplate/plugins/_category_.json b/docs/boilerplate/plugins/_category_.json
new file mode 100644
index 000000000..aec323de0
--- /dev/null
+++ b/docs/boilerplate/plugins/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "plugins",
+  "position": 50,
+  "link": {
+    "type": "doc",
+    "id": "Plugins"
+  }
+}
diff --git a/docs/boilerplate/plugins/withSplashScreen.md b/docs/boilerplate/plugins/withSplashScreen.md
new file mode 100644
index 000000000..82fa25f7e
--- /dev/null
+++ b/docs/boilerplate/plugins/withSplashScreen.md
@@ -0,0 +1,15 @@
+# withSplashScreen Config Plugin
+
+## Purpose
+
+`withSplashScreen` addresses the double splash screen issue in Expo apps (documented in [Expo GitHub issue #16084](https://github.com/expo/expo/issues/16084)), by ensuring a seamless transition between the initial native splash screen and the one managed by `expo-splash-screen`.
+
+## Functionality
+
+- **Transparent Splash Screen**: Replaces the default splash screen with a transparent one on Android.
+- **Translucent Status Bar**: Sets the status bar to translucent to match the transparent splash screen.
+
+## Implementation
+
+1. **Modifies `strings.xml`**: Adds a setting for a translucent status bar.
+2. **Updates `styles.xml`**: Adjusts `Theme.App.SplashScreen` to make the window translucent.
diff --git a/docs/boilerplate/test/Test.md b/docs/boilerplate/test/Test.md
new file mode 100644
index 000000000..0189f6fa5
--- /dev/null
+++ b/docs/boilerplate/test/Test.md
@@ -0,0 +1,10 @@
+# Test Folder
+
+Ignite includes support for writing [Jest](https://jestjs.io/) tests, which can be located anywhere in your codebase. But the initial Jest setup, mocking objects for testing, and any global scoped tests belong in the `test` directory.
+
+### i18n.test.ts
+
+`test/i18n.test.ts` is a handy test to check for any missing or mistyped translation keys in your app.
+It searches the codebase for components using the `tx=""` prop, or any `translate("")` commands, and checks for a valid i18n key between the double quotes.
+
+This approach isn't 100% perfect. If you are storing your key string in a variable because you are setting it conditionally, then it won't be picked up.
diff --git a/docs/boilerplate/test/_category_.json b/docs/boilerplate/test/_category_.json
new file mode 100644
index 000000000..c72f45a8d
--- /dev/null
+++ b/docs/boilerplate/test/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "test",
+  "position": 55,
+  "link": {
+    "type": "doc",
+    "id": "Test"
+  }
+}