Capacitor Configuration Options — A capacitor.config.ts Reference

Capacitor is a modern hybrid app tool for building iOS and Android apps with a WebView. Its flexibility and extensibility hinge on settings in capacitor.config.ts (or capacitor.config.json).

This article explains each field on the CapacitorConfig interface. There are many options and most goals are reachable, so I hope it helps if you are evaluating WebView apps or already using Capacitor.

Basic settings

• appId (string, optional): A unique app identifier. On iOS this is the Bundle ID; on Android the Application ID. Use reverse-domain notation (e.g. com.example.myapp). Required for App Store and Google Play.

• appName (string, optional): A human-readable app name, used on the stores. You can override it per platform.

• webDir (string, optional): The directory of compiled web assets—the folder that contains the app's index.html. Default is www.

• bundledWebRuntime (boolean, optional, deprecated): Whether to copy the Capacitor runtime bundle. Set true when you do not use a bundler and add capacitor.js to index.html. Deprecated since Capacitor 5.0.0 and scheduled for removal.

Logging and user agent

• loggingBehavior ('none' | 'debug' | 'production', optional): Controls native and JavaScript logging. Choose debug (logs in development only), production (always log), or none (no logs). Default is debug.

• overrideUserAgent (string, optional): Fully replaces the Capacitor WebView user agent.

• appendUserAgent (string, optional): Appends a string to the Capacitor WebView user agent. Ignored when overrideUserAgent is set.

• backgroundColor (string, optional): Sets the Capacitor WebView background color.

• zoomEnabled (boolean, optional): Enables or disables zoom in the Capacitor WebView. Default is false.

Platform-specific settings

Capacitor supports Android and iOS. Each platform can override global settings in more detail.

Android settings (android object)

• path (string, optional): Path to the native Android project. Default is android.
• overrideUserAgent, appendUserAgent, backgroundColor, zoomEnabled: Platform-specific overrides for user agent, appended string, background color, and zoom.
• allowMixedContent (boolean, optional): Allows mixed content while developing so files from different schemes can load. Disable in production. Default is false.
• captureInput (boolean, optional): Use a simplified keyboard. Default is false.
• webContentsDebuggingEnabled (boolean, optional): Always enable debuggable web contents. Enabled automatically during development. Default is false.
• loggingBehavior: Android-specific logging override.
• includePlugins: Whitelist of plugins to include on npx cap sync. Overrides the global setting.
• flavor (string, optional): Android build flavor.
• initialFocus (boolean, optional): Give the WebView initial focus. Default is true.
• minWebViewVersion, minHuaweiWebViewVersion (number, optional): Minimum supported WebView versions.
• buildOptions (object, optional): Android build options: keystorePath, keystorePassword, keystoreAlias, keystoreAliasPassword, releaseType, signingType.
• useLegacyBridge (boolean, optional): Use the legacy addJavascriptInterface bridge. Default is false, using the safer addWebMessageListener.

iOS settings (ios object)

• path (string, optional): Path to the native iOS project. Default is ios.
• scheme (string, optional): iOS build scheme. Default is App.
• overrideUserAgent, appendUserAgent, backgroundColor, zoomEnabled: Platform-specific overrides for user agent, appended string, background color, and zoom.
• contentInset ('automatic' | 'scrollableAxes' | 'never' | 'always', optional): Scroll view content inset behavior. Default is never.
• scrollEnabled (boolean, optional): Whether the scroll view can scroll.
• cordovaLinkerFlags (string array, optional): Custom linker flags when compiling Cordova plugins.
• allowsLinkPreview (boolean, optional): Allow link preview on long-press.
• loggingBehavior: iOS-specific logging override.
• includePlugins: Whitelist of plugins to include on npx cap sync. Overrides the global setting.
• limitsNavigationsToAppBoundDomains (boolean, optional): Sets WKWebView's limitsNavigationsToAppBoundDomains. Default is false.
• preferredContentMode ('recommended' | 'desktop' | 'mobile', optional): WebView content mode. Default is recommended.
• handleApplicationNotifications (boolean, optional): Whether Capacitor handles local and push notifications. Default is true.
• webContentsDebuggingEnabled (boolean, optional): Enable debuggable web contents in release builds.

Server settings

• server object: Local development server settings.
  • hostname (string, optional): Local hostname. Default is localhost.
  • iosScheme, androidScheme (string, optional): Local URL schemes for iOS and Android. Defaults are capacitor and https.
  • url (string, optional): Load an external URL in the WebView—for example a live-reload server. Do not use in production.
  • cleartext (boolean, optional): Allow cleartext traffic. Do not use in production. Default is false.
  • allowNavigation (string array, optional): Additional URLs the WebView may navigate to. Do not use in production. Default is an empty array.
  • errorPath (string, optional): Path to a local HTML page shown on errors.

Cordova settings (cordova object)

• accessOrigins (string array, optional): Origins written to <access> in config.xml.
• preferences (object, optional): Cordova preferences.
• staticPlugins (string array, optional): Plugins that must be treated as static.

Plugin settings (plugins object)

• plugins object: Per-plugin configuration as key/value pairs of plugin name and settings object.

Global plugin include (includePlugins array)

• includePlugins (string array, optional): Whitelist of plugins to include on npx cap sync.

Capacitor Cookies and Capacitor Http settings

Under plugins, you can configure CapacitorCookies and CapacitorHttp.

• CapacitorCookies.enabled (boolean, optional): Override global document.cookie natively. Default is false.
• CapacitorHttp.enabled (boolean, optional): Override global fetch and XMLHttpRequest natively. Default is false.

Summary

Tuning these options helps optimize Capacitor app performance, security, and user experience. Understand each setting's purpose and limits, and configure for your app's needs.

See you next time.