v5.0.0

[christocracy]

🚀 Migration Guide: Flat Config → Compound Config

Version: 5.0.0
Applies to: react-native-background-geolocation v5.0.0 and above

See the README in the 5.0.0-beta branch.

---

📢 Overview

Version 5 introduces a new Compound Config format that replaces the legacy “flat” config structure. This guide explains how to migrate, shows before/after examples, and highlights key differences for the React Native SDK.

---

⚙️ Compatibility

The legacy flat config style remains fully supported for backward compatibility.
You can continue using your existing flat configuration if you prefer, though new features may only appear in the compound structure.

Recommendation: New apps and major refactors should migrate to the compound config to stay aligned with the native SDKs and shared type system.

---

⏩ Why Compound Config?

• Clarity: Groups related settings together (geolocation, HTTP, logging, app lifecycle, etc).
• Extensibility: Easier to add new config domains without polluting the top-level.
• Consistency: Aligns with native SDKs and shared TypeScript types across platforms.
• Tooling: Better IntelliSense / autocomplete when using @transistorsoft/background-geolocation-types.

---

🏗️ Old vs. New Config Structure (React Native)

Before (Flat Config – JS/TS)

import BackgroundGeolocation from 'react-native-background-geolocation';

BackgroundGeolocation.ready({
  desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
  distanceFilter: 50,
  stopOnTerminate: false,
  startOnBoot: true,
  url: 'https://my.server.com/locations',
  headers: { Authorization: 'Bearer TOKEN' },
  logLevel: BackgroundGeolocation.LogLevel.Verbose,
  debug: true,
});

After (Compound Config)

import BackgroundGeolocation from 'react-native-background-geolocation';

BackgroundGeolocation.ready({
  geolocation: {
    desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
    distanceFilter: 50,
  },
  app: {
    stopOnTerminate: false,
    startOnBoot: true,
  },
  http: {
    url: 'https://my.server.com/locations',
    headers: { Authorization: 'Bearer TOKEN' },
  },
  logger: {
    logLevel: BackgroundGeolocation.LogLevel.Verbose,
    debug: true,
  },
});

---

🗺️ Mapping Table: Flat → Compound

Flat Key	Compound Group	Compound Property	Example
desiredAccuracy	geolocation	desiredAccuracy	geolocation: GeoConfig(desiredAccuracy: ...)
distanceFilter	geolocation	distanceFilter
stopOnTerminate	app	stopOnTerminate	app: AppConfig(stopOnTerminate: ...)
startOnBoot	app	startOnBoot
url	http	url	http: HttpConfig(url: ...)
headers	http	headers
logLevel	logger	logLevel	logger: LoggerConfig(logLevel: ...)
debug	logger	debug
...	...	...

See the full mapping table below for all properties.

---

🧑‍💻 Migration Steps

1. Update your dependency:
   Ensure you are using react-native-background-geolocation v5.0.0 or later.

2. Import as before:

   import BackgroundGeolocation from "react-native-background-geolocation";

3. Group related options:

   • Move geolocation-related keys into GeoConfig
   • Move HTTP-related keys into HttpConfig
   • Move logging/debug keys into LoggerConfig
   • Move app lifecycle keys into AppConfig
   • Move activity-recognition keys into ActivityConfig
   • Move persistence keys into PersistenceConfig

4. Replace flat keys:

   • Instead of passing all options to Config(...) directly, pass the relevant compound config objects.
   • Remove any duplicate or conflicting flat keys.

5. Check for breaking changes:

   • Some keys may have been renamed, moved, or refactored.
   • See Breaking Changes below.

---

📝 Example Migration

Flat Config (Old)

BackgroundGeolocation.ready({
  desiredAccuracy: BackgroundGeolocation.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10,
  stopOnTerminate: false,
  startOnBoot: true,
  url: "https://my.server.com/locations",
  headers: { "Authorization": "Bearer TOKEN" },
  logLevel: BackgroundGeolocation.LOG_LEVEL_DEBUG,
  debug: true,
  autoSync: true,
  batchSync: false,
});

Compound Config (New)

BackgroundGeolocation.ready({
  geolocation: {
    desiredAccuracy: BackgroundGeolocation.DesiredAccuracy.High,
    distanceFilter: 10,
  },
  app: {
    stopOnTerminate: false,
    startOnBoot: true,
  },
  http: {
    url: "https://my.server.com/locations",
    headers: { "Authorization": "Bearer TOKEN" },
    autoSync: true,
    batchSync: false,
  },
  logger: {
    logLevel: LogLevel.debug,
    debug: true,
  },
});

---

🧩 Compound Config Groups

Group	Class Name	Description
geolocation	GeoConfig	Location and geofencing options
app	AppConfig	App lifecycle and scheduling
http	HttpConfig	HTTP sync, batching, headers, etc.
logger	LoggerConfig	Debug, log-level, log retention
activity	ActivityConfig	Activity recognition, stop detection
persistence	PersistenceConfig	Data storage, max days, max records

Each group is a separate Typescript interface. See API docs for details.

---

🛠️ Full Mapping Table

Flat Key	Compound Group	Compound Property	Notes
desiredAccuracy	geolocation	desiredAccuracy
distanceFilter	geolocation	distanceFilter
stationaryRadius	geolocation	stationaryRadius
stopTimeout	geolocation	stopTimeout
stopAfterElapsedMinutes	geolocation	stopAfterElapsedMinutes
geofenceProximityRadius	geolocation	geofenceProximityRadius
geofenceInitialTriggerEntry	geolocation	geofenceInitialTriggerEntry
geofenceModeHighAccuracy	geolocation	geofenceModeHighAccuracy
pausesLocationUpdatesAutomatically	geolocation	pausesLocationUpdatesAutomatically
showsBackgroundLocationIndicator	geolocation	showsBackgroundLocationIndicator
activityType	geolocation	activityType	iOS only
locationAuthorizationAlert	geolocation	locationAuthorizationAlert	iOS only
maxMonitoredGeofences	geolocation	maxMonitoredGeofences
filter	geolocation	filter	Advanced filtering
stopOnTerminate	app	stopOnTerminate
startOnBoot	app	startOnBoot
enableHeadless	app	enableHeadless	Android only
heartbeatInterval	app	heartbeatInterval
schedule	app	schedule
scheduleUseAlarmManager	app	scheduleUseAlarmManager	Android only
notification	app	notification	Android only
backgroundPermissionRationale	app	backgroundPermissionRationale	Android only
preventSuspend	app	preventSuspend	iOS only
url	http	url
autoSync	http	autoSync
autoSyncThreshold	http	autoSyncThreshold
disableAutoSyncOnCellular	http	disableAutoSyncOnCellular
batchSync	http	batchSync
maxBatchSize	http	maxBatchSize
method	http	method
params	http	params
headers	http	headers
rootProperty/httpRootProperty	http	rootProperty
timeout/httpTimeout	http	timeout
debug	logger	debug
logLevel	logger	logLevel	Now an enum: LogLevel
logMaxDays	logger	logMaxDays
activityRecognitionInterval	activity	activityRecognitionInterval	Android only
minimumActivityRecognitionConfidence	activity	minimumActivityRecognitionConfidence	Android only
disableStopDetection	activity	disableStopDetection
stopOnStationary	activity	stopOnStationary
motionTriggerDelay	activity	motionTriggerDelay	Android only
triggerActivities	activity	triggerActivities	Android only
disableMotionActivityUpdates	activity	disableMotionActivityUpdates	iOS only
stopDetectionDelay	activity	stopDetectionDelay	iOS only
persistMode	persistence	persistMode
maxDaysToPersist	persistence	maxDaysToPersist
maxRecordsToPersist	persistence	maxRecordsToPersist
locationsOrderDirection	persistence	locationsOrderDirection

Not all legacy keys are shown above. See API docs for full details.

---

New License Key Format

A new license key format has been introduced for v5. Also, iOS now requires a license key. Generate your new license keys in the Customer Dashboard. See the usual Setup Guides for license setup instructions.

⚠️ Breaking Changes

• Some keys have new enum types:
  • logLevel is now a LogLevel enum (e.g., LogLevel.info), but legacy integer values are still supported for backward compatibility. You may use either the new enum or the legacy integer type.
• Some keys have moved to new groups:
  • E.g., debug is now in LoggerConfig.
• Legacy flat config remains supported but deprecated:
  • Using the legacy flat config will show warnings at runtime, but will not result in an error. Migration to the new grouped config is recommended for future compatibility.
• New license keys. Apps using v5 now require a new license key to be generated. iOS now requires a license.

---

🧪 Testing Your Migration

1. Run your app after migration.
2. Check for errors or warnings about missing or misplaced config keys.
3. Review logs to ensure config is applied as expected.
4. Consult the API docs for each config group if unsure.

---

🆘 Need Help?

• See the API Reference for each config class.
• Ask questions on GitHub Discussions or open an issue.

---

📚 Resources

• Full API Reference
• GitHub Project
• Changelog
• README

---

🎉 Happy Migrating!

If you have suggestions for improving this guide, please open a PR or issue.

[doneill]

Migration Steps

Ensure you are using flutter_background_geolocation v5.0.0 or later.

Typo? References to Dart?

[christocracy]

Thanks, fixed.

[christocracy]

I'll be publishing 5.0.0-beta.1 tomorrow.

[christocracy]

5.0.0-beta.1 is published. See the README at branch 5.0.0-beta

npm install react-native-background-geolocation@beta

[christocracy]

v5.0.0 has a new license key format. You can now generate v5.0.0 keys in the customer dashboard:

(both iOS and Android now require a key)

[christocracy]

Published 5.0.0-beta.2 with Turbo Module support and improved iOS Setup Instructions.

[christocracy]

Published v5.0.0-beta.3 with Expo fixes and updated Setup Instructions.

[PhilipGrefe]

FYI after upgrading to 5-beta I had a conflict of the react-native-background-fetch package when building for iOS simulator.

The error was:
The 'Pods-fmfappdev' target has frameworks with conflicting names: tsbackgroundfetch.xcframework.

After uninstalling react-native-background-fetch, the build worked (did not do further tests yet).

[christocracy]

You just to need to install the latest version of background-fetch

[PhilipGrefe]

I am on version 4.2.8 (latest) and it still doesn't work.
Let me know if you need further information.

[christocracy]

I must have forgotten to release 4.3.0.

Just remove it for now, until 4.3.0 is released.

[joegrabski]

I'm having some trouble migrating to 5.x.x. I'm on 5.0.0-beta.4 and I keep seeing this error:

ERROR TypeError: RNBackgroundGeolocation.log is not a function (it is undefined), js engine: hermes

I've tried cleaning my build and reinstalling dependencies but it keeps giving me this message. I get a similar message when trying to upload logs too.

For additional context, I'm accessing the logger like so: export const Logger: BackgroundGeolocationLogger = BackgroundGeolocation.logger;

and then trying to record logs with: Logger.debug(message)

[christocracy]

@joegrabski I'm looking into the Logger issue. It seems to have been neglected.

[joegrabski]

Just wondering how far away this might be?

[christocracy]

Oops, forgot about this. I'll have a look today.

[christocracy]

Fixed in 5.0.3, released now.

[jayeshpurohit12]

After upgrading to 5.0.3 from 4.19.3 I am unable to test in simulator when I try to simulate the location it does not move

[christocracy]

"Discussions" are not where tech support is handled.

Post an issue, provide logs.

[joegrabski]

Is this uploadLog function implemented in v5? It's not sending an API request for me in the latest version

[christocracy]

I'll investigate this.

[joegrabski]

Just wondering if there was any update here?

[christocracy]

Still in backlog.

[christocracy]

@joegrabski Post a new issue. I need more info.

[joegrabski]

This one seems to be an issue on our end, appreciate you taking a look though

[joegrabski]

Is auth handled the same in v5? For me the library is receiving a 2xx code from our refresh token endpoint, but then it's not using the returned token in subsequent requests.

[christocracy]

As far the tests are concerned, yes.

If you have a specific problem, post an issue.

[dougschurman]

I'm not seeing a clear mapping for "locationTemplate"

My api expects a certain JSON schema and I would send that by using the config

locationTemplate: '{"latitude":<%= latitude %>,"longitude":<%= longitude %>, "age": <%= age %>}',

Looks like the "params" property just appends additional params to the location request, but doesn't allow you to override where a location value gets set.

[christocracy]

Please post an issue.

[UnderTheMoonspell]

I think im having the same issue. LocationTemplate and GeofenceTemplate are being ignored. My team will need to run more tests, but it seems thats the case.

[christocracy]

I'm sure the templates are not broken.

Search the FAQ "locationTemplate".

https://docs.transistorsoft.com/help/faq/

[UnderTheMoonspell]

Im opening an issue with the details I found. Everything else seems to be working except this specific property

[UnderTheMoonspell]

Why is isShrinkResources required as false? We are currently using it and we don't like the idea of having to set it to false.

[christocracy]

Do you understand how shrinkResources works in a compiled Java / Kotlin app?

[UnderTheMoonspell]

Being originally a web developer and having migrated to a react native app, I can't say I fully do, but my understanding is that not having it has an impact in the bundle size.

Having said that, I still dont see why a library would force an app thats using it to having to set it to false.

[christocracy]

React Native’s value proposition — write JS once, run everywhere — comes with a cost: you’re now two layers away from the metal.
The Android tree-shaker works bottom-up, analyzing your compiled code for resource references. But your app logic flows top-down: JS → React Native bridge → native SDK. The resource references live inside the pre-compiled SDK, in a layer the tree-shaker simply can’t see. It finds zero references and prunes the resources. Runtime crash.
This is the fundamental tension of every cross-platform framework — Flutter, Cordova, Capacitor, all of them:

The higher the abstraction, the less the low-level tooling can see.

shrinkResources was designed for a world where one team owns the full stack in one visible codebase. Pre-compiled cross-platform SDKs break that assumption. Disabling it isn’t a workaround for a bug — it’s acknowledging that the tool wasn’t designed for this architecture.​​​​​​​​​​​​​​​​

This SDK does contain resources that would be stripped away because there's no reference detected using them.

[UnderTheMoonspell]

Thats a very clear explanation. Thanks 👍

[jdegger]

Hi @christocracy we want to thank you for your continued effort into improving bg geolocation 👍 Very much appreciated.