Capacitor Workflow

Working with Capacitor is slightly different than working with a traditional web app. To make your web native Capacitor application, you'll need to do the following steps.

Building your web code

Once you are ready to test your web app on a mobile device, you'll need to build your web app for distribution. If you are using a tool like Create React App or Vite that command will be npm build; while a tool like Angular uses the command ng build. Whatever your command is, you will need to build your web code for distribution in order to use it with Capacitor.

Syncing your web code to your Capacitor project

Once your web code has been built for distribution, you will need to push your web code to the web native Capacitor application. To do this, you can use the Capacitor CLI to "sync" your web code and install/update the required native dependencies.

To sync your project, run:

npx cap sync

Running npx cap sync will copy over your already built web bundle to both your Android and iOS projects as well as update the native dependencies that Capacitor uses.

You can read our docs on sync and more on the Capacitor CLI reference documentation.

info

Did you get an error about "not being able to find the web assets directory?" Update your Capacitor configuration file to use the proper webDir.

Testing your Capacitor app

Once you've synced over your web bundle to your native project, it is time to test your application on a mobile device. There are a few different ways to do this, but the easiest way is to use the built in Capacitor CLI commands.

To run a debug build of your Capacitor app on an iOS device, you can run:

npx cap run ios

Similarly, to run a debug build of your Capacitor app on an Android device, you can run:

npx cap run android

Once you've iterated and tested your application, it is time to compile the final binary to distribute to other mobile devices.

info

You can also run your app on iOS via Xcode or run your app on Android via Android Studio as well. Both options are valid for development. Go ahead and try both to see which option you prefer!

Open your Native IDE

If you'd like more control over your native project you can quickly open the native IDEs using the Capacitor CLI.

To open the iOS Capacitor .xcworkspace project in Xcode, you can run:

npx cap open ios

Similarly, to open the Android Capacitor project in Android Studio, you can run:

npx cap open android

Opening the native project can give you full control over the native runtime of your application. You can create plugins, add custom native code, or compile your application for releasing.

Compiling your native binary

Capacitor does not have a build or compile command, nor will there ever be one. After sync, you are encouraged to open your target platform's IDE: Xcode for iOS or Android Studio for Android, for compiling your native app.

To compile your app in a terminal or in CI environments, you can use gradle or xcodebuild directly. We also suggest using tools such as Fastlane or a cloud build tool Appflow to automate these processes for you. While every application is different, we have an example of a general release process for Capacitor projects. Go and read our publishing guides for iOS and Android for more info on how to deploy to the Apple App Store or the Google Play Store.

Updating Capacitor

Updating your Capacitor runtime is as straightforward as runnin an npm install.

npm i @capacitor/core @capacitor/ios @capacitor/android
npm i -D @capacitor/cli

When updating Capacitor, you want to make sure your Core, Android, and iOS libraries are all the same version. Capacitor Core, Android, and iOS releases are all uploaded simultaneously, meaning that if you install all of the libraries at the same time, you'll be fine!

info

You can subscribe to the Capacitor repo to be notified of new releases. At the top of the repository index, click Watch -> Releases only.