Skip to content

Commit e716840

Browse files
kikosodkhawk
kikoso
and
dkhawk
authored
docs: add LLM integration guide and Gemini skill (#859)
* docs: added LLM guide * docs: added release-please * docs: added android-maps-compose Gemini skill * docs: update LLM guide with secrets plugin instructions * chore: add SKILL.md to release-please extra files * docs: update LLM guide with version catalogs instructions --------- Co-authored-by: Dale Hawkins <107309+dkhawk@users.noreply.github.com>
1 parent 3b12a24 commit e716840

File tree

3 files changed

+280
-1
lines changed

3 files changed

+280
-1
lines changed

‎.gemini/skills/android-maps-compose/SKILL.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
name: android-maps-compose
3+
description: Guide for integrating the android-maps-compose library into an Android application. Use when users ask to add Google Maps Compose to their Android app or set up Maps in Compose.
4+
---
5+
6+
# Android Maps Compose Integration
7+
8+
You are an expert Android developer specializing in Jetpack Compose and modern Android architecture. Follow these instructions carefully to integrate the `android-maps-compose` library into the user's Android application.
9+
10+
## 1. Setup Dependencies
11+
12+
First, add the necessary dependencies to the app-level `build.gradle.kts` file.
13+
Verify the latest versions if possible, but use these as a baseline:
14+
15+
```kotlin
16+
dependencies {
17+
// Google Maps Compose library
18+
implementation("com.google.maps.android:maps-compose:8.2.0") // x-release-please-version
19+
20+
// Optional: Maps Compose Utilities (for clustering, etc.)
21+
// implementation("com.google.maps.android:maps-compose-utils:8.2.0") // x-release-please-version
22+
23+
// Optional: Maps Compose Widgets (for UI components)
24+
// implementation("com.google.maps.android:maps-compose-widgets:8.2.0") // x-release-please-version
25+
}
26+
```
27+
28+
## 2. Setup the Secrets Gradle Plugin
29+
30+
Instead of hardcoding the Google Maps API key in `AndroidManifest.xml`, use the Secrets Gradle Plugin for Android to inject the API key securely.
31+
32+
First, add the plugin to the project-level `build.gradle.kts`:
33+
34+
```kotlin
35+
buildscript {
36+
dependencies {
37+
classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
38+
}
39+
}
40+
```
41+
42+
Then, apply the plugin in the app-level `build.gradle.kts`:
43+
44+
```kotlin
45+
plugins {
46+
// ...
47+
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
48+
}
49+
```
50+
51+
Add the API Key to `local.properties`:
52+
53+
```properties
54+
MAPS_API_KEY=YOUR_API_KEY
55+
```
56+
57+
In `AndroidManifest.xml`, add the required permissions and reference the injected API key meta-data:
58+
59+
```xml
60+
<manifest ...>
61+
<!-- Required for Google Maps -->
62+
<uses-permission android:name="android.permission.INTERNET" />
63+
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
64+
65+
<application ...>
66+
<!-- Google Maps API Key injected by Secrets Gradle Plugin -->
67+
<meta-data
68+
android:name="com.google.android.geo.API_KEY"
69+
android:value="${MAPS_API_KEY}" />
70+
...
71+
</application>
72+
</manifest>
73+
```
74+
75+
## 3. Implement the Map Composable
76+
77+
Create a new file named `MapScreen.kt` (or similar, depending on the app's architecture) and add a basic Jetpack Compose map implementation.
78+
79+
Use `CameraPositionState` to control the camera and `Marker` to display points of interest.
80+
81+
```kotlin
82+
import androidx.compose.foundation.layout.fillMaxSize
83+
import androidx.compose.runtime.Composable
84+
import androidx.compose.ui.Modifier
85+
import com.google.android.gms.maps.model.CameraPosition
86+
import com.google.android.gms.maps.model.LatLng
87+
import com.google.maps.android.compose.GoogleMap
88+
import com.google.maps.android.compose.Marker
89+
import com.google.maps.android.compose.MarkerState
90+
import com.google.maps.android.compose.rememberCameraPositionState
91+
92+
@Composable
93+
fun MapScreen() {
94+
// Default location (e.g., Singapore)
95+
val defaultLocation = LatLng(1.35, 103.87)
96+
val cameraPositionState = rememberCameraPositionState {
97+
position = CameraPosition.fromLatLngZoom(defaultLocation, 10f)
98+
}
99+
100+
GoogleMap(
101+
modifier = Modifier.fillMaxSize(),
102+
cameraPositionState = cameraPositionState
103+
) {
104+
Marker(
105+
state = MarkerState(position = defaultLocation),
106+
title = "Singapore",
107+
snippet = "Marker in Singapore"
108+
)
109+
}
110+
}
111+
```
112+
113+
## 4. Best Practices & Guidelines
114+
* **State Management:** Hoist state (like camera position and marker lists) to the ViewModel if the map is dynamic.
115+
* **Performance:** For large numbers of markers, use the `Clustering` composable from the `maps-compose-utils` artifact instead of rendering thousands of individual `Marker` composables.
116+
* **Lifecycle:** `GoogleMap` handles its own lifecycle under the hood in Compose, so you generally don't need to manually manage `MapView` lifecycle events unless doing custom integrations.
117+
118+
## 5. Execution Steps
119+
1. Create a new branch `feature/maps-compose-integration`.
120+
2. Add the Maps Compose dependencies to the app-level `build.gradle.kts`.
121+
3. Set up the Secrets Gradle Plugin in both project-level and app-level `build.gradle.kts`.
122+
4. Update `AndroidManifest.xml` with permissions and the `${MAPS_API_KEY}` placeholder.
123+
5. Create the `MapScreen.kt` composable.
124+
6. Provide a summary of the changes and instruct the user on how to add their API key to `local.properties`.

‎llm-integration-prompt.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Android Maps Compose - AI Integration Prompt
2+
3+
You are an expert Android developer specializing in Jetpack Compose and modern Android architecture. Your task is to integrate the `android-maps-compose` library into the user's Android application.
4+
5+
Please follow these instructions carefully to ensure a complete and idiomatic implementation.
6+
7+
## 1. Setup Dependencies
8+
9+
You can add dependencies using either version catalogs (recommended) or directly in your `build.gradle.kts` file. Verify the latest versions if possible, but use these as a baseline:
10+
11+
### Option A: Using Version Catalogs (Recommended)
12+
13+
Add the following to your `gradle/libs.versions.toml` file:
14+
15+
```toml
16+
[versions]
17+
mapsCompose = "8.2.0" # x-release-please-version
18+
19+
[libraries]
20+
maps-compose = { group = "com.google.maps.android", name = "maps-compose", version.ref = "mapsCompose" }
21+
maps-compose-utils = { group = "com.google.maps.android", name = "maps-compose-utils", version.ref = "mapsCompose" }
22+
maps-compose-widgets = { group = "com.google.maps.android", name = "maps-compose-widgets", version.ref = "mapsCompose" }
23+
```
24+
25+
Then add them to your app-level `build.gradle.kts`:
26+
27+
```kotlin
28+
dependencies {
29+
// Google Maps Compose library
30+
implementation(libs.maps.compose)
31+
32+
// Optional: Maps Compose Utilities (for clustering, etc.)
33+
// implementation(libs.maps.compose.utils)
34+
35+
// Optional: Maps Compose Widgets (for UI components)
36+
// implementation(libs.maps.compose.widgets)
37+
}
38+
```
39+
40+
### Option B: Direct Dependencies
41+
42+
If you are not using version catalogs, add the dependencies directly to your app-level `build.gradle.kts`:
43+
44+
```kotlin
45+
dependencies {
46+
// Google Maps Compose library
47+
implementation("com.google.maps.android:maps-compose:8.2.0") // x-release-please-version
48+
49+
// Optional: Maps Compose Utilities (for clustering, etc.)
50+
// implementation("com.google.maps.android:maps-compose-utils:8.2.0") // x-release-please-version
51+
52+
// Optional: Maps Compose Widgets (for UI components)
53+
// implementation("com.google.maps.android:maps-compose-widgets:8.2.0") // x-release-please-version
54+
}
55+
```
56+
57+
## 2. Setup the Secrets Gradle Plugin
58+
59+
Instead of hardcoding the Google Maps API key in `AndroidManifest.xml`, use the Secrets Gradle Plugin for Android to inject the API key securely.
60+
61+
First, add the plugin to the project-level `build.gradle.kts`:
62+
63+
```kotlin
64+
buildscript {
65+
dependencies {
66+
classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
67+
}
68+
}
69+
```
70+
71+
Then, apply the plugin in the app-level `build.gradle.kts`:
72+
73+
```kotlin
74+
plugins {
75+
// ...
76+
id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
77+
}
78+
```
79+
80+
Add the API Key to `local.properties`:
81+
82+
```properties
83+
MAPS_API_KEY=YOUR_API_KEY
84+
```
85+
86+
In `AndroidManifest.xml`, add the required permissions and reference the injected API key meta-data:
87+
88+
```xml
89+
<manifest ...>
90+
<!-- Required for Google Maps -->
91+
<uses-permission android:name="android.permission.INTERNET" />
92+
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
93+
94+
<application ...>
95+
<!-- Google Maps API Key injected by Secrets Gradle Plugin -->
96+
<meta-data
97+
android:name="com.google.android.geo.API_KEY"
98+
android:value="${MAPS_API_KEY}" />
99+
...
100+
</application>
101+
</manifest>
102+
```
103+
104+
## 3. Implement the Map Composable
105+
106+
Create a new file named `MapScreen.kt` (or similar, depending on the app's architecture) and add a basic Jetpack Compose map implementation.
107+
108+
Use `CameraPositionState` to control the camera and `Marker` to display points of interest.
109+
110+
```kotlin
111+
import androidx.compose.foundation.layout.fillMaxSize
112+
import androidx.compose.runtime.Composable
113+
import androidx.compose.ui.Modifier
114+
import com.google.android.gms.maps.model.CameraPosition
115+
import com.google.android.gms.maps.model.LatLng
116+
import com.google.maps.android.compose.GoogleMap
117+
import com.google.maps.android.compose.Marker
118+
import com.google.maps.android.compose.MarkerState
119+
import com.google.maps.android.compose.rememberCameraPositionState
120+
121+
@Composable
122+
fun MapScreen() {
123+
// Default location (e.g., Singapore)
124+
val defaultLocation = LatLng(1.35, 103.87)
125+
val cameraPositionState = rememberCameraPositionState {
126+
position = CameraPosition.fromLatLngZoom(defaultLocation, 10f)
127+
}
128+
129+
GoogleMap(
130+
modifier = Modifier.fillMaxSize(),
131+
cameraPositionState = cameraPositionState
132+
) {
133+
Marker(
134+
state = MarkerState(position = defaultLocation),
135+
title = "Singapore",
136+
snippet = "Marker in Singapore"
137+
)
138+
}
139+
}
140+
```
141+
142+
## 4. Best Practices & Guidelines
143+
* **State Management:** Hoist state (like camera position and marker lists) to the ViewModel if the map is dynamic.
144+
* **Performance:** For large numbers of markers, use the `Clustering` composable from the `maps-compose-utils` artifact instead of rendering thousands of individual `Marker` composables.
145+
* **Lifecycle:** `GoogleMap` handles its own lifecycle under the hood in Compose, so you generally don't need to manually manage `MapView` lifecycle events unless doing custom integrations.
146+
147+
## 5. Execution Steps
148+
1. Create a new branch `feature/maps-compose-integration`.
149+
2. Add the Maps Compose dependencies to the app-level `build.gradle.kts`.
150+
3. Set up the Secrets Gradle Plugin in both project-level and app-level `build.gradle.kts`.
151+
4. Update `AndroidManifest.xml` with permissions and the `${MAPS_API_KEY}` placeholder.
152+
5. Create the `MapScreen.kt` composable.
153+
6. Provide a summary of the changes and instruct the user on how to add their API key to `local.properties`.

‎release-please-config.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44
"release-type": "simple",
55
"extra-files": [
66
"build.gradle.kts",
7-
"README.md"
7+
"README.md",
8+
"llm-integration-prompt.md",
9+
".gemini/skills/android-maps-compose/SKILL.md"
810
]
911
}
1012
}

0 commit comments

Comments
 (0)