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

@@ -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.

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

docs/boilerplate/android.md

@@ -1,6 +1,6 @@
 ---
 title: android
-sidebar_position: 20
+sidebar_position: 5
 ---
 
 # `android`

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.

docs/boilerplate/app/_category_.json

@@ -1,9 +1,9 @@
 {
   "label": "app",
-  "position": 5,
+  "position": 10,
   "link": {
     "type": "doc",
     "id": "app"
   },
-  "collapsed": true
+  "collapsed": false
 }

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

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/)

docs/boilerplate/app/devtools/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "devtools",
+  "position": 50,
+  "link": {
+    "type": "doc",
+    "id": "Devtools"
+  }
+}

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`.

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.

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)

docs/boilerplate/ios.md

@@ -1,6 +1,6 @@
 ---
 title: ios
-sidebar_position: 20
+sidebar_position: 30
 ---
 
 # `ios` folder

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/)

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/).