@niondigital/widgets-expo-config-plugin

Overview

This plugin is an Expo Config Plugin that enables you to add iOS widgets to your Expo project.

Note: Currently, this plugin only supports iOS widgets. Android widget support may be added in the future.

---

Installation

# Using npx
npx expo install @niondigital/widgets-expo-config-plugin

# Using npm
npm install @niondigital/widgets-expo-config-plugin

# Using yarn
yarn add @niondigital/widgets-expo-config-plugin

Quick Start

1. Copy Example Widget Files

Copy the files from the example/ios/ExampleWidget directory into your project's directory.

Important: Your widget directory must include a complete Info.plist with build variable references (like $(CURRENT_PROJECT_VERSION) and $(MARKETING_VERSION)). The example Info.plist already includes these. This is required for agvtool (used by EAS Build) to correctly sync version numbers between your app and the widget extension.

2. Add and Configure the Plugin

Modify your app.json / app.config.js / app.config.ts to include the plugin configuration. Ensure the path property points to the directory where you copied the example widget files.

Example: app.json

{
  "plugins": [
    [
      "@niondigital/widgets-expo-config-plugin",
      {
        "name": "MyWidget",
        "path": "./widgets/ios/ExampleWidget"
      }
    ]
  ]
}

3. Run a Clean Prebuild

Execute the following command to rebuild the project:

npx expo prebuild --clean

Plugin Properties

The following properties can be configured in the plugin:

Property	Required	Description
name	Required	The name of the widget extension.
path	Required	The path to the directory containing the widget files, relative to the project root.
additionalFiles	Optional	List of additional files that should be added to the target (e.g. shared classes like a bridge)
entitlements	Optional	A key-value object of entitlements to add to the main target and widget target.
buildSettings	Optional	A key-value object to override default build settings (e.g., { "IPHONEOS_DEPLOYMENT_TARGET": "17.0" }).

FAQ

How can I change the iOS deployment target?

By default, the deployment target is set to 18.0 because iOS 18.0 introduces new widget capabilities (e.g., Control Center widgets). However, if you do not require these features, you can lower the deployment target.

To modify the iOS deployment target, add the following configuration to your app.json / app.config.js / app.config.ts:

{
  "plugins": [
    [
      "@niondigital/widgets-expo-config-plugin",
      {
        // ...
        "buildSettings": {
          "IPHONEOS_DEPLOYMENT_TARGET": "17.0"
        }
      }
    ]
  ]
}

How can I add multiple widgets?

You can add multiple widgets by creating a widget bundle which can include multiple widgets of each type. You can find an example of a widget bundle in the example/ios/ExampleWidget/ExampleWidgetBundle.swift file.