flutter_map_cache 1.4.0

A slim yet powerful caching plugin for flutter_map tile layers.

flutter_map_cache

A slim yet powerful caching plugin for flutter_map tile layers.

Many tile providers require users in their tile usage policy to cache tile requests. This lowers the load on those servers and provides a better experience to users.

Features

The package uses dio with the dio_cache_interceptor package and supports the storage backend that you like.

Supported storage backends are:

Storage backend	Description
In-Memory	- For testing purposes - flutter_map has memory caching itself
File System	- Easy to setup, no additional storage backend package required - potentially slower than using a database
Drift	- SQLite database - good platform support
Hive	- key-value database - easy to integrate
ObjectBox	- NoSQL, ACID compliant - Fast library - More complex integration
Isar	- NoSQL, ACID compliant - Fast library - More complex integration

Other storage backends will be supported as soon as the underlying package dio_cache_interceptor supports them.

Getting started

1. Add the packages you want to use to your pubspec.yaml file. Only add the packages for the backend you want to use.

dependencies:
  flutter_map: ^6.0.0 # in case you don't have it yet 
  flutter_map_cache: ^1.3.0 # this package
  path_provider: ^2.1.2 # in case the storage backend requires a path

  # drift
  dio_cache_interceptor_db_store: ^5.1.0
  sqlite3_flutter_libs: ^0.5.15

  # file system
  dio_cache_interceptor_file_store: ^1.2.2

  # hive
  dio_cache_interceptor_hive_store: ^3.2.1

  # objectbox
  dio_cache_interceptor_objectbox_store: ^1.1.3
  objectbox_flutter_libs: ^1.4.1

  # isar
  isar: ^3.1.0+1
  isar_flutter_libs: ^3.1.0+1

2. ⚠️ Some storage backends have their own required setups. Please check them out in their package documentations.

Usage

Using the cache is easy. Here is an example how to use the Hive backend:

1. First get the cache directory of the app (i.e. with the path_provider package).

import 'package:path_provider/path_provider.dart';

Future<String> getPath() async {
  final cacheDirectory = await getTemporaryDirectory();
  return cacheDirectory.path;
}

2. Then use the directory path to initialize the HiveCacheStore. You can wrap FlutterMap inside a FutureBuilder to use the getPath() method.

@override
Widget build(BuildContext context) {
  return FlutterMap(
    options: MapOptions(),
    children: [
      TileLayer(
        urlTemplate: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
        tileProvider: CachedTileProvider(
          // maxStale keeps the tile cached for the given Duration and 
          // tries to revalidate the next time it gets requested
          maxStale: const Duration(days: 30),
          store: HiveCacheStore(
            path,
            hiveBoxName: 'HiveCacheStore',
          ),
        ),
      ),
    ],
  );
}

You can find additional example usages for other storage backends here:

• In Memory (for testing)
• File System

...or check out the example app on GitHub for a full example implementation of most storage backends.

Common use cases & frequent questions

How about web?

Click here to expand.

This package supports the web as long as you use a storage backend that supports web.

• In Memory works out of the box
• Hive uses for its web support IndexedDB under the hood to support web.
• Drift (SqLite) requires additional setup steps for web

---

Does this package support cancellation of tile requests?

Click here to expand.

Yes. This package includes the tile cancellation that would otherwise be provided by flutter_map_cancellable_tile_provider out of the box.

---

Remove the api key from the url before it gets used for caching

Click here to expand.

Commercial tile providers often use an api key that is attached as a parameter to the url. While this shouldn't be a problem when the api key stays the same you might want to make it immune to api key changes anyway.

final _uuid = Uuid();

CachedTileProvider(
  keyBuilder: (request) {
    return _uuid.v5(
      Uuid.NAMESPACE_URL,
      request.uri.replace(queryParameters: {}).toString(),
    );
  },
),

---

How about pre-downloading, bulk-downloading or offline map?

Click here to expand.

This package does not provide support to download tiles automatically. Only tiles that were previously visited with an active internet connection show up on the map.

If you need bulk-downloading functionality you can check out the package flutter_map_tile_caching (Paid license is needed or your project has to be open sourced under the GPL-3.0 license).

Please note that free tile providers such as OpenStreetMap forbids bulk downloading (more than 250 tiles on a higher zoom level) of tiles in their tile usage policy. If you use a paid tile provider, bulk-downloading can cause high costs if you pay per tile request. Using a proper offline map solution (e.g. MBTiles) would be my recommendation here.

---

What if I want to use sqflite?

Click here to expand.

Because dio_cache_interceptor already supports Drift as a SQLite solution it's unlikely that sqflite will be supported any day soon.

If you still are required to use only sqflite, I recommend to create your own tile provider by using the cached_network_image package.

---

Additional information

Pull requests are welcome. If you want to add support for another storage backend you can check out dio_cache_interceptor.

If you need help you can open an issue or join the flutter_map discord server.