(null);
const [pushStatus, setPushStatus] = useState("Enable Push Notifications");
const [pushLoading, setPushLoading] = useState(false);
const subscribeToPush = useCallback(async () => {
setPushLoading(true);
setPushStatus("Subscribing…");
setPushError(null);
try {
// Check if we're on a native platform
if (!Capacitor.isNativePlatform()) {
setPushError("Push notifications are only available on mobile devices.");
setPushStatus("Enable Push Notifications");
return;
}
// Request permissions
const permission = await PushNotifications.requestPermissions();
if (permission.receive === "denied") {
setPushError("Notification permission denied.");
setPushStatus("Enable Push Notifications");
return;
}
// Set up listeners BEFORE calling register()
const registrationListener = await PushNotifications.addListener(
"registration",
async (token) => {
if (!token || !token.value) {
setPushError("Received invalid registration token.");
setPushStatus("Enable Push Notifications");
return;
}
// Send token to your backend
try {
const response = await fetch("https://your-api.com/api/push/subscribe", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ token: token.value }),
});
if (response.ok) {
setPushEnabled(true);
setPushStatus("Push notifications enabled!");
} else {
setPushError("Failed to save notification token.");
setPushStatus("Enable Push Notifications");
}
} catch (err) {
setPushError("Failed to send token to server.");
setPushStatus("Enable Push Notifications");
}
}
);
const registrationErrorListener = await PushNotifications.addListener(
"registrationError",
(error) => {
const errorMessage = (error as any)?.error || String(error) || "Unknown error";
setPushError(`Failed to register: ${errorMessage}`);
setPushStatus("Enable Push Notifications");
}
);
// Listen for received notifications
const receivedListener = await PushNotifications.addListener(
"pushNotificationReceived",
(notification) => {
console.log("Push notification received:", notification);
// Handle notification received while app is in foreground
}
);
// Listen for notification actions
const actionListener = await PushNotifications.addListener(
"pushNotificationActionPerformed",
(notification) => {
console.log("Push notification action:", notification);
// Handle notification tap/action
}
);
// Create notification channel for Android (required for Android 8.0+)
try {
await PushNotifications.createChannel({
id: "default",
name: "Default Channel",
description: "General notifications",
importance: 5, // High importance
visibility: 1, // Public visibility
lights: true,
vibration: true,
});
} catch (channelError) {
console.warn("Failed to create notification channel:", channelError);
// Continue anyway - channel might already exist
}
// Register for push notifications AFTER listeners are set up
await PushNotifications.register();
} catch (err) {
const errorMessage = (err as Error).message.toLowerCase();
let userFriendlyError = "Failed to enable push notifications.";
if (errorMessage.includes("simulator") || errorMessage.includes("emulator")) {
userFriendlyError = "Push notifications are not available in the simulator. Please test on a physical device.";
} else if (errorMessage.includes("permission") || errorMessage.includes("denied")) {
userFriendlyError = "Notification permission was denied. Please enable notifications in your device settings.";
}
setPushError(userFriendlyError);
setPushStatus("Enable Push Notifications");
} finally {
setPushLoading(false);
}
}, []);
const unsubscribeFromPush = async () => {
setPushLoading(true);
setPushError(null);
setPushStatus("Unsubscribing…");
try {
// Remove token from your backend
const response = await fetch("https://your-api.com/api/push/unsubscribe", {
method: "POST",
});
if (response.ok) {
setPushEnabled(false);
setPushStatus("Enable Push Notifications");
} else {
setPushError("Failed to unsubscribe.");
setPushStatus("Disable Push Notifications");
}
} catch (err) {
setPushError("Failed to unsubscribe from push notifications.");
setPushStatus("Disable Push Notifications");
} finally {
setPushLoading(false);
}
};
return {
pushEnabled,
pushError,
pushStatus,
pushLoading,
subscribeToPush,
unsubscribeFromPush,
};
}
```
### Step 6: Use Push Notifications in Components
```tsx
"use client";
import { usePushNotifications } from "@/app/hooks/usePushNotifications";
import { IonButton } from "@ionic/react";
export default function SettingsPage() {
const {
pushEnabled,
pushError,
pushStatus,
pushLoading,
subscribeToPush,
unsubscribeFromPush,
} = usePushNotifications();
return (
Push Notifications
{pushError &&
{pushError}
}
{pushStatus}
);
}
```
### Step 7: Backend Integration
Your backend needs to:
1. **Store push tokens** when users subscribe
2. **Send push notifications** using:
- **iOS**: APNs (using your APNs key/certificate)
- **Android**: FCM (using Firebase Admin SDK)
Example backend endpoint (Node.js):
```typescript
// Store token
app.post("/api/push/subscribe", async (req, res) => {
const { token, userId } = req.body;
// Store token in database associated with userId
await db.pushTokens.create({ userId, token, platform: "ios" });
res.json({ success: true });
});
// Send notification (example using firebase-admin for Android)
import admin from "firebase-admin";
app.post("/api/push/send", async (req, res) => {
const { userId, title, body } = req.body;
const tokens = await db.pushTokens.findAll({ where: { userId } });
const messages = tokens.map(token => ({
token: token.token,
notification: { title, body },
}));
await admin.messaging().sendAll(messages);
res.json({ success: true });
});
```
### Step 8: Badge Management (Optional)
You can clear notification badges when the app becomes active:
```typescript
import { App, AppState } from "@capacitor/app";
import { PushNotifications } from "@capacitor/push-notifications";
useEffect(() => {
if (Capacitor.isNativePlatform()) {
const clearBadge = async () => {
try {
await PushNotifications.removeAllDeliveredNotifications();
} catch (error) {
console.warn("Failed to clear badge:", error);
}
};
// Clear badge on app launch
clearBadge();
// Clear badge when app becomes active
const stateListener = App.addListener("appStateChange", (state: AppState) => {
if (state.isActive) {
clearBadge();
}
});
return () => {
stateListener.remove();
};
}
}, []);
```
## Development Workflow
### Running Development Server
```bash
npm run dev
```
This runs Next.js normally (not static export) for development.
### Building for Capacitor
```bash
# Build and sync to both platforms
npm run cap:sync
# Build and sync to iOS only
npm run cap:ios
# Build and sync to Android only
npm run cap:android
```
### Opening Native Projects
```bash
# Open iOS project in Xcode
npm run cap:open:ios
# Open Android project in Android Studio
npm run cap:open:android
```
### Testing on Devices
1. **iOS**: Connect device, select it in Xcode, click Run
2. **Android**: Connect device, enable USB debugging, click Run in Android Studio
**Important**: Push notifications only work on physical devices, not simulators/emulators.
## Common Patterns
### Client Components
Always use `"use client"` for components that:
- Use Capacitor APIs
- Use Ionic components that access `window`
- Use browser-only APIs
- Handle user interactions
```tsx
"use client";
import { Capacitor } from "@capacitor/core";
export default function MyComponent() {
// Can use Capacitor APIs here
}
```
### SSR-Safe Patterns
Check for client-side mounting before accessing `window`:
```tsx
"use client";
import { useState, useEffect } from "react";
export default function MyComponent() {
const [isMounted, setIsMounted] = useState(false);
useEffect(() => {
setIsMounted(true);
}, []);
if (!isMounted) {
return null; // or a loading state
}
// Now safe to use window
return {window.location.pathname}
;
}
```
### Platform Detection
```tsx
import { Capacitor } from "@capacitor/core";
if (Capacitor.isNativePlatform()) {
// Native iOS/Android code
} else {
// Web code
}
// Get specific platform
const platform = Capacitor.getPlatform(); // "ios", "android", or "web"
```
### API Client Configuration
For Capacitor apps, use absolute URLs:
```typescript
import { Capacitor } from "@capacitor/core";
export function getApiBaseUrl(): string {
if (process.env.NEXT_PUBLIC_API_URL) {
return process.env.NEXT_PUBLIC_API_URL;
}
if (Capacitor.isNativePlatform()) {
return process.env.NODE_ENV === "development"
? "http://localhost:3000"
: "https://your-api.com";
}
return process.env.NODE_ENV === "development"
? "http://localhost:3000"
: "https://your-api.com";
}
```
## Troubleshooting
### Build Errors
**Issue**: "window is not defined"
- **Solution**: Ensure components using `window` are client components (`"use client"`) and check for mounting
**Issue**: Capacitor build fails
- **Solution**:
- Ensure `CAPACITOR_BUILD=true` is set during build
- Check that all Node.js polyfills are included in `next.config.js`
- Verify `dist` directory exists and contains built files
**Issue**: TypeScript errors with Capacitor
- **Solution**: Ensure `strict: false` in `tsconfig.json` and `ignoreBuildErrors: true` in `next.config.js`
### Capacitor Sync Issues
**Issue**: Sync fails with "webDir not found"
- **Solution**:
- Run `CAPACITOR_BUILD=true npm run build` first
- Verify `capacitor.config.ts` `webDir` matches `next.config.js` `distDir`
**Issue**: Native dependencies not updating
- **Solution**:
- Delete `ios/Pods` and `android/.gradle`
- Run `npx cap sync` again
### Push Notification Issues
**Issue**: Push notifications not working on iOS
- **Solution**:
- Verify APNs key/certificate is configured correctly
- Check that Push Notifications capability is enabled in Xcode
- Ensure testing on physical device (not simulator)
- Check that token is being sent to backend correctly
**Issue**: Push notifications not working on Android
- **Solution**:
- Verify `google-services.json` is in `android/app/`
- Check that Firebase project is configured correctly
- Ensure testing on physical device (not emulator)
- Verify notification channel is created (Android 8.0+)
**Issue**: "Registration event did not fire"
- **Solution**:
- This often indicates APNs configuration issue on iOS
- Verify APNs key/certificate is valid
- Check that app is properly signed with correct provisioning profile
## Additional Resources
- [Next.js Documentation](https://nextjs.org/docs)
- [Capacitor Documentation](https://capacitorjs.com/docs)
- [Ionic React Documentation](https://ionicframework.com/docs/react)
- [Capacitor Push Notifications Plugin](https://capacitorjs.com/docs/apis/push-notifications)
- [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)
- [Apple Push Notification Service](https://developer.apple.com/documentation/usernotifications)