Ionic + Capacitor Mobile Development
Stack
{
"@ionic/react": "8.0.0",
"@ionic/react-router": "8.0.0",
"@capacitor/core": "6.0.0",
"@capacitor/ios": "6.0.0",
"@capacitor/android": "6.0.0",
"@capacitor/camera": "6.0.0",
"@capacitor/push-notifications": "6.0.0",
"@capacitor/network": "6.0.0",
"@capacitor-community/sqlite": "6.0.0"
}
Project Structure
apps/mobile/
├── capacitor.config.ts
├── ionic.config.json
├── src/
│ ├── App.tsx
│ ├── main.tsx
│ ├── theme/variables.css
│ ├── pages/
│ │ ├── Dashboard.tsx
│ │ └── Settings.tsx
│ ├── components/
│ │ ├── OfflineIndicator.tsx
│ │ └── SensorCard.tsx
│ ├── hooks/
│ │ ├── useOfflineData.ts
│ │ ├── useCamera.ts
│ │ └── usePushNotifications.ts
│ ├── services/
│ │ ├── api.ts
│ │ ├── database.ts
│ │ └── sync.ts
│ └── stores/
├── ios/
├── android/
└── resources/
Capacitor Configuration
// capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'My App',
webDir: 'dist',
server: {
androidScheme: 'https',
iosScheme: 'https',
},
plugins: {
SplashScreen: {
launchAutoHide: false,
splashFullScreen: true,
},
PushNotifications: {
presentationOptions: ['badge', 'sound', 'alert'],
},
CapacitorSQLite: {
iosDatabaseLocation: 'Library/CapacitorDatabase',
},
},
};
export default config;
App Setup
// src/App.tsx
import { IonApp, IonRouterOutlet, IonSplitPane, setupIonicReact } from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';
import { Route, Redirect } from 'react-router-dom';
import '@ionic/react/css/core.css';
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
import './theme/variables.css';
setupIonicReact({ mode: 'ios' });
export function App() {
return (
<IonApp>
<IonReactRouter>
<IonSplitPane contentId="main">
<Menu />
<IonRouterOutlet id="main">
<Route exact path="/dashboard" component={Dashboard} />
<Route exact path="/settings" component={Settings} />
<Route exact path="/"><Redirect to="/dashboard" /></Route>
</IonRouterOutlet>
</IonSplitPane>
</IonReactRouter>
</IonApp>
);
}
Theme Variables
/* src/theme/variables.css */
:root {
--ion-color-primary: #0969ff;
--ion-color-primary-contrast: #ffffff;
--ion-color-secondary: #3dc2ff;
--ion-color-success: #2dd36f;
--ion-color-warning: #ffc409;
--ion-color-danger: #eb445a;
--ion-font-family: 'Inter', -apple-system, sans-serif;
}
@media (prefers-color-scheme: dark) {
body {
--ion-background-color: #121212;
--ion-text-color: #ffffff;
}
}
Page Example
// src/pages/Dashboard.tsx
import {
IonContent, IonHeader, IonPage, IonTitle, IonToolbar,
IonRefresher, IonRefresherContent, IonGrid, IonRow, IonCol,
RefresherEventDetail,
} from '@ionic/react';
export function Dashboard() {
const { data: items, refetch } = useItems();
const handleRefresh = async (event: CustomEvent<RefresherEventDetail>) => {
await refetch();
event.detail.complete();
};
return (
<IonPage>
<IonHeader>
<IonToolbar>
<IonTitle>Dashboard</IonTitle>
<OfflineIndicator slot="end" />
</IonToolbar>
</IonHeader>
<IonContent fullscreen>
<IonRefresher slot="fixed"
<IonRefresherContent />
</IonRefresher>
<IonGrid>
<IonRow>
{items?.map((item) => (
<IonCol size="12" sizeMd="6" key={item.id}>
<ItemCard item={item} />
</IonCol>
))}
</IonRow>
</IonGrid>
</IonContent>
</IonPage>
);
}
Capacitor Plugins
Camera
// src/hooks/useCamera.ts
import { Camera, CameraResultType, CameraSource } from '@capacitor/camera';
export function useCamera() {
const takePhoto = async (): Promise<string | null> => {
try {
const photo = await Camera.getPhoto({
resultType: CameraResultType.Base64,
source: CameraSource.Camera,
quality: 80,
width: 1024,
});
return photo.base64String ?? null;
} catch (error) {
console.error('Camera error:', error);
return null;
}
};
return { takePhoto };
}
Push Notifications
// src/hooks/usePushNotifications.ts
import { useEffect } from 'react';
import { PushNotifications } from '@capacitor/push-notifications';
import { Capacitor } from '@capacitor/core';
export function usePushNotifications() {
useEffect(() => {
if (!Capacitor.isNativePlatform()) return;
const setup = async () => {
const perm = await PushNotifications.requestPermissions();
if (perm.receive !== 'granted') return;
await PushNotifications.register();
PushNotifications.addListener('registration', (token) => {
console.log('Push token:', token.value);
// Send to backend
});
PushNotifications.addListener('pushNotificationReceived', (notification) => {
console.log('Notification:', notification);
});
PushNotifications.addListener('pushNotificationActionPerformed', (action) => {
const data = action.notification.data;
if (data.type === 'alert') {
window.location.href = `/alerts/${data.alertId}`;
}
});
};
setup();
return () => { PushNotifications.removeAllListeners(); };
}, []);
}
Network Status
// src/hooks/useNetwork.ts
import { useEffect, useState } from 'react';
import { Network, ConnectionStatus } from '@capacitor/network';
export function useNetwork() {
const [status, setStatus] = useState<ConnectionStatus>({ connected: true, connectionType: 'unknown' });
useEffect(() => {
const handler = Network.addListener('networkStatusChange', setStatus);
Network.getStatus().then(setStatus);
return () => { handler.remove(); };
}, []);
return { isOnline: status.connected, connectionType: status.connectionType };
}
SQLite Offline Storage
// src/services/database.ts
import { CapacitorSQLite, SQLiteConnection } from '@capacitor-community/sqlite';
class DatabaseService {
private sqlite = new SQLiteConnection(CapacitorSQLite);
private db = null;
async init() {
this.db = await this.sqlite.createConnection('appdb', false, 'no-encryption', 1, false);
await this.db.open();
await this.runMigrations();
}
private async runMigrations() {
await this.db.execute(`
CREATE TABLE IF NOT EXISTS items (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
value REAL,
updated_at INTEGER
);
CREATE TABLE IF NOT EXISTS sync_queue (
id INTEGER PRIMARY KEY AUTOINCREMENT,
entity_type TEXT NOT NULL,
entity_id TEXT NOT NULL,
operation TEXT NOT NULL,
payload TEXT NOT NULL,
created_at INTEGER NOT NULL
);
`);
}
async getItems() {
const result = await this.db.query('SELECT * FROM items ORDER BY name');
return result.values ?? [];
}
async saveItem(item) {
await this.db.run(
`INSERT OR REPLACE INTO items (id, name, value, updated_at) VALUES (?, ?, ?, ?)`,
[item.id, item.name, item.value, Date.now()]
);
}
async addToSyncQueue(entityType, entityId, operation, payload) {
await this.db.run(
`INSERT INTO sync_queue (entity_type, entity_id, operation, payload, created_at) VALUES (?, ?, ?, ?, ?)`,
[entityType, entityId, operation, JSON.stringify(payload), Date.now()]
);
}
}
export const database = new DatabaseService();
Sync Service
// src/services/sync.ts
import { database } from './database';
import { api } from './api';
import { Network } from '@capacitor/network';
class SyncService {
private syncing = false;
async start() {
Network.addListener('networkStatusChange', async (status) => {
if (status.connected) await this.sync();
});
setInterval(() => this.sync(), 5 * 60 * 1000);
await this.sync();
}
async sync() {
if (this.syncing) return;
const status = await Network.getStatus();
if (!status.connected) return;
this.syncing = true;
try {
await this.pullData();
await this.pushData();
} finally {
this.syncing = false;
}
}
private async pullData() {
const items = await api.items.list();
for (const item of items) {
await database.saveItem(item);
}
}
private async pushData() {
const pending = await database.getPendingSyncItems();
for (const item of pending) {
await api.generic[item.operation](item.entityType, item.payload);
await database.markSynced(item.id);
}
}
}
export const syncService = new SyncService();
Offline-First Hook
// src/hooks/useOfflineData.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { database } from '../services/database';
import { api } from '../services/api';
import { useNetwork } from './useNetwork';
export function useOfflineItems() {
const { isOnline } = useNetwork();
return useQuery({
queryKey: ['items'],
queryFn: async () => {
if (isOnline) {
const items = await api.items.list();
for (const item of items) await database.saveItem(item);
return items;
}
return database.getItems();
},
});
}
export function useOfflineCreate() {
const { isOnline } = useNetwork();
const queryClient = useQueryClient();
return useMutation({
mutationFn: async (data) => {
if (isOnline) return api.items.create(data);
const localId = crypto.randomUUID();
await database.saveItem({ ...data, id: localId });
await database.addToSyncQueue('item', localId, 'create', data);
return { ...data, id: localId };
},
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
});
}
Offline Indicator Component
// src/components/OfflineIndicator.tsx
import { IonBadge, IonIcon } from '@ionic/react';
import { cloudOfflineOutline, syncOutline } from 'ionicons/icons';
import { useNetwork } from '../hooks/useNetwork';
export function OfflineIndicator({ slot }: { slot?: string }) {
const { isOnline } = useNetwork();
const { pendingCount } = useSyncStatus();
if (isOnline && pendingCount === 0) return null;
return (
<IonBadge slot={slot} color={isOnline ? 'warning' : 'danger'}>
<IonIcon icon={isOnline ? syncOutline : cloudOfflineOutline} />
{pendingCount > 0 && ` ${pendingCount}`}
</IonBadge>
);
}
Best Practices
- Offline-First - Always check network before API calls
const { isOnline } = useNetwork();
if (isOnline) await api.fetch(); else await database.get();
- Use Ionic Components - Native look and feel
// Good
<IonButton>Click</IonButton>
<IonCard>Content</IonCard>
// Avoid raw HTML in pages
<button>Click</button>
- Pull to Refresh - On all list pages
<IonRefresher slot="fixed"
<IonRefresherContent />
</IonRefresher>
- Loading States - Show spinners
if (isLoading) return <IonContent><IonSpinner /></IonContent>;
- Platform Detection - For native-only features
import { Capacitor } from '@capacitor/core';
if (Capacitor.isNativePlatform()) { /* native code */ }
Related Skills
mobile-ionic: Full mobile patternssqlite-embedded: Local databasejwt-auth: Mobile authentication
jnzader-vault