{"slug":"flutter-pre-caching","title":"flutter-pre-caching","summary":"Use when preloading fonts, asset/network images, Lottie/Rive animations, local JSON/config, warming initial API data, or optimizing Flutter Web startup.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-30T09:57:19.419728Z","repo":{"url":"https://github.com/evanca/flutter-ai-rules","stars":644,"forks":67,"license":"MIT","updatedAt":"2026-09-14T07:51:38Z"},"bodyHtml":"
\n

name: flutter-pre-caching\ndescription: \"Use when preloading fonts, asset/network images, Lottie/Rive animations, local JSON/config, warming initial API data, or optimizing Flutter Web startup.\"\nlicense: MIT

\n

Pre-caching in Flutter and Flutter Web

\n

Pre-caching helps avoid jank, loading flashes, font swaps, and delayed first renders.

\n

The key rule:

\n
\n

Pre-cache only what the user will likely see in the next 1 to 2 screens.

\n
\n

Do not pre-cache the whole app. That can slow startup and waste memory.

\n
\n

1. Google Fonts

\n

Runtime Google Fonts preloading

\n

Use GoogleFonts.pendingFonts() to load the font variants before showing text.

\n
import 'package:flutter/material.dart';\nimport 'package:google_fonts/google_fonts.dart';\n\nclass ExampleSimple extends StatefulWidget {\n  const ExampleSimple({super.key});\n\n  @override\n  State<ExampleSimple> createState() => _ExampleSimpleState();\n}\n\nclass _ExampleSimpleState extends State<ExampleSimple> {\n  late final Future<List<void>> googleFontsPending;\n\n  @override\n  void initState() {\n    super.initState();\n\n    googleFontsPending = GoogleFonts.pendingFonts([\n      GoogleFonts.poppins(),\n      GoogleFonts.montserrat(fontStyle: FontStyle.italic),\n    ]);\n  }\n\n  @override\n  Widget build(BuildContext context) {\n    final pushButtonTextStyle = GoogleFonts.poppins(\n      textStyle: Theme.of(context).textTheme.headlineMedium,\n    );\n\n    final counterTextStyle = GoogleFonts.montserrat(\n      fontStyle: FontStyle.italic,\n      textStyle: Theme.of(context).textTheme.displayLarge,\n    );\n\n    return FutureBuilder<List<void>>(\n      future: googleFontsPending,\n      builder: (context, snapshot) {\n        if (snapshot.connectionState != ConnectionState.done) {\n          return const SizedBox();\n        }\n\n        return Column(\n          mainAxisAlignment: MainAxisAlignment.center,\n          children: [\n            Text(\n              'You have pushed the button this many times:',\n              style: pushButtonTextStyle,\n            ),\n            Text(\n              '0',\n              style: counterTextStyle,\n            ),\n          ],\n        );\n      },\n    );\n  }\n}\n
\n

Production recommendation

\n

For production and offline support, prefer bundling critical fonts as assets.

\n
flutter:\n  fonts:\n    - family: AppFont\n      fonts:\n        - asset: assets/fonts/AppFont-Regular.ttf\n        - asset: assets/fonts/AppFont-Bold.ttf\n          weight: 700\n
\n

Use it in the app theme:

\n
MaterialApp(\n  theme: ThemeData(\n    fontFamily: 'AppFont',\n  ),\n)\n
\n
\n

2. Asset images

\n

Use precacheImage for images that appear soon.

\n
@override\nvoid didChangeDependencies() {\n  super.didChangeDependencies();\n\n  precacheImage(\n    const AssetImage('assets/images/header.png'),\n    context,\n  );\n}\n
\n

Then use the image normally:

\n
Image.asset('assets/images/header.png')\n
\n
\n

3. Network images

\n

Use precacheImage with NetworkImage.

\n
@override\nvoid didChangeDependencies() {\n  super.didChangeDependencies();\n\n  precacheImage(\n    const NetworkImage('https://example.com/image.png'),\n    context,\n  );\n}\n
\n

Then use it normally:

\n
Image.network('https://example.com/image.png')\n
\n

Important:\nprecacheImage warms Flutter’s in-memory image cache. It does not provide long-term offline caching.

\n

For disk caching, use a package like cached_network_image:

\n
dependencies:\n  cached_network_image: ^latest\n
\n

Example:

\n
CachedNetworkImage(\n  imageUrl: 'https://example.com/image.png',\n)\n
\n
\n

4. Multiple image preloading

\n
@override\nvoid didChangeDependencies() {\n  super.didChangeDependencies();\n\n  final images = <ImageProvider>[\n    const AssetImage('assets/images/header.png'),\n    const AssetImage('assets/images/avatar.png'),\n    const NetworkImage('https://example.com/banner.png'),\n  ];\n\n  for (final image in images) {\n    precacheImage(image, context);\n  }\n}\n
\n
\n

5. Waiting until images are ready

\n

precacheImage returns a Future<void>, so you can wait before rendering the real UI.

\n
late Future<void> _preloadImagesFuture;\n\n@override\nvoid didChangeDependencies() {\n  super.didChangeDependencies();\n\n  _preloadImagesFuture = Future.wait([\n    precacheImage(\n      const AssetImage('assets/images/header.png'),\n      context,\n    ),\n    precacheImage(\n      const NetworkImage('https://example.com/banner.png'),\n      context,\n    ),\n  ]);\n}\n\n@override\nWidget build(BuildContext context) {\n  return FutureBuilder<void>(\n    future: _preloadImagesFuture,\n    builder: (context, snapshot) {\n      if (snapshot.connectionState != ConnectionState.done) {\n        return const CircularProgressIndicator();\n      }\n\n      return Column(\n        children: [\n          Image.asset('assets/images/header.png'),\n          Image.network('https://example.com/banner.png'),\n        ],\n      );\n    },\n  );\n}\n
\n
\n

Note

\n

Use didChangeDependencies, not initState, when you need context for precacheImage.

\n
\n
\n

6. What should normally be pre-cached on app start?

\n

Good candidates:

\n\n

Bad candidates:

\n\n
\n

7. Practical app-start preloader

\n
class AppPreloader {\n  const AppPreloader();\n\n  Future<void> preload(BuildContext context) async {\n    await Future.wait([\n      _precacheImages(context),\n      _loadCriticalAssets(),\n      _warmUpInitialData(),\n    ]);\n  }\n\n  Future<void> _precacheImages(BuildContext context) {\n    return Future.wait([\n      precacheImage(\n        const AssetImage('assets/images/home_hero.png'),\n        context,\n      ),\n      precacheImage(\n        const AssetImage('assets/images/logo.png'),\n        context,\n      ),\n    ]);\n  }\n\n  Future<void> _loadCriticalAssets() async {\n    await rootBundle.loadString('assets/config/app_config.json');\n  }\n\n  Future<void> _warmUpInitialData() async {\n    // Example:\n    // await userRepository.getCurrentUser();\n  }\n}\n
\n

Usage:

\n
late Future<void> _preloadFuture;\n\n@override\nvoid didChangeDependencies() {\n  super.didChangeDependencies();\n\n  _preloadFuture = const AppPreloader().preload(context);\n}\n
\n

With FutureBuilder:

\n
@override\nWidget build(BuildContext context) {\n  return FutureBuilder<void>(\n    future: _preloadFuture,\n    builder: (context, snapshot) {\n      if (snapshot.connectionState != ConnectionState.done) {\n        return const SplashScreen();\n      }\n\n      return const HomeScreen();\n    },\n  );\n}\n
\n
\n

8. Local JSON / config preloading

\n

Useful for feature flags, local app config, mock data, translations, or onboarding content.

\n
import 'package:flutter/services.dart';\n\nfinal configJson = await rootBundle.loadString(\n  'assets/config/app_config.json',\n);\n
\n

Example:

\n
class AppConfigLoader {\n  Future<String> load() {\n    return rootBundle.loadString('assets/config/app_config.json');\n  }\n}\n
\n
\n

9. Initial API request warm-up

\n

This is not pre-caching in the Flutter image-cache sense, but it is often the most useful startup optimization.

\n
final userFuture = userRepository.getCurrentUser();\nfinal dashboardFuture = dashboardRepository.getDashboard();\n
\n

Example:

\n
class StartupData {\n  const StartupData({\n    required this.user,\n    required this.dashboard,\n  });\n\n  final User user;\n  final Dashboard dashboard;\n}\n\nFuture<StartupData> loadStartupData() async {\n  final results = await Future.wait([\n    userRepository.getCurrentUser(),\n    dashboardRepository.getDashboard(),\n  ]);\n\n  return StartupData(\n    user: results[0] as User,\n    dashboard: results[1] as Dashboard,\n  );\n}\n
\n
\n

10. Lottie preloading

\n

If the animation appears immediately, preload it.

\n
final composition = await AssetLottie(\n  'assets/animations/success.json',\n).load();\n
\n

Use this only for animations shown early. Avoid preloading many large animations on app start.

\n
\n

11. Rive preloading

\n

Rather than triggering the asset load during a build (which causes jank), preload the RiveFile byte data in advance:

\n
import 'package:flutter/services.dart';\nimport 'package:rive/rive.dart';\n\n// Preload the RiveFile\nfinal data = await rootBundle.load('assets/animations/character.riv');\nfinal riveFile = RiveFile.import(data);\n\n// Display using direct constructor to avoid initialization delays:\nRiveAnimation.direct(riveFile);\n
\n

This ensures that the animation renders immediately upon widget mount.

\n
\n

12. Shader warm-up

\n

Most apps do not need this. It can help if you have:

\n\n

Basic shape:

\n
class CustomShaderWarmUp extends ShaderWarmUp {\n  @override\n  void warmUpOnCanvas(Canvas canvas) {\n    final paint = Paint();\n\n    canvas.drawRect(\n      const Rect.fromLTWH(0, 0, 100, 100),\n      paint,\n    );\n  }\n}\n
\n

Then set it before runApp:

\n
void main() {\n  PaintingBinding.instance.shaderWarmUp = CustomShaderWarmUp();\n\n  runApp(const MyApp());\n}\n
\n

Use this only when profiling shows shader compilation jank.

\n
\n

13. Flutter Web: different mindset

\n

On Flutter Web, think less:

\n\n

Think more:

\n\n
\n

14. Flutter Web image preload

\n

For critical first-screen images, use both browser preload and Flutter precacheImage.

\n

In web/index.html:

\n
<link\n  rel=\"preload\"\n  href=\"assets/assets/images/home_hero.png\"\n  as=\"image\"\n>\n
\n

In Flutter:

\n
await precacheImage(\n  const AssetImage('assets/images/home_hero.png'),\n  context,\n);\n
\n

Why both?

\n\n
\n

15. Flutter Web network image preload

\n

In web/index.html:

\n
<link\n  rel=\"preload\"\n  href=\"https://example.com/banner.png\"\n  as=\"image\"\n>\n
\n

In Flutter:

\n
await precacheImage(\n  const NetworkImage('https://example.com/banner.png'),\n  context,\n);\n
\n

Only do this for images the user is almost guaranteed to see.

\n
\n

16. Flutter Web font preload

\n

Declare the font in pubspec.yaml:

\n
flutter:\n  fonts:\n    - family: AppFont\n      fonts:\n        - asset: assets/fonts/AppFont-Regular.ttf\n        - asset: assets/fonts/AppFont-Bold.ttf\n          weight: 700\n
\n

Preload the critical font in web/index.html:

\n
<link\n  rel=\"preload\"\n  href=\"assets/assets/fonts/AppFont-Regular.ttf\"\n  as=\"font\"\n  type=\"font/ttf\"\n  crossorigin\n>\n
\n

Use it in Flutter:

\n
ThemeData(\n  fontFamily: 'AppFont',\n)\n
\n

Usually preload:

\n\n

Avoid preloading every weight and italic variant unless the first screen needs them.

\n
\n

17. Flutter Web and emojis

\n

Emojis can trigger font fallback work.

\n

Example:

\n
Text('Welcome \uD83D\uDC4B \uD83C\uDF89')\n
\n

On web, this can cause:

\n\n
\n

18. Option 1: avoid emojis on first paint

\n

Simple and effective:

\n
Text('Welcome')\n
\n

Then show emojis after the app has loaded:

\n
Text('Welcome \uD83D\uDC4B')\n
\n

This is often the best option if emojis are decorative.

\n
\n

19. Option 2: bundle and preload an emoji font

\n

Add the font to pubspec.yaml:

\n
flutter:\n  fonts:\n    - family: NotoColorEmoji\n      fonts:\n        - asset: assets/fonts/NotoColorEmoji.ttf\n
\n

Preload it in web/index.html:

\n
<link\n  rel=\"preload\"\n  href=\"assets/assets/fonts/NotoColorEmoji.ttf\"\n  as=\"font\"\n  type=\"font/ttf\"\n  crossorigin\n>\n
\n

Use it where needed:

\n
const Text(\n  '\uD83D\uDC4B \uD83C\uDF89 ❤️',\n  style: TextStyle(\n    fontFamily: 'NotoColorEmoji',\n  ),\n)\n
\n

Important:

\n\n
\n

20. When emoji preloading makes sense

\n

Good cases:

\n\n

Bad cases:

\n\n

Rule:

\n\n
\n

21. Flutter Web renderer files

\n

Flutter Web startup can also include renderer assets, for example CanvasKit or Skwasm files.

\n

Usually, you do not preload these from Dart. You configure the renderer through Flutter Web initialization.

\n

Example in web bootstrap:

\n
_flutter.loader.load({\n  config: {\n    renderer: 'canvaskit',\n  },\n});\n
\n

Other configs can include things like:

\n
_flutter.loader.load({\n  config: {\n    renderer: 'canvaskit',\n    canvasKitBaseUrl: '/canvaskit/',\n  },\n});\n
\n

Most apps should let Flutter manage this unless there is a clear hosting or performance reason to change it.

\n
\n

22. Practical Flutter Web startup list

\n

Usually preload:

\n\n

Usually avoid:

\n\n
\n

23. Suggested folder structure

\n
assets/\n  images/\n    logo.png\n    home_hero.png\n    onboarding_hero.png\n\n  fonts/\n    AppFont-Regular.ttf\n    AppFont-Bold.ttf\n    NotoColorEmoji.ttf\n\n  config/\n    app_config.json\n\n  animations/\n    success.json\n    character.riv\n
\n
\n

24. Example pubspec.yaml

\n
flutter:\n  assets:\n    - assets/images/\n    - assets/config/\n    - assets/animations/\n\n  fonts:\n    - family: AppFont\n      fonts:\n        - asset: assets/fonts/AppFont-Regular.ttf\n        - asset: assets/fonts/AppFont-Bold.ttf\n          weight: 700\n\n    - family: NotoColorEmoji\n      fonts:\n        - asset: assets/fonts/NotoColorEmoji.ttf\n
\n
\n

25. Example web/index.html preload block

\n
<!-- App fonts -->\n<link\n  rel=\"preload\"\n  href=\"assets/assets/fonts/AppFont-Regular.ttf\"\n  as=\"font\"\n  type=\"font/ttf\"\n  crossorigin\n>\n\n<link\n  rel=\"preload\"\n  href=\"assets/assets/fonts/AppFont-Bold.ttf\"\n  as=\"font\"\n  type=\"font/ttf\"\n  crossorigin\n>\n\n<!-- Only if emojis are critical to first paint -->\n<link\n  rel=\"preload\"\n  href=\"assets/assets/fonts/NotoColorEmoji.ttf\"\n  as=\"font\"\n  type=\"font/ttf\"\n  crossorigin\n>\n\n<!-- Critical images -->\n<link\n  rel=\"preload\"\n  href=\"assets/assets/images/logo.png\"\n  as=\"image\"\n>\n\n<link\n  rel=\"preload\"\n  href=\"assets/assets/images/home_hero.png\"\n  as=\"image\"\n>\n
\n
\n

Note

\n

Flutter web asset URLs often include assets/assets/... because Flutter serves declared assets under the assets/ path, while your asset path also starts with assets/.

\n

For example:

\n\n
\n
\n

26. Complete startup example

\n
import 'package:flutter/material.dart';\nimport 'package:flutter/services.dart';\nimport 'package:google_fonts/google_fonts.dart';\n\nclass AppStartupPreloader {\n  const AppStartupPreloader();\n\n  Future<void> preload(BuildContext context) async {\n    await Future.wait([\n      _preloadFonts(),\n      _preloadImages(context),\n      _preloadLocalConfig(),\n      _preloadStartupData(),\n    ]);\n  }\n\n  Future<void> _preloadFonts() {\n    return GoogleFonts.pendingFonts([\n      GoogleFonts.inter(),\n      GoogleFonts.inter(fontWeight: FontWeight.w700),\n    ]);\n  }\n\n  Future<void> _preloadImages(BuildContext context) {\n    return Future.wait([\n      precacheImage(\n        const AssetImage('assets/images/logo.png'),\n        context,\n      ),\n      precacheImage(\n        const AssetImage('assets/images/home_hero.png'),\n        context,\n      ),\n    ]);\n  }\n\n  Future<void> _preloadLocalConfig() async {\n    await rootBundle.loadString('assets/config/app_config.json');\n  }\n\n  Future<void> _preloadStartupData() async {\n    // Start your critical first API calls here.\n    //\n    // Example:\n    // await userRepository.getCurrentUser();\n    // await dashboardRepository.getDashboard();\n  }\n}\n
\n

Usage:

\n
class StartupGate extends StatefulWidget {\n  const StartupGate({super.key});\n\n  @override\n  State<StartupGate> createState() => _StartupGateState();\n}\n\nclass _StartupGateState extends State<StartupGate> {\n  Future<void>? _startupFuture;\n\n  @override\n  void didChangeDependencies() {\n    super.didChangeDependencies();\n\n    _startupFuture ??= const AppStartupPreloader().preload(context);\n  }\n\n  @override\n  Widget build(BuildContext context) {\n    return FutureBuilder<void>(\n      future: _startupFuture,\n      builder: (context, snapshot) {\n        if (snapshot.connectionState != ConnectionState.done) {\n          return const SplashScreen();\n        }\n\n        return const HomeScreen();\n      },\n    );\n  }\n}\n
\n
\n

27. Final rule of thumb

\n

Pre-cache this:

\n\n

Do not pre-cache this:

\n\n

For Flutter Web specifically:

\n\n
\n

References

\n\n","files":[{"path":"SKILL.md","sizeBytes":18956,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-30T09:58:34.76064Z","sha256":"5D6CC9D8354D984610960FE05FD557C3833053A8C8535E4A5E44B0D22150CBDC","sizeBytes":5573},"review":null,"source":{"repositoryUrl":"https://github.com/evanca/flutter-ai-rules","path":"skills/flutter-pre-caching","license":"MIT","commit":"7b9cce235714ae17acbae896b1e8c8627e128f4c","subtreeSha":"50784CFC3A332B84C8D67A6997C48EBA23EA53A69DFB3B145A73894E6B34771F","lastSyncedAt":"2026-09-29T23:32:26.661053Z"},"reviewedAt":"2026-08-30T10:14:43.425931Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/evanca/flutter-ai-rules/tree/main/skills/flutter-pre-caching"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install evanca-flutter-ai-rules@llmmart"},{"target":"git","command":"git clone https://github.com/evanca/flutter-ai-rules.git"}]}