diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs index 3f82aff653..3f572a1b4e 100644 --- a/apps/docs/astro.config.mjs +++ b/apps/docs/astro.config.mjs @@ -1,89 +1,91 @@ -import { defineConfig } from "astro/config"; -import starlight from "@astrojs/starlight"; +import {defineConfig} from 'astro/config'; +import starlight from '@astrojs/starlight'; export default defineConfig({ integrations: [ starlight({ - title: "Flagship Code", - favicon: "./src/assets/logo.svg", + title: 'Flagship Code', + favicon: './src/assets/logo.svg', logo: { - src: "./src/assets/logo.svg", + src: './src/assets/logo.svg', }, social: { - github: "https://github.com/brandingbrand/flagship", + github: 'https://github.com/brandingbrand/flagship', }, - customCss: ["./src/styles.css"], + customCss: ['./src/styles.css'], sidebar: [ { - label: "Overview", + label: 'Overview', items: [ - { label: "Overview", link: "/overview/overview/" }, - { label: "Objectives", link: "/overview/objectives/" }, - { label: "How It Works", link: "/overview/how-it-works/" }, + {label: 'Overview', link: '/overview/overview/'}, + {label: 'Objectives', link: '/overview/objectives/'}, + {label: 'How It Works', link: '/overview/how-it-works/'}, ], }, { - label: "Guides", + label: 'Guides', items: [ { - label: "Getting Started", - link: "/guides/getting-started", + label: 'Getting Started', + link: '/guides/getting-started', }, { - label: "Flagship Code Configuration", - link: "/guides/config/", + label: 'Flagship Code Configuration', + link: '/guides/config/', }, - { label: "Build Configuration", link: "/guides/build/" }, - { label: "Env Configuration", link: "/guides/env/" }, - { label: "Plugins", link: "/guides/plugins/" }, - { label: "Migration", link: "/guides/migration/" }, + {label: 'Build Configuration', link: '/guides/build/'}, + {label: 'Env Configuration', link: '/guides/env/'}, + {label: 'Plugins', link: '/guides/plugins/'}, + {label: 'Migration', link: '/guides/migration/'}, ], }, { - label: "Packages", + label: 'Packages', items: [ - { label: "cli", link: "/packages/cli/" }, + {label: 'app-env', link: '/packages/app-env/'}, + {label: 'app-router', link: '/packages/app-router/'}, + {label: 'cli', link: '/packages/cli/'}, { - label: "cli-kit", - link: "/packages/cli-kit/", + label: 'cli-kit', + link: '/packages/cli-kit/', }, { - label: "jest-config", - link: "/packages/jest-config/", + label: 'jest-config', + link: '/packages/jest-config/', }, { - label: "plugin-app-icon", - link: "/packages/plugin-app-icon/", + label: 'plugin-app-icon', + link: '/packages/plugin-app-icon/', }, { - label: "plugin-asset", - link: "/packages/plugin-asset/", + label: 'plugin-asset', + link: '/packages/plugin-asset/', }, { - label: "plugin-fastlane", - link: "/packages/plugin-fastlane/", + label: 'plugin-fastlane', + link: '/packages/plugin-fastlane/', }, { - label: "plugin-native-navigation", - link: "/packages/plugin-native-navigation/", + label: 'plugin-native-navigation', + link: '/packages/plugin-native-navigation/', }, { - label: "plugin-permissions", - link: "/packages/plugin-permissions/", + label: 'plugin-permissions', + link: '/packages/plugin-permissions/', }, { - label: "plugin-splash-screen", - link: "/packages/plugin-splash-screen/", + label: 'plugin-splash-screen', + link: '/packages/plugin-splash-screen/', }, { - label: "plugin-target-extension", - link: "/packages/plugin-target-extension/", + label: 'plugin-target-extension', + link: '/packages/plugin-target-extension/', }, ], }, ], }), ], - site: "https://brandingbrand.github.io", - base: "flagship", + site: 'https://brandingbrand.github.io', + base: 'flagship', }); diff --git a/apps/docs/src/content/docs/packages/app-env.mdx b/apps/docs/src/content/docs/packages/app-env.mdx new file mode 100644 index 0000000000..1673baa58b --- /dev/null +++ b/apps/docs/src/content/docs/packages/app-env.mdx @@ -0,0 +1,309 @@ +--- +title: app-env +--- + +## **Introduction** + +The **`app-env`** package provides a comprehensive solution for managing environment configurations in React Native applications. It supports both iOS and Android platforms and integrates seamlessly with `@brandingbrand/code-app-router`. With **`app-env`**, developers can: + +- Define environment-specific settings. +- Switch between development, staging, and production environments. +- Access native environment modules and developer tools. + +--- + +## **Installation** + +To add the **`app-env`** package to your project, follow these steps: + +### **Step 1: Install the Package** + +import {Tabs, TabItem} from '@astrojs/starlight/components'; + + + + +```sh +yarn add @brandingbrand/code-app-env +``` + + + + +```sh +npm install @brandingbrand/code-app-env +``` + + + + +```sh +pnpm add @brandingbrand/code-app-env +``` + + + + +```sh +bun add @brandingbrand/code-app-env +``` + + + + +### **Step 2: Link Native Modules** + +If you are using **React Native 0.60+**, auto-linking should handle the native dependencies. However, for manual linking or troubleshooting, follow these steps: + +#### **For iOS** + +1. **Install CocoaPods dependencies**: + + ```bash + cd ios && pod install && cd .. + ``` + +2. Ensure the **`react-native-flagship-env`** module is included in your `Podfile`: + + ```ruby + pod 'react-native-flagship-env', :path => '../node_modules/@brandingbrand/code-app-env' + ``` + +#### **For Android** + +1. Add the module to your **`settings.gradle`**: + + ```gradle + include ':react-native-flagship-env' + project(':react-native-flagship-env').projectDir = new File(rootProject.projectDir, '../node_modules/@brandingbrand/code-app-env/android') + ``` + +2. Add the dependency in your **`app/build.gradle`**: + + ```gradle + implementation project(':react-native-flagship-env') + ``` + +3. Update **`MainApplication.java`** to include the package: + + ```java + import com.flagshipenv.FlagshipEnvPackage; + + @Override + protected List getPackages() { + return Arrays.asList( + new MainReactPackage(), + new FlagshipEnvPackage() // Add this line + ); + } + ``` + +### **Step 3: Verify Installation** + +Run the following command to ensure the package is properly linked: + +```bash +npx react-native run-ios +# or +npx react-native run-android +``` + +If you encounter errors related to missing modules, follow the linking instructions above or clean your build: + +```bash +cd ios && pod install --repo-update && cd .. +npx react-native start --reset-cache +``` + +--- + +## **Configuration** + +### **Environment Configuration Files** + +Create environment configuration files in your project. These files define environment-specific settings and are named using the pattern **`env..ts`**. For example: + +1. **`env.development.ts`** + + ```typescript + export default { + apiUrl: 'https://api-dev.example.com', + featureFlag: true, + }; + ``` + +2. **`env.staging.ts`** + + ```typescript + export default { + apiUrl: 'https://api-staging.example.com', + featureFlag: false, + }; + ``` + +3. **`env.production.ts`** + + ```typescript + export default { + apiUrl: 'https://api.example.com', + featureFlag: false, + }; + ``` + +### **`.flagshipappenvrc` Configuration** + +Create a **`.flagshipappenvrc`** file in your project root to specify the location of your environment files and hidden environments. + +Example **`.flagshipappenvrc`**: + +```json +{ + "dir": "./config/environments", + "hiddenEnvs": ["test"], + "singleEnv": "development" +} +``` + +#### **Options:** + +- **`dir`**: Path to the directory containing your environment files. +- **`hiddenEnvs`**: Array of environments to exclude from selection. +- **`singleEnv`**: (Optional) Specify a single environment to use. + +--- + +## **Using the `FlagshipEnv` Native Module** + +The `FlagshipEnv` module provides constants and methods to manage environment settings at runtime. + +### **Constants** + +- **`envName`**: Current environment name. + + ```typescript + import {envName} from '@brandingbrand/code-app-env'; + + console.log(envName); // 'development' + ``` + +- **`appVersion`**: The current app version. + + ```typescript + import {appVersion} from '@brandingbrand/code-app-env'; + + console.log(appVersion); // '1.0.0' + ``` + +- **`buildNumber`**: The current build number. + + ```typescript + import {buildNumber} from '@brandingbrand/code-app-env'; + + console.log(buildNumber); // '42' + ``` + +### **Methods** + +- **`setEnv(name: string)`**: Set the current environment and update configurations. + + ```typescript + import {setEnv} from '@brandingbrand/code-app-env'; + + await setEnv('staging'); + ``` + +--- + +## **Components** + +### **`DevMenu`** + +The `DevMenu` component provides a developer menu for managing environments and performing common tasks. + +#### **Props** + +- **`screens`**: Array of React components for additional screens in the menu. +- **`onRestart`**: Function to restart the app. +- **`onEnvChange`**: Function to handle environment changes. +- **`location`**: Position of the Version Overlay (`'topLeft'`, `'topRight'`, `'bottomLeft'`, `'bottomRight'`). + +#### **Example** + +```tsx +import {DevMenu} from '@brandingbrand/code-app-env'; +import {DebugScreen} from './DebugScreen'; + +export default function App() { + return ( + console.log('Restarting...')} + onEnvChange={env => console.log(`Switched to ${env}`)} + location="bottomRight"> + Welcome to the app! + + ); +} +``` + +### **`EnvSwitcher`** + +The `EnvSwitcher` component allows developers to switch between different environments dynamically. + +#### **Example** + +```tsx +import {EnvSwitcher} from '@brandingbrand/code-app-env'; + +export default function DevSettings() { + return ; +} +``` + +--- + +## **File Structure** + +``` +app-env/ + ├── android/ + │ └── src/ + │ └── main/ + │ └── java/ + │ └── com/ + │ └── flagshipenv/ + │ ├── FlagshipEnvModule.kt + │ └── FlagshipEnvPackage.kt + ├── ios/ + │ ├── FlagshipEnv-Bridging-Header.h + │ └── FlagshipEnv.swift + ├── src/ + │ ├── components/ + │ │ ├── DevMenu.tsx + │ │ └── EnvSwitcher.tsx + │ └── lib/ + │ └── env.ts + ├── .flagshipappenvrc + └── package.json +``` + +--- + +## **Troubleshooting** + +### **Common Issues** + +1. **Native Module Not Linked**: + + - Ensure you've run `pod install` for iOS. + - Check that `MainApplication.java` includes `FlagshipEnvPackage` for Android. + +2. **Configuration File Not Found**: + + - Verify that `.flagshipappenvrc` exists in your project root. + - Ensure the `dir` field in `.flagshipappenvrc` points to the correct path. + +3. **Environment Not Switching**: + + - Check if `setEnv` is called correctly. + - Restart the app after changing environments. diff --git a/apps/docs/src/content/docs/packages/app-router.mdx b/apps/docs/src/content/docs/packages/app-router.mdx new file mode 100644 index 0000000000..e899be942f --- /dev/null +++ b/apps/docs/src/content/docs/packages/app-router.mdx @@ -0,0 +1,298 @@ +--- +title: app-router +--- + +The **`app-router`** package is a routing and navigation solution for React Native applications built on top of **React Native Navigation**. It provides a robust API to manage navigation stacks, bottom tabs, modals, deep linking, and route guards. The package is designed to be highly configurable and TypeScript-friendly, making it ideal for scalable applications. + +--- + +## **Installation** + +### **Step 1: Install the Package** + +import {Tabs, TabItem} from '@astrojs/starlight/components'; + + + + +```sh +yarn add @brandingbrand/code-app-router +``` + + + + +```sh +npm install @brandingbrand/code-app-router +``` + + + + +```sh +pnpm add @brandingbrand/code-app-router +``` + + + + +```sh +bun add @brandingbrand/code-app-router +``` + + + + +### **Step 2: Install Peer Dependencies** + +Ensure **React**, **React Native**, and **React Native Navigation** are installed: + +```bash +pnpm add react react-native react-native-navigation +``` + +### **Step 3: Link Native Dependencies** + +For React Native **0.60+**, auto-linking should handle native dependencies. If needed, follow these manual steps: + +#### **For iOS** + +1. Install CocoaPods dependencies: + + ```bash + cd ios && pod install && cd .. + ``` + +#### **For Android** + +Ensure the following in your **`settings.gradle`**: + +```gradle +include ':react-native-navigation' +project(':react-native-navigation').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-navigation/android/app') +``` + +--- + +## **Configuration** + +### **Step 1: Define Your Routes** + +Create a routes file, e.g., **`routes.ts`**: + +```typescript +import HomeScreen from './screens/HomeScreen'; +import ProfileScreen from './screens/ProfileScreen'; + +export const routes = [ + { + name: 'Home', + path: '/', + Component: HomeScreen, + type: 'bottomtab', + options: {bottomTab: {text: 'Home'}}, + stackId: 'mainStack', + }, + { + name: 'Profile', + path: '/profile', + Component: ProfileScreen, + type: 'component', + }, +]; +``` + +### **Step 2: Register Routes** + +In your **entry file** (e.g., **`App.tsx`**), register the routes and set the root layout: + +```typescript +import {register} from '@brandingbrand/code-app-router'; +import {routes} from './routes'; + +register({ + routes, + onAppLaunched: async () => { + console.log('App launched'); + }, +}); +``` + +--- + +## **API Overview** + +### **Router Configuration** + +#### `register({ routes, onAppLaunched, Provider, setRoot })` + +Registers routes and initializes the router. + +- **`routes`**: Array of route definitions. +- **`onAppLaunched`** (optional): Callback when the app launches. +- **`Provider`** (optional): A React component to provide global context. +- **`setRoot`** (optional): Function to customize root layout logic. + +--- + +## **Hooks** + +### **1. `useNavigator`** + +Provides navigation functions like `push`, `pop`, `showModal`, etc. + +**Example:** + +```typescript +import { useNavigator } from '@brandingbrand/code-app-router'; + +function HomeScreen() { + const navigator = useNavigator(); + + const goToProfile = () => navigator.push('/profile'); + + return