Working With Capacitor

Learn how to use the command line to add and use Capacitor plugins within an Ionic project.

We'll cover the following

Adding Capacitor to a project

Capacitor can be added to an existing frontend project or by starting a new project.

To add Capacitor to an existing non-Ionic frontend project, we simply need to run the following from the command line:

cd name-of-project-directory-here
npm install @capacitor/core @capacitor/cli --save-dev

Note: Your frontend project must have a valid package.json file and a <head> element within the project’s main index.html file, as this will be used to inject Capacitor into upon app initialization.

Once installed, Capacitor needs to be initialized with information about the application with the following command:

npx cap init

This command then prompts us to enter the name of the application and the app ID (the bundle identifier for iOS and the package name for Android). The --web-dir flag can also be used to set the web assets directory (the default is www), if desired.

Finally, the following native platforms (depending on which we want to target) can be used within our project:

npm install @capacitor/android
npx cap add android
npm install @capacitor/ios
npx cap add ios

Now Capacitor is installed, configured, and ready to use within a non-Ionic frontend project. Optionally, Capacitor can also be used to create a brand new project (to which a frontend framework and/or UI library can be added onto afterward) with the following command:

npx @capacitor/cli create

Here, we will be prompted to enter the name of the application and the app ID (the bundle identifier for iOS and the package name for Android). After entering this information, a new application will be created after entering this information, albeit with no UI library or framework.

Using Capacitor within Ionic

Capacitor is installed by default whenever we create a new Ionic project:

ionic start app-name blank --type=angular

Within an existing non-Capacitor Ionic project, Capacitor can be installed as follows:

cd name-of-project-directory
ionic integrations enable capacitor

We recommend installing the following plugins:

npm install @capacitor/app @capacitor/haptics @capacitor/keyboard @capacitor/status-bar --save

After installing Capacitor within an Ionic project, we’ll need to initialize Capacitor with our application information. Our appName is the name of the application and appId is the bundle identifier for iOS and the package name for Android, which would typically be written in reverse domain name notation. For example: com.masteringIonic.myApp. We do this like so:

npx cap init appName appId

These will be written into the capacitor.config.json file, located at the root of the project directory. This file is responsible for managing Capacitor’s tooling and, as a general rule, does not modify native functionality.

Native functionality configuration is handled outside of Capacitor and is detailed in the following guides:

With our Ionic application now configured to use Capacitor, we’ll need to run an Ionic build process at least once before adding any native platforms, like so:

ionic build

This command creates the www directory, which will contain our application assets, that Capacitor has been automatically configured to use as the webDir within the capacitor.config.json file.

Note: Run the commands for creating a new Ionic/Capacitor project and initializing Capacitor in the terminal below! Answer the prompts as they appear.

Get hands-on with 1200+ tech skills courses.