DEV Community: irinaivanovaalex

How to launch a React Native app from the Lock Screen on iPhone

irinaivanovaalex — Fri, 13 Dec 2024 19:16:36 +0000

With the release of iOS 18, it became possible to customize the Lock Screen. Naturally, this opens up opportunities to experiment and add interesting features to your React Native app. In this article, I'll explain how to make your app accessible directly from the Lock Screen.

Requirements

To accomplish this, you'll need:

React Native (I used version 0.76.3).
Configured deep links. If you haven’t set this up yet, check out the guide: https://reactnative.dev/docs/linking.

Steps to Get It Working

1. Create a Widget Template

First, create a widget template using Xcode:

Go to Targets -> "+", and select a widget.
For this example, name it QScan. Xcode will create two widgets: a regular widget and a Control Widget.
The Control Widget is the one you can place on the Lock Screen.

In the Control Widget, you can choose between two types of interactions:

Button (ControlWidgetButton).
Toggle (ControlWidgetToggle).

For my use case, I chose the first option: ControlWidgetButton.

Here’s the implementation:

struct QScanWidgetControl: ControlWidget {
 static let kind: String = "QScanWidget"

 var body: some ControlWidgetConfiguration {
  StaticControlConfiguration(kind: Self.kind) {
   ControlWidgetButton(action: PerformAction()) {

   // Button with a name and a system icon
   Label("displayName", systemImage: "barcode.viewfinder")
   }
  }
  .displayName("displayName")
  .description("widgetDescription")
 }
}

struct PerformAction: AppIntent {
 static let title: LocalizedStringResource = "displayName"

 // Determines if the app should automatically open when the intent is triggered.
 static var openAppWhenRun = true

 init() {}

 @MainActor
 func perform() async throws -> some IntentResult {
  guard let url = URL(string: "your deeplink") else {
  throw PerformError.invalidURL
  }

  await EnvironmentValues().openURL(url)
  return .result()
 }
}

2. Add App Groups

For the Control Widget to open your app via deep links, you need to enable communication between the widget and the app. This is done using App Groups:

Enable App Groups in the Capabilities section for both the app and widget targets.

App Groups allow the widget, which operates in an isolated container, to share data with the app.

3. Configure Target Membership

To ensure the widget can interact with your app:

In the QScanWidgetControl.swift file, add the app target to Target Membership.

This step is crucial for proper deep link functionality.

Launching the Control Widget: 20 Minutes of Fun and Frustration

At first, everything seemed to work: the widget was added to the Lock Screen and launched the app. However, the deep link didn’t work when the app was closed. The app opened but displayed the home screen, as if the deep link wasn’t passed.

After some trial and error, I identified these challenges:

Deep Links and Control Widget Don’t Cooperate If the app is closed, the widget fails to correctly pass the deep link. This happens because the widget operates in an isolated container and can only trigger the app launch. The deep link data is lost during initialization.
Universal Links Are Not a Solution Universal Links seemed like the next logical step, as they are often recommended for Control Widgets. However, they had similar issues:
- If the app is in the background, Universal Links work as expected and open the correct screen.
- If the app is closed, only the home screen is displayed.

Besides, I wasn’t keen on using Universal Links, so I continued debugging to find a better approach.

My Solution (A Bit of Magic)

After hours of debugging, I realized the issue lay in the sequence of events:

The widget sends a request to open the deep link.
iOS launches the app first.
Only then does iOS pass the deep link data.

At this point, the app might not be fully initialized, causing the deep link request to fail.

But! I found a workaround (it’s not perfect, but it works). By adding a small delay before triggering the deep link, the app has time to initialize, ensuring the deep link request is processed correctly.


struct PerformAction: AppIntent {
 static let title: LocalizedStringResource = "displayName"
 static var openAppWhenRun = true

 init() {}

 @MainActor
 func perform() async throws -> some IntentResult {
  guard let url = URL(string: "your deeplink") else {
   throw PerformError.invalidURL
  }

  try await Task.sleep(nanoseconds: 1_000_000_000)

  await EnvironmentValues().openURL(url)
  return .result()
 }
}

Conclusion

This workaround solved the problem for me. If you have ideas for a more elegant solution, share them in the comments—we can brainstorm together!

P.S. You can download and test this feature on iOS here, in the ohmygoods.app.

How I upgraded project from NX to the latest version 0.72.3 of React Native

irinaivanovaalex — Sat, 26 Aug 2023 12:20:12 +0000

Updating react-native is often associated with significant challenges for developers, often consuming a considerable amount of working time and effort, especially when a project utilizes numerous libraries or possesses a non-standard structure.

In this article, I will share the experiences I encountered in a project using the NX monorepository and discuss what helped me overcome this issue.

Upgrading to the new version of React Native following the guide

Initial dependency versions:

"nx": "16.4.0",
"react-native": "0.71.10",

Having a monorepository, it was necessary to upgrade to the latest version of React Native. Upon upgrading to version 0.72.3 using the React Native Helper, the projects build successfully, but we encounter an error:

react-native could not be found within the project or in these directories:
  ../../node_modules
> 1 | import { AppRegistry } from 'react-native'

The issue is that Metro built the project somewhat incorrectly. The build process through Metro involves several stages:

Metro constructs a graph of all modules.
It transpiles modules into a format understandable by React Native.
Then, it serializes them, bundling the modules into one or more bundles. However, since the project uses NX, its structure differs from the basic one, resulting in distinct configuration files at various project levels. Let's take a look at the repository structure within NX:

monorepo-name/
├── apps/
│   └── mobile/
│     ├── app.json
│     ├── metro.config.js
│     ├── package.json
│     ├── project.json 
│   └── mobile-e2e/
├── libs/ 
│   └── shared-ui-layout/
│       ├── src/
│       │   └── index.ts
│       ├── .babelrc
│       ├── jest.config.js
│       ├── project.json
│       ├── README.md
│       ├── test-setup.ts
│       ├── tsconfig.json
│       ├── tsconfig.lib.json
│       └── tsconfig.spec.json
├── tools/
├── babel.config.json
├── jest.config.js
├── jest.preset.js
├── nx.json
├── package-lock.json
├── package.json
└── tsconfig.base.json

Configurations Adjustment

In this project structure, each application has its set of configuration files, such as metro.config.js, package.json, and others. However, besides these configurations, there are also files in the repository's root directory that need to be taken into account during the build process. NX itself provides the withNxMetro function, which allows merging NX configurations and user-defined ones into a single configuration. As a result, to achieve the necessary configuration in the metro.config.js file, we will make the following changes:

We will begin by merging the default and user-defined configurations using the mergeConfig function, following the guidelines of the React Native guide.
Then, we will pass the result of this merge to the withNxMetro function to combine it with the NX configuration.

const { withNxMetro } = require('@nx/react-native')
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const exclusionList = require('metro-config/src/defaults/exclusionList')

const defaultConfig = getDefaultConfig(__dirname)
const { assetExts, sourceExts } = defaultConfig.resolver

/**
 * Metro configuration
 * https://facebook.github.io/metro/docs/configuration
 *
 * @type {import('metro-config').MetroConfig}
 */
const customConfig = {
  transformer: {
    babelTransformerPath: require.resolve('react-native-svg-transformer'),
  },
  resolver: {
    assetExts: assetExts.filter(ext => ext !== 'svg'),
    sourceExts: [...sourceExts, 'svg'],
    blockList: exclusionList([/^(?!.*node_modules).*\/dist\/.*/]),
    unstable_enableSymlinks: true,
    unstable_enablePackageExports: true,
  },
}

module.exports = withNxMetro(mergeConfig(defaultConfig, customConfig), {
  // Change this to true to see debugging info.
  // Useful if you have issues resolving modules
  debug: false,
  // all the file extensions used for imports other than 'ts', 'tsx', 'js', 'jsx', 'json'
  extensions: [],
  // Specify folders to watch, in addition to Nx defaults (workspace libraries and node_modules)
  watchFolders: [],
})

After such an upgrade, the project's metro.config.js will launch, and we'll see the initial app screen that we've been longing to see again. 🎉

Final library versions:

"nx": "16.6.0",
"react-native": "0.72.3",

To sum up:

Follow the update guide at this link.
Upgrade library versions with NX.
Modify the metro.config.js file.

Conclusion

I trust that this article provided a solution for individuals who faced this issue or are still utilizing outdated versions of NX and React Native.

Translation of this article into Russian

Как я апгрейдила проект с NX на последнюю версию 0.72.3 React Native

irinaivanovaalex — Fri, 25 Aug 2023 11:05:55 +0000

Обновление react-native связано с большой болью у разработчиков, часто это занимает много рабочего времени и сил, особенно если проект использует большое количество библиотек или имеет нестандартную структуру.

В этой статье я расскажу с чем мне пришлось столкнуться в проекте c монорепозиторием NX и что мне помогло решить эту проблему.

Переход по гайду на новую версию React Native

Изначальные версии зависимостей:

"nx": "16.4.0",
"react-native": "0.71.10",

Имея монорепозиторий нужно было перейти на последний React Native. При переезде на 0.72.3 версию по React Native Helper проекты собираются, но в итоге мы получаем ошибку:

react-native could not be found within the project or in these directories:
  ../../node_modules
> 1 | import { AppRegistry } from 'react-native'

Проблема в том, что Metro собрал проект не совсем корректно, сборка через Metro проходит в несколько этапов:

Metro строит граф всех модулей,
транспилирует модуля в формат, понятный React Native
и сериализует их, объединяя модули для создания одного или нескольких bundle

Но так как проект использует NX, его структура отличается от базовой и мы имеем разные конфигурационные файлы на разных уровнях проекта.

Рассмотрим структуру репозитория на NX:

monorepo-name/
├── apps/             // список наших приложений
│   └── mobile/
│     ├── app.json
│     ├── metro.config.js
│     ├── package.json
│     ├── project.json 
│   └── mobile-e2e/
├── libs/            // общие библиотеки, которые мы можем подключать к приложениям
│   └── shared-ui-layout/
│       ├── src/
│       │   └── index.ts
│       ├── .babelrc
│       ├── jest.config.js
│       ├── project.json
│       ├── README.md
│       ├── test-setup.ts
│       ├── tsconfig.json
│       ├── tsconfig.lib.json
│       └── tsconfig.spec.json
├── tools/
├── babel.config.json
├── jest.config.js
├── jest.preset.js
├── nx.json
├── package-lock.json
├── package.json
└── tsconfig.base.json

Изменение конфига

В данной структуре проекта каждое приложение имеет свой набор конфигурационных файлов, таких как metro.config.js, package.json и другие. Однако помимо этих конфигов, существуют также файлы в корневой директории репозитория, которые также необходимо учесть в процессе сборки. У самого NX есть withNxMetro - эта функция, которая позволяет объединить конфиги NX и пользовательские в одну. В итоге, для достижения необходимого конфига в файле metro.config.js, мы внесем следующие изменения:

Начнем со слияния дефолтных и пользовательских конфигов с помощью функции mergeConfig, следуя рекомендациям из гайда React Native.
Затем, результат этого слияния передадим в функцию withNxMetro для объединения с конфигом NX.

const { withNxMetro } = require('@nx/react-native')
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
const exclusionList = require('metro-config/src/defaults/exclusionList')

const defaultConfig = getDefaultConfig(__dirname)
const { assetExts, sourceExts } = defaultConfig.resolver

/**
 * Metro configuration
 * https://facebook.github.io/metro/docs/configuration
 *
 * @type {import('metro-config').MetroConfig}
 */
const customConfig = {
  transformer: {
    babelTransformerPath: require.resolve('react-native-svg-transformer'),
  },
  resolver: {
    assetExts: assetExts.filter(ext => ext !== 'svg'),
    sourceExts: [...sourceExts, 'svg'],
    blockList: exclusionList([/^(?!.*node_modules).*\/dist\/.*/]),
    unstable_enableSymlinks: true,
    unstable_enablePackageExports: true,
  },
}

module.exports = withNxMetro(mergeConfig(defaultConfig, customConfig), {
  // Change this to true to see debugging info.
  // Useful if you have issues resolving modules
  debug: false,
  // all the file extensions used for imports other than 'ts', 'tsx', 'js', 'jsx', 'json'
  extensions: [],
  // Specify folders to watch, in addition to Nx defaults (workspace libraries and node_modules)
  watchFolders: [],
})

После такого апгрейда metro.config.js проект запуститься и мы увидим первый экран приложения, который мы так долго хотели увидеть снова. 🎉

Финальные весии библиотек:

"nx": "16.6.0",
"react-native": "0.72.3",

Подытожим:

Апдейтимся по гайду
Апгрейдим версии библиотек с NX
Меняем metro.config.js

Заключение

Надеюсь, что это статья помогла решить проблему тех, кто столкнулся с такой ошибкой или все еще сидит на старых версиях NX и React Native.