Dev Solve

English

中文
日本語

English

中文
日本語

Appearance

Related Posts

Flutter 'File.create' Method Argument Mismatch Error

Xcode PhaseScriptExecution Error Fix

Flutter FirebaseError: 'FirebaseAppPlatform.verifyExtends' Member Not Found

Resolve Flutter Doctor Dart Path Warning on macOS

Missing `libarclite_iphoneos.a` in Xcode 14.3

Flutter Web App serviceWorkerVersion Deprecation Resolution ​

Problem Statement ​

When building or serving Flutter web apps with versions 3.22+, you may encounter this warning in your console:

Warning: In index.html:60: Local variable for "serviceWorkerVersion" is deprecated. Use "{{flutter_service_worker_version}}" template token instead.

This occurs because Flutter has deprecated manual management of service worker versions. In legacy Flutter web projects, the index.html file contained JavaScript that explicitly managed service worker versions through a serviceWorkerVersion variable. Modern Flutter builds require using the {{flutter_service_worker_version}} template token instead, which gets replaced automatically during the build process.

🔧 Minimal Code Change ​

For existing projects where you want to preserve your customizations in index.html, replace the deprecated variable assignment with the official template token:

html
// Old implementation (deprecated)
var serviceWorkerVersion = null;

// New implementation (recommended)
var serviceWorkerVersion = '{{flutter_service_worker_version}}';

This simple change:

  1. Maintains your existing serviceworker initialization logic
  2. Allows Flutter to inject the correct version during build
  3. Eliminates the deprecation warning
  4. Preserves any custom HTML/CSS in your index.html

⚡ Modern Flutter Initialization (For New Projects) ​

Flutter 3.22+ introduced a simpler initialization approach using flutter_bootstrap.js. For new projects or if you can update your infrastructure, use this streamlined implementation:

html
<!DOCTYPE html>
<html lang="en">
<head>
  <base href="$FLUTTER_BASE_HREF">
  <meta charset="UTF-8">
  <title>Your App Title</title>
  <link rel="manifest" href="manifest.json">
</head>

<body>
  <script src="flutter_bootstrap.js" async></script>
</body>
</html>

This modern approach:

  • Automatically handles service worker management
  • Simplifies your HTML structure
  • Uses Flutter's built-in initialization sequence
  • Requires updating to Flutter 3.22+

Regenerate your web files with:

bash
flutter create --platforms web .

🔄 Project Regeneration Options ​

If you're comfortable replacing your entire web folder:

  1. Complete refresh (safest for stock projects):

    bash
    rm -rf web
flutter create --platforms web .

  2. Partial refresh (preserves assets/manifest):

    bash
    mv web/assets .
mv web/manifest.json .
rm -rf web
flutter create --platforms web .
mv assets web/
mv manifest.json web/

⚠️ Important Considerations

  • Back up your web folder before regeneration
  • If you have custom files (icons, CSS, scripts), move them to web/assets
  • Check the manifest.json after regeneration to merge any customizations

🚫 Outdated Approaches to Avoid ​

  • Don't manually edit flutter_bootstrap.js - it's auto-generated
  • Don't mix old service worker logic with new initialization methods
  • Don't omit the template quotes: '{{...}}' is required

Implementation Example ​

Here's a complete modern index.html with loading indicator and service worker template:

html
<!DOCTYPE html>
<html lang="en">
<head>
  <base href="$FLUTTER_BASE_HREF">
  <meta charset="UTF-8">
  <title>My Flutter App</title>
  
  <style>
    #loading-indicator {
      position: absolute;
      top: 50%;
      left: 50%;
      border: 2px solid #f3f3f3;
      border-radius: 50%;
      width: 20px;
      height: 20px;
      animation: spin 1s linear infinite;
    }
    @keyframes spin {
      0% { transform: rotate(0deg); }
      100% { transform: rotate(360deg); }
    }
  </style>
</head>

<body>
  <div id="loading-indicator"></div>
  
  <script>
    var serviceWorkerVersion = '{{flutter_service_worker_version}}';
    
    window.addEventListener('load', function() {
      // Service worker initialization logic here
      // ...

      // Remove loading indicator after initialization
      document.getElementById('loading-indicator').remove();
    });
  </script>
</body>
</html>

Key Takeaway ​

Flutter manages service worker versions automatically when you use either:

  1. The template token {{flutter_service_worker_version}} in your existing JS logic
  2. The modern flutter_bootstrap.js initialization approach

Choose the first method for quick compatibility fixes in existing projects, or migrate to the modern approach for new implementations and full framework compatibility. Both solutions will eliminate the deprecation warning while ensuring proper service worker functionality.