Integrating Capacitor Core

1. Installing Capacitor

Capacitor is the official cross-platform runtime for Ionic apps. It allows you to build native mobile and desktop apps using web technologies like HTML, CSS, and JavaScript.

Step	Description	Action
1	Ensure your Ionic project is set up with the latest version of Ionic CLI.	`npm install -g @ionic/cli`
2	Initialize Capacitor in your project.	`ionic integrations add capacitor`
3	Install the Capacitor core packages.	`npm install @capacitor/core`
4	Install platform-specific packages (e.g., iOS or Android).	`npm install @capacitor/ios` or `npm install @capacitor/android`
5	Initialize the Capacitor configuration file.	`npx cap init`

Example: Initializing Capacitor

ionic integrations add capacitor
npm install @capacitor/core @capacitor/ios @capacitor/android
npx cap init

Note: Capacitor requires a minimum version of Ionic 6 or higher to function properly.

2. Initializing Capacitor

Initializing Capacitor in an Ionic project involves setting up the core Capacitor configuration and integrating it with your existing Ionic app structure.

Step	Description	Action
1. Install Capacitor	Install the latest version of Capacitor in your Ionic project.	`npm install @capacitor/core @capacitor/cli`
2. Initialize Capacitor	Run the init command to set up Capacitor in your project.	`npx cap init`
3. Configure Capacitor	Update the `capacitor.config.ts` file with project-specific settings.	`{<br> "appId": "com.example.app",<br> "appName": "MyApp",<br> "webDir": "www",<br> "server": {<br> "androidScheme": "https"<br> }<br>}`

Note: Ensure that the webDir path matches your Ionic build output directory.

Example: Basic Capacitor Configuration

import { CapacitorConfig } from '@capacitor/cli';<br><br>const config: CapacitorConfig = {<br>  appId: 'com.example.app',<br>  appName: 'MyApp',<br>  webDir: 'www',<br>  bundledWebRuntime: false,<br>};<br><br>export default config;

Initialization Steps Summary

Install @capacitor/core and @capacitor/cli.
Run npx cap init to initialize the Capacitor project.
Update capacitor.config.ts with your app's configuration.

3. Adding Native Platforms

To add native platforms to your Ionic project using Capacitor, follow these steps:

Workflow

Install the native platform packages using npm or yarn.
Update the Capacitor configuration file (capacitor.config.ts or capacitor.config.json) to include the new platform.
Synchronize the project with the native platforms using the Capacitor CLI.

Below is a table summarizing the steps for adding iOS and Android platforms:

Platform	Command	Description
iOS	`npx cap add ios`	Adds the iOS platform to your project.
Android	`npx cap add android`	Adds the Android platform to your project.

Example: Adding iOS Platform

npx cap add ios

Example: Adding Android Platform

npx cap add android

Note: After adding a platform, you must run npx cap sync to update the native project files.

4. Syncing Project

Example: Syncing Capacitor Project

npm run build
npx cap sync

Command	Description	Notes
npm run build	Builds the web assets	Required before syncing
npx cap sync	Syncs web assets to native platforms	Updates all platforms

Note: The cap sync command copies built web assets to the native platforms (iOS, Android) and updates the configuration files.

5. Copying Web Assets

When building an Ionic app with Capacitor, web assets such as images, stylesheets, and JavaScript files need to be copied to the native platforms. This ensures that the app functions correctly on both web and mobile devices.

Asset Type	Description	Copy Location
Images	Static image files used in the app.	Native project's `resources` directory or `www` folder.
CSS/SCSS	Styling files for the app.	Native project's `www` folder or `resources` directory.
JavaScript	Client-side scripts and libraries.	Native project's `www` folder or `resources` directory.

Example: Copying Assets with Capacitor CLI

npm run build
npx cap sync

Note: The cap sync command copies all necessary assets to the native platforms. Ensure that your build process includes all required assets before running this command.

6. Opening Native IDE

To open the native IDE for your Ionic project using Capacitor:

Run the command: npx cap open
If no platform is specified, it will open the default IDE for all configured platforms
For a specific platform, run: npx cap open <platform> where <platform> is either ios or android

This command will launch the appropriate native IDE (Xcode for iOS, Android Studio for Android) with your project loaded.

Note: Ensure that the native project files have been built using npx cap sync before opening the IDE.

Command	Description	Platform Support
npx cap open	Opens the native IDE for all platforms	iOS, Android
npx cap open ios	Opens Xcode for iOS project	iOS
npx cap open android	Opens Android Studio for Android project	Android

7. Running on Device

Command	Description	Notes
ionic capacitor run android	Builds and runs the app on an Android device	Requires Android device with USB debugging enabled
ionic capacitor run ios	Builds and runs the app on an iOS device	Requires iOS device with provisioning profile
ionic capacitor run android --livereload	Runs with live reload on Android device	Useful for development and testing
ionic capacitor run ios --livereload	Runs with live reload on iOS device	Useful for development and testing

Example: Running on Android Device

ionic capacitor run android --livereload

Example: Running on iOS Device

ionic capacitor run ios --livereload

Note: Ensure that your device is properly connected and recognized by the development environment before running these commands.

8. Updating Capacitor

Version	Update Command	Notes
Capacitor 5	`npx cap update`	Latest stable version as of 2026
Capacitor 4	`npx cap update`	Deprecated in favor of v5

Example: Updating to Capacitor 5

npm install @capacitor/core@latest
npm install @capacitor/cli@latest
npx cap update

Note: Ensure all plugins are compatible with Capacitor 5 before updating.

Warning: Capacitor 4 is deprecated and no longer supported as of 2026.

9. Configuring Capacitor

Property	Value	Description
appId	`com.example.app`	Unique identifier for the app
appName	`MyApp`	Name of the application as displayed to users
webDir	`build`	Directory where built web assets are stored
bundledWebRuntime	`false`	Whether to bundle the web runtime with the app

Example: capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'MyApp',
  webDir: 'build',
  bundledWebRuntime: false
};

export default config;

Note: The webDir should point to the directory where your built web assets are located.

Warning: Changing appId after initial setup may cause issues with plugins or native functionality.

10. Using Environment Variables

Variable	Value	Description
IONIC_ENV	`production`	Set to `development` or `production` to control behavior
IONIC_APP_ID	`com.example.app`	Unique identifier for the app in Capacitor
CAPACITOR_SERVER_URL	`http://localhost:3000`	URL to the development server (used in dev mode)

Example: Setting Environment Variables in Ionic

export IONIC_ENV=production
export IONIC_APP_ID=com.example.app

Note: Environment variables can also be set in .env files or via build scripts.