NextNative

https://nextnative.dev/docs
Admin
NextNative is a framework for launching mobile apps 10x faster by leveraging Next.js for iOS and...
Tokens:13,598
Snippets:169
Trust Score:7.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Modal Controller Example

Source: https://nextnative.dev/docs/components/modal

A complete example demonstrating the usage of `useModalController` to open a modal via a button click and render the `ModalWrapper` with custom content and a close action.

```javascript
const {
modalRef,
open,
close,
} = useModalController();

<IonButton onClick={open}>Open Modal</IonButton>

<ModalWrapper modalRef={modalRef} presentingElement={pageRef.current}>
  <X onClick={close} />
  <PremiumScreen dismiss={close} />
</ModalWrapper>
```

--------------------------------

### Basic Ionic Router Setup

Source: https://nextnative.dev/docs/tutorials/ionic-router

Sets up the root IonApp with IonReactRouter and IonRouterOutlet to manage application routes. Includes a default redirect to '/app'.

```typescript
import { IonApp, IonRouterOutlet, setupIonicReact } from "@ionic/react";
import { IonReactRouter } from "@ionic/react-router";
import { Redirect, Route } from "react-router-dom";

// Initialize Ionic React
setupIonicReact({});

const AppRouter = () => {
  return (
    <IonApp>
      <IonReactRouter>
        <IonRouterOutlet id="main">
          <Route path="/app" render={() => <YourApp />} />
          <Route exact path="/">
            <Redirect to="/app" />
          </Route>
        </IonRouterOutlet>
      </IonReactRouter>
    </IonApp>
  );
};

```

--------------------------------

### Install and Import a Capacitor Plugin

Source: https://nextnative.dev/docs/tutorials/native-device-features

Install a new Capacitor plugin using npm and import its functionalities into your app. Ensure you run the mobile development command after installation.

```bash
npm install @capacitor/plugin-name
npm run mobile:dev
```

```typescript
import { PluginName } from "@capacitor/plugin-name";

// Use the plugin
async function usePlugin() {
  const result = await PluginName.methodName();
  console.log(result);
}
```

--------------------------------

### Clone and Install NextNative Boilerplate

Source: https://nextnative.dev/docs

Clone the NextNative boilerplate repository, install dependencies, remove the default origin, and set up the local environment file. Ensure Node.js version 20 or greater is installed.

```bash
git clone https://github.com/lite1pal/nextnative_boilerplate.git [YOUR_APP_NAME]

cd [YOUR_APP_NAME]

npm i

git remote remove origin

mv .env.example .env.local
```

--------------------------------

### Install CocoaPods with Homebrew

Source: https://nextnative.dev/docs

Install CocoaPods using Homebrew if it's not already installed. Homebrew is a package manager for macOS.

```bash
brew install cocoapods
```

--------------------------------

### Usage Example for useDeviceCamera Hook

Source: https://nextnative.dev/docs/tutorials/native-device-features

Demonstrates how to use the `useDeviceCamera` hook in a React component to display a photo and trigger the camera.

```typescript
function ProfileScreen() {
  const { photo, takePhoto, loading } = useDeviceCamera();
 
  return (
    <div>
      {photo && (
        <img
          src={photo}
          alt="Profile Photo"
          className="h-32 w-32 rounded-full object-cover"
        />
      )}
 
      <Button onClick={takePhoto} disabled={loading}>
        {loading ? "Processing..." : "Take Photo"}
      </Button>
    </div>
  );
}
```

--------------------------------

### Tab-Based Navigation Setup

Source: https://nextnative.dev/docs/tutorials/ionic-router

Implements tab-based navigation using IonTabs, IonRouterOutlet, and IonTabBar. Defines routes for different sections and includes a default redirect to the home tab.

```typescript
import {
  IonRouterOutlet,
  IonTabBar,
  IonTabButton,
  IonTabs,
} from "@ionic/react";
import { Redirect, Route } from "react-router-dom";

export default function AppWithTabs() {
  return (
    <IonTabs>
      <IonRouterOutlet>
        {/* Define your routes here */}
        <Route exact path="/app/home" component={HomeScreen} />
        <Route exact path="/app/profile" component={ProfileScreen} />
        <Route exact path="/app/settings" component={SettingsScreen} />

        {/* Default redirect */}
        <Route exact path="/app">
          <Redirect to="/app/home" />
        </Route>
      </IonRouterOutlet>

      <IonTabBar slot="bottom">
        <IonTabButton tab="home" href="/app/home">
          <HomeIcon />
        </IonTabButton>
        <IonTabButton tab="profile" href="/app/profile">
          <ProfileIcon />
        </IonTabButton>
        <IonTabButton tab="settings" href="/app/settings">
          <SettingsIcon />
        </IonTabButton>
      </IonTabBar>
    </IonTabs>
  );
}

```

--------------------------------

### Run Mobile Dev Server

Source: https://nextnative.dev/docs/tutorials/ship-in-5-minutes

Starts your mobile app in development mode, handling static builds, Next.js API support, watching changes, and reloading updates. Recommended to turn off the Firewall for live reload to function properly.

```bash
npm run mobile:dev
```

--------------------------------

### Firebase Authentication Actions

Source: https://nextnative.dev/docs/features/authorization

Code examples for signing in with Google or Apple and signing out using the Firebase Authentication Capacitor plugin.

```typescript
import { FirebaseAuthentication } from "@capacitor-firebase/authentication";

await FirebaseAuthentication.signInWithGoogle();
// or
await FirebaseAuthentication.signInWithApple();
```

```typescript
await FirebaseAuthentication.signOut();
```

--------------------------------

### Create a GET API Route in Next.js

Source: https://nextnative.dev/docs/features/nextjs-api

Define a simple GET API route in Next.js to return a JSON response. This is the basic structure for creating API endpoints.

```typescript
// app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: "Hello from the API!" });
}
```

--------------------------------

### Animation Transitions Example

Source: https://nextnative.dev/docs/tutorials/ionic-router

Illustrates how Ionic Router automatically handles page transitions. This snippet shows a route definition for a detail page within an IonRouterOutlet.

```typescript
<IonRouterOutlet>
  <Route
    path="/app/messages/:id"
    render={({ match }) => (
      <IonPage>
        <IonHeader>...</IonHeader>
        <IonContent>
          <MessageDetail id={match.params.id} />
        </IonContent>
      </IonPage>
    )}
  />
</IonRouterOutlet>

```

--------------------------------

### Check CocoaPods Version

Source: https://nextnative.dev/docs

Verify if CocoaPods is installed by checking its version. This is necessary for running iOS apps in Xcode emulators.

```bash
pod --version
```

--------------------------------

### Location-Based Photo Capture Feature

Source: https://nextnative.dev/docs/tutorials/native-device-features

This example demonstrates how to capture a photo with associated geolocation data and share it. It checks if the app is running on a native platform before proceeding. Requires @capacitor/geolocation, @capacitor/camera, @capacitor/core, and @capacitor/share.

```typescript
import React, { useState, useEffect } from "react";
import { IonContent, IonPage, IonButton } from "@ionic/react";
import { Geolocation } from "@capacitor/geolocation";
import { Camera, CameraResultType, CameraSource } from "@capacitor/camera";
import { Capacitor } from "@capacitor/core";
import { Share } from "@capacitor/share";
import ScreenContainer from "@/app/(mobile)/components/ScreenContainer";

interface LocationPhoto {
  photoUrl: string;
  location: {
    latitude: number;
    longitude: number;
  };
  timestamp: number;
}

export default function LocationPhotoScreen() {
  const [photos, setPhotos] = useState<LocationPhoto[]>([]);
  const [loading, setLoading] = useState(false);

  async function captureLocationPhoto() {
    if (!Capacitor.isNativePlatform()) {
      alert("This feature requires a mobile device");
      return;
    }

    try {
      setLoading(true);

      // 1. Get current location
      const position = await Geolocation.getCurrentPosition();

      // 2. Take a photo
      const image = await Camera.getPhoto({
        quality: 90,
        allowEditing: false,
        resultType: CameraResultType.Uri,
        source: CameraSource.Camera,
      });

      const photoUrl = image.webPath || "";

      // 3. Create a new entry
      const newPhoto: LocationPhoto = {
        photoUrl,
        location: {
          latitude: position.coords.latitude,
          longitude: position.coords.longitude,
        },
        timestamp: Date.now(),
      };

      // 4. Update state
      setPhotos((prev) => [...prev, newPhoto]);

      // 5. Show success message
      alert("Photo captured with location!");
    } catch (error) {
      console.error("Error capturing location photo:", error);
      alert("Failed to capture photo with location");
    } finally {
      setLoading(false);
    }
  }

  async function sharePhoto(photo: LocationPhoto) {
    try {
      await Share.share({
        title: "My Location Photo",
        text: `Photo taken at coordinates: ${photo.location.latitude}, ${photo.location.longitude}`,
        url: photo.photoUrl,
      });
    } catch (error) {
      console.error("Error sharing photo:", error);
    }
  }

  return (
    <ScreenContainer>
      <div className="p-4">
        <h1 className="mb-4 text-2xl font-bold">Location Photos</h1>

        <div className="mb-4">
          <IonButton
            expand="block"
            onClick={captureLocationPhoto}
            disabled={loading || !Capacitor.isNativePlatform()}
          >
            {loading ? "Processing..." : "Capture Photo with Location"}
          </IonButton>
        </div>

        <div className="grid grid-cols-2 gap-4">
          {photos.map((photo, index) => (
            <div
              key={index}
              className="overflow-hidden rounded-lg border bg-white dark:bg-gray-800"
            >
              <img
                src={photo.photoUrl}
                alt={`Location ${index}`}
                className="h-40 w-full object-cover"
              />
              <div className="p-2">
                <p className="text-xs text-gray-500">
                  {new Date(photo.timestamp).toLocaleString()}
                </p>
                <p className="text-xs">
                  {photo.location.latitude.toFixed(4)},
                  {photo.location.longitude.toFixed(4)}
                </p>
                <button
                  className="mt-2 text-sm text-blue-500"
                  onClick={() => sharePhoto(photo)}
                >
                  Share
                </button>
              </div>
            </div>
          ))}
        </div>

        {photos.length === 0 && (
          <p className="mt-8 text-center text-gray-500">
            No photos yet. Tap the button above to capture one!
          </p>
        )}
      </div>
    </ScreenContainer>
  );
}
```

--------------------------------

### Send POST Request with Authorization Header

Source: https://nextnative.dev/docs/features/nextjs-api

Example of making a POST request to a Next.js API route, including setting the `Content-Type` and `Authorization` headers with a Bearer token.

```javascript
const res = await fetch(`${config.api.url}/chat`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${user.token}`, // 👈 Add your token here
  },
  body: JSON.stringify({ text }),
});
```

--------------------------------

### Integrating ScreenContainer in App Navigation

Source: https://nextnative.dev/docs/components/screen-container

This example shows how to integrate a screen using ScreenContainer within an Ionic Tabs navigation structure. Ensure your routes and tab buttons are correctly configured.

```typescript
export default function App() {
  return (
    <IonTabs>
      <IonRouterOutlet>
        {/* Other screens */}
 
        <Route exact path="/app/settings" component={SettingsScreen} />
 
        <Route exact path="/app">
          <Redirect to="/app/settings" />
        </Route>
      </IonRouterOutlet>
 
      <IonTabBar slot="bottom">
        {/* Other tabs */}
 
        <IonTabButton tab="/app/settings" href="/app/settings">
          <Settings size={22} />
        </IonTabButton>
      </IonTabBar>
    </IonTabs>
  );
}
```

--------------------------------

### Android Sign Out

Source: https://nextnative.dev/docs/features/authorization

Code example for signing out a user using the Firebase Authentication Capacitor plugin on Android.

```typescript
await FirebaseAuthentication.signOut();
```

--------------------------------

### Update Environment Variables for Custom Postgres

Source: https://nextnative.dev/docs/features/database

Replace Supabase variables with your direct Postgres connection string when using your own database setup. This is for advanced users seeking full control.

```env
DATABASE_URL=postgresql://user:password@host:port/database
```

--------------------------------

### Messenger App Route Structure with Ionic Router

Source: https://nextnative.dev/docs/tutorials/ionic-router

Example of how a messenger app might structure its routes using IonTabs, IonRouterOutlet, and Route components. Includes handling chat lists, details, contacts, and settings.

```typescript
<IonTabs>
  <IonRouterOutlet>
    {/* Chat list */}
    <Route exact path="/app/chats" component={ChatsScreen} />
 
    {/* Chat detail */}
    <Route
      path="/app/chats/:chatId"
      render={({ match }) => <ChatDetailScreen chatId={match.params.chatId} />}
    />
 
    {/* Contacts list */}
    <Route exact path="/app/contacts" component={ContactsScreen} />
 
    {/* Contact profile */}
    <Route
      path="/app/contacts/:contactId"
      render={({ match }) => (
        <ContactProfileScreen contactId={match.params.contactId} />
      )}
    />
 
    {/* Settings */}
    <Route exact path="/app/settings" component={SettingsScreen} />
 
    {/* Default route */}
    <Route exact path="/app">
      <Redirect to="/app/chats" />
    </Route>
  </IonRouterOutlet>
 
  {/* Tab bar */}
  <IonTabBar slot="bottom">
    <IonTabButton tab="chats" href="/app/chats">
      <ChatIcon />
    </IonTabButton>
    <IonTabButton tab="contacts" href="/app/contacts">
      <ContactsIcon />
    </IonTabButton>
    <IonTabButton tab="settings" href="/app/settings">
      <SettingsIcon />
    </IonTabButton>
  </IonTabBar>
</IonTabs>
```

--------------------------------

### Get Current Device Location

Source: https://nextnative.dev/docs/tutorials/native-device-features

Utilize the Capacitor Geolocation API to retrieve the user's current coordinates. Ensure user permission is granted for location access.

```typescript
import { Geolocation } from "@capacitor/geolocation";
 
async function getCurrentPosition() {
  try {
    const coordinates = await Geolocation.getCurrentPosition();
 
    console.log("Current position:", coordinates);
 
    const { latitude, longitude } = coordinates.coords;
    setUserLocation({ lat: latitude, lng: longitude });
  } catch (error) {
    console.error("Failed to get location:", error);
  }
}
```

--------------------------------

### Get Android Debug Keystore SHA-1 Fingerprint

Source: https://nextnative.dev/docs/features/authorization

Command to retrieve the SHA-1 fingerprint for your Android debug keystore, essential for enabling Google sign-in. The default password for the debug keystore is 'android'.

```bash
keytool -list -v \
-alias androiddebugkey -keystore ~/.android/debug.keystore
```

```bash
keytool -list -v \
-alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore
```

--------------------------------

### Configure RevenueCat API Keys and Product IDs

Source: https://nextnative.dev/docs/features/in-app-purchases

Add your RevenueCat API key and product identifiers to your .env.local file. These are necessary for the application to communicate with RevenueCat and identify specific in-app products.

```env
NEXT_PUBLIC_REVENUECAT_API_KEY=your_revenuecat_key_here
NEXT_PUBLIC_REVENUECAT_MONTHLY_ID=your_monthly_product_id
NEXT_PUBLIC_REVENUECAT_ANNUALY_ID=your_annualy_product_id
NEXT_PUBLIC_REVENUECAT_LIFETIME_ID=your_lifetime_product_id
```

--------------------------------

### Add Supabase Keys to .env

Source: https://nextnative.dev/docs/features/database

Paste your Supabase URL and Anon Key into your .env file. These are required for Supabase client initialization.

```env
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
```

--------------------------------

### Directory Structure for App Icons

Source: https://nextnative.dev/docs/preparing-for-deployment/change-app-icon

Place your logo files in the `assets/` directory. The tool supports PNG and SVG formats. For dark mode, include `logo-dark.png`.

```bash
assets/
├── logo.png
└── logo-dark.png
```

--------------------------------

### Integrate Onboarding Flow into Router

Source: https://nextnative.dev/docs/tutorials/onboarding-flow

Wrap your main application router with the `OnboardInitializer` component to ensure the onboarding flow is presented correctly on the first launch.

```typescript
// app/(mobile)/router.tsx
import OnboardInitializer from "@/app/(mobile)/components/OnboardInitializer";
 
const AppRouter = () => {
  const { showSplash } = useSplashScreen();
 
  return (
    <IonApp>
      {showSplash && <SplashScreen />}
      <OnboardInitializer>
        {/* Your main app */}
        <IonReactRouter>{/* Routes */}</IonReactRouter>
      </OnboardInitializer>
    </IonApp>
  );
};

```

--------------------------------

### Open Android Project in Android Studio

Source: https://nextnative.dev/docs/features/authorization

Command to open the Android project in Android Studio for further configuration.

```bash
npx cap open android
```

--------------------------------

### Build App for Production

Source: https://nextnative.dev/docs/preparing-for-deployment/build-app-for-production

Run this command whenever you make changes to the code before deploying your NextNative app.

```bash
npm run mobile
```

--------------------------------

### Generate App Assets with Capacitor CLI

Source: https://nextnative.dev/docs/preparing-for-deployment/change-app-icon

Run this command in your project's root directory to generate all required app icon and splash screen assets.

```bash
npx @capacitor/assets generate
```

--------------------------------

### Open iOS Project in Xcode

Source: https://nextnative.dev/docs/preparing-for-deployment/rename-your-app

Use this command to open your iOS project in Xcode for further modifications.

```bash
npx cap open ios
```

--------------------------------

### Onboarding Screen Component

Source: https://nextnative.dev/docs/tutorials/onboarding-flow

The `OnboardingScreen` component manages the display and navigation of onboarding slides. It handles animations and user interactions for moving between slides.

```typescript
// Simplified version of app/(mobile)/components/OnboardingScreen.tsx
const OnboardingScreen: React.FC<OnboardingScreenProps> = ({ onComplete }) => {
  const [currentIndex, setCurrentIndex] = useState(0);
  const [direction, setDirection] = useState(0);
  const [isExiting, setIsExiting] = useState(false);
 
  // Navigation functions and animations
  // ...
 
  return (
    <motion.div className="fixed inset-0 bg-gradient-to-br from-blue-500 via-blue-600 to-blue-700">
      {/* Skip button */}
      {/* Slide content with animations */}
      {/* Progress dots and next/done button */}
    </motion.div>
  );
};

```

--------------------------------

### Initialize Modal Controller

Source: https://nextnative.dev/docs/components/modal

Import and initialize the `useModalController` hook to manage modal state. This hook provides functions to open and close the modal.

```javascript
const { modalRef, isOpen, open, close } = useModalController();
```

--------------------------------

### Capacitor Configuration

Source: https://nextnative.dev/docs/tutorials/native-device-features

Configure your app's ID, name, and plugin-specific options in `capacitor.config.ts`. This file is crucial for setting up native features.

```typescript
// capacitor.config.ts
import type { CapacitorConfig } from "@capacitor/cli";
 
const config: CapacitorConfig = {
  appId: "com.nextnative.app",
  appName: "NextNative",
  webDir: "out",
 
  ios: {
    scheme: "NextNative",
  },
 
  plugins: {
    SplashScreen: {
      backgroundColor: "#1a1a1a",
      splashFullScreen: true,
      splashImmersive: true,
      launchAutoHide: false,
    },
    FirebaseAuthentication: {
      skipNativeAuth: false,
      providers: ["google.com", "apple.com"],
    },
    FirebaseMessaging: {
      presentationOptions: ["sound", "alert"],
    },
  },
};
 
export default config;
```

--------------------------------

### Define Onboarding Slides Content

Source: https://nextnative.dev/docs/tutorials/onboarding-flow

Customize the content of your onboarding slides by modifying the `onboardingSlides` array. Each object in the array represents a single slide with a title and description.

```javascript
const onboardingSlides = [
  {
    id: 1,
    title: "Welcome!",
    description: "Discover the amazing features of our app.",
  },
  {
    id: 2,
    title: "Connect Seamlessly",
    description: "Stay in touch with friends and colleagues effortlessly.",
  },
  {
    id: 3,
    title: "Get Started",
    description: "You're all set to explore. Let's dive in!",
  },
];

```

--------------------------------

### App Initializer Component

Source: https://nextnative.dev/docs/tutorials/onboarding-flow

The `OnboardInitializer` component determines whether to display the onboarding flow or the main application content. It checks for previous completion using `Preferences` and manages the state for initialization and onboarding status.

```typescript
// app/(mobile)/components/OnboardInitializer.tsx
const AppInitializer: React.FC<AppInitializerProps> = ({ children }) => {
  const [onboardingCompleted, setOnboardingCompleted] = useState(false);
  const [isInitialized, setIsInitialized] = useState(false);
 
  useEffect(() => {
    const initializeApp = async () => {
      // Check if onboarding has been completed before
      const onboardingStatus = await Preferences.get({
        key: "onboardingCompleted10",
      });
      setOnboardingCompleted(onboardingStatus.value === "true");
      setIsInitialized(true);
    };
    initializeApp();
  }, []);
 
  const handleOnboardingComplete = async () => {
    await Preferences.set({ key: "onboardingCompleted10", value: "true" });
    setOnboardingCompleted(true);
  };
 
  if (!isInitialized) return null;
 
  if (!onboardingCompleted) {
    return <OnboardingScreen onComplete={handleOnboardingComplete} />;
  }
 
  return <>{children}</>;
};

```

--------------------------------

### Handling Web Fallbacks for Native Features

Source: https://nextnative.dev/docs/tutorials/native-device-features

Provides a robust sharing function that checks for native platform availability using Capacitor. It implements native sharing, the Web Share API, and a fallback to copying text to the clipboard.

```typescript
import { Capacitor } from "@capacitor/core";
import { Share } from "@capacitor/share";
 
async function shareContent() {
  const content = {
    title: "NextNative",
    text: "Build mobile apps with web technologies",
    url: "https://nextnative.dev",
  };
 
  try {
    if (Capacitor.isNativePlatform()) {
      // Native sharing
      await Share.share({
        ...content,
        dialogTitle: "Share with friends",
      });
    } else if (navigator.share) {
      // Web Share API (modern browsers)
      await navigator.share({
        title: content.title,
        text: content.text,
        url: content.url,
      });
    } else {
      // Fallback for browsers without share capability
      copyToClipboard(`${content.text} ${content.url}`);
      alert("Link copied to clipboard!");
    }
  } catch (error) {
    console.error("Error sharing:", error);
  }
}
 
function copyToClipboard(text: string) {
  navigator.clipboard.writeText(text).catch((err) => {
    console.error("Could not copy text: ", err);
  });
}
```

--------------------------------

### Create In-App Splash Screen Component

Source: https://nextnative.dev/docs/tutorials/splash-screen

This component uses Framer Motion for smooth animations. Replace `DefaultLogo` with your own logo.

```typescript
import React from "react";
import { motion } from "framer-motion";

const SplashScreen = () => {
  return (
    <motion.div
      className="fixed inset-0 z-50 overflow-hidden bg-gradient-to-br from-blue-500 via-blue-600 to-blue-700"
      initial={{ opacity: 1 }}
      animate={{ opacity: 0 }}
      transition={{ duration: 0.5, delay: 1.5 }}
      style={{ pointerEvents: "none" }}
    >
      <DefaultLogo />
    </motion.div>
  );
};

export default SplashScreen;
```

--------------------------------

### Update Android String Resources

Source: https://nextnative.dev/docs/preparing-for-deployment/rename-your-app

Change the app_name, title_activity_main, package_name, and custom_url_scheme in the strings.xml file.

```xml
<string name="app_name">MyApp</string>
<string name="title_activity_main">MyApp</string>
<string name="package_name">com.mycompany.appname</string>
<string name="custom_url_scheme">com.mycompany.appname</string>
```

--------------------------------

### Capacitor Preferences Plugin for Data Storage

Source: https://nextnative.dev/docs/tutorials/native-device-features

Use the Preferences plugin for persistent key-value storage. Includes functions for saving, loading, removing, and clearing data.

```typescript
import { Preferences } from "@capacitor/preferences";
 
// Saving data
async function saveData() {
  await Preferences.set({
    key: "user_settings",
    value: JSON.stringify({
      darkMode: true,
      notifications: true,
    }),
  });
}
 
// Loading data
async function loadData() {
  const { value } = await Preferences.get({ key: "user_settings" });
  if (value) {
    return JSON.parse(value);
  }
  return null;
}
 
// Removing data
async function removeData() {
  await Preferences.remove({ key: "user_settings" });
}
 
// Clearing all data
async function clearAll() {
  await Preferences.clear();
}
```

```typescript
import {
  PreferencesStorageAdapter,
  StorageService,
} from "@/app/(mobile)/services/storage";
 
// Using the storage service in a component
async function loadUserSettings() {
  try {
    const settings = await StorageService.loadSettings();
    setDarkMode(settings.darkMode || false);
    setNotifications(settings.notifications || false);
  } catch (error) {
    console.error("Failed to load settings:", error);
  }
}
```

--------------------------------

### Check and Request Push Permissions

Source: https://nextnative.dev/docs/features/push-notifications

Automatically checks for existing push notification permissions and requests them if not granted. This is the recommended way to handle permission requests.

```javascript
checkAndRequestPermissionsForPushNotifications();
```

--------------------------------

### Render Modal Wrapper

Source: https://nextnative.dev/docs/components/modal

Use the `ModalWrapper` component to structure your modal content. Pass the `modalRef` from the controller and the `presentingElement` for context. Include a close button within the modal content.

```javascript
<ModalWrapper modalRef={modalRef} presentingElement={presentingElement}>
  <div>
    <button onClick={close}>Close</button>
    <PremiumScreen dismiss={close} />
  </div>
</ModalWrapper>
```

--------------------------------

### Implement In-App Purchase Logic with useRevenueCat Hook

Source: https://nextnative.dev/docs/features/in-app-purchases

Utilize the `useRevenueCat` hook to manage in-app purchases and subscriptions within your app. This hook provides state management for purchase status, initialization, loading, customer information, and error handling, along with functions to initiate purchases and restore transactions.

```javascript
function PremiumFeature({ user }) {
  const {
    isPro,
    isInitialized,
    isLoading,
    customerInfo,
    error,
    purchase,
    restore,
  } = useRevenueCat(user.id);
 
  if (!isPro) {
    return (
      <div>
        <h2>Unlock Premium Features</h2>
        <button onClick={() => purchase("monthly")}>
          Go Premium - $4.99/month
        </button>
      </div>
    );
  }
 
  return <div>Welcome to premium features!</div>;
}
```

--------------------------------

### Create a POST API Route in Next.js

Source: https://nextnative.dev/docs/features/nextjs-api

Implement a POST API route that accepts JSON data and extracts an Authorization header. This route is designed to handle authenticated requests.

```typescript
// app/api/chat/route.ts
export async function POST(req: Request) {
  const body = await req.json();

  // 🔐 Get auth token from header
  const token = req.headers.get("Authorization")?.replace("Bearer ", "");

  console.log("Received token:", token);

  return Response.json({
    message: `You said: ${body.text}`,
  });
}
```

--------------------------------

### Manually Check and Request Push Permissions

Source: https://nextnative.dev/docs/features/push-notifications

Manually check the current push notification permission status and then request permissions if necessary. Use this if you need finer control over the permission flow.

```javascript
await checkPermissions();
await requestPermissions();
```

--------------------------------

### Integrate Splash Screen in App Router

Source: https://nextnative.dev/docs/tutorials/splash-screen

Import the splash screen hook and component into your app's router to manage the splash screen's display during app initialization.

```typescript
import { useSplashScreen } from "@/app/(mobile)/hooks/use SplashScreen";
import SplashScreen from "@/app/(mobile)/components/SplashScreen";

const AppRouter = () => {
  const { showSplash } = useSplashScreen();

  return (
    <IonApp>
      {showSplash && <SplashScreen />}
      {/* Rest of your app */}
    </IonApp>
  );
};
```

--------------------------------

### Check Platform with Capacitor

Source: https://nextnative.dev/docs/tutorials/native-device-features

Determine the current platform (iOS, Android, or web) your app is running on. This is essential for implementing platform-specific behavior.

```typescript
import { Capacitor } from "@capacitor/core";
 
// Check if running on a native platform (iOS/Android)
const isNative = Capacitor.isNativePlatform();
 
// Get the specific platform
const platform = Capacitor.getPlatform(); // 'ios', 'android', or 'web'
 
// Example usage
if (platform === "ios") {
  // iOS-specific code
} else if (platform === "android") {
  // Android-specific code
} else {
  // Web fallback
}
```

--------------------------------

### Android Google Sign-In

Source: https://nextnative.dev/docs/features/authorization

Use the Capacitor plugin to trigger Google sign-in on Android. Ensure you are testing on a physical device with Google Play Services.

```typescript
import { FirebaseAuthentication } from "@capacitor-firebase/authentication";

await FirebaseAuthentication.signInWithGoogle();
```

--------------------------------

### Add Firebase iOS SDK via Swift Package Manager

Source: https://nextnative.dev/docs/features/authorization

Steps to add the Firebase iOS SDK using Swift Package Manager in Xcode. Ensure to select only the necessary modules like FirebaseAuth.

```swift
https://github.com/firebase/firebase-ios-sdk
```

--------------------------------

### Set Production URL Environment Variable

Source: https://nextnative.dev/docs/troubleshooting

Ensure the `NEXT_PUBLIC_PRODUCTION_URL` environment variable is correctly set in your `.env.local` file to your deployed API endpoint. This is crucial for your mobile app to fetch data correctly.

```env
NEXT_PUBLIC_PRODUCTION_URL
```

--------------------------------

### Configure Android for Firebase

Source: https://nextnative.dev/docs/tutorials/ship-in-5-minutes

This snippet shows how to conditionally apply the Google Services plugin in the Android build.gradle file. It checks for the existence of google-services.json to determine if the plugin should be applied, which is necessary for push notifications.

```gradle
try {
    def servicesJSON = file('google-services.json')
    if (servicesJSON.text) {
        apply plugin: 'com.google.gms.google-services'
    }
} catch(Exception e) {
    logger.info("google-services.json not found, google-services plugin not applied. Push Notifications won't work")
}
```

--------------------------------

### Implement OPTIONS Handler for CORS Preflight

Source: https://nextnative.dev/docs/features/nextjs-api

Add an OPTIONS handler to a Next.js API route to support CORS preflight requests, essential for cross-origin requests from mobile apps, especially those with custom headers.

```typescript
// app/api/chat/route.ts
export async function OPTIONS() {
  return new Response(null, {
    status: 204,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  });
}
```

--------------------------------

### Manage Splash Screen Visibility with Custom Hook

Source: https://nextnative.dev/docs/tutorials/splash-screen

This hook handles the native Capacitor splash screen, controls the in-app splash screen's visibility, and returns a `showSplash` boolean for conditional rendering.

```typescript
import { useState, useEffect } from "react";
import { SplashScreen as SplashScreenPlugin } from "@capacitor/splash-screen";

export const useSplashScreen = () => {
  const [showSplash, setShowSplash] = useState(true);

  useEffect(() => {
    const hideSplash = async () => {
      await SplashScreenPlugin.hide();
      setTimeout(() => {
        setShowSplash(false);
      }, 2000);
    };
    hideSplash();
  }, []);

  return { showSplash };
};
```

--------------------------------

### Custom Hook for Device Camera

Source: https://nextnative.dev/docs/tutorials/native-device-features

Encapsulates camera functionality into a reusable React hook. Includes state management for photo, loading, and errors, with a check for native platform availability.

```typescript
// hooks/useDeviceCamera.ts
import { useState } from "react";
import { Camera, CameraResultType, CameraSource } from "@capacitor/camera";
import { Capacitor } from "@capacitor/core";
 
export function useDeviceCamera() {
  const [photo, setPhoto] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);
 
  async function takePhoto() {
    if (!Capacitor.isNativePlatform()) {
      setError(new Error("Camera is only available on native platforms"));
      return null;
    }
 
    try {
      setLoading(true);
      setError(null);
 
      const image = await Camera.getPhoto({
        quality: 90,
        allowEditing: true,
        resultType: CameraResultType.Uri,
        source: CameraSource.Camera,
      });
 
      const photoUrl = image.webPath || "";
      setPhoto(photoUrl);
      return photoUrl;
    } catch (err) {
      setError(err instanceof Error ? err : new Error("Unknown camera error"));
      return null;
    } finally {
      setLoading(false);
    }
  }
 
  return {
    photo,
    takePhoto,
    loading,
    error,
  };
}
```

--------------------------------

### Basic ScreenContainer Usage

Source: https://nextnative.dev/docs/components/screen-container

Wrap your screen content with ScreenContainer to ensure consistent spacing and safe area padding. This component handles avoiding notches and bottom tabs.

```javascript
import ScreenContainer from "@/components/ScreenContainer";
 
export default function SettingsScreen() {
  return (
    <ScreenContainer>
      <div>Settings screen</div>
    </ScreenContainer>
  );
}
```

--------------------------------

### Navigation Between Screens

Source: https://nextnative.dev/docs/tutorials/ionic-router

Shows two common methods for navigating between screens in Ionic React applications: using the Link component from react-router-dom and programmatically via the useHistory hook.

```typescript
// Using Link component
import { Link } from "react-router-dom";

<Link to="/app/messages/123">View Message</Link>;

// Using history object
import { useHistory } from "react-router-dom";

const history = useHistory();
history.push("/app/messages/123");

```

--------------------------------

### Update Capacitor Configuration

Source: https://nextnative.dev/docs/preparing-for-deployment/rename-your-app

Ensure the app ID in capacitor.config.js is updated to match the new application name.

```javascript
{
  "appId": "com.mycompany.appname",
  "appName": "MyApp"
}
```

--------------------------------

### Skip Auth Logic for Testing

Source: https://nextnative.dev/docs/features/authorization

Set this boolean to true to bypass the sign-in screen during development and testing.

```typescript
// (mobile)/router.tsx
const isSignedInTest = true;
```

--------------------------------

### Fetch Data with SWR in a React Component

Source: https://nextnative.dev/docs/features/nextjs-api

Use the SWR hook to fetch data from a Next.js API route within a client component. Configure optional polling with `refreshInterval`.

```typescript
"use client";

import config from "@/config";
import { fetcher } from "@/lib/utils";
import useSWR from "swr";

function HelloMessage() {
  const { data, isLoading, error } = useSWR(
    `${config.api.url}/hello`,
    fetcher,
    {
      refreshInterval: 500, // optional polling
    }
  );

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error loading chat</div>;

  return (
    <div className="text-3xl font-[600] mt-36 mx-auto w-fit">
      {data?.message}
    </div>
  );
}

export default HelloMessage;
```

--------------------------------

### Conditionally Showing Tab Bar

Source: https://nextnative.dev/docs/tutorials/ionic-router

Demonstrates how to conditionally render the IonTabBar based on the current route, hiding it on detail pages to provide a cleaner user experience.

```typescript
const [showTabs, setShowTabs] = useState(true);

// Use effect to determine when to show tabs
useEffect(() => {
  const isDetailRoute =
    location.pathname.includes("/app/messages/") ||
    location.pathname.includes("/app/profile/edit");
  setShowTabs(!isDetailRoute);
}, [location]);

return (
  <IonTabs>
    <IonRouterOutlet>{/* Your routes here */}</IonRouterOutlet>

    {showTabs && (
      <IonTabBar slot="bottom">{/* Your tab buttons here */}</IonTabBar>
    )}
  </IonTabs>
);

```

--------------------------------

### Capacitor Share Plugin for Native Sharing

Source: https://nextnative.dev/docs/tutorials/native-device-features

Access the native sharing dialog to share content from your app. This includes setting the title, text, URL, and dialog title.

```typescript
import { Share } from "@capacitor/share";
 
async function shareContent() {
  await Share.share({
    title: "Check out NextNative!",
    text: "Build cross-platform apps with Next.js",
    url: "https://nextnative.dev",
    dialogTitle: "Share with your friends",
  });
}
```

```typescript
import { Share } from "@capacitor/share";
 
// In a component
<Button
  onClick={async () => {
    await Share.share({
      title: "NextNative",
      text: "Build mobile apps with NextNative",
      url: "https://nextnative.dev",
      dialogTitle: "Share with friends",
    });
  }}>
  Share App
</Button>
```

--------------------------------

### Update Android App Configuration

Source: https://nextnative.dev/docs/preparing-for-deployment/rename-your-app

Modify the namespace and applicationId in the app's build.gradle file to reflect the new app name.

```gradle
android {
  -       namespace "com.nextnative.app"
  +       namespace "com.mycompany.appname"
defaultConfig {
  -       applicationId "com.nextnative.app"
  +       applicationId "com.mycompany.appname"
  }
}
```

--------------------------------

### Access Device Camera

Source: https://nextnative.dev/docs/tutorials/native-device-features

Use the Capacitor Camera API to capture photos. Configure quality, editing options, result type, and source. The image URI can be used directly or uploaded.

```typescript
import { Camera, CameraResultType, CameraSource } from "@capacitor/camera";
 
async function takePicture() {
  try {
    const image = await Camera.getPhoto({
      quality: 90,
      allowEditing: true,
      resultType: CameraResultType.Uri,
      source: CameraSource.Camera,
    });
 
    // The image URI can be used in an <img> tag or uploaded to a server
    const imageUrl = image.webPath;
    setProfileImage(imageUrl);
  } catch (error) {
    console.error("Failed to take photo:", error);
  }
}
```

--------------------------------

### Handle Push Notifications with Firebase

Source: https://nextnative.dev/docs/tutorials/native-device-features

Integrate Firebase Messaging for push notifications. This includes requesting permissions, registering for notifications, obtaining the FCM token, and listening for incoming messages.

```typescript
import { FirebaseMessaging } from "@capacitor-firebase/messaging";
 
// Request permission to receive notifications
async function requestNotificationPermission() {
  try {
    const { receive } = await FirebaseMessaging.requestPermissions();
    if (receive === "granted") {
      await registerNotifications();
    }
  } catch (error) {
    console.error("Notification permission error:", error);
  }
}
 
// Register for push notifications
async function registerNotifications() {
  // Get the FCM token
  const { token } = await FirebaseMessaging.getToken();
 
  // Save the token to your server
  await saveTokenToServer(token);
 
  // Listen for incoming messages
  FirebaseMessaging.addListener("notificationReceived", (notification) => {
    console.log("New notification:", notification);
  });
}
```

--------------------------------

### Update MainActivity Package Name

Source: https://nextnative.dev/docs/troubleshooting

After manually renaming the Android project directory, update the 'package' declaration in `android/src/main/java/com/[yourcompany]/[appname]/MainActivity.java` to reflect your new app's package name.

```java
package com.[yourcompany].[appname];
```

--------------------------------

### Refresh Cached Data with SWR `mutate`

Source: https://nextnative.dev/docs/features/nextjs-api

Use the `mutate` function from SWR to re-fetch data after a POST request, ensuring the UI reflects the latest information. This is useful for instant UI updates.

```typescript
import useSWR, { mutate } from "swr";

const sendMessage = async () => {
  await fetch(`${config.api.url}/chat`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text }),
  });

  mutate(`/api/chat`); // 🔁 Re-fetch latest data from API
};
```

--------------------------------

### Add Notification Listeners

Source: https://nextnative.dev/docs/features/push-notifications

Enables listeners for receiving incoming push notifications and handling user interactions with them. These listeners should be enabled when the app is active.

```javascript
addNotificationReceivedListener();
addNotificationActionPerformedListener();
```

--------------------------------

### Nested Routes for Detail Pages

Source: https://nextnative.dev/docs/tutorials/ionic-router

Configures nested routes within an IonRouterOutlet to handle list and detail views, including routes with dynamic parameters like message IDs.

```typescript
<IonRouterOutlet>
  {/* List route */}
  <Route exact path="/app/messages" component={MessagesListScreen} />

  {/* Detail route with parameter */}
  <Route
    path="/app/messages/:messageId"
    render={({ match }) => (
      <MessageDetailScreen messageId={match.params.messageId} />
    )}
  />
</IonRouterOutlet>

```

--------------------------------

### ModalWrapper Component

Source: https://nextnative.dev/docs/components/modal

The ModalWrapper component provides the structure and layout for the modal, optionally including a header.

```APIDOC
## ModalWrapper
Clean layout with optional header.

### Props
- **modalRef** (Ref): A ref object obtained from `useModalController`.
- **presentingElement** (React.RefObject): A ref to the element that will present the modal.

### Example Usage
```javascript
<ModalWrapper modalRef={modalRef} presentingElement={presentingElement}>
  <div>
    <button onClick={close}>Close</button>
    <PremiumScreen dismiss={close} />
  </div>
</ModalWrapper>
```
```

--------------------------------

### Rename Java Package in Android Studio

Source: https://nextnative.dev/docs/preparing-for-deployment/rename-your-app

Refactor the package name in Android Studio to match your new app's package name.

```java
package com.mycompany.appname;
```

--------------------------------

### useModalController Hook

Source: https://nextnative.dev/docs/components/modal

The useModalController hook provides functions to manage the open and close states of a modal.

```APIDOC
## useModalController
A custom hook that makes modal management easier.

Returns:
- **modalRef**: Ref to pass into modal
- **isOpen**: Whether modal is open
- **open()**: Opens the modal
- **close()**: Closes the modal

### Example Usage
```javascript
const { modalRef, isOpen, open, close } = useModalController();

// To open the modal
<button onClick={open}>Open Modal</button>

// To render the modal
<ModalWrapper modalRef={modalRef} presentingElement={presentingElement}>
  <div>
    <button onClick={close}>Close</button>
    {/* Modal content */}
  </div>
</ModalWrapper>
```
```

--------------------------------

### Add Token and Delivered Notifications Listeners

Source: https://nextnative.dev/docs/features/push-notifications

Includes listeners for when the FCM token is received or updated, and for retrieving notifications that have been delivered to the device. Useful for debugging and advanced handling.

```javascript
addTokenReceivedListener();
getDeliveredNotifications();
```

--------------------------------

### Remove Google Services Plugin for Android

Source: https://nextnative.dev/docs/features/authorization

If Firebase Auth/Notifications are not needed, remove this line from your app's build.gradle file.

```gradle
apply plugin: 'com.google.gms.google-services'
```

--------------------------------

### Update FCM Token for User

Source: https://nextnative.dev/docs/features/push-notifications

Requests the FCM token for the current device and sends it to your backend API to associate it with the user. This is crucial for targeting notifications to specific users.

```javascript
await updateFcmToken(user);
```

--------------------------------

### Remove All Notification Listeners

Source: https://nextnative.dev/docs/features/push-notifications

Cleans up all active push notification listeners. This is important for preventing memory leaks and ensuring correct behavior when a user logs out or the app is closed.

```javascript
removeAllListeners();
```

--------------------------------

### Send FCM Push Notification

Source: https://nextnative.dev/docs/features/push-notifications

Use this function to send a push notification to a specific device token via Firebase Cloud Messaging. Ensure your Firebase service account is configured.

```javascript
await sendFcmMessage({
  message: {
    token: "<device-fcm-token>",
    notification: {
      title: "New Message",
      body: "You've got mail 🚀",
    },
  },
});
```
Tokens:
Raw