declarations.d.ts 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589
  1. export interface CapacitorConfig {
  2. /**
  3. * The unique identifier of your packaged app.
  4. *
  5. * This is also known as the Bundle ID in iOS and the Application ID in
  6. * Android. It must be in reverse domain name notation, generally
  7. * representing a domain name that you or your company owns.
  8. *
  9. * @since 1.0.0
  10. */
  11. appId?: string;
  12. /**
  13. * The human-friendly name of your app.
  14. *
  15. * This should be what you'd see in the App Store, but can be changed after
  16. * within each native platform after it is generated.
  17. *
  18. * @since 1.0.0
  19. */
  20. appName?: string;
  21. /**
  22. * The directory of your compiled web assets.
  23. *
  24. * This directory should contain the final `index.html` of your app.
  25. *
  26. * @since 1.0.0
  27. */
  28. webDir?: string;
  29. /**
  30. * Whether to copy the Capacitor runtime bundle or not.
  31. *
  32. * If your app is not using a bundler, set this to `true`, then Capacitor
  33. * will create a `capacitor.js` file that you'll need to add as a script in
  34. * your `index.html` file.
  35. *
  36. * It's deprecated and will be removed in Capacitor 6
  37. *
  38. * @since 1.0.0
  39. * @deprecated 5.0.0
  40. * @default false
  41. */
  42. bundledWebRuntime?: boolean;
  43. /**
  44. * The build configuration (as defined by the native app) under which Capacitor
  45. * will send statements to the log system. This applies to log statements in
  46. * native code as well as statements redirected from JavaScript (`console.debug`,
  47. * `console.error`, etc.). Enabling logging will let statements render in the
  48. * Xcode and Android Studio windows but can leak information on device if enabled
  49. * in released builds.
  50. *
  51. * 'none' = logs are never produced
  52. * 'debug' = logs are produced in debug builds but not production builds
  53. * 'production' = logs are always produced
  54. *
  55. * @since 3.0.0
  56. * @default debug
  57. */
  58. loggingBehavior?: 'none' | 'debug' | 'production';
  59. /**
  60. * User agent of Capacitor Web View.
  61. *
  62. * @since 1.4.0
  63. */
  64. overrideUserAgent?: string;
  65. /**
  66. * String to append to the original user agent of Capacitor Web View.
  67. *
  68. * This is disregarded if `overrideUserAgent` is used.
  69. *
  70. * @since 1.4.0
  71. */
  72. appendUserAgent?: string;
  73. /**
  74. * Background color of the Capacitor Web View.
  75. *
  76. * @since 1.1.0
  77. */
  78. backgroundColor?: string;
  79. /**
  80. * Enable zooming within the Capacitor Web View.
  81. *
  82. * @default false
  83. * @since 6.0.0
  84. */
  85. zoomEnabled?: boolean;
  86. android?: {
  87. /**
  88. * Specify a custom path to the native Android project.
  89. *
  90. * @since 3.0.0
  91. * @default android
  92. */
  93. path?: string;
  94. /**
  95. * User agent of Capacitor Web View on Android.
  96. *
  97. * Overrides global `overrideUserAgent` option.
  98. *
  99. * @since 1.4.0
  100. */
  101. overrideUserAgent?: string;
  102. /**
  103. * String to append to the original user agent of Capacitor Web View for Android.
  104. *
  105. * Overrides global `appendUserAgent` option.
  106. *
  107. * This is disregarded if `overrideUserAgent` is used.
  108. *
  109. * @since 1.4.0
  110. */
  111. appendUserAgent?: string;
  112. /**
  113. * Background color of the Capacitor Web View for Android.
  114. *
  115. * Overrides global `backgroundColor` option.
  116. *
  117. * @since 1.1.0
  118. */
  119. backgroundColor?: string;
  120. /**
  121. * Enable zooming within the Capacitor Web View for Android.
  122. *
  123. * @default false
  124. * @since 6.0.0
  125. */
  126. zoomEnabled?: boolean;
  127. /**
  128. * Enable mixed content in the Capacitor Web View for Android.
  129. *
  130. * [Mixed
  131. * content](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content)
  132. * is disabled by default for security. During development, you may need to
  133. * enable it to allow the Web View to load files from different schemes.
  134. *
  135. * **This is not intended for use in production.**
  136. *
  137. * @since 1.0.0
  138. * @default false
  139. */
  140. allowMixedContent?: boolean;
  141. /**
  142. * This enables a simpler keyboard which may have some limitations.
  143. *
  144. * This will capture JS keys using an alternative
  145. * [`InputConnection`](https://developer.android.com/reference/android/view/inputmethod/InputConnection).
  146. *
  147. * @since 1.0.0
  148. * @default false
  149. */
  150. captureInput?: boolean;
  151. /**
  152. * Always enable debuggable web content.
  153. *
  154. * This is automatically enabled during development.
  155. *
  156. * @since 1.0.0
  157. * @default false
  158. */
  159. webContentsDebuggingEnabled?: boolean;
  160. /**
  161. * The build configuration under which Capacitor will generate logs on Android.
  162. *
  163. * Overrides global `loggingBehavior` option.
  164. *
  165. * @since 3.0.0
  166. * @default debug
  167. */
  168. loggingBehavior?: 'none' | 'debug' | 'production';
  169. /**
  170. * Allowlist of plugins to include during `npx cap sync` for Android.
  171. *
  172. * Overrides global `includePlugins` option.
  173. *
  174. * @since 3.0.0
  175. */
  176. includePlugins?: string[];
  177. /**
  178. * Android flavor to use.
  179. *
  180. * If the app has flavors declared in the `build.gradle`
  181. * configure the flavor you want to run with `npx cap run` command.
  182. *
  183. * @since 3.1.0
  184. */
  185. flavor?: string;
  186. /**
  187. * Whether to give the webview initial focus.
  188. *
  189. * @since 3.5.1
  190. * @default true
  191. */
  192. initialFocus?: boolean;
  193. /**
  194. * The minimum supported webview version on Android supported by your app.
  195. *
  196. * The minimum supported cannot be lower than version `55`, which is required for Capacitor.
  197. *
  198. * If the device uses a lower WebView version, an error message will be shown on Logcat.
  199. * If `server.errorPath` is configured, the WebView will redirect to that file, so can be
  200. * used to show a custom error.
  201. *
  202. * @since 4.0.0
  203. * @default 60
  204. */
  205. minWebViewVersion?: number;
  206. /**
  207. * The minimum supported Huawei webview version on Android supported by your app.
  208. *
  209. * The minimum supported cannot be lower than version `10`, which is required for Capacitor.
  210. *
  211. * If the device uses a lower WebView version, an error message will be shown on Logcat.
  212. * If `server.errorPath` is configured, the WebView will redirect to that file, so can be
  213. * used to show a custom error.
  214. *
  215. * @since 4.6.4
  216. * @default 10
  217. */
  218. minHuaweiWebViewVersion?: number;
  219. buildOptions?: {
  220. /**
  221. * Path to your keystore
  222. *
  223. * @since 4.4.0
  224. */
  225. keystorePath?: string;
  226. /**
  227. * Password to your keystore
  228. *
  229. * @since 4.4.0
  230. */
  231. keystorePassword?: string;
  232. /**
  233. * Alias in the keystore to use
  234. *
  235. * @since 4.4.0
  236. */
  237. keystoreAlias?: string;
  238. /**
  239. * Password for the alias in the keystore to use
  240. *
  241. * @since 4.4.0
  242. */
  243. keystoreAliasPassword?: string;
  244. /**
  245. * Bundle type for your release build
  246. *
  247. * @since 4.4.0
  248. * @default "AAB"
  249. */
  250. releaseType?: 'AAB' | 'APK';
  251. /**
  252. * Program to sign your build with
  253. *
  254. * @since 5.1.0
  255. * @default "jarsigner"
  256. */
  257. signingType?: 'apksigner' | 'jarsigner';
  258. };
  259. /**
  260. * Use legacy [addJavascriptInterface](https://developer.android.com/reference/android/webkit/WebView#addJavascriptInterface(java.lang.Object,%20java.lang.String))
  261. * instead of the new and more secure [addWebMessageListener](https://developer.android.com/reference/androidx/webkit/WebViewCompat#addWebMessageListener(android.webkit.WebView,java.lang.String,java.util.Set%3Cjava.lang.String%3E,androidx.webkit.WebViewCompat.WebMessageListener))
  262. *
  263. * @since 4.5.0
  264. * @default false
  265. */
  266. useLegacyBridge?: boolean;
  267. };
  268. ios?: {
  269. /**
  270. * Specify a custom path to the native iOS project.
  271. *
  272. * @since 3.0.0
  273. * @default ios
  274. */
  275. path?: string;
  276. /**
  277. * iOS build scheme to use.
  278. *
  279. * Usually this matches your app's target in Xcode. You can use the
  280. * following command to list schemes:
  281. *
  282. * ```shell
  283. * xcodebuild -workspace ios/App/App.xcworkspace -list
  284. * ```
  285. *
  286. * @since 3.0.0
  287. * @default App
  288. */
  289. scheme?: string;
  290. /**
  291. * User agent of Capacitor Web View on iOS.
  292. *
  293. * Overrides global `overrideUserAgent` option.
  294. *
  295. * @since 1.4.0
  296. */
  297. overrideUserAgent?: string;
  298. /**
  299. * String to append to the original user agent of Capacitor Web View for iOS.
  300. *
  301. * Overrides global `appendUserAgent` option.
  302. *
  303. * This is disregarded if `overrideUserAgent` is used.
  304. *
  305. * @since 1.4.0
  306. */
  307. appendUserAgent?: string;
  308. /**
  309. * Background color of the Capacitor Web View for iOS.
  310. *
  311. * Overrides global `backgroundColor` option.
  312. *
  313. * @since 1.1.0
  314. */
  315. backgroundColor?: string;
  316. /**
  317. * Enable zooming within the Capacitor Web View for iOS.
  318. *
  319. * @default false
  320. * @since 6.0.0
  321. */
  322. zoomEnabled?: boolean;
  323. /**
  324. * Configure the scroll view's content inset adjustment behavior.
  325. *
  326. * This will set the
  327. * [`contentInsetAdjustmentBehavior`](https://developer.apple.com/documentation/uikit/uiscrollview/2902261-contentinsetadjustmentbehavior)
  328. * property on the Web View's
  329. * [`UIScrollView`](https://developer.apple.com/documentation/uikit/uiscrollview).
  330. *
  331. * @since 2.0.0
  332. * @default never
  333. */
  334. contentInset?: 'automatic' | 'scrollableAxes' | 'never' | 'always';
  335. /**
  336. * Configure whether the scroll view is scrollable.
  337. *
  338. * This will set the
  339. * [`isScrollEnabled`](https://developer.apple.com/documentation/uikit/uiscrollview/1619395-isscrollenabled)
  340. * property on the Web View's
  341. * [`UIScrollView`](https://developer.apple.com/documentation/uikit/uiscrollview).
  342. *
  343. * @since 1.0.0
  344. */
  345. scrollEnabled?: boolean;
  346. /**
  347. * Configure custom linker flags for compiling Cordova plugins.
  348. *
  349. * @since 1.0.0
  350. * @default []
  351. */
  352. cordovaLinkerFlags?: string[];
  353. /**
  354. * Allow destination previews when pressing on links.
  355. *
  356. * This will set the
  357. * [`allowsLinkPreview`](https://developer.apple.com/documentation/webkit/wkwebview/1415000-allowslinkpreview)
  358. * property on the Web View, instead of using the default value.
  359. *
  360. * @since 2.0.0
  361. */
  362. allowsLinkPreview?: boolean;
  363. /**
  364. * The build configuration under which Capacitor will generate logs on iOS.
  365. *
  366. * Overrides global `loggingBehavior` option.
  367. *
  368. * @since 3.0.0
  369. * @default debug
  370. */
  371. loggingBehavior?: 'none' | 'debug' | 'production';
  372. /**
  373. * Allowlist of plugins to include during `npx cap sync` for iOS.
  374. *
  375. * Overrides global `includePlugins` option.
  376. *
  377. * @since 3.0.0
  378. */
  379. includePlugins?: string[];
  380. /**
  381. * Sets WKWebView configuration for limitsNavigationsToAppBoundDomains.
  382. *
  383. * If the Info.plist file includes `WKAppBoundDomains` key, it's recommended to
  384. * set this option to true, otherwise some features won't work.
  385. * But as side effect, it blocks navigation outside the domains in the
  386. * `WKAppBoundDomains` list.
  387. * `localhost` (or the value configured as `server.hostname`) also needs to be
  388. * added to the `WKAppBoundDomains` list.
  389. *
  390. * @since 3.1.0
  391. * @default false
  392. */
  393. limitsNavigationsToAppBoundDomains?: boolean;
  394. /**
  395. * The content mode for the web view to use when it loads and renders web content.
  396. *
  397. * - 'recommended': The content mode that is appropriate for the current device.
  398. * - 'desktop': The content mode that represents a desktop experience.
  399. * - 'mobile': The content mode that represents a mobile experience.
  400. *
  401. * @since 4.0.0
  402. * @default recommended
  403. */
  404. preferredContentMode?: 'recommended' | 'desktop' | 'mobile';
  405. /**
  406. * Configure if Capacitor will handle local/push notifications.
  407. * Set to false if you want to use your own UNUserNotificationCenter to handle notifications.
  408. *
  409. * @since 4.5.0
  410. * @default true
  411. */
  412. handleApplicationNotifications?: boolean;
  413. /**
  414. * Using Xcode 14.3, on iOS 16.4 and greater, enable debuggable web content for release builds.
  415. *
  416. * If not set, it's `true` for development builds.
  417. *
  418. * @since 4.8.0
  419. * @default false
  420. */
  421. webContentsDebuggingEnabled?: boolean;
  422. };
  423. server?: {
  424. /**
  425. * Configure the local hostname of the device.
  426. *
  427. * It is recommended to keep this as `localhost` as it allows the use of
  428. * Web APIs that would otherwise require a [secure
  429. * context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts)
  430. * such as
  431. * [`navigator.geolocation`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/geolocation)
  432. * and
  433. * [`MediaDevices.getUserMedia`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia).
  434. *
  435. * @since 1.0.0
  436. * @default localhost
  437. */
  438. hostname?: string;
  439. /**
  440. * Configure the local scheme on iOS.
  441. *
  442. * [Can't be set to schemes that the WKWebView already handles, such as http or https](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/2875766-seturlschemehandler)
  443. * This can be useful when migrating from
  444. * [`cordova-plugin-ionic-webview`](https://github.com/ionic-team/cordova-plugin-ionic-webview),
  445. * where the default scheme on iOS is `ionic`.
  446. *
  447. * @since 1.2.0
  448. * @default capacitor
  449. */
  450. iosScheme?: string;
  451. /**
  452. * Configure the local scheme on Android.
  453. *
  454. * Custom schemes on Android are unable to change the URL path as of Webview 117. Changing this value from anything other than `http` or `https` can result in your
  455. * application unable to resolve routing. If you must change this for some reason, consider using a hash-based url strategy, but there are no guarentees that this
  456. * will continue to work long term as allowing non-standard schemes to modify query parameters and url fragments is only allowed for compatibility reasons.
  457. * https://ionic.io/blog/capacitor-android-customscheme-issue-with-chrome-117
  458. *
  459. * @since 1.2.0
  460. * @default https
  461. */
  462. androidScheme?: string;
  463. /**
  464. * Load an external URL in the Web View.
  465. *
  466. * This is intended for use with live-reload servers.
  467. *
  468. * **This is not intended for use in production.**
  469. *
  470. * @since 1.0.0
  471. */
  472. url?: string;
  473. /**
  474. * Allow cleartext traffic in the Web View.
  475. *
  476. * On Android, all cleartext traffic is disabled by default as of API 28.
  477. *
  478. * This is intended for use with live-reload servers where unencrypted HTTP
  479. * traffic is often used.
  480. *
  481. * **This is not intended for use in production.**
  482. *
  483. * @since 1.5.0
  484. * @default false
  485. */
  486. cleartext?: boolean;
  487. /**
  488. * Set additional URLs the Web View can navigate to.
  489. *
  490. * By default, all external URLs are opened in the external browser (not
  491. * the Web View).
  492. *
  493. * **This is not intended for use in production.**
  494. *
  495. * @since 1.0.0
  496. * @default []
  497. */
  498. allowNavigation?: string[];
  499. /**
  500. * Specify path to a local html page to display in case of errors.
  501. * On Android the html file won't have access to Capacitor plugins.
  502. *
  503. * @since 4.0.0
  504. * @default null
  505. */
  506. errorPath?: string;
  507. };
  508. cordova?: {
  509. /**
  510. * Populates <access> tags in the config.xml with the origin set to
  511. * the values entered here.
  512. * If not provided, a single <access origin="*" /> tag gets included.
  513. * It only has effect on a few Cordova plugins that respect the whitelist.
  514. *
  515. * @since 3.3.0
  516. */
  517. accessOrigins?: string[];
  518. /**
  519. * Configure Cordova preferences.
  520. *
  521. * @since 1.3.0
  522. */
  523. preferences?: {
  524. [key: string]: string | undefined;
  525. };
  526. /**
  527. * List of Cordova plugins that need to be static but are not
  528. * already in the static plugin list.
  529. *
  530. * @since 3.3.0
  531. */
  532. staticPlugins?: string[];
  533. };
  534. /**
  535. * Configure plugins.
  536. *
  537. * This is an object with configuration values specified by plugin class
  538. * name.
  539. *
  540. * @since 1.0.0
  541. */
  542. plugins?: PluginsConfig;
  543. /**
  544. * Allowlist of plugins to include during `npx cap sync`.
  545. *
  546. * This should be an array of strings representing the npm package name of
  547. * plugins to include when running `npx cap sync`. If unset, Capacitor will
  548. * inspect `package.json` for a list of potential plugins.
  549. *
  550. * @since 3.0.0
  551. */
  552. includePlugins?: string[];
  553. }
  554. export interface PluginsConfig {
  555. /**
  556. * Plugin configuration by class name.
  557. *
  558. * @since 1.0.0
  559. */
  560. [key: string]: {
  561. [key: string]: any;
  562. } | undefined;
  563. /**
  564. * Capacitor Cookies plugin configuration
  565. *
  566. * @since 4.3.0
  567. */
  568. CapacitorCookies?: {
  569. /**
  570. * Enable CapacitorCookies to override the global `document.cookie` on native.
  571. *
  572. * @default false
  573. */
  574. enabled?: boolean;
  575. };
  576. /**
  577. * Capacitor Http plugin configuration
  578. *
  579. * @since 4.3.0
  580. */
  581. CapacitorHttp?: {
  582. /**
  583. * Enable CapacitorHttp to override the global `fetch` and `XMLHttpRequest` on native.
  584. *
  585. * @default false
  586. */
  587. enabled?: boolean;
  588. };
  589. }