{"id":3909,"date":"2021-11-02T16:22:12","date_gmt":"2021-11-02T16:22:12","guid":{"rendered":"https:\/\/ionicframework.com\/blog\/?p=3909"},"modified":"2021-11-02T21:40:16","modified_gmt":"2021-11-02T21:40:16","slug":"automated-capacitor-project-configuration-with-capacitor-configure","status":"publish","type":"post","link":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure","title":{"rendered":"Automated Capacitor Project Configuration with Capacitor Configure"},"content":{"rendered":"

Many developers need to script and automate the configuration of their Capacitor projects. For example, apps that generate multiple versions of themselves for whitelabeling, automated tooling that needs to update version and build numbers, or plugins that need to automatically configure user projects to correctly run and use the plugin.<\/p>\n

Until now, developers had to manually write scripts to read and write complex iOS and Android project settings, resulting in error-prone code and extra project maintenance. Today, we are releasing the first version of a utility that should make managing Capacitor projects through code or configuration much easier: Capacitor Configure<\/a>.<\/p>\n

Capacitor Configure comes with two useful packages that developers can use depending on their needs: @capacitor\/project<\/code>, a JavaScript\/TypeScript library and API used for writing custom configuration scripts, and @capacitor\/configure<\/code>, an automated configuration tool based on a YAML file spec. Both have similar functionality but are targeted at two different use cases.<\/p>\n

Let\u2019s explore the Project API first:<\/p>\n

<\/p>\n

Project API<\/h2>\n

The Project API is useful for writing complex, custom project management scripts, and handles the messy bits of managing Xcode pbxproj files, Android Manifest\/Gradle files, and more.<\/p>\n

To use it, install and import from the @capacitor\/project<\/code> package and initialize it:<\/p>\n

import { CapacitorProject } from '@capacitor\/project';\nimport { CapacitorConfig } from '@capacitor\/cli';\n\nconst config: CapacitorConfig = {\n  ios: {\n    path: 'ios',\n  },\n  android: {\n    path: 'android',\n  },\n};\n\nconst project = new CapacitorProject(config);\nawait project.load();\n<\/code><\/pre>\n
Then, operations on the iOS and Android portions of the project can be performed. Here\u2019s a small example of setting and incrementing build numbers and versions on iOS and Android:<\/p>\n
project.ios.setBuild(targetName, buildName, 42);\nproject.ios.incrementBuild(targetName, buildName);\nproject.ios.setVersion(targetName, buildName, '1.2.3');\n\n\nawait project.android.setVersionName('1.0.2');\nawait project.android.setVersionCode(11);\nawait project.android.incrementVersionCode();\n<\/code><\/pre>\n
There are many other operations, see the project readme<\/a> to explore the capabilities of the Project API.<\/p>\n
Configuration Tool<\/h2>\n
The @capacitor\/configure<\/code> package provides a YAML-based configuration tool that uses the Project API under the hood, and is particularly well suited to plugin configuration and other scenarios where a set of well-defined configuration changes must be made against a project. The tool has some additional features, such as variable support, interactive mode to confirm changes, and dry run mode.<\/p>\n
In fact, the configuration tool was the initial focus of this project as the Ionic team has built and shipped some very complicated plugins, like Microsoft Intune<\/a>, that require considerable amounts of configuration which we wanted to make much easier.<\/p>\n
Here\u2019s an example of a YAML file that declares a set of configuration options that will be made against a project:<\/p>\n
vars:\n  BUNDLE_ID:\n    default: io.ionic.greatStarter\n  PACKAGE_NAME:\n    default: io.ionic.greatStarter\n  REQUIRED_VARIABLE:\n\nplatforms:\n  ios:\n    targets:\n      App:\n        bundleId: $BUNDLE_ID\n        version: 16.4\n        incrementBuild: true\n        productName: Awesome App\n        displayName: My Awesome App\n\n android:\n    packageName: $PACKAGE_NAME\n    versionName: 1.2.3\n    incrementVersionCode: true\n\n    manifest:\n      - file: AndroidManifest.xml\n        target: manifest\/application\n        attrs:\n          android:name: com.ionicframework.intune.IntuneApplication\n<\/code><\/pre>\n
This is just a small sampling of the options available in the configuration file. See the full example file<\/a> for all the different options supported in the YAML configuration file.<\/p>\n
To run the tool, install it and then run<\/p>\n
npx cap-config run config.yml\n<\/code><\/pre>\n
Getting Started<\/h2>\n
This is a new project and we want your feedback on problems you\u2019re trying to solve through automation, to make sure this tool is truly achieving the goal of liberating developers from writing custom configuration scripts that work with low-level native project configuration files and project structure.<\/p>\n
We are also working on documentation for the tool and integration into the standard Capacitor workflow and integration into Appflow<\/a> once the project matures.<\/p>\n
Give it a try today<\/a> and let us know what you think!<\/p>\n
P.S. We’re hiring!<\/h2>\n
Capacitor has been growing quickly lately and powering thousands of app store apps. We’re looking for a Lead Engineer to help take Capacitor to the next level. Is that you? Learn more here<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Many developers need to script and automate the configuration of their Capacitor projects. For example, apps that generate multiple versions of themselves for whitelabeling, automated tooling that needs to update version and build numbers, or plugins that need to automatically configure user projects to correctly run and use the plugin. Until now, developers had to […]<\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"publish_to_discourse":"0","publish_post_category":"26","wpdc_auto_publish_overridden":"","wpdc_topic_tags":"","wpdc_pin_topic":"","wpdc_pin_until":"","discourse_post_id":"535928","discourse_permalink":"https:\/\/forum.ionicframework.com\/t\/automated-capacitor-project-configuration-with-capacitor-configure\/216900","wpdc_publishing_response":"","wpdc_publishing_error":"","_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[1,120,122],"tags":[151],"class_list":["post-3909","post","type-post","status-publish","format-standard","hentry","category-all","category-announcements","category-product","tag-capacitor"],"acf":[],"yoast_head":"\nAutomated Capacitor Project Configuration with Capacitor Configure - Ionic Blog<\/title>\n<meta name=\"description\" content=\"Automatically manage and configure Capacitor app projects with the new Capacitor Configure tool and API\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Automated Capacitor Project Configuration with Capacitor Configure\" \/>\n<meta property=\"og:description\" content=\"Automatically manage and configure Capacitor app projects with the new Capacitor Configure tool and API\" \/>\n<meta property=\"og:url\" content=\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure\" \/>\n<meta property=\"og:site_name\" content=\"Ionic Blog\" \/>\n<meta property=\"article:published_time\" content=\"2021-11-02T16:22:12+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2021-11-02T21:40:16+00:00\" \/>\n<meta name=\"author\" content=\"Max Lynch\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@maxlynch\" \/>\n<meta name=\"twitter:site\" content=\"@ionicframework\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Max Lynch\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"3 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#article\",\"isPartOf\":{\"@id\":\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure\"},\"author\":{\"name\":\"Max Lynch\",\"@id\":\"https:\/\/ionic.io\/blog\/#\/schema\/person\/91f360cffbd804a464b0c4a87b5c5f1e\"},\"headline\":\"Automated Capacitor Project Configuration with Capacitor Configure\",\"datePublished\":\"2021-11-02T16:22:12+00:00\",\"dateModified\":\"2021-11-02T21:40:16+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure\"},\"wordCount\":540,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\/\/ionic.io\/blog\/#organization\"},\"keywords\":[\"Capacitor\"],\"articleSection\":[\"All\",\"Announcements\",\"Product\"],\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure\",\"url\":\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure\",\"name\":\"Automated Capacitor Project Configuration with Capacitor Configure - Ionic Blog\",\"isPartOf\":{\"@id\":\"https:\/\/ionic.io\/blog\/#website\"},\"datePublished\":\"2021-11-02T16:22:12+00:00\",\"dateModified\":\"2021-11-02T21:40:16+00:00\",\"description\":\"Automatically manage and configure Capacitor app projects with the new Capacitor Configure tool and API\",\"breadcrumb\":{\"@id\":\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/ionic.io\/blog\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Automated Capacitor Project Configuration with Capacitor Configure\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/ionic.io\/blog\/#website\",\"url\":\"https:\/\/ionic.io\/blog\/\",\"name\":\"ionic.io\/blog\",\"description\":\"Build amazing native and progressive web apps with the web\",\"publisher\":{\"@id\":\"https:\/\/ionic.io\/blog\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/ionic.io\/blog\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/ionic.io\/blog\/#organization\",\"name\":\"Ionic\",\"url\":\"https:\/\/ionic.io\/blog\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/ionic.io\/blog\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2020\/10\/white-on-color.png\",\"contentUrl\":\"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2020\/10\/white-on-color.png\",\"width\":1920,\"height\":854,\"caption\":\"Ionic\"},\"image\":{\"@id\":\"https:\/\/ionic.io\/blog\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/x.com\/ionicframework\"]},{\"@type\":\"Person\",\"@id\":\"https:\/\/ionic.io\/blog\/#\/schema\/person\/91f360cffbd804a464b0c4a87b5c5f1e\",\"name\":\"Max Lynch\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/ionic.io\/blog\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2018\/05\/max-avatar-150x150.jpg\",\"contentUrl\":\"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2018\/05\/max-avatar-150x150.jpg\",\"caption\":\"Max Lynch\"},\"description\":\"CEO\",\"sameAs\":[\"http:\/\/twitter.com\/maxlynch\",\"https:\/\/x.com\/maxlynch\"],\"url\":\"https:\/\/ionic.io\/blog\/author\/max\"}]}<\/script>\n<!-- \/ Yoast SEO Premium plugin. -->","yoast_head_json":{"title":"Automated Capacitor Project Configuration with Capacitor Configure - Ionic Blog","description":"Automatically manage and configure Capacitor app projects with the new Capacitor Configure tool and API","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure","og_locale":"en_US","og_type":"article","og_title":"Automated Capacitor Project Configuration with Capacitor Configure","og_description":"Automatically manage and configure Capacitor app projects with the new Capacitor Configure tool and API","og_url":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure","og_site_name":"Ionic Blog","article_published_time":"2021-11-02T16:22:12+00:00","article_modified_time":"2021-11-02T21:40:16+00:00","author":"Max Lynch","twitter_card":"summary_large_image","twitter_creator":"@maxlynch","twitter_site":"@ionicframework","twitter_misc":{"Written by":"Max Lynch","Est. reading time":"3 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#article","isPartOf":{"@id":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure"},"author":{"name":"Max Lynch","@id":"https:\/\/ionic.io\/blog\/#\/schema\/person\/91f360cffbd804a464b0c4a87b5c5f1e"},"headline":"Automated Capacitor Project Configuration with Capacitor Configure","datePublished":"2021-11-02T16:22:12+00:00","dateModified":"2021-11-02T21:40:16+00:00","mainEntityOfPage":{"@id":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure"},"wordCount":540,"commentCount":0,"publisher":{"@id":"https:\/\/ionic.io\/blog\/#organization"},"keywords":["Capacitor"],"articleSection":["All","Announcements","Product"],"inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#respond"]}]},{"@type":"WebPage","@id":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure","url":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure","name":"Automated Capacitor Project Configuration with Capacitor Configure - Ionic Blog","isPartOf":{"@id":"https:\/\/ionic.io\/blog\/#website"},"datePublished":"2021-11-02T16:22:12+00:00","dateModified":"2021-11-02T21:40:16+00:00","description":"Automatically manage and configure Capacitor app projects with the new Capacitor Configure tool and API","breadcrumb":{"@id":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/ionic.io\/blog\/automated-capacitor-project-configuration-with-capacitor-configure#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/ionic.io\/blog"},{"@type":"ListItem","position":2,"name":"Automated Capacitor Project Configuration with Capacitor Configure"}]},{"@type":"WebSite","@id":"https:\/\/ionic.io\/blog\/#website","url":"https:\/\/ionic.io\/blog\/","name":"ionic.io\/blog","description":"Build amazing native and progressive web apps with the web","publisher":{"@id":"https:\/\/ionic.io\/blog\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/ionic.io\/blog\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/ionic.io\/blog\/#organization","name":"Ionic","url":"https:\/\/ionic.io\/blog\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/ionic.io\/blog\/#\/schema\/logo\/image\/","url":"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2020\/10\/white-on-color.png","contentUrl":"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2020\/10\/white-on-color.png","width":1920,"height":854,"caption":"Ionic"},"image":{"@id":"https:\/\/ionic.io\/blog\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/x.com\/ionicframework"]},{"@type":"Person","@id":"https:\/\/ionic.io\/blog\/#\/schema\/person\/91f360cffbd804a464b0c4a87b5c5f1e","name":"Max Lynch","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/ionic.io\/blog\/#\/schema\/person\/image\/","url":"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2018\/05\/max-avatar-150x150.jpg","contentUrl":"https:\/\/ionic.io\/blog\/wp-content\/uploads\/2018\/05\/max-avatar-150x150.jpg","caption":"Max Lynch"},"description":"CEO","sameAs":["http:\/\/twitter.com\/maxlynch","https:\/\/x.com\/maxlynch"],"url":"https:\/\/ionic.io\/blog\/author\/max"}]}},"jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/posts\/3909","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/comments?post=3909"}],"version-history":[{"count":0,"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/posts\/3909\/revisions"}],"wp:attachment":[{"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/media?parent=3909"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/categories?post=3909"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/ionic.io\/blog\/wp-json\/wp\/v2\/tags?post=3909"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}