Building Android Widgets in Expo with Custom Native Modules

A guide to creating Android home screen widgets using Expo modules, complete with state management, auto-updates, and best practices.

Overview

This guide demonstrates how to create Android home screen widgets in Expo applications using custom native modules. Unlike traditional widgets that exist independently, this approach allows seamless integration between your React Native app and Android widgets with shared state management.

What You'll Learn

Create custom Expo modules for Android widgets

Implement widget logic in Kotlin with Jetpack Compose Glance

Set up state management between app and widget

Configure auto-updating widgets with WorkManager

Use config plugins for build-time configurations

High-Level Process

Before diving into the specifics, here's the overall workflow for creating Android widgets in Expo:

1. Architecture Overview

typescript

1┌─────────────────────────────────────────────────────────────────┐
2│                     Expo React Native App                      │
3├─────────────────────────────────────────────────────────────────┤
4│  ┌─────────────────┐    ┌─────────────────┐                   │
5│  │  Native Module  │◄──►│  Android Widget │                   │
6│  │  (Bridge Layer) │    │  (Glance UI)    │                   │
7│  └─────────────────┘    └─────────────────┘                   │
8├─────────────────────────────────────────────────────────────────┤
9│                   Android System Layer                         │
10│  ┌─────────────────┐    ┌─────────────────┐                   │
11│  │ App Manifest    │◄──►│ Widget Manifest │                   │
12│  │ (Main Entry)    │    │ (Widget Entry)  │                   │
13│  └─────────────────┘    └─────────────────┘                   │
14└─────────────────────────────────────────────────────────────────┘

2. Build Process Flow

Development: Write widget code in Kotlin using Jetpack Compose Glance

Native Module: Create bridge between React Native and Android widget

Config Plugins: Configure build-time settings and manifest merging

Prebuild: expo prebuild merges widget manifest into main app manifest

Build: Standard Android build process includes widget in APK

Runtime: Widget appears in launcher, communicates with app via native module

3. Key Components

1package expo.modules.widget.widgets

3import androidx.compose.runtime.Composable

4import androidx.compose.ui.unit.dp

5import androidx.compose.ui.unit.sp

6import androidx.glance.GlanceId

7import androidx.glance.GlanceModifier

8import androidx.glance.appwidget.GlanceAppWidget

9import androidx.glance.appwidget.provideContent

10import androidx.glance.layout.Alignment

11import androidx.glance.layout.Column

12import androidx.glance.layout.fillMaxSize

13import androidx.glance.layout.padding

14import androidx.glance.text.FontWeight

15import androidx.glance.text.Text

16import androidx.glance.text.TextStyle

17import androidx.glance.currentState

18import androidx.glance.state.GlanceStateDefinition

19import androidx.glance.state.PreferencesGlanceStateDefinition

20import android.content.Context

22class MyWidget : GlanceAppWidget() {

24 override val stateDefinition: GlanceStateDefinition<*> = PreferencesGlanceStateDefinition

26 override suspend fun provideGlance(context: Context, id: GlanceId) {

27 provideContent {

28 WidgetContent()

29 }

30 }

32 @Composable

33 private fun WidgetContent() {

34 val prefs = currentState<androidx.datastore.preferences.core.Preferences>()

35 val title = prefs[stringPreferencesKey("widget_title")] ?: "Default Title"

36 val subtitle = prefs[stringPreferencesKey("widget_subtitle")] ?: "Default Subtitle"

38 Column(

39 modifier = GlanceModifier

40 .fillMaxSize()

41 .padding(16.dp),

42 verticalAlignment = Alignment.CenterVertically,

43 horizontalAlignment = Alignment.CenterHorizontally

44 ) {

45 Text(

46 text = title,

47 style = TextStyle(

48 fontSize = 18.sp,

49 fontWeight = FontWeight.Bold

50 )

51 )

53 Text(

54 text = subtitle,

55 style = TextStyle(

56 fontSize = 14.sp

57 )

58 )

59 }

60 }

61}

1package expo.modules.widget

3import android.content.Context

4import androidx.glance.appwidget.GlanceAppWidgetManager

5import androidx.glance.appwidget.state.updateAppWidgetState

6import androidx.glance.appwidget.updateAll

7import expo.modules.kotlin.modules.Module

8import expo.modules.kotlin.modules.ModuleDefinition

9import expo.modules.kotlin.records.Field

10import expo.modules.kotlin.records.Record

11import expo.modules.widget.widgets.MyWidget

12import kotlinx.coroutines.CoroutineScope

13import kotlinx.coroutines.Dispatchers

14import kotlinx.coroutines.launch

15import androidx.datastore.preferences.core.stringPreferencesKey

17data class WidgetData(

18 @Field val title: String,

19 @Field val subtitle: String

20) : Record

22class ExpoWidgetModule : Module() {

23 private val context: Context

24 get() = requireNotNull(appContext.reactContext)

26 override fun definition() = ModuleDefinition {

27 Name("ExpoWidgetModule")

29 AsyncFunction("updateWidget") { data: WidgetData ->

30 CoroutineScope(Dispatchers.IO).launch {

31 try {

32 val glanceIds = GlanceAppWidgetManager(context)

33 .getGlanceIds(MyWidget::class.java)

35 glanceIds.forEach { glanceId ->

36 updateAppWidgetState(context, glanceId) { prefs ->

37 prefs[stringPreferencesKey("widget_title")] = data.title

38 prefs[stringPreferencesKey("widget_subtitle")] = data.subtitle

39 }

40 }

42 MyWidget().updateAll(context)

43 } catch (e: Exception) {

44 e.printStackTrace()

45 }

46 }

47 }

49 AsyncFunction("refreshWidget") {

50 CoroutineScope(Dispatchers.IO).launch {

51 try {

52 MyWidget().updateAll(context)

53 } catch (e: Exception) {

54 e.printStackTrace()

55 }

56 }

57 }

58 }

59}

More posts

Setting Up Android Studio on Linux for React Native (Expo) Development

Understanding Discriminated Unions in TypeScript

How to get the Oauth providre access tokens from next auth/authjs

More posts

Setting Up Android Studio on Linux for React Native (Expo) Development

Understanding Discriminated Unions in TypeScript

How to get the Oauth providre access tokens from next auth/authjs

Overview

What You'll Learn

High-Level Process

1. Architecture Overview

2. Build Process Flow

3. Key Components

Native Modules vs Native Views

Native Views

Native Modules (Our Choice)

Why We Use Native Modules for Widgets

Development Client Setup

Prerequisites

Using Expo Dev Client

1. Install Development Build Dependencies

2. Configure Development Build

3. Create Development Build

4. Widget Testing Workflow

Quick Start (TL;DR)

Project Structure

Step-by-Step Implementation

Step 1: Create the Expo Module

Step 2: Configure Module Dependencies

Step 3: Implement the Widget

Step 4: Create Widget Receiver

Step 5: Implement the Native Module

Step 6: TypeScript Interface

Step 7: Android Manifest Configuration

Step 8: Widget Info XML

Advanced Features

Auto-Updating with WorkManager

Config Plugin for WorkManager Initialization

Best Practices

1. State Management

2. Performance Optimization

3. User Experience

4. Development Workflow

Troubleshooting

Common Issues

Debug Tips

Examples

Basic Usage in React Native

Integration with App State

Conclusion

Key Takeaways

References

Official Documentation & Videos

Example Implementation

Additional Resources