{"id":13611099,"url":"https://github.com/ozontech/kelp","last_synced_at":"2025-06-11T11:42:22.026Z","repository":{"id":211614850,"uuid":"728178660","full_name":"ozontech/kelp","owner":"ozontech","description":"Kelp is an Android Studio plugin that enhances support for custom design systems","archived":false,"fork":false,"pushed_at":"2024-05-22T14:34:06.000Z","size":4021,"stargazers_count":35,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-22T15:37:13.050Z","etag":null,"topics":["android","android-studio-plugin","design-system","design-systems","ide-plugin","idea-plugin","jetpack-compose","studio-plugin"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ozontech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-06T11:53:27.000Z","updated_at":"2024-05-22T15:37:25.182Z","dependencies_parsed_at":"2024-05-22T15:37:10.654Z","dependency_job_id":null,"html_url":"https://github.com/ozontech/kelp","commit_stats":null,"previous_names":["ozontech/kelp"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozontech%2Fkelp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozontech%2Fkelp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozontech%2Fkelp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ozontech%2Fkelp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ozontech","download_url":"https://codeload.github.com/ozontech/kelp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248654031,"owners_count":21140236,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","android-studio-plugin","design-system","design-systems","ide-plugin","idea-plugin","jetpack-compose","studio-plugin"],"created_at":"2024-08-01T19:01:51.781Z","updated_at":"2025-04-13T01:34:36.110Z","avatar_url":"https://github.com/ozontech.png","language":"Kotlin","readme":"![kelp-banner-light.svg](images%2Fkelp-banner-light.svg#gh-light-mode-only)\n![kelp-banner-dark.svg](images%2Fkelp-banner-dark.svg#gh-dark-mode-only)\n\n# Kelp\n\n[![Introductory Medium Article](https://img.shields.io/badge/medium-article-grey?labelColor=black\u0026logo=medium\u0026logoColor=white\u0026link=https://proandroiddev.com/kelp-plugin-for-android-studio-4374127939aa)](https://proandroiddev.com/kelp-plugin-for-android-studio-4374127939aa)\n![License](https://img.shields.io/github/license/ozontech/Kelp?color=blue)\n[![Gradle Plugin Portal](https://img.shields.io/gradle-plugin-portal/v/ru.ozon.kelp?color=green\u0026label=Gradle%20Plugin%20Portal\u0026logo=gradle)](https://plugins.gradle.org/plugin/ru.ozon.kelp)\n\nKelp is an Android Studio plugin that enhances support for **custom design systems** written using Jetpack Compose.\n\n[Introductory Medium Article](https://proandroiddev.com/kelp-plugin-for-android-studio-4374127939aa)\n\n| Feature                                                                                                                                                                   | Screenshot                                                                                                                                                                                                       |\n|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 🔧 Customizable icon for\u003cbr\u003e design system **component functions**                                                                                                        | \u003cimg src=\"https://github.com/ozontech/kelp/raw/main/images/componentFunHighlighting-light.png#gh-light-mode-only\" width=\"600\"\u003e\u003cimg src=\"images/componentFunHighlighting-dark.png#gh-dark-mode-only\" width=\"600\"\u003e |\n| 🎨 DS **icons** in the code completion\u003cbr\u003e and gutter (where breakpoints are),\u003cbr\u003e like with `R.drawable`                                                                 | \u003cimg src=\"https://github.com/ozontech/kelp/raw/main/images/iconsRendering-light.png#gh-light-mode-only\" width=\"600\"\u003e\u003cimg src=\"images/iconsRendering-dark.png#gh-dark-mode-only\" width=\"600\"\u003e                     |\n| 🌈 **Colors** from DS palette in \u003cbr\u003ethe code completion and\u003cbr\u003e gutter (where breakpoints are),\u003cbr\u003e like with `R.color`                                                  | \u003cimg src=\"https://github.com/ozontech/kelp/raw/main/images/colorPreview-light.png#gh-light-mode-only\" width=\"600\"\u003e\u003cimg src=\"images/colorPreview-dark.png#gh-dark-mode-only\" width=\"600\"\u003e                         |\n| 📱 Installing the apk file of \u003cbr\u003ethe **demo app** (showcase app) on an Android \u003cbr\u003edevice, as well as navigating to the component \u003cbr\u003epage in it via an Intention Action | \u003cimg src=\"https://github.com/ozontech/kelp/raw/main/images/demoApkInstalling-light.png#gh-light-mode-only\" width=\"600\"\u003e\u003cimg src=\"images/demoApkInstalling-dark.png#gh-dark-mode-only\" width=\"600\"\u003e               |\n| 📱 The same via the gutter icons near **function declarations**                                                                                                           | \u003cimg src=\"https://github.com/ozontech/kelp/raw/main/images/demoApkGutter-light.png#gh-light-mode-only\" width=\"600\"\u003e\u003cimg src=\"images/demoApkGutter-dark.png#gh-dark-mode-only\" width=\"600\"\u003e                       |\n| 🖼 **KDoc Images** Rendering                                                                                                                                              | \u003cimg src=\"https://github.com/ozontech/kelp/raw/main/images/kdocImagesRendering-light.png#gh-light-mode-only\" width=\"600\"\u003e\u003cimg src=\"images/kdocImagesRendering-dark.png#gh-dark-mode-only\" width=\"600\"\u003e           |\n| ⌨️ Handy **live templates**\u003cbr\u003e(customizable; after applying, automatically opens code completion popup)                                                                  | \u003cimg src=\"https://github.com/ozontech/kelp/raw/main/images/live-templates-light.png#gh-light-mode-only\" width=\"600\"\u003e\u003cimg src=\"images/live-templates-dark.png#gh-dark-mode-only\" width=\"600\"\u003e                     |\n\nThese features enable users of your custom design system to develop UI **faster and easier**.\n\u003c!--\n-- Plugin description --\nKelp is an Android Studio plugin that enhances support for **custom design systems** written using Jetpack Compose.\n\n- [Introductory Medium Article](https://proandroiddev.com/kelp-plugin-for-android-studio-4374127939aa)\n- [Documentation](https://github.com/ozontech/kelp)\n\n## Features:\n1. 🔧 Customizable Icons for Component Functions\n2. 🎨 Design System Icons\n3. 🌈 Color Previews\n4. 📱 Demo App Integration\n5. 🖼️ KDoc Image Rendering\n6. ⌨️ Live Templates\n\n-- Plugin description end --\n--\u003e\n\n## ⚒️ Customization\nPlugin allows you to configure aforementioned features and adapt them to _your_ project by using `config.json` \nfile (see below).\n\nHowever, if your custom design system is part of a large project with unique requirements, it is _encouraged_ to fork\nthis repo and add/modify features needed only by your company's project.\n\nDon't worry, it is **not at all hard** to do it! You can create many powerful and incredibly useful features to increase \ndeveloper happiness and productivity. These are some of the resources that will help you on your journey:\n1. [IntelliJ Platform SDK](https://plugins.jetbrains.com/docs/intellij/welcome.html)\n2. [Intellij IDEA GitHub repo](https://github.com/JetBrains/intellij-community) — use search to find examples of desired functionality\n3. [The JetBrains Platform Slack community](https://plugins.jetbrains.com/slack) — ask the community\n\n## 🖼 KDoc Images Rendering\nUntil this [issue](https://youtrack.jetbrains.com/issue/KTIJ-13687/KDoc-support-inline-images) is resolved,\nAndroid Studio cannot render images referenced in KDoc.\n\nThis plugin ✨automatically✨ fixes this behaviour.\n\nHowever, KDoc image syntax does not support specifying image size. This plugin introduces new syntax to achieve this:\n```kotlin\n/**\n * ![Extended FAB image](https://example.com/image.png)\n * ![256x75 Extended FAB image](https://example.com/image.png)\n * ![256x Extended FAB image](https://example.com/image.png)\n * ![x75 Extended FAB image](https://example.com/image.png)\n * \n * Space is not necessary but is used for readability.\n */\nfun Button()\n```\n\nThis feature is especially useful for design system creators and users — it increases **discoverability** of ds\ncomponents, allowing users to instantly preview them, for example, in code completion menu.\n\n## 🌈 Color Previews\nFor this feature to work, you need to implement your color system like this:\n```kotlin\nclass MyColors(\n  val primary: Color,\n  val secondary: Color,\n  val accent: Color,\n) {\n  /**\n   * This class MUST have this structure and name.\n   * It MUST be placed here.\n   * You can create it manually or autogenerate it using code generators.\n   */\n  private class KelpColorPreview {\n    /**\n     * The pattern is \"name_lightColor_darkColor\"\n     * If you don't have a dark theme, you MUST set `darkColor`\n     * to be the same as `lightColor`, then it won't be rendered.\n     * \n     * Colors MUST be in ARGB:\n     * The format of an ARGB hexadecimal color is AARRGGBB. \n     * AA is the alpha channel. It represents the opacity of the color. \n     * RR is the red value, GG is the green, and BB is the blue.\n     * \n     * If your colors are in RGB format, just add FF to them, \n     * representing no transparency.\n     */\n    val primary_FFD0BCFF_FF6650A4 = Unit\n    val secondary_12CCC2DC_FF625B71 = Unit\n    val accent_FFEFB8C8_FF7D5260 = Unit\n  }\n}\n\n// Another example:\nclass MyColors2 {\n  var primary: Color by mutableStateOf(Color.Red)\n  val secondary: Color = TODO()\n\n  private class KelpColorPreview {\n    val primary_FFD0BCFF_FF6650A4 = Unit\n    val secondary_12CCC2DC_FF625B71 = Unit\n  }\n}\n```\n\nOptionally, Kelp also supports color tokens.\nTo enable, set `enumColorTokensEnabled` in `config.json` (see below)\n\nMore info about color tokens — [here](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/ColorScheme.kt;l=879?q=ColorSchemeKeyTokens\u0026ss=androidx%2Fplatform%2Fframeworks%2Fsupport).\n\n```kotlin\nenum class MyColorTokens {\n  Primary,\n  Secondary,\n  Accent,\n  ;\n\n  private class KelpColorPreview {\n    val Primary_FFD0BCFF_FF6650A4 = Unit\n    val Secondary_12CCC2DC_FF625B71 = Unit\n    val Accent_FFEFB8C8_FF7D5260 = Unit\n  }\n}\n```\nUsing this convention, there is **no need** to connect a configuration file with \ncolor values to the plugin per project.\n\n\u003e [!WARNING]  \n\u003e Until [this issue](https://youtrack.jetbrains.com/issue/GRZ-4351) is resolved, **Grazie Pro** plugin\n\u003e is incompatible with color previews in the gutter.\n\u003e\n\u003e Please, disable the Grazie Pro plugin if you want to use this feature.\n\n## ⌨️ Live templates\nThese are prebuilt templates that are in the default `config.json` located below:\n- `dt` — `DsTheme.`\n- `dtc` — `DsTheme.colors.`\n- `dtt` — `DsTheme.typography.`\n- `dti` — `DsTheme.icons.`\n- `rmso` — `var/val name by remember { mutableStateOf(false/null/0/0f) }`\n\nReplace abbreviations, package and class names with your own.\n\nYou can add your own templates: just [export](https://www.jetbrains.com/help/idea/2024.1/sharing-live-templates.html#the-quick-way-copy-and-paste) \nthem from the IDE and manually convert xml to json.\n\nAll templates are shared with your teammates through git (in contrast with the IDE templates).\n\n## 🧪 Experimental support for IntelliJ IDEA\nKelp plugin supports IntelliJ IDEA in addition to Android Studio.\n\n\u003e [!WARNING]  \n\u003e However, IntelliJ IDEA support is experimental and can be **dropped** anytime. **DO NOT** rely on it.\n\n## 📦 Installation\n\n1. Make sure that you are using **Android Studio Meerkat | 2024.3.1** or later\n2. In \u003ckbd\u003eSettings/Preferences\u003c/kbd\u003e \u003e \u003ckbd\u003ePlugins\u003c/kbd\u003e \u003e \u003ckbd\u003e⚙️\u003c/kbd\u003e \u003e \u003ckbd\u003eManage Plugin Repositories...\u003c/kbd\u003e \n   add the following url:\n   \n   ```\n   https://github.com/ozontech/kelp/releases/download/ideRepo/updatePlugins.xml\n   ```\n3. Close this window, select \"Marketplace\", type \"kelp\" into the search box and click \"Install\" ([full tutorial](https://www.jetbrains.com/help/idea/managing-plugins.html#repos))\n4. _(Optional)_ If you want to notify developers about the need to install this plugin, \ncreate this file `/.idea/externalDependencies.xml`, add it to git, and paste this in the file:\n    ```xml\n    \u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n    \u003cproject version=\"4\"\u003e\n      \u003ccomponent name=\"ExternalDependencies\"\u003e\n        \u003cplugin id=\"ru.ozon.ideplugin.kelp\" min-version=\"1.1.1\" /\u003e\n      \u003c/component\u003e\n    \u003c/project\u003e\n    ```\n    You can read more about it [here](https://www.jetbrains.com/help/idea/managing-plugins.html#required-plugins).\n5. Open the project you want to use this plugin with, create this file:\n  `/.idea/kelp/config.json`, and add it to git.\n6. Paste this content into it (without comments, they are unsupported in JSON):\n\n\u003cdetails\u003e\n\u003csummary\u003eWithout comments\u003c/summary\u003e\n\n```json\n{\n  \"componentFunHighlighting\": {\n    \"functionFqnPrefix\": \"com.your.designsystem.package.components.\",\n    \"functionSimpleNamePrefix\": \"Ds\"\n  },\n  \"colorPreview\": {\n    \"codeCompletionEnabled\": true,\n    \"gutterEnabled\": true,\n    \"enumColorTokensEnabled\": true\n  },\n  \"iconsRendering\": {\n    \"codeCompletionEnabled\": true,\n    \"gutterEnabled\": true,\n    \"containerClassName\": \"com.your.designsystem.package.DsIcons\",\n    \n    \"propertyNameFilter\": {\n      \"startsWith\": [\"ic_\"],\n      \"doesNotStartWith\": [\"allIconsAsList\", \"otherProperty\"]\n    },\n    \n    \"propertyToResourceMapper\": {\n      \"addPrefix\": \"ic_\",\n      \"convertToSnakeCase\": true\n    }\n  },\n  \"demoApp\": {\n    \"intentionName\": \"🚀 Open in MY CUSTOM design system demo app\",\n    \"functionFqnPrefix\": \"com.your.designsystem.package.components.\",\n    \"functionSimpleNamePrefix\": \"Ds\",\n    \"appPackageName\": \"com.your.designsystem.package.demo\",\n    \"componentDeeplink\": \"yourscheme://component/DS_COMPONENT_FQN_DEEPLINK_PLACEHOLDER\",\n    \"apkInstallation\": true\n  },\n  \"liveTemplates\": [\n    {\n      \"abbreviation\": \"dt\",\n      \"text\": \"com.your.designsystem.DsTheme.$CODE_COMPLETION$\",\n      \"description\": \"Writes \\\"DsTheme.\\\"\",\n      \"variables\": [{ \"name\": \"CODE_COMPLETION\", \"expression\": \"complete()\" }]\n    },\n    {\n      \"abbreviation\": \"dtc\",\n      \"text\": \"com.your.designsystem.DsTheme.colors.$CODE_COMPLETION$\",\n      \"description\": \"Writes \\\"DsTheme.colors.\\\"\",\n      \"variables\": [{ \"name\": \"CODE_COMPLETION\", \"expression\": \"complete()\" }]\n    },\n    {\n      \"abbreviation\": \"dtt\",\n      \"text\": \"com.your.designsystem.DsTheme.typography.$CODE_COMPLETION$\",\n      \"description\": \"Writes \\\"DsTheme.typography.\\\"\",\n      \"variables\": [{ \"name\": \"CODE_COMPLETION\", \"expression\": \"complete()\" }]\n    },\n    {\n      \"abbreviation\": \"dti\",\n      \"text\": \"com.your.designsystem.DsTheme.icons.$CODE_COMPLETION$\",\n      \"description\": \"Writes \\\"DsTheme.icons.\\\"\",\n      \"variables\": [{ \"name\": \"CODE_COMPLETION\", \"expression\": \"complete()\" }]\n    },\n    {\n      \"abbreviation\": \"rmso\",\n      \"text\": \"$VAL_TYPE$ $NAME$ by androidx.compose.runtime.remember { androidx.compose.runtime.mutableStateOf($VALUE$) }\",\n      \"description\": \"Creates mutableStateOf\",\n      \"reformat\": true,\n      \"variables\": [\n        { \"name\": \"VAL_TYPE\", \"expression\": \"enum(\\\"var\\\", \\\"val\\\")\" },\n        { \"name\": \"NAME\" },\n        { \"name\": \"VALUE\", \"expression\": \"enum(\\\"false\\\", \\\"null\\\", \\\"0\\\", \\\"0f\\\")\" }\n      ],\n      \"context\": [\"KOTLIN_CLASS\", \"KOTLIN_STATEMENT\", \"KOTLIN_TOPLEVEL\"]\n    }\n  ]\n}\n```\n\u003c/details\u003e\n\n```json5\n{\n  // If you want to disable some of these features, just don't include their sections in your json file.\n  \n  // Replacing the default icon of design system components\n  // in the code completion with a customizable icon\n  // Custom icon MUST be \n  // 1. an svg \n  // 2. with size — 40x40\n  // 3. placed here: /.idea/kelp/dsComponentFunIcon.svg\n  // 4. optionally, a dark version can be added : /.idea/kelp/dsComponentFunIcon_dark.svg\n  \"componentFunHighlighting\": {\n    // custom icon will be added to all functions in this package\n    \"functionFqnPrefix\": \"com.your.designsystem.package.components.\",\n    \"functionSimpleNamePrefix\": \"Ds\" // optional\n  },\n\n  // Rendering design system colors in the code completion and gutter (where breakpoints are). \n  // Like with regular Android resources.\n  \"colorPreview\": {\n    \"codeCompletionEnabled\": true,\n    \"gutterEnabled\": true,\n    // optional, color tokens from enum class\n    \"enumColorTokensEnabled\": true,\n  },\n  \n  // Rendering design system icons in the code completion and gutter (where breakpoints are). \n  // Like with regular Android resources.\n  // This feature:\n  // 1. scans the fields of `containerClassName`\n  // 2. filters them using `propertyNameFilter`\n  // 3. applies `propertyToResourceMapper`\n  // 4. retrieves an icon by the resulting name from the xml that is available in the project\n  // or it's dependencies and places this icon in the code completion and gutter.\n  \"iconsRendering\": {\n    \"codeCompletionEnabled\": true,\n    \"gutterEnabled\": true,\n    // class with a lot of properties that return icons and are named as icons\n    \"containerClassName\": \"com.your.designsystem.package.DsIcons\",\n    \n    // optional: filters out properties that do not represent an icon\n    \"propertyNameFilter\": {\n      // optional: only properties with this prefix will be considered as an icon\n      \"startsWith\": [\"ic_\"],\n      // optional: all properties with this prefix will be skipped\n      \"doesNotStartWith\": [\"allIconsAsList\", \"otherProperty\"]\n    },\n    \n    // maps property names to drawable resource names\n    \"propertyToResourceMapper\": {\n      \"addPrefix\": \"ic_\", // optional\n      \"convertToSnakeCase\": true // optional; e.g. \"AddAccount\" -\u003e \"add_account\"\n    }\n  },\n  \n  // Opening the component page in the demo app via an Intention Action and a gutter icon\n  // only `public` functions will be processed\n  \"demoApp\": {\n    // optional: custom name of the intention action\n    \"intentionName\": \"🚀 Open in MY CUSTOM design system demo app\",\n    \"functionFqnPrefix\": \"com.your.designsystem.package.components.\",\n    \"functionSimpleNamePrefix\": \"Ds\", // optional\n    // package name of the demo app\n    \"appPackageName\": \"com.your.designsystem.package.demo\",\n    // deeplink that will be used to open a component page in the demo app.\n    // DS_COMPONENT_FQN_DEEPLINK_PLACEHOLDER will be replaced with\n    // the fully qualified name of the \n    // composable function, e.g. com.your.designsystem.package.components.Badge\n    \"componentDeeplink\": \"yourscheme://component/DS_COMPONENT_FQN_DEEPLINK_PLACEHOLDER\",\n    \n    // optional\n    // Installing (if not installed) the apk file\n    // of the demo app (showcase app) on an Android device.\n    \n    // Demo app apk must be placed here with this name: /.idea/kelp/demoApp-VERSION_NAME.apk\n    // For example: /.idea/kelp/demoApp-0.12.0.apk\n    // The plugin will acquire the latest version from the apk file name (for example, 0.12.0).\n    // If the app is not installed OR installed, but has a lower\n    // version, the plugin will install the apk on the device.\n    \"apkInstallation\": true,\n    // optional\n    // if apkInstallation == true, and there is no apk file found, launches this gradle command.\n    // If you use Kelp Gradle Plugin, value must be \"kelpCheckDemoAppApk\"\n    \"apkDownloadGradleCommand\": \"kelpCheckDemoAppApk\"\n  },\n  \n  // Installs live templates into the IDE.\n  // Useful for writing frequent code, like \"MaterialTheme.colors.\" in just 3 keystrokes.\n  // If you'd like add your own custom templates, export them and manually convert xml to json.\n  // More: https://www.jetbrains.com/help/idea/2024.1/sharing-live-templates.html#the-quick-way-copy-and-paste\n  \"liveTemplates\": [\n    {\n      \"abbreviation\": \"dtc\",\n      \"text\": \"com.your.designsystem.DsTheme.colors.\",\n      \"description\": \"Writes \\\"DsTheme.colors.\\\"\"\n    }\n    // a list of useful templates is in the comment-less json\n  ]\n}\n```\nNow, press \u003ckbd\u003e⌘\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e (or \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eS\u003c/kbd\u003e) to save the config.json and plugin will \npick up new changes.\n\n## 💥 Boom\nEverything should work now!\n\nIf it doesn't, please, make sure that your `config.json` complies with \n[this](https://github.com/ozontech/kelp/blob/main/src/main/kotlin/ru/ozon/ideplugin/kelp/pluginConfig/KelpConfig.kt) format.\n\nIf that does not help, please, file [an issue](https://github.com/ozontech/kelp/issues/new/choose) in this repo.\n\n## 🐘 Gradle Plugin\nIn addition to the IDE plugin, you can optionally use a companion gradle plugin.\nIt has 2 features/gradle tasks:\n1. `kelpCheckIdePluginPresence` — Notifies if Kelp IDE plugin is absent. Can fail the build or print out a warning in \nthe console.\n2. `kelpCheckDemoAppApk` — Checks presence and version of the design system demo app apk. Downloads one if needed.\n\nYou can enable/disable these features independently.\n\n## ⚙️ Configuration\n\n[Kelp on Gradle Plugin Portal](https://plugins.gradle.org/plugin/ru.ozon.kelp)\n\nInstructions for using `buildscript` are [here](https://plugins.gradle.org/plugin/ru.ozon.kelp).\n\n```kotlin\n// in build.gradle.kts of the app module that developers compile frequently to launch the app\nplugins {\n    id(\"ru.ozon.kelp\") version \"1.0.0\"\n}\n\nkelp {\n    idePluginAbsenceBehaviour = IdePluginAbsenceBehaviour.WARNING // NOTHING, WARNING, BUILD_FAIL\n    requiredDemoApkVersion = \"1.3.0\" // libs.versions.yourDesignSystem.get()\n  \n    // If your apk file can be downloaded without requiring to log in through web browser, use SimpleApkDownloader:\n    setApkDownloader(\n        SimpleApkDownloader(\n            additionalErrorMsg = \"Make sure to turn on the corporate VPN\", // optional\n            urlProvider = { version -\u003e \"https://example.com/demo-$version.apk\" },\n        ),\n    )\n  \n    // In other cases, when manual interactions with the browser are required, use BrowserApkDownloader:\n    setApkDownloader(BrowserApkDownloader { version -\u003e \"https://example.com/?query=android/$version\" })\n  \n    // It does the following:\n    // 1. Opens the provided url in the browser\n    // 2. Asks the user to download an apk\n    // 3. Listens for the appearance of the new \".apk\" file in the downloads folder\n    // 4. Copies it to the [destinationDir] with the [fileName].\n  \n    // You can also implement fully custom ApkDownloader:\n    setApkDownloader(ApkDownloader { version, destinationDir, fileName, logger -\u003e\n        // ...\n        file(\"your apk file\").copyTo(destinationDir.resolve(fileName))\n    })\n}\n```\n\u003cdetails\u003e\n\u003csummary\u003eGroovy\u003c/summary\u003e\n\n```groovy\nimport ru.ozon.kelp.IdePluginAbsenceBehaviour\nimport ru.ozon.kelp.downloaders.SimpleApkDownloader\n\nkelp {\n  idePluginAbsenceBehaviour = IdePluginAbsenceBehaviour.BUILD_FAIL\n  requiredDemoApkVersion = \"1.3.0\"\n\n  def apkDownloader = new SimpleApkDownloader(\n          \"Make sure to turn on the corporate VPN\",\n          {},\n          { version -\u003e \"https://example.com/demo-${version}.apk\".toString() }\n  )\n  setApkDownloader(project, apkDownloader)\n  setApkDownloader(project, new BrowserApkDownloader(null, { version -\u003e \"https://example.com/?query=android/{$version}\".toString() }))\n}\n```\n\n\u003c/details\u003e\n\n### 🚚 Choosing how to distribute the demo app apk\nTLDR:\n```mermaid\nflowchart TD\n    SeparateRepo{Design system \u003cbr\u003ein a separate repo?}\n    SeparateRepo --\u003e|No| NotSupported[Automatic apk installation \u003cbr\u003eis unsupported]\n    SeparateRepo --\u003e|Yes| IsOneUser{Only one user of the \u003cbr\u003edesign system library?}\n    IsOneUser --\u003e|Yes| ManualAddToGit[Add apk to git] --\u003e ManualUpdate[Update manually with \u003cbr\u003eevery version bump]\n    IsOneUser --\u003e|No| EasyDownloading{How easy is it\u003cbr\u003e to download the \u003cbr\u003edemo app apk?}\n    EasyDownloading --\u003e|Easy| NoGit[Do not add to git] --\u003e SimpleApkDownloader[Use SimpleApkDownloader]\n    EasyDownloading --\u003e|Hard| AddToGit[Add apk to git] --\u003e BrowserApkDownloader[Use BrowserApkDownloader]\n    \n```\n1️⃣. Is your design system located in a separate repo? If no, then demo app installation is currently unsupported.\n\nYou can either:\n- Include the demo app gradle module into your app's debug build. Then Kelp will just open a deeplink to your app.\n- Expect developers to manually install the demo app.\n\n2️⃣. How many clients use your design system library?\n\n- If there is only one user and the design system library maintainer is responsible for version bumps in the client \nrepo, you can add the latest demo app apk to git (possibly using git lfs) and update it with the new version every \ntime you perform a version bump. This way, everybody will have the latest apk file in their `/.idea/kelp/apk` dir.\n\n- If you have many clients, and they update the lib version themselves, you can advise them to integrate Kelp Gradle \nPlugin and configure it with either: `SimpleApkDownloader` or `BrowserApkDownloader`.\n\n3️⃣. How easy is it to download the demo app apk?\n\n\u003e [!TIP]\n\u003e Consider pushing the demo app apk together with the design system lib `.aar` file to maven. \n\u003e \n\u003e This way, you can use `SimpleApkDownloader`.\n\u003e \n\u003e \u003cdetails\u003e\n\u003e \u003csummary\u003eHow?\u003c/summary\u003e\n\u003e \n\u003e ```kotlin\n\u003e tasks.named(\"publish\") {\n\u003e     dependsOn(\":app:assembleRelease\")\n\u003e }\n\u003e \n\u003e publishing {\n\u003e     publications {\n\u003e         register\u003cMavenPublication\u003e(\"release\") {\n\u003e             from(components[\"release\"])\n\u003e             groupId = \"com.company.lib\"\n\u003e             artifactId = \"lib\"\n\u003e             version = \"1.0.0\"\n\u003e \n\u003e             artifact(\"$rootDir/app/build/outputs/apk/release/app-release.apk\") {\n\u003e                 classifier = \"demoApp\"\n\u003e             }\n\u003e         }\n\u003e     }\n\u003e }\n\u003e ```\n\u003e \n\u003e \u003c/details\u003e\n\n- If the demo app apk can be downloaded from the direct link (maybe it's only accessible from a corporate VPN), then\nyou can use `SimpleApkDownloader` and **do not** add the apk to git. This way, all developers working on the projects\nthat depend on your design system will experience automatic downloading of the latest demo app apk.\n\n- Otherwise, if manual interactions with the browser are required to download the apk, use `BrowserApkDownloader` and\nadd the apk to git. \n\u003cbr\u003e\u003cbr\u003eThen, when the project maintainer performs a version bump of the design system library and builds their app,\nKelp Gradle Plugin will detect the mismatch between the old demo app apk version and the new design system version. \n\u003cbr\u003e\u003cbr\u003eIt will open the browser and ask the maintainer to download the apk. Gradle plugin will automatically detect its\nappearance in the _Downloads_ dir, rename and copy it to the project. \n\u003cbr\u003e\u003cbr\u003eFinally, the project maintainer will commit the version bump changes _along_ with the new apk to the git.\n\u003cbr\u003e\u003cbr\u003eIn this case, `BrowserApkDownloader` simplifies the task of updating the design system to the new version. Project \nmaintainers do not have to go to the design system docs to acquire the apk downloading link and manually place the apk \ninto the project.\n\n## License\n\n```\nCopyright © 2023 LLC \"Internet Solutions\"\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":[],"categories":["Kotlin"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozontech%2Fkelp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fozontech%2Fkelp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fozontech%2Fkelp/lists"}