MicroSaaSFast Mobile App

This documentation provides step-by-step instructions on how to set up and configure the MicroSaaSFast mobile application built with Expo and React Native.

Project Structure

The mobile app follows Expo Router's file-based routing system with the following structure:

Project Structure
microsaasfast-mobile/
├── app/
│   ├── _layout.tsx          # Root layout with ClerkProvider
│   ├── index.tsx             # Entry point with auth redirect
│   ├── checkout-success.tsx  # Stripe checkout success handler
│   ├── (auth)/
│   │   ├── _layout.tsx      # Auth stack layout
│   │   ├── sign-in.tsx      # Sign in screen
│   │   └── sign-up.tsx      # Sign up screen
│   └── (tabs)/
│       ├── _layout.tsx      # Tabs navigation layout
│       ├── home.tsx         # Home screen with projects
│       └── profile.tsx       # Profile screen
├── components/
│   └── OAuthButton.tsx      # OAuth provider buttons
├── constants/
│   └── theme.ts             # Theme system (light/dark/system)
├── assets/                  # App icons and splash screens
├── app.config.js            # Expo configuration
├── app.json                 # Expo app manifest
└── package.json             # Dependencies

Installation

1. Clone the Repository

Clone the repository to your local machine and navigate to the project directory.

bash
git clone <repository-url>
cd microsaasfast-mobile

2. Install Dependencies

Install all required npm packages using npm or yarn.

bash
npm install

3. Environment Variables

Create a `.env` file in the root directory with the required environment variables.

.env
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key_here
EXPO_PUBLIC_APP_URL=https://your.microsaasfast.domain

4. Start Development Server

Start the Expo development server to run the app on iOS, Android, or web.

bash
npm start

Configuration

1. Clerk Authentication Setup

• Create a Clerk account at clerk.com

• Create a new application in Clerk dashboard

• Configure OAuth providers (Google, Apple, GitHub, Facebook)

• Copy your publishable key to the `.env` file

• Ensure your app URL scheme matches: microsaasfast

app.config.js
import 'dotenv/config';
export default {
  expo: {
    name: 'MicroSaaSFast Mobile',
    slug: 'microsaasfast-mobile',
    scheme: 'microsaasfast',
    extra: {
      clerkPublishableKey: process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY,
      appUrl: process.env.EXPO_PUBLIC_APP_URL,
    },
  },
};

2. Backend API Configuration

The app connects to a backend API. Ensure your backend API is properly configured and accessible. The following endpoints are used:

• GET /api/projects - Fetch user projects

• GET /api/subscription - Check subscription status

• POST /api/stripe/create-checkout - Create Stripe checkout session

• POST /api/stripe/create-portal - Create Stripe customer portal session

API Configuration
// The app URL is configured via environment variable
const appUrl = Constants.expoConfig?.extra?.appUrl || process.env.EXPO_PUBLIC_APP_URL;
// Example API call
const response = await axios.get(`${appUrl}/api/projects`, {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json',
  },
});

Authentication Flow

1. Root Layout Setup

The root layout wraps the app with ClerkProvider and ThemeProvider, handling authentication state.

app/_layout.tsx
import { ClerkProvider } from '@clerk/clerk-expo';
import { ThemeProvider } from '@/constants/theme';
export default function RootLayout() {
  const publishableKey = Constants.expoConfig?.extra?.clerkPublishableKey;
  
  return (
    <ClerkProvider tokenCache={tokenCache} publishableKey={publishableKey}>
      <ThemeProvider>
        <InitialLayout />
      </ThemeProvider>
    </ClerkProvider>
  );
}

2. Authentication Routing

The app automatically redirects users based on their authentication state:

• Signed-in users are redirected to /(tabs)/home

• Signed-out users are redirected to /(auth)/sign-in

• Deep links for checkout-success are handled automatically

app/_layout.tsx - InitialLayout
const InitialLayout = () => {
  const { isLoaded, isSignedIn } = useAuth();
  const segments = useSegments();
  const router = useRouter();
  useEffect(() => {
    if (!isLoaded) return;
    const inAuthGroup = segments[0] === '(auth)';
    if (isSignedIn && inAuthGroup) {
      router.replace('/(tabs)/home');
    } else if (!isSignedIn && !inAuthGroup) {
      router.replace('/(auth)/sign-in');
    }
  }, [isSignedIn, isLoaded, segments, router]);
};

3. OAuth Providers

The app supports multiple OAuth providers through Clerk. OAuth buttons are implemented in a reusable component.

components/OAuthButton.tsx
import { useOAuth } from '@clerk/clerk-expo';
export default function OAuthButton({ provider }: { provider: 'google' | 'apple' }) {
  const { startOAuthFlow } = useOAuth({ 
    strategy: `oauth_${provider}` 
  });
  const handlePress = async () => {
    const { createdSessionId, setActive } = await startOAuthFlow();
    if (createdSessionId) {
      await setActive!({ session: createdSessionId });
      router.replace('/(tabs)/home');
    }
  };
}

Theme System

The app includes a comprehensive theme system supporting light, dark, and system themes. Theme preferences are persisted using Expo SecureStore.

1. Theme Provider

• Provides theme context to all components

• Supports light, dark, and system theme modes

• Persists theme preference in SecureStore

• Automatically adapts to system color scheme when set to 'system'

constants/theme.ts
export const lightTheme = {
  background: '#FFFFFF',
  text: '#010610',
  button: '#007AFF',
  // ... other colors
};
export const darkTheme = {
  background: '#010814',
  text: '#FFFFFF',
  button: '#FFFFFF',
  // ... other colors
};
export function ThemeProvider({ children }) {
  const [themeMode, setThemeMode] = useState<ThemeMode>('system');
  // Loads and saves theme preference
}

2. Using Themes in Components

Components access the theme through the useTheme hook.

Example Component
import { useTheme } from '@/constants/theme';
export default function MyComponent() {
  const theme = useTheme();
  
  return (
    <View style={{ backgroundColor: theme.background }}>
      <Text style={{ color: theme.text }}>Hello</Text>
    </View>
  );
}

Subscription & Payments

1. Stripe Checkout Flow

The app integrates with Stripe for subscription management. The checkout flow uses deep links to return users to the app after payment.

Checkout Implementation
const handlePurchase = async () => {
  // Create deep link URL for Stripe redirect
  const deepLinkUrl = Linking.createURL('checkout-success', {});
  
  // Create checkout session
  const response = await axios.post(`${appUrl}/api/stripe/create-checkout`, {
    priceId: 'price_1SaM3rEM1PGI2jZXuF1no3ea',
    email: user.primaryEmailAddress?.emailAddress,
    userId: user.id,
    successUrl: deepLinkUrl,
  });
  // Open checkout in browser
  await WebBrowser.openBrowserAsync(checkoutUrl);
  
  // Deep link listener handles redirect back to app
};

2. Deep Link Handling

The app listens for deep links to handle Stripe redirects and subscription updates.

Deep Link Listener
useEffect(() => {
  // Listen for deep links when app is open
  const subscription = Linking.addEventListener('url', (event) => {
    const { url } = event;
    if (url.includes('checkout-success')) {
      WebBrowser.dismissBrowser();
      setTimeout(() => {
        checkSubscription();
      }, 1000);
    }
  });
  return () => subscription.remove();
}, []);

3. Subscription Management

Users can manage their subscriptions through the Stripe Customer Portal.

Customer Portal
const handleManageSubscription = async () => {
  const response = await axios.post(
    `${appUrl}/api/stripe/create-portal`,
    {
      email: user.primaryEmailAddress?.emailAddress,
      userId: user.id,
    },
    {
      headers: {
        'Authorization': `Bearer ${token}`,
      },
    }
  );
  const portalUrl = response.data.portalUrl;
  await WebBrowser.openBrowserAsync(portalUrl);
};

Building for Production

1. iOS Build

Build the iOS app using Expo CLI or EAS Build.

iOS Build Commands
# Using Expo CLI
expo build:ios
# Using EAS Build (recommended)
eas build --platform ios

2. Android Build

Build the Android app using Expo CLI or EAS Build.

Android Build Commands
# Using Expo CLI
expo build:android
# Using EAS Build (recommended)
eas build --platform android

3. App Configuration

Ensure your app.json and app.config.js are properly configured with:

• Bundle identifier (iOS): com.microsaasfast.mobile

• Package name (Android): com.microsaasfast.mobile

• App scheme: microsaasfast

• Icon and splash screen assets

app.json
{
  "expo": {
    "name": "MicroSaaSFast Mobile",
    "slug": "microsaasfast-mobile",
    "scheme": "microsaasfast",
    "ios": {
      "bundleIdentifier": "com.microsaasfast.mobile"
    },
    "android": {
      "package": "com.microsaasfast.mobile"
    }
  }
}

Environment Variables

The following environment variables are required for the app to function properly.

Required Variables

• EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY - Your Clerk publishable key (required)

• EXPO_PUBLIC_APP_URL - Backend API URL - your microsaasfast-full domain (required)

.env
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
EXPO_PUBLIC_APP_URL=https://your.microsaasfast.domain

Make sure to never commit your `.env` file to version control. The `.gitignore` file should already exclude it. These environment variables are loaded at build time and are accessible through Constants.expoConfig?.extra in your app code.

Key Features

1. Authentication

• Email/password authentication

• OAuth providers: Google, Apple, GitHub, Facebook

• Secure token storage with Expo SecureStore

• Automatic session management

2. Project Management

• View user projects from backend API

• Chat interface for each project

• Project status indicators

• Webhook integration for AI assistants

3. Subscription Management

• Stripe checkout integration

• Subscription status checking

• Customer portal access

• Deep link handling for payment flows

4. Theme System

• Light, dark, and system themes

• Persistent theme preferences

• Smooth theme transitions

Troubleshooting

Common Issues

1. Missing Clerk Key: Ensure EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY is set in .env

2. API Connection Errors: Verify EXPO_PUBLIC_APP_URL points to your backend

3. Deep Links Not Working: Check that scheme matches in app.json and Clerk dashboard

4. Build Errors: Ensure all dependencies are installed and environment variables are set

For additional support, visit the discord server