DEV Community: Codexlancers

The Complete Guide to Firebase Security Rules: Why They Matter and how to Write Them

Codexlancers — Mon, 29 Jun 2026 05:30:00 +0000

When building modern web and mobile applications, backend security is often the most stressful piece of the puzzle. Traditional architectures require you to spin up a custom server, write middleware, and handle authentication routing just to protect a single database row.

Firebase flips this model on its head. By allowing client applications to talk directly to backend services like Firestore and Cloud Storage, it drastically speeds up development. But this architectural shift introduces a critical question: If the client can touch the database directly, what stops a user from modifying someone else's data?

The answer is Firebase Security Rules. Let's break down what they are, why they are non-negotiable for production apps, and exactly how to implement them across different Firebase services.

What is Firebase Security, and Why Is It Crucial?

Firebase Security Rules are server-side access control configurations that sit directly between your client app and your cloud data. They act as an invisible, structural shield. Every single incoming read or write request is intercepted by Firebase and evaluated against these rules. If the request doesn't meet your criteria, Firebase rejects it entirely.

Why You Can't Ignore Them

The Client is Insecure: No matter how secure your Flutter, React, or native mobile code feels, an advanced user can decompile your app package, extract your Firebase configuration keys, and make direct calls to your endpoints via tools like Postman or custom scripts.
Data Integrity: Security rules do more than just check user identity - they validate schemas. They ensure strings aren't passed into number fields, field lengths don't exceed limits, and mandatory fields aren't missing.
Billing Protection: Leaving your database wide open allows malicious actors or rogue bots to scrape your data continuously, executing millions of reads that can instantly maximize your billing tier.

Which Firebase Services Use Security Rules?

Firebase applies individual security rule structures across three core backend services:

Cloud Firestore: Flexible, scalable NoSQL cloud database.
Realtime Database: Original, low-latency document-store database.
Cloud Storage: Built for storing and serving user-generated content like images, audio, and videos.

Let's look at two practical, real-world examples for each service to see how these rules look in action.

1. Cloud Firestore Examples

Firestore rules leverage granular path matching and custom conditions to control access down to specific document fields.

Example A: User-Owned Data Only (CRUD Isolation)

In a social or note-taking application, a user should only be able to view, edit, or delete notes that they created. This rule matches the user's logged-in unique ID (request.auth.uid) against the document's path variable.

service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId}/notes/{noteId} {
      // Allow access only if the authenticated user matches the path ID
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

Example B: Strict Content and Type Validation

If you run an e-commerce platform or inventory app, any authenticated user can browse products, but only incoming data that passes formatting checks can be added to the catalog.

service cloud.firestore {
  match /databases/{database}/documents {
    match /products/{productId} {
      // Anyone can read product details
      allow read: if true;

      // Enforce data integrity during creation
      allow create: if request.auth != null 
        && request.resource.data.price is int 
        && request.resource.data.price > 0
        && request.resource.data.title.size() <= 50;
    }
  }
}

request.resource.data: Points to the map data of the document as it will look if the write succeeds.

2. Realtime Database Examples

Realtime Database rules use a unique, hierarchical JSON structure rather than matching specific service paths.

Example A: Chat Room - Read Allowed, Write Restrained

In a global chat application, any user who is logged in should be able to read the history of a chat room, but they can only post messages that carry their own UID.

{
  "rules": {
    "public_chats": {
      "$roomId": {
        ".read": "auth != null",
        "messages": {
          "$messageId": {
            ".write": "auth != null && newData.child('senderId').val() === auth.uid"
          }
        }
      }
    }
  }
}

Example B: Preventing Data Overwrites (Immutable Records)

For critical logging data, financial audits, or transaction histories, you want users to be able to submit a log once, but prevent anyone from editing or deleting it later.

{
  "rules": {
    "transaction_logs": {
      "$logId": {
        ".read": "auth != null",
        // Allow creation only if data doesn't exist yet; prevent modifications
        ".write": "auth != null && !data.exists() && newData.exists()"
      }
    }
  }
}

3. Cloud Storage Examples

Firestore security parameters do not automatically safeguard your file assets. Cloud Storage handles rules separately to regulate asset uploads and size caps.

Example A: Restricting Upload File Sizes and MIME Types

To keep your storage costs under control and prevent bad actors from executing Denial of Service (DoS) attacks via massive files, you can restrict uploads to specific image file formats under 5MB.

service firebase.storage {
  match /b/{bucket}/o {
    match /profile_pictures/{userId}/{allPaths=**} {
      // Profiles are publicly readable
      allow read: if true;

      // Uploads must belong to the user, be an image, and be under 5MB
      allow write: if request.auth != null && request.auth.uid == userId
                   && request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

Example B: Private Business Document Multi-User Access

Imagine an app where multiple users belong to an organization account. They need access to a shared bucket of secure PDFs, while outside users are completely blocked.

service firebase.storage {
  match /b/{bucket}/o {
    match /organizations/{orgId}/documents/{docId} {
      // Allow access if the user's custom auth token contains the matching organization ID
      allow read, write: if request.auth != null 
                         && request.auth.token.organizationId == orgId;
    }
  }
}

Best Practices for Writing Firebase Security Rules

As your application grows, security rules can quickly become difficult to manage. Following a few best practices can help keep your Firebase project secure and maintainable.

Start With Deny-By-Default

Instead of allowing broad access and restricting it later, begin with restrictive rules and explicitly grant permissions where needed. This reduces the risk of accidentally exposing sensitive data.

Never Trust Client-Side Validation

Validating forms in your app improves user experience, but it does not provide security. Attackers can bypass your UI entirely and send requests directly to Firebase. Always enforce critical validations in your security rules.

Follow the Principle of Least Privilege

Users should only have access to the data and operations they absolutely need. Avoid granting collection-wide write access when document-level access is sufficient.

Use Custom Claims for Roles

For applications with administrators, moderators, or organization-based permissions, use Firebase Authentication custom claims instead of storing roles directly in client-accessible documents.

Test Rules Before Deployment

Firebase provides the Emulator Suite to test security rules locally. Verify both successful and failed requests to ensure your rules behave exactly as expected.

Keep Rules Under Version Control

Treat security rules like application code. Review changes carefully, track them in Git, and include them in your deployment process.

Conclusion

Writing Firebase Security Rules can feel like extra overhead when you are trying to ship features quickly, but they are the literal foundation of your app's security model. Treat your security rules with the same respect as your frontend architecture - write them early, test them using the local Firebase Emulator Suite, and track them under version control.

Flutter Animations for Beginners: What You Can Build Without Plugins

Codexlancers — Fri, 26 Jun 2026 10:30:00 +0000

Animations are often where apps start to feel alive instead of just functional.
And if you're just getting started with Flutter, it's easy to assume:
"I'll need a bunch of animation libraries to make things look good."

We used to think the same.
But in reality, Flutter already gives you a powerful set of built-in animation tools - no plugins required.

In this blog, we'll walk through real UI animations we've built in production apps, using only Flutter's default capabilities.

Why Avoid Plugins (At First)?

From our experience:

Plugins increase dependency risk
Updates can break things unexpectedly
Debugging becomes harder

Flutter's built-in animations are:

Lightweight
Performant
Fully customizable

And honestly more than enough for most use cases.

Animations You Can Build Without Plugins

1. Button Click Animation (Scale Effect)

On tap, the button slightly scales down and then smoothly returns to its original size.

It's a subtle effect, but it plays a big role - without feedback like this, users can feel unsure if their action was registered. This small touch makes the UI feel responsive and polished.

Where to use?

Buttons
Cards
Any tappable UI

import 'package:flutter/material.dart';

class AnimatedButton extends StatefulWidget {
  @override
  _AnimatedButtonState createState() => _AnimatedButtonState();
}

class _AnimatedButtonState extends State<AnimatedButton> {
  double _scale = 1.0;

  void _onTapDown(_) => setState(() => _scale = 0.95);
  void _onTapUp(_) => setState(() => _scale = 1.0);

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTapDown: _onTapDown,
      onTapUp: _onTapUp,
      child: AnimatedScale(
        scale: _scale,
        duration: Duration(milliseconds: 150),
        child: Container(
          padding: EdgeInsets.all(16),
          color: Colors.blue,
          child: Text("Tap Me", style: TextStyle(color: Colors.white)),
        ),
      ),
    );
  }
}

2. Expand / Collapse Cards

When tapped, the container smoothly expands or collapses to reveal or hide content.

Rather than content appearing abruptly, this creates a more natural flow, making the UI easier to read and noticeably more polished.

Where to use?

FAQs
Settings
Dashboards

class ExpandableCard extends StatefulWidget {
  @override
  _ExpandableCardState createState() => _ExpandableCardState();
}

class _ExpandableCardState extends State<ExpandableCard> {
  bool isExpanded = false;

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () => setState(() => isExpanded = !isExpanded),
      child: AnimatedContainer(
        duration: Duration(milliseconds: 300),
        padding: EdgeInsets.all(16),
        height: isExpanded ? 150 : 70,
        color: Colors.grey[200],
        child: Column(
          children: [
            Text("Tap to Expand"),
            if (isExpanded) Text("More content here...")
          ],
        ),
      ),
    );
  }
}

3. Image Zoom (Hero Animation)

The image smoothly moves from one screen to another, as if it's the same element transitioning between pages.

This creates a seamless experience and makes the app feel more polished.

Where to use?

Profile pictures
Product previews
Galleries

Hero(
  tag: "imageHero",
  child: Image.network("https://via.placeholder.com/150"),
)

Next screen:

Hero(
  tag: "imageHero",
  child: Image.network("https://via.placeholder.com/600"),
)

4. Fade-In Screens

Instead of instantly appearing, the screen fades in smoothly.

This removes the harshness of sudden transitions and creates a more pleasant, polished user experience.

Where to use?

Onboarding
Splash to home
First load screens

class FadeScreen extends StatefulWidget {
  @override
  _FadeScreenState createState() => _FadeScreenState();
}

class _FadeScreenState extends State<FadeScreen> {
  double opacity = 0;

  @override
  void initState() {
    super.initState();
    Future.delayed(Duration(milliseconds: 200), () {
      setState(() => opacity = 1);
    });
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedOpacity(
      duration: Duration(milliseconds: 500),
      opacity: opacity,
      child: Scaffold(
        body: Center(child: Text("Welcome")),
      ),
    );
  }
}

5. Smooth List Insert / Remove

When items are added or removed, they animate smoothly instead of just appearing or disappearing.

This makes the changes feel more natural and easier to follow.

Where to use?

Chat apps
Todo lists
Notifications

AnimatedList(
  initialItemCount: items.length,
  itemBuilder: (context, index, animation) {
    return SizeTransition(
      sizeFactor: animation,
      child: ListTile(
        title: Text(items[index]),
      ),
    );
  },
)

6. Page Transitions (Custom Navigation)

This controls how screens transition when navigating between them.

While default transitions work fine, custom ones can make the experience feel smoother and more intentional.

Where to use?

Screen navigation
Onboarding flows

Navigator.push(
  context,
  PageRouteBuilder(
    pageBuilder: (_, __, ___) => NextScreen(),
    transitionsBuilder: (_, animation, __, child) {
      return FadeTransition(
        opacity: animation,
        child: child,
      );
    },
  ),
);

7. Toggle UI Animations

The switch smoothly slides and updates its color when toggled.

This clear visual feedback helps users instantly understand the current state, making interactions feel more intuitive.

Where to use?

Settings
Filters
Feature toggles

class ToggleAnimation extends StatefulWidget {
  @override
  _ToggleAnimationState createState() => _ToggleAnimationState();
}

class _ToggleAnimationState extends State<ToggleAnimation> {
  bool isOn = false;

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () => setState(() => isOn = !isOn),
      child: AnimatedContainer(
        duration: Duration(milliseconds: 300),
        width: 60,
        height: 30,
        decoration: BoxDecoration(
          color: isOn ? Colors.green : Colors.grey,
          borderRadius: BorderRadius.circular(20),
        ),
        alignment: isOn ? Alignment.centerRight : Alignment.centerLeft,
        child: Padding(
          padding: EdgeInsets.all(4),
          child: CircleAvatar(radius: 10),
        ),
      ),
    );
  }
}

8. Tween Animation (Advanced Control)

This approach lets you animate values such as size, position, or opacity from one state to another.

It offers much finer control, making it ideal for cases where built-in animation widgets don't quite meet your needs.

Where to use?

Custom animations
Complex UI interactions

class TweenExample extends StatefulWidget {
  @override
  _TweenExampleState createState() => _TweenExampleState();
}

class _TweenExampleState extends State<TweenExample>
    with SingleTickerProviderStateMixin {
  late AnimationController controller;
  late Animation<double> animation;

  @override
  void initState() {
    super.initState();

    controller = AnimationController(
      duration: Duration(seconds: 1),
      vsync: this,
    );

    animation = Tween<double>(begin: 0, end: 200).animate(controller);

    controller.forward();
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: animation,
      builder: (_, child) {
        return Container(
          width: animation.value,
          height: 50,
          color: Colors.blue,
        );
      },
    );
  }

  @override
  void dispose() {
    controller.dispose();
    super.dispose();
  }
}

Common Mistakes Beginners Make

Overusing animations

Just because you can animate something doesn't mean you should.

If everything is moving, nothing really stands out - and the UI starts to feel noisy instead of smooth.

Making animations too slow

Long animations often feel frustrating instead of smooth.

In most cases, anything above ~500ms starts to feel laggy and hurts the experience.

No consistency in motion

If every screen uses a different animation style, the app starts to feel disconnected.

Consistency in motion is just as important as consistency in colors or fonts.

Ignoring performance

Animations can get expensive if not handled carefully.

Avoid rebuilding heavy widgets unnecessarily while animations are running - it can quickly impact performance.

Final Thoughts

If you're just starting with Flutter animations, don't jump to plugins.

Start with:

AnimatedContainer
AnimatedOpacity
Hero
AnimatedList
Tween + AnimationController

These alone can help you build smooth, production-level UI.

From our experience, mastering these basics gives you:

Better control
Cleaner code
More confidence

And honestly most apps don't need more than this.

Zero to Hero: Setup Flutter on Windows & macOS (The Quick Guide)

Codexlancers — Thu, 25 Jun 2026 05:00:00 +0000

Are you ready to build beautiful, cross-platform apps from a single codebase? Before you write your first line of Dart, you need to set up your environment.

Don't let installation guides overwhelm you. Here is the absolute quickest, no-nonsense way to get Flutter up and running on both Windows and macOS.

The Prerequisites (Both OS)

Before touching Flutter, install Visual Studio Code (VS Code). It is light, fast, and the absolute best editor for beginners.

Once installed:

Open VS Code.
Go to the Extensions tab (Ctrl+Shift+X or Cmd+Shift+X).
Search for Flutter and click Install (this automatically installs the Dart extension too).

Setting Up on Windows

Step 1: Install Git

Download and install Git for Windows. Just use the default settings during installation.

Step 2: Download & Extract Flutter

Download the latest stable Flutter SDK zip file from the Official Flutter Docs.
Create a folder named C:\src.
Extract the downloaded zip file directly inside C:\src, so your path looks like C:\src\flutter.

⚠️ Important: Do NOT extract it into C:\Program Files as it requires admin permissions and will break things.

Step 3: Update Your Environment Path

To run Flutter commands anywhere, Windows needs to know where it lives:

Press the Windows key and type "env", then select Edit the system environment variables.
Click Environment Variables… at the bottom.
Under User Variables, look for Path and double-click it.
Click New and paste: C:\src\flutter\bin
Click OK on all windows to save.

Setting Up on macOS

Step 1: Install Homebrew (If Not Installed)

Open Terminal and run the command package manager script:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Verify the installation is live:

brew --version

Step 2: Install Flutter

You can download the Flutter SDK manually from the Flutter Official Website, or install it instantly via Homebrew:

brew install --cask flutter

Step 3: Add Flutter to PATH

Locate your installation destination:

which flutter

Open your configuration script (nano ~/.zshrc). If you used Homebrew on an Apple Silicon Mac (M series), paste this line at the bottom:

export PATH = "$PATH:/opt/homebrew/Caskroom/flutter/latest/flutter/bin"

(For manual zip installation, paste: export PATH="$PATH:/path/to/flutter/bin" instead).

Apply the terminal changes and verify:

source ~/.zshrc
flutter --version

Step 4: Install Xcode (For iOS Target Development)

Download Xcode from the Mac App Store.
Configure the developer tools command paths:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

Accept the Apple licensing agreement:

sudo xcodebuild -license accept

Step 5: Install CocoaPods

Manage your native iOS dependencies cleanly. Install via Ruby gems or Homebrew:

brew install cocoapods

Verify it runs:

pod --version

Step 6: Install Android Studio (For Android Target Development)

Download and run Android Studio. During the initial setup wizard, ensure you check the boxes to download:

Android SDK & Android SDK Platform Tools
Android Emulator & Android SDK Command-line Tools

Step 7: Configure Android SDK

Open Android Studio, navigate to Settings → Android SDK.
Under SDK Tools, explicitly verify Android SDK Command-line Tools is checked and installed.
Open your terminal and accept the developer licenses:

flutter doctor --android-licenses

Press y to accept all incoming prompt licenses.

The Magic Check (Flutter Doctor)

Now for the ultimate tool in the Flutter ecosystem. Close and reopen your terminal or command prompt, and run:

flutter doctor

This command analyzes your system and prints a report. Don't panic if you see red [X] marks!

If it asks for Android Studio/SDK: Download Android Studio, run it once, and let it install the default SDK components.
If you are on Mac and want iOS support: Download Xcode from the Mac App Store.

Once you get green checkmarks next to Flutter and VS Code, you are officially ready to build!

Create Your First Project

Want to test it instantly? Open VS Code, press Ctrl+Shift+P (or Cmd+Shift+P), type "Flutter: New Project", select Application, and watch the magic happen.

Happy Coding!

Firebase Hosting for Flutter Web: What Actually Works (and What Breaks)

Codexlancers — Wed, 24 Jun 2026 09:00:00 +0000

When we first started deploying Flutter web apps, Firebase Hosting felt like the obvious choice.

It's fast, reliable, and backed by Google - but like most "easy" tools, things get tricky the moment you move beyond the basics.

In this blog, we're not just covering setup. We're sharing what actually works in real projects, the mistakes we've seen (and made), and a few things most guides don't talk about.

Why We Prefer Firebase Hosting for Flutter Web

We've tried different hosting solutions, but Firebase keeps coming back into our workflow for a few solid reasons:

Global CDN out of the box - your app loads fast everywhere
Free SSL - no extra configuration headaches
Simple deployment - one command and you're live
Version control with previews -helpful for testing before pushing to production

For most Flutter web apps, especially MVPs and dashboards, it just makes sense.

Quick Setup (The Practical Version)

Instead of overcomplicating things, here's the version that works:

1. Install Firebase CLI

npm install -g firebase-tools

2. Login & Initialize

firebase login
firebase init

While initializing:

Select Hosting
Choose your Firebase project
Set build folder to:

build/web

Configure as a single-page app (SPA) → YES

3. Build Flutter Web

flutter build web

4. Deploy

firebase deploy

That's it - your Flutter web app is live.

But honestly, this is the easy part. The real issues start after deployment.

The "#" in Flutter Web URLs (And Why You Should Care)

If you've deployed your app and see URLs like this:
"yourdomain.com/#/dashboard"

That # is coming from Flutter's default routing strategy.

Why it exists

Flutter uses hash-based routing because:

It avoids server configuration
Works out-of-the-box on any hosting

But

Why we remove it

From our experience, keeping # in URLs is not ideal:

Looks unprofessional
Bad for SEO
Harder to share clean URLs
Not aligned with modern web standards

How We Remove "#" from Flutter Web URLs

We switch to Path URL Strategy.

Step 1: Add this in main.dart

import 'package:flutter_web_plugins/flutter_web_plugins.dart';

void main() {
  setUrlStrategy(PathUrlStrategy());
  runApp(MyApp());
}

Step 2: Update Firebase Hosting Rewrite

In firebase.json, make sure you have:

"rewrites": [
  {
    "source": "**",
    "destination": "/index.html"
  }
]

Result

Now your URLs look clean:
"yourdomain.com/dashboard"

This small change makes a big difference in production apps.

Common Mistakes We See (Again and Again)

This is where most developers struggle - not in setup, but in the details.

1. Forgetting SPA Rewrite

Without rewrites, refreshing any route gives a 404 error.

We've seen this happen in production apps - easy to miss, painful to debug.

2. Deploying Without Testing Build

Running locally ≠ production build.

We always run:

flutter build web

and test the build/web folder before deploying.

3. Ignoring Cache Issues

Firebase aggressively caches files.
So when updates don't reflect:

Users still see old UI
API changes don't appear

Fix: Use proper cache headers or versioning.

4. Not Optimizing Build Size

Flutter web builds can get heavy.
Common mistakes:

Large images
Unused assets
Debug mode builds

We always:

Compress assets
Use - release build
Avoid unnecessary packages

5. Not Handling Environment Config Properly

Hardcoding API URLs is a common mistake.
Instead, we:

Use environment-based configs
Keep dev and prod setups separate

What We've Learned After Multiple Deployments

After working on multiple Flutter web projects, a few patterns are clear:

Firebase Hosting is great for speed and simplicity
Most issues come from configuration, not code
Small things (like URL strategy) make a big production difference

When Firebase Hosting Might Not Be Enough

We still use Firebase a lot, but it's not perfect for everything.
You might outgrow it if:

You need advanced server-side rendering
You want full backend control
You're building SEO-heavy public platforms

For dashboards, admin panels, internal tools - it's still one of the best choices.

Final Thoughts

Firebase Hosting + Flutter Web is a powerful combo - but only if you handle the details right.

Most tutorials stop at deployment.
Real-world apps fail in the gaps after that.

If you:

Fix routing properly
Avoid common mistakes
Optimize your build

you'll have a fast, clean, production-ready web app.

If you're working on Flutter web and stuck somewhere, chances are it's one of these small things - we've been there too.

Modern Way to Launch Flutter Desktop Apps on Boot

Codexlancers — Tue, 23 Jun 2026 12:00:00 +0000

Imagine building a brilliant productivity tool, a system monitor, or a sleek menu bar utility in Flutter, only for users to forget to open it. If your desktop application relies on seamless, background availability, integrating a "Launch at Startup" feature is essential.

While doing this natively requires writing platform-specific code (C++ for Windows, Swift for macOS, and C for Linux), the Flutter ecosystem has a fantastic package that handles the heavy lifting: launch_at_startup.

Why Launch at Startup?

Auto-launching your application can be useful for:

Background utilities
Productivity applications
Communication tools
System monitoring software
Menu bar or tray applications

Instead of asking users to manually open the app every time they restart their computer, your application can automatically start when the operating system launches.

Adding the Package

First, add the latest version of launch_at_startup and the package_info_plus package (which is highly recommended for dynamically fetching your app's name and executable path) to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  launch_at_startup: ^0.2.2 # Use the latest version
  package_info_plus: ^8.0.0

Run flutter pub get in your terminal to fetch the packages.

Initialize launch_at_startup

Before enabling startup launch, initialize the package with your application details.

import 'dart:io';

import 'package:launch_at_startup/launch_at_startup.dart';
import 'package:package_info_plus/package_info_plus.dart';

Future<void> main() async {
  final packageInfo = await PackageInfo.fromPlatform();

  launchAtStartup.setup(
    appName: packageInfo.appName,
    appPath: Platform.resolvedExecutable,
    // Required when using MSIX packaging on Windows
    packageName: 'com.app.startup_launch',
  );

  runApp(const MyApp());
}

Platform.resolvedExecutable automatically provides the correct executable path for the running app.

Check Current Status

Before enabling or disabling startup behavior, you may want to check whether it is already enabled.

final isEnabled = await launchAtStartup.isEnabled();
print('Launch at startup: $isEnabled');

This is useful for displaying the current state in your settings screen.

Enable Auto Launch

To register the application for startup:

await launchAtStartup.enable();

Disable Auto Launch

If the user decides to turn off the feature:

await launchAtStartup.disable();

Creating a Settings Toggle

A common implementation is providing a switch in your app settings.

final isStartupEnabled = await launchAtStartup.isEnabled();

SwitchListTile(
  title: const Text('Launch at Startup'),
  value: isStartupEnabled,
  onChanged: (value) async {
    if (value) {
      await launchAtStartup.enable();
    } else {
      await launchAtStartup.disable();
    }
    setState(() => isStartupEnabled = value);
  },
)

This gives users full control over the startup behavior.

Supported Platforms

The package currently supports:

Windows
macOS
Linux

Make sure to test the functionality on your target operating system before releasing your application.

Things to Keep in Mind

Auto-start should be optional whenever possible.
Always provide users with a way to disable it.
Consider combining startup launch with system tray support for a better desktop experience.
Test both debug and release builds, as startup behavior is typically used in production environments.

Final Thoughts

Adding startup launch support is a small feature that can significantly improve the desktop user experience. With the launch_at_startup package, Flutter developers can implement this functionality with just a few lines of code across Windows, macOS, and Linux.

If you're building a desktop utility, communication tool, or productivity application, enabling auto-launch can make your app feel much more professional and convenient for users.

How to Fetch Apple Calendar Events and Reminders in Flutter (macOS)

Codexlancers — Fri, 19 Jun 2026 04:00:00 +0000

Building a macOS app with Flutter and need access to Apple Calendar events and Reminders? Flutter cannot directly access EventKit (Apple's framework for calendars and reminders), so we bridge using native Swift and MethodChannels.
In this guide, we'll build a complete pipeline that even a beginner can follow.

1. Understanding the Architecture

Flutter side (Dart):

Sends a method name and optional arguments to Swift.
Example: "fetchCalendarEvents" with a list of calendar IDs.

Swift side:

Checks which method Flutter called (call.method).
Does the EventKit work (fetch events or reminders).
Sends the results back to Flutter using result(...).

Important:

Flutter can only understand simple data from Swift:

Strings, numbers, booleans, lists, maps.
No custom objects or raw Date objects.
Convert Date to a string in ISO8601 format first.

Permissions:

macOS asks the user only once for calendar/reminder access.
First time: a system dialog appears.
After that, macOS remembers the choice until the user changes it manually in System Settings → Privacy

2. macOS Project Setup

a) Add Entitlements

Open:

macos/Runner/DebugProfile.entitlements
macos/Runner/Release.entitlements

Add inside <dict>:

<key>com.apple.security.personal-information.calendars</key>
<true/>
<key>com.apple.security.personal-information.reminders</key>
<true/>

b) Update Info.plist

Add usage descriptions:

<key>NSCalendarsFullAccessUsageDescription</key>
<string>This app needs access to your calendar.</string>
<key>NSRemindersFullAccessUsageDescription</key>
<string>This app needs access to your reminders.</string>

<!-- For macOS 13 or older -->
<key>NSCalendarsUsageDescription</key>
<string>This app needs access to your calendar.</string>
<key>NSRemindersUsageDescription</key>
<string>This app needs access to your reminders.</string>

3. Native Swift Implementation

a) Create CalendarBridge.swift

import Cocoa
import EventKit

@objc class CalendarBridge: NSObject {

    // Use a single shared EKEventStore for the whole app
    static let store = EKEventStore()

    // MARK: - Permission Requests

    /// Request calendar access permission from the user
    @objc static func requestCalendarPermission(_ result: @escaping (Bool) -> Void) {
        if #available(macOS 14.0, *) {
            store.requestFullAccessToEvents { granted, _ in
                if granted { store.reset() } // Refresh calendars after permission
                DispatchQueue.main.async { result(granted) }
            }
        } else {
            store.requestAccess(to: .event) { granted, _ in
                if granted { store.reset() }
                DispatchQueue.main.async { result(granted) }
            }
        }
    }

    /// Request reminders access permission from the user
    @objc static func requestReminderPermission(_ result: @escaping (Bool) -> Void) {
        if #available(macOS 14.0, *) {
            store.requestFullAccessToReminders { granted, _ in
                if granted { store.reset() }
                DispatchQueue.main.async { result(granted) }
            }
        } else {
            store.requestAccess(to: .reminder) { granted, _ in
                if granted { store.reset() }
                DispatchQueue.main.async { result(granted) }
            }
        }
    }

    // MARK: - Authorization Check

    /// Check if calendar access is already authorized
    @objc static func isCalendarAuthorized() -> Bool {
        switch EKEventStore.authorizationStatus(for: .event) {
        case .authorized, .fullAccess:
            return true
        default:
            return false
        }
    }

    // MARK: - Calendars

    /// Get all available calendars for events
    @objc static func getCalendars() -> [[String: String]] {
        let calendars = store.calendars(for: .event)
        return calendars.map { cal in
            let source = cal.source.sourceType == .local ? "Default" : cal.source.title
            return [
                "id": cal.calendarIdentifier,
                "title": cal.title,
                "sourceType": source,
                "sourceTitle": cal.source.title
            ]
        }
    }

    /// Fetch events from the selected calendar IDs for the next 7 days
    @objc static func fetchEvents(calendarIds: [String], result: @escaping ([[String: Any]]) -> Void) {
        guard isCalendarAuthorized() else {
            result([["error": "permission_denied"]])
            return
        }

        let calendars = store.calendars(for: .event).filter { calendarIds.contains($0.calendarIdentifier) }
        let now = Date()
        let weekAhead = Calendar.current.date(byAdding: .day, value: 7, to: now)!

        let isoFormatter = ISO8601DateFormatter()
        isoFormatter.formatOptions = [.withInternetDateTime]

        var events: [[String: Any]] = []

        for cal in calendars {
            let predicate = store.predicateForEvents(withStart: now, end: weekAhead, calendars: [cal])
            for event in store.events(matching: predicate) {
                events.append([
                    "id": event.eventIdentifier ?? "",
                    "title": event.title ?? "No Title",
                    "start": isoFormatter.string(from: event.startDate),
                    "end": isoFormatter.string(from: event.endDate),
                    "location": event.location ?? "",
                    "notes": event.notes ?? "",
                    "isAllDay": event.isAllDay,
                    "calendarId": event.calendar.calendarIdentifier,
                    "calendarTitle": event.calendar.title
                ])
            }
        }

        result(events)
    }

    // MARK: - Reminders

    /// Get all reminder lists
    @objc static func getReminderLists() -> [[String: String]] {
        store.reset() // Refresh lists after permission granted
        return store.calendars(for: .reminder).map { cal in
            let source = cal.source.sourceType == .local ? "Default" : cal.source.title
            return [
                "id": cal.calendarIdentifier,
                "title": cal.title,
                "sourceType": source
            ]
        }
    }

    /// Fetch all reminders in a specific list
    @objc static func fetchReminders(listId: String, result: @escaping ([[String: Any]]) -> Void) {
        let lists = store.calendars(for: .reminder)
        guard let list = lists.first(where: { $0.calendarIdentifier == listId }) else {
            result([["error": "list_not_found"]])
            return
        }

        let isoFormatter = ISO8601DateFormatter()
        isoFormatter.formatOptions = [.withInternetDateTime]

        let predicate = store.predicateForReminders(in: [list])
        store.fetchReminders(matching: predicate) { reminders in
            let mapped = (reminders ?? []).map { r -> [String: Any] in
                let dueDate = r.dueDateComponents?.date.map { isoFormatter.string(from: $0) } ?? ""
                return [
                    "id": r.calendarItemIdentifier,
                    "title": r.title ?? "No Title",
                    "notes": r.notes ?? "",
                    "completed": r.isCompleted,
                    "dueDate": dueDate,
                    "hasDueDate": r.dueDateComponents != nil,
                    "priority": r.priority
                ]
            }
            result(mapped)
        }
    }
}

b) Wire it up in AppDelegate.swift

import Cocoa
import FlutterMacOS
import EventKit

@main
class AppDelegate: FlutterAppDelegate {
    private var channel: FlutterMethodChannel?

    override func applicationDidFinishLaunching(_ notification: Notification) {
        let controller = NSApplication.shared.windows.first!.contentViewController as! FlutterViewController
        channel = FlutterMethodChannel(name: "method_macos_native", binaryMessenger: controller.engine.binaryMessenger)

        channel!.setMethodCallHandler { call, result in
            switch call.method {
            case "requestCalendarPermission":
                CalendarBridge.requestCalendarPermission { granted in result(granted) }
            case "requestReminderPermission":
                CalendarBridge.requestReminderPermission { granted in result(granted) }
            case "checkCalendarPermission":
                result(CalendarBridge.isCalendarAuthorized())
            case "getCalendars":
                result(CalendarBridge.getCalendars())
            case "fetchCalendarEvents":
                let ids = (call.arguments as? [String: Any])?["calendarIds"] as? [String] ?? []
                DispatchQueue.global().async {
                    CalendarBridge.fetchEvents(calendarIds: ids) { events in
                        DispatchQueue.main.async { result(events) }
                    }
                }
            case "getReminderLists":
                DispatchQueue.global().async {
                    let lists = CalendarBridge.getReminderLists()
                    DispatchQueue.main.async { result(lists) }
                }
            case "fetchReminders":
                let listId = (call.arguments as? [String: Any])?["listId"] as? String ?? ""
                DispatchQueue.global().async {
                    CalendarBridge.fetchReminders(listId: listId) { reminders in
                        DispatchQueue.main.async { result(reminders) }
                    }
                }
            default:
                result(FlutterMethodNotImplemented)
            }
        }

        setupCalendarChangeObserver()
        super.applicationDidFinishLaunching(notification)
    }

    private func setupCalendarChangeObserver() {
        NotificationCenter.default.addObserver(forName: .EKEventStoreChanged,
                                               object: CalendarBridge.store,
                                               queue: .main) { [weak self] _ in
            self?.channel?.invokeMethod("onCalendarChanged", arguments: nil)
        }
    }
}

4. Flutter (Dart) Side - CalendarService

Create lib/services/calendar_service.dart:

import 'dart:io';
import 'package:flutter/services.dart';

class CalendarService {
  static const MethodChannel _channel = MethodChannel('method_macos_native');

  static Future<bool> requestCalendarPermission() async { ... }
  static Future<bool> requestReminderPermission() async { ... }
  static Future<List<Map<String, dynamic>>> getCalendars() async { ... }
  static Future<List<Map<String, dynamic>>> fetchEvents(List<String> calendarIds) async { ... }
  static Future<List<Map<String, dynamic>>> getReminderLists() async { ... }
  static Future<List<Map<String, dynamic>>> fetchReminders(String listId) async { ... }
}

5. Calling From UI

Future<void> loadCalendar() async {
  final granted = await CalendarService.requestCalendarPermission();
  if (!granted) return;
  final calendars = await CalendarService.getCalendars();
  final ids = calendars.map((c) => c['id'] as String).toList();
  final events = await CalendarService.fetchEvents(ids);
  events.forEach((e) => print('${e['title']} @ ${e['start']}'));
}

Future<void> loadReminders() async {
  if (!await CalendarService.requestReminderPermission()) return;
  final lists = await CalendarService.getReminderLists();
  for (final list in lists) {
    final reminders = await CalendarService.fetchReminders(list['id'] as String);
    print('${list['title']}: ${reminders.length} reminders');
  }
}

6. Fetching Reminders In Depth

Reminder Lists = EKCalendar of type .reminder.
Each reminder = EKReminder.
Permissions are separate from calendars.
Fetch asynchronously using store.fetchReminders.

final lists = await CalendarService.getReminderLists();
for (final list in lists) {
  final all = await CalendarService.fetchReminders(list['id'] as String);
  final open = all.where((r) => r['completed'] != true).toList();
  print('- ${list['title']} (${open.length} open) -');
}

7. Live Updates

EventKit fires .EKEventStoreChanged for any changes. In Flutter:

void listenForCalendarChanges(VoidCallback onChanged) {
  const channel = MethodChannel('method_macos_native');
  channel.setMethodCallHandler((call) async {
    if (call.method == 'onCalendarChanged') onChanged();
  });
}

8. Things to Watch Out For

Empty results after permission

If you just gave access, sometimes calendars/reminders show empty.
Fix: Use only one shared EKEventStore for the whole app.

Reminders fetch is asynchronous

Fetching reminders does not happen instantly.
Fix: Always return the data to Flutter inside the completion block.

macOS 14+ API changes

New versions of macOS use requestFullAccessToEvents and requestFullAccessToReminders.
Old methods may not work correctly.

Dates must be strings

You cannot send Date objects directly to Flutter.
Fix: Convert dates to ISO8601 strings using ISO8601DateFormatter.

Channel or method name typos

If names don't match exactly between Flutter and Swift, nothing will work and there's no error.
Double-check spelling and capitalization.

Entitlements in Debug and Release

You must add calendar/reminder entitlements in both Debug and Release files.
Otherwise, it may work in release but not during testing.

Heavy fetches on main thread

Fetching a lot of events can freeze your app.
Fix: Do heavy work on a background thread, not the main UI thread.

Building a Microservices Architecture in .NET 8 Using Ocelot API Gateway

Codexlancers — Thu, 18 Jun 2026 08:52:26 +0000

Introduction

In modern applications, we often split our system into multiple smaller services called Microservices. Each service is responsible for a specific business function.

For example:

User Service → Handles users
Product Service → Handles products
Order Service → Handles orders

When we have multiple services, clients need a simple way to access them. Instead of calling each service directly, we use an API Gateway.

In this tutorial, we'll build:

User Microservice
Product Microservice
Ocelot API Gateway

By the end of this article, you'll understand how API Gateway routing works and how Ocelot can help manage communication between microservices.

What We Are Building

Our architecture will look like this:

Browser / Postman
        |
        v
   API Gateway
      (Ocelot)
      /     \
     /       \
    v         v
User API   Product API

Instead of calling User API or Product API directly, all requests will go through the API Gateway.

Step 1: Create the Solution

Open Visual Studio and create:

Project 1: UserService

dotnet new webapi -n UserService

Project 2: ProductService

dotnet new webapi -n ProductService

Project 3: ApiGateway

dotnet new webapi -n ApiGateway

Your solution structure should look like:

MicroserviceDemo
|
├── ApiGateway
├── UserService
└── ProductService

Step 2: Create User Service

Open UserService and create a controller.

[ApiController]
[Route("user")]
public class UserController : ControllerBase
{
    [HttpGet]
    public IActionResult GetUser()
    {
        return Ok(new
        {
            Id = 1,
            Name = "John Doe"
        });
    }
}

Run the application.

Test:

https://localhost:7044/user

Response:

{
  "id": 1,
  "name": "John Doe"
}

Great! Our User Service is working.

Step 3: Create Product Service

Now create a ProductController.

[ApiController]
[Route("product")]
public class ProductController : ControllerBase
{
    [HttpGet]
    public IActionResult GetProduct()
    {
        return Ok(new
        {
            Id = 100,
            Name = "Laptop"
        });
    }
}

Run Product Service.

Test:

https://localhost:7220/product

Response:

{
  "id": 100,
  "name": "Laptop"
}

Now both microservices are working independently.

Step 4: Why Do We Need an API Gateway?

At this point, the client needs to know:

https://localhost:7044/user

https://localhost:7220/product

Imagine having 20 microservices.

The frontend would need to manage 20 different URLs.

This becomes difficult to maintain.

An API Gateway solves this problem by providing a single entry point.

Example:

https://localhost:5000/gateway/user

https://localhost:5000/gateway/product

The gateway automatically forwards requests to the correct service.

Step 5: Install Ocelot

Open Package Manager Console inside ApiGateway.

Install Ocelot:

Install-Package Ocelot

dotnet add package Ocelot

Ocelot is a popular API Gateway library built specifically for ASP.NET Core.

Step 6: Create Ocelot Configuration

Create a new file:

ocelot.json

Add:

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/user",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 7044
        }
      ],
      "UpstreamPathTemplate": "/gateway/user",
      "UpstreamHttpMethod": [ "GET" ]
    },
    {
      "DownstreamPathTemplate": "/product",
      "DownstreamScheme": "https",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 7220
        }
      ],
      "UpstreamPathTemplate": "/gateway/product",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ]
}

Let's understand what this means.

When someone calls:

/gateway/user

Ocelot forwards the request to:

/user

inside User Service.

Similarly:

/gateway/product

is forwarded to Product Service.

Step 7: Configure Ocelot in Program.cs

Open ApiGateway Program.cs.

Replace the code with:

using Ocelot.DependencyInjection;
using Ocelot.Middleware;

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddJsonFile(
    "ocelot.json",
    optional: false,
    reloadOnChange: true);

builder.Services.AddOcelot();

var app = builder.Build();

await app.UseOcelot();

app.Run();

This tells the application:

Load Ocelot configuration
Enable API Gateway middleware
Route requests using ocelot.json

Step 8: Test the Gateway

Start:

UserService
ProductService
ApiGateway

Now call:

https://localhost:5000/gateway/user

Expected Response:

{
  "id": 1,
  "name": "John Doe"
}

Call:

https://localhost:5000/gateway/product

Expected Response:

{
  "id": 100,
  "name": "Laptop"
}

Notice something important.

The client never talks directly to User Service or Product Service.

Everything goes through the API Gateway.

Step 9: Add Rate Limiting

Suppose we want to allow only 4 requests per minute.

Update User Route:

"RateLimitOptions": {
  "EnableRateLimiting": true,
  "Period": "60s",
  "Limit": 4
}

Now:

Request 1 → Success
Request 2 → Success
Request 3 → Success
Request 4 → Success
Request 5 → Blocked

Response:

429 Too Many Requests

This helps protect APIs from abuse.

Step 10: Add Load Balancing

Suppose User Service is getting heavy traffic.

We create another instance running on:

https://localhost:7045/user

Update Ocelot:

"DownstreamHostAndPorts": [
  {
    "Host": "localhost",
    "Port": 7044
  },
  {
    "Host": "localhost",
    "Port": 7045
  }
],
"LoadBalancerOptions": {
  "Type": "RoundRobin"
}

How it works:

Request 1 → Server 1

Request 2 → Server 2

Request 3 → Server 1

Request 4 → Server 2

Traffic gets distributed automatically.

Conclusion

In this guide, we built a simple Microservices Architecture using .NET 8 and Ocelot API Gateway. We started by creating separate User and Product services, then configured Ocelot to act as a central entry point for routing requests to the appropriate service.

Along the way, we learned how API Gateways simplify communication between clients and microservices, how route configuration works, and how features like rate limiting and load balancing can improve the reliability and scalability of an application.

While this example is intentionally simple, the same concepts are used in real-world enterprise applications. As systems grow, an API Gateway becomes an important component for managing traffic, securing APIs, and providing a consistent entry point for consumers.

If you're new to Microservices, I recommend experimenting further by adding:

JWT Authentication
Health Checks
Swagger Aggregation
Docker Containers
Service Discovery
Distributed Logging

These additions will help you move from a basic microservices setup to a production-ready architecture.

I hope this article helped you understand how Ocelot works and how it can be used to build scalable .NET applications. If you have any questions or suggestions, feel free to leave a comment or connect with me.

Flutter File Uploads Made Easy: Working with Multipart APIs

Codexlancers — Thu, 18 Jun 2026 05:00:00 +0000

File uploads are one of the most common requirements in real-world Flutter applications-whether it's uploading profile images, documents, or media files.

At our company, we've implemented file upload systems across multiple production apps, and one thing is clear:

Most developers don't struggle with the concept-they struggle with clean implementation.

In this article, we'll break down Multipart file uploads in Flutter using the latest stable packages in a simple, production-ready way.

Why Multipart Requests Matter

When sending data to APIs:

JSON works for text data
Files (images, PDFs, videos) require multipart/form-data

This format allows sending:

Normal fields (userId, email, etc.)
Files (binary data)

in a single request.

Real-World Use Cases

We've used multipart uploads in:

Profile image uploads
KYC verification documents
E-commerce product images
Chat attachments
Resume uploads

Dependencies (Latest Versions)

dependencies:
  http: ^1.6.0
  image_picker: ^1.2.1
  path: ^1.9.1

Step 1: Picking an Image

With the latest image_picker, the API remains stable while ensuring null safety + proper typing.

import 'package:image_picker/image_picker.dart';

final ImagePicker _picker = ImagePicker();

Future<XFile?> pickImage() async {
  try {
    final XFile? image = await _picker.pickImage(
      source: ImageSource.gallery,
      imageQuality: 80,
    );

    return image;
  } catch (e) {
    print("Error picking image: $e");
    return null;
  }
}

Step 2: Multipart Upload Using http

The http ^1.6.0 package still uses MultipartRequest, but we'll structure it more cleanly and safely.

import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:path/path.dart' as path;

Future<void> uploadFile(XFile file) async {
  try {
    var uri = Uri.parse("https://yourapi.com/upload");

    var request = http.MultipartRequest("POST", uri);

    // Optional fields
    request.fields['userId'] = "12345";

    // File name handling
    String fileName = path.basename(file.path);

    // Attach file
    request.files.add(
      await http.MultipartFile.fromPath(
        'file',
        file.path,
        filename: fileName,
      ),
    );

    // Send request
    var streamedResponse = await request.send();

    // Convert response stream
    var response = await http.Response.fromStream(streamedResponse);

    if (response.statusCode == 200) {
      print("Upload successful");
      print("Response: ${response.body}");
    } else {
      print("Upload failed: ${response.statusCode}");
      print("Response: ${response.body}");
    }
  } catch (e) {
    print("Upload error: $e");
  }
}

Step 3: UI Integration

ElevatedButton(
  onPressed: () async {
    final file = await pickImage();

    if (file != null) {
      await uploadFile(file);
    }
  },
  child: const Text("Upload File"),
)

Important Validation (Production Ready)

Always validate file size before uploading:

if (file.lengthSync() > 10 * 1024 * 1024) {
  print("File too large (Max 10MB allowed)");
  return;
}

What Changed in the Latest Approach?

With updated packages, best-practice improvements include:

✔ Proper Response Conversion

http.Response.fromStream(streamedResponse)

✔ Safe Filename Extraction

path.basename(file.path)

Common Mistakes Developers Still Make

1. Not Converting Streamed Responses

Multipart responses come as streams. Ignoring this often results in unreadable output.

2. Missing Filename in Upload Requests

Some servers reject files without explicit filenames.

3. No Error Handling Around Image Picker

Image selection can fail or be cancelled by the user.

4. Uploading Oversized Files

Always validate file size before sending requests.

Best Practices We Follow

At scale, we always ensure:

Validate files before upload
Use proper filename handling
Convert response streams properly
Handle cancelled selections gracefully
Keep upload logic separated from UI
Use HTTPS only

Final Thoughts

File uploads in Flutter aren't complicated—but implementing them correctly makes a huge difference in production applications.

Once you understand how multipart requests work, the workflow becomes straightforward:

Pick a file
Attach it to a request
Send it securely to the server

With Flutter's latest stable packages like http, image_picker, and path, it's possible to build a clean and reliable upload system without unnecessary complexity.

At our company, this exact approach is used across multiple production apps where performance, maintainability, and reliability are critical.

Building a Real-Time Flutter SDUI Architecture with Stac and Cloud Firestore

Codexlancers — Wed, 17 Jun 2026 12:00:00 +0000

Imagine shipping a major UI redesign, fixing a broken layout, or launching an A/B test on your mobile application instantly - without waiting for App Store or Play Store approvals.

In traditional mobile development, the presentation layer is tightly coupled with the client application. If you need to change a button color, adjust padding, or reorganize a screen, you must modify the codebase, compile a new binary, submit it to the stores, and wait hours or days for approval.

Server-Driven UI (SDUI) flips this paradigm completely. By moving the presentation structure to the cloud, the backend dictates what to render, while the client app simply focuses on how to render it natively.

In this article, we'll explore how to build a production-ready, dynamic interface using Stac (a powerful, open-source SDUI framework for Flutter) backed by the real-time capabilities of Cloud Firestore.

Overview: The Architecture of SDUI

Server-Driven UI isn't web-view wrapping. When implemented correctly, it leverages native components driven entirely by lightweight configuration files (typically JSON).

Why Stac?

Stac (formerly Mirai) bridges the gap between server configurations and Flutter. It allows you to define your layout using an intuitive Dart DSL on the server or raw JSON schemas that map directly to native Flutter widgets like Scaffold, Column, ListView, and ElevatedButton.

Why Cloud Firestore?

While Stac manages the transformation from JSON to native Flutter widgets, it needs a fast, scalable delivery mechanism. Cloud Firestore is uniquely suited for this role because:

Real-time Synchronization: Firestore can stream layout changes to active clients instantly via listeners.
Document-Based Hierarchy: Layout payloads match Firestore's document format perfectly.
Robust Caching: Out-of-the-box offline support guarantees that your application remains functional even on unstable networks.

Implementation Guide: Step-by-Step

Let's walk through implementing a dynamic home screen that updates in real time whenever the Firestore database updates.

Step 1: Set Up the Firestore Layout Schema

First, we need to store our layout JSON inside a Firestore collection. Let's create a collection called screens and a document named home_page.

Inside the home_page document, add a field called layout of type Map. Here is the Stac-compliant JSON layout structure to insert:

{
  "type": "scaffold",
  "appBar": {
    "type": "appBar",
    "title": {
      "type": "text",
      "data": "Dynamic Dashboard"
    },
    "backgroundColor": "#FF6200EE"
  },
  "body": {
    "type": "center",
    "child": {
      "type": "column",
      "mainAxisAlignment": "center",
      "children": [
        {
          "type": "text",
          "data": "Welcome back, Developer!",
          "style": {
            "fontSize": 20,
            "fontWeight": "bold"
          }
        },
        {
          "type": "padding",
          "padding": {
            "top": 16
          },
          "child": {
            "type": "filledButton",
            "child": {
              "type": "text",
              "data": "Explore Offers"
            }
          }
        }
      ]
    }
  }
}

Step 2: Initialize Stac and Firebase in Flutter

Add the required dependencies to your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  firebase_core: ^3.0.0 # Use up-to-date compatible versions
  cloud_firestore: ^5.0.0
  stac: ^1.4.0

Initialize both frameworks within your application's entry point (main.dart):

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:stac/stac.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize Firebase Ecosystem
  await Firebase.initializeApp();

  // Initialize Stac Configuration Engine
  await Stac.initialize();

  runApp(const MyApp());
}
class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Stac SDUI',
      theme: ThemeData(primarySwatch: Colors.deepPurple),
      home: const ServerDrivenHomeScreen(),
    );
  }
}

Step 3: Create the Real-Time Render Stream

Now, create a widget that listens to the Firestore document stream and passes the data payload directly to Stac's parsing engine.
We will use a StreamBuilder connected to Firestore, feeding into Stac.fromJson() to parse and generate native components on the fly.

import 'package:flutter/material.dart';
import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:stac/stac.dart';

class ServerDrivenHomeScreen extends StatelessWidget {
  const ServerDrivenHomeScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<DocumentSnapshot>(
      stream: FirebaseFirestore.instance
          .collection('screens')
          .doc('home_page')
          .snapshots(),
      builder: (context, snapshot) {
        // Handle loading state
        if (snapshot.connectionState == ConnectionState.waiting) {
          return const Scaffold(
            body: Center(child: CircularProgressIndicator()),
          );
        }
        // Handle errors or missing layout documents gracefully
        if (snapshot.hasError || !snapshot.hasData || !snapshot.data!.exists) {
          return const Scaffold(
            body: Center(child: Text('Failed to load dynamic layout.')),
          );
        }
        // Extract the layout schema map
        final data = snapshot.data!.data() as Map<String, dynamic>;
        final Map<String, dynamic>? layoutMap = data['layout'];
        if (layoutMap == null) {
          return const Scaffold(
            body: Center(child: Text('Layout data is corrupted.')),
          );
        }
        // Pass the backend map to Stac to render native widgets instantly
        return Stac.fromJson(layoutMap, context) ?? const SizedBox.shrink();
      },
    );
  }
}

Production Best Practices

Deploying Server-Driven UI introduces structural changes to app behavior. Keep these strategies in mind:

Fallback Assets: Always ship your application with a baseline, static JSON file stored in your Flutter local assets folder (Stac.fromAsset). If a user launches the app completely offline without a Firestore local cache history, you can seamlessly fall back to the asset layout.
Version Control for Payloads: As your app evolves, certain widget structures may change. Keep your layouts backward-compatible by appending a version structural suffix to the collection queries (e.g., home_page_v1, home_page_v2).
Performance Optimization: Limit SDUI to dynamic sections of the app - such as promotional headers, settings configurations, or product landing experiences. Keep highly transactional, intensive native logic (like camera pipelines or complex custom animations) hardcoded within traditional client widgets.

Conclusion

Combining the layout-parsing capabilities of Stac with the real-time operational database infrastructure of Cloud Firestore creates a frictionless pipeline for application delivery. By changing a map layout inside a console database, your user base updates instantly, bypassing long App Store processing times completely.

Dynamic App Icons in Flutter: The Ultimate Guide to Manual Selection & Over-the-Air Cloud Updates

Codexlancers — Mon, 15 Jun 2026 05:00:00 +0000

An application's home screen presence is prime real estate. Giving users the option to customize their app icon manually creates a delightful sense of personalization. Simultaneously, having the power to change app icons remotely allows you to ship global thematic shifts - like a festive holiday theme, a dark mode rebranding, or temporary promotional campaign artwork - without pushing a new build to the App Store or Google Play Store.

In this deep-dive guide, we will implement a dual-mode dynamic icon framework in Flutter without relying on buggy or outdated third-party packages. We will build our own MethodChannels using Kotlin and Swift to support two core features:

Manual Selection: Letting the user pick their preference inside an settings UI menu.
Over-the-Air Updates: Overriding or syncing the icon automatically using Firebase Remote Config.

Architectural Deep Dive

Before writing code, it is important to understand how the underlying platform behaviors differ. Flutter operates on a single execution context, meaning we must use platform channels to trigger native operating system APIs.

Android: Component Aliases

Android handles launcher icons statically via the AndroidManifest.xml. To circumvent this limitation, we declare multiple <activity-alias> tags that all point to the primary MainActivity. By toggling the enablement state of these aliases via the native PackageManager, the device home screen refreshes to reflect the icon linked to the active alias.

⚠️ Android Side Effect: Enabling or disabling an activity alias clears the recent apps stack and briefly kills the background application state to remap the launcher profile.

iOS: Alternate Icons API

Apple provides an explicit native framework via UIApplication.shared.setAlternateIconName(). Unlike standard graphic bundles, alternative icon resources cannot be included in a compiled asset catalog (Assets.xcassets). Instead, they must be bundled into the root app directory as loose files and mapped manually inside the project's properties dictionary (Info.plist).

Step 1: Building the Native Infrastructure

1. Flutter MethodChannel Connection

Create a clean utility class in your Dart project to establish the native system communication pipeline.

import 'package:flutter/services.dart';

class DynamicIconService {
  static const MethodChannel _channel = MethodChannel('com.dynamicicon.app/dynamic_icon');
  /// Requests the native OS platform layer to swap the active launcher asset icon profile.
  static Future<void> changeIcon(String iconName) async {
    try {
      await _channel.invokeMethod('setIcon', {'iconName': iconName});
    } on PlatformException catch (e) {
      print("Failed to change application launcher profile: '${e.message}'.");
    }
  }
}

2. Android Integration (AndroidManifest.xml & Kotlin)

First, add your alternative graphic assets directly to your resource directories:

android/app/src/main/res/mipmap-hdpi/ic_launcher_dark.png
android/app/src/main/res/mipmap-hdpi/ic_launcher_festive.png

Next, modify android/app/src/main/AndroidManifest.xml. Set the root .MainActivity property android:enabled to false. We will delegate all initial system hooks to our aliases.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application
        android:label="Dynamic App"
        android:name="${applicationName}">

        <!-- Base Target Activity Framework (Deactivated) -->
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:enabled="false"
            android:launchMode="singleTop"
            android:theme="@style/LaunchTheme">
            <meta-data
                android:name="io.flutter.embedding.android.NormalTheme"
                android:resource="@style/NormalTheme" />
        </activity>

        <!-- Default Application Icon Alias -->
        <activity-alias
            android:name=".DefaultIcon"
            android:enabled="true"
            android:exported="true"
            android:icon="@mipmap/ic_launcher"
            android:targetActivity=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity-alias>

        <!-- Dark Variant Icon Alias -->
        <activity-alias
            android:name=".DarkIcon"
            android:enabled="false"
            android:exported="true"
            android:icon="@mipmap/ic_launcher_dark"
            android:targetActivity=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity-alias>

        <!-- Festive Variant Icon Alias -->
        <activity-alias
            android:name=".FestiveIcon"
            android:enabled="false"
            android:exported="true"
            android:icon="@mipmap/ic_launcher_festive"
            android:targetActivity=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity-alias>
    </application>
</manifest>

Open your MainActivity.kt file to receive channel methods and trigger the state switch loop:

package com.dynamicicon.app

import android.content.ComponentName
import android.content.pm.PackageManager
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel

class MainActivity: FlutterActivity() {
    private val CHANNEL = "com.dynamicicon.app/dynamic_icon"
    private val packageNamespace = "com.dynamicicon.app"
    private val aliasRegistry = listOf("DefaultIcon", "DarkIcon", "FestiveIcon")
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)

        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL).setMethodCallHandler { call, result ->
            if (call.method == "setIcon") {
                val targetIcon = call.argument<String>("iconName")
                if (targetIcon != null && aliasRegistry.contains(targetIcon)) {
                    toggleLauncherComponent(targetIcon)
                    result.success(null)
                } else {
                    result.error("ALIAS_NOT_FOUND", "The target alias mapping configuration is missing.", null)
                }
            } else {
                result.notImplemented()
            }
        }
    }
    private fun toggleLauncherComponent(targetAlias: String) {
        val pm = applicationContext.packageManager

        for (alias in aliasRegistry) {
            val componentState = if (alias == targetAlias) {
                PackageManager.COMPONENT_ENABLED_STATE_ENABLED
            } else {
                PackageManager.COMPONENT_ENABLED_STATE_DISABLED
            }

            pm.setComponentEnabledSetting(
                ComponentName(applicationContext, "$packageNamespace.$alias"),
                componentState,
                PackageManager.DONT_KILL_APP
            )
        }
    }
}

3. iOS Integration (Info.plist & Swift)

Drop your loose alternative icon images directly under the ios/Runner/ folder structure as un-cataloged raw items (e.g., ic_launcher_dark@2x.png, ic_launcher_festive@3x.png).

<key>CFBundleIcons</key>
<dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconFiles</key>
        <array>
            <string>AppIcon</string>
        </array>
    </dict>
    <key>CFBundleAlternateIcons</key>
    <dict>
        <key>DarkIcon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>ic_launcher_dark</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <false/>
        </dict>
        <key>FestiveIcon</key>
        <dict>
            <key>CFBundleIconFiles</key>
            <array>
                <string>ic_launcher_festive</string>
            </array>
            <key>UIPrerenderedIcon</key>
            <false/>
        </dict>
    </dict>
</dict>

Open ios/Runner/AppDelegate.swift and configure the channel logic:

import UIKit
import Flutter

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {

    let controller : FlutterViewController = window?.rootViewController as! FlutterViewController
    let iconChannel = FlutterMethodChannel(name: "com.dynamicicon.app/dynamic_icon",
                                           binaryMessenger: controller.binaryMessenger)

    iconChannel.setMethodCallHandler({
      (call: FlutterMethodCall, result: @escaping FlutterResult) -> Void in
      guard call.method == "setIcon" else {
          result(FlutterMethodNotImplemented)
          return
      }

      if let arguments = call.arguments as? [String: Any],
         let iconName = arguments["iconName"] as? String {
          self.updateAlternateIcon(named: iconName, response: result)
      } else {
          result(FlutterError(code: "BAD_ARGS", message: "Arguments malformed", details: nil))
      }
    })
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
  private func updateAlternateIcon(named targetName: String, response: @escaping FlutterResult) {
      if #available(iOS 10.3, *) {
          let systemKey = (targetName == "DefaultIcon") ? nil : targetName

          UIApplication.shared.setAlternateIconName(systemKey) { error in
              if let error = error {
                  response(FlutterError(code: "IOS_ERROR", message: error.localizedDescription, details: nil))
              } else {
                  response(null)
              }
          }
      } else {
          response(FlutterError(code: "UNSUPPORTED_OS", message: "Minimum OS layout required", details: nil))
      }
  }
}

Step 2: Implementing the Management Strategy

Now that our native code is ready, we need to balance manual selection with remote config updates.

To handle this cleanly, we'll establish a business rule priority: Firebase Remote Config acts as a global override. If a remote key is published from the cloud dashboard, it overrides manual user settings. If no cloud configuration override is set (or it returns 'DefaultIcon'), the application respects the user's manual in-app selection.

First, add your framework dependencies to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  firebase_core: ^3.0.0
  firebase_remote_config: ^5.0.0
  shared_preferences: ^2.2.0

The Dual-Control Integration Engine

Create a manager file app_icon_manager.dart to cleanly orchestrate both sources:

import 'package:firebase_remote_config/firebase_remote_config.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'dynamic_icon_service.dart';

class AppIconManager {
  static const String _remoteOverrideKey = 'cloud_icon_override';
  static const String _userPrefKey = 'user_selected_icon';
  static const String _activeCachedKey = 'currently_applied_icon';

  /// Mode 1: Executed manually when a user taps an in-app icon preference menu item
  static Future<void> updateUserIconPreference(String targetIconName) async {
    final SharedPreferences prefs = await SharedPreferences.getInstance();
    await prefs.setString(_userPrefKey, targetIconName);

    // Evaluate if the cloud override is currently blocking changes before updating
    final FirebaseRemoteConfig remoteConfig = FirebaseRemoteConfig.instance;
    final String cloudOverride = remoteConfig.getString(_remoteOverrideKey);
    if (cloudOverride == 'DefaultIcon' || cloudOverride.isEmpty) {
      await _applyIconSafetyGuard(targetIconName);
    } else {
      print("User setting cached, but blocked by active Cloud Override: $cloudOverride");
    }
  }

  /// Mode 2: Triggered automatically during application launch to fetch cloud rules over-the-air
  static Future<void> syncCloudConfiguration() async {
    final FirebaseRemoteConfig remoteConfig = FirebaseRemoteConfig.instance;
    try {
      await remoteConfig.setDefaults(<String, dynamic>{_remoteOverrideKey: 'DefaultIcon'});
      await remoteConfig.setConfigSettings(RemoteConfigSettings(
        fetchTimeout: const Duration(seconds: 10),
        minimumFetchInterval: const Duration(hours: 2),
      ));
      bool updated = await remoteConfig.fetchAndActivate();
      if (!updated) return;
      final String cloudOverrideValue = remoteConfig.getString(_remoteOverrideKey);
      final SharedPreferences prefs = await SharedPreferences.getInstance();
      if (cloudOverrideValue != 'DefaultIcon' && cloudOverrideValue.isNotEmpty) {
        // Cloud override takes precedence
        await _applyIconSafetyGuard(cloudOverrideValue);
      } else {
        // Fall back to local user selection or fallback default
        final String userPreference = prefs.getString(_userPrefKey) ?? 'DefaultIcon';
        await _applyIconSafetyGuard(userPreference);
      }
    } catch (e) {
      print('Failed to synchronize Firebase Remote Config layer: $e');
    }
  }

  /// Evaluates and runs the method channel call only if a real delta is detected
  static Future<void> _applyIconSafetyGuard(String targetValue) async {
    final SharedPreferences prefs = await SharedPreferences.getInstance();
    final String currentlyActive = prefs.getString(_activeCachedKey) ?? 'DefaultIcon';
    // Guard Clause: Stop redundant channel triggers to avoid execution loops or app flash cycles
    if (currentlyActive == targetValue) return;
    print('Modifying launcher layout state from $currentlyActive to $targetValue');
    await DynamicIconService.changeIcon(targetValue);
    await prefs.setString(_activeCachedKey, targetValue);
  }
}

Step 3: Wiring It to the UI Layer & Lifecycle Boot

To wrap things up, initialize our syncing layer inside your app's main() startup routine, and build a quick selection UI.

import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
import 'app_icon_manager.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // Run the cloud check instantly at boot time
  await AppIconManager.syncCloudConfiguration();
  runApp(const MyApp());
}
class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: SettingsIconScreen(),
    );
  }
}
class SettingsIconScreen extends StatelessWidget {
  const SettingsIconScreen({super.key});
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Customize App Icon')),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text(
              'Select Your Preference:',
              style: TextStyle(fontSize: 18, fontWeight: FontWeight.bold),
            ),
            const SizedBox(height: 12),
            ListTile(
              leading: const Icon(Icons.phone_android),
              title: const Text('Default Classic Blue'),
              onTap: () => AppIconManager.updateUserIconPreference('DefaultIcon'),
            ),
            ListTile(
              leading: const Icon(Icons.dark_mode),
              title: const Text('Premium Minimalist Dark'),
              onTap: () => AppIconManager.updateUserIconPreference('DarkIcon'),
            ),
            ListTile(
              leading: const Icon(Icons.celebration),
              title: const Text('Festive Celebration Theme'),
              onTap: () => AppIconManager.updateUserIconPreference('FestiveIcon'),
            ),
          ],
        ),
      ),
    );
  }
}

Wrap Up & Cloud Control

Your application is now fully dual-controlled! To push a global theme override over the air:

Open the Firebase Console and head to Remote Config.
Create a parameter matching cloud_icon_override.
Set its value to FestiveIcon (or keep it as DefaultIcon to defer to your user's preferences).
Hit Publish Changes.

Flutter APNs Token Not Generating (Complete Fix Guide for iOS)

Codexlancers — Fri, 05 Jun 2026 05:00:00 +0000

There’s a very specific kind of frustration every Flutter developer hits when working with iOS push notifications:

👉 Everything is set up correctly
👉 Firebase is configured
👉 Permissions are granted
but still: APNs token is null or not generating at all.

If you’ve been stuck here - you’re not alone. This is one of the most common (and confusing) issues when integrating push notifications in Flutter apps.

In this guide, We’ll walk you through why this happens and how to fix it step-by-step - based on real debugging experience.

What is APNs Token (and Why It Matters)?

Before jumping into fixes, let’s quickly understand the basics.

APNs = Apple Push Notification service
The APNs token is a unique device identifier required for push notifications on iOS
Firebase Cloud Messaging (FCM) depends on it to send notifications to Apple devices

👉 No APNs token = No push notifications on iOS

Common Symptoms

If you’re facing this issue, you’ve probably seen:

getAPNSToken() returns null.
FirebaseMessaging.instance.getToken() works on Android but not iOS.
Foreground/background notifications not working on iOS.
No errors - just silent failure.

Complete Fix Guide (Step-by-Step)

Let’s fix this properly.

1️⃣ Enable Push Notifications in Xcode

This is the most commonly missed step.

Steps:

Open your Flutter iOS project in Xcode
Go to Runner → Signing & Capabilities
Add: Push Notifications , Background Modes → Enable Remote notifications

👉 Without this, APNs will never generate a token

2️⃣ Upload APNs Key to Firebase
Even if your app runs, Firebase won’t deliver notifications without this.

Steps:

Go to Firebase Console
Project Settings → Cloud Messaging
Upload: APNs Authentication Key (.p8) , Key ID, Team ID

👉 If this is missing → token may generate, but notifications won’t work

3️⃣ Request Notification Permission (iOS 10+)

iOS is strict. No permission = no token.

NotificationSettings settings =
    await FirebaseMessaging.instance.requestPermission(
  alert: true,
  badge: true,
  sound: true,
);

👉 Always call this before fetching token

4️⃣ Ensure You Are Testing on a Real Device

This one catches a lot of developers.
❌ APNs does NOT work on iOS Simulator
✅ Only works on real iPhone/iPad

5️⃣ Wait for APNs Token Before Fetching FCM Token

Sometimes the issue is just timing.

String? apnsToken = await FirebaseMessaging.instance.getAPNSToken();

print("APNS Token: $apnsToken");

👉 If it’s null, add a delay or retry:

Future<void> fetchAPNSToken() async {
  String? token;
  int retries = 0;

  while (token == null && retries < 5) {
    await Future.delayed(Duration(seconds: 2));
    token = await FirebaseMessaging.instance.getAPNSToken();
    retries++;
  }

  print("Final APNS Token: $token");
}

6️⃣ Check AppDelegate Configuration

Make sure your AppDelegate.swift is properly set up.

import UIKit
import Flutter
import Firebase

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    FirebaseApp.configure()
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

7️⃣ Disable Method Swizzling (If You Know What You’re Doing)

If you’ve disabled Firebase swizzling:

FirebaseAppDelegateProxyEnabled = NO

Then you MUST manually handle APNs token:

Messaging.messaging().apnsToken = deviceToken

👉 Otherwise, token will never be registered

8️⃣ Check Bundle Identifier Matches Everywhere

Make sure this matches in:

Apple Developer Account
Xcode project
Firebase project

👉 Even a small mismatch = token issues

9️⃣ Clean & Rebuild Project

Sometimes it’s just caching issues.

flutter clean
flutter pub get
cd ios
pod install

Then rebuild from Xcode.

🔍 Debug Checklist (Quick Summary)

If you’re still stuck, check this:

Real device used
Push Notifications enabled in Xcode
Background modes enabled
APNs key uploaded to Firebase
Permissions requested
AppDelegate configured correctly
Bundle ID matches
No swizzling misconfiguration

Final Thoughts

This issue feels tricky because:

There’s no clear error
Everything “looks” correct
Android works fine

But once you understand the flow:
👉 iOS Permission → APNs Token → FCM Token → Notification it becomes much easier to debug.

🔔 Flutter Push Notifications (Foreground, Background, Terminated) — Complete Fix Guide

Codexlancers — Tue, 02 Jun 2026 06:07:09 +0000

Push notifications in Flutter look easy…
until you actually try to implement them.

Everything seems fine - until:

Notifications don't show in foreground
Background handlers never trigger
And terminated state? Completely broken.

If you've been there… yeah, same

We've faced all of this while working on a production app, and this guide is the exact setup that finally worked.

First - Understand Notification States (This is where most people go wrong)
Before writing a single line of code, you need to understand this:

👉 Each state behaves differently. And if you treat them the same, things will break.

Basic Setup

1. Add dependencies

// pubspec.yaml

firebase_core: ^4.6.0
firebase_messaging: ^16.1.3
flutter_local_notifications: ^21.0.0

2. Initialize Firebase

Before using FCM, initialize Firebase when your app starts:

await Firebase.initializeApp();

3. Request Notification Permission

This step is mandatory on iOS and Android 13+.

FirebaseMessaging messaging = FirebaseMessaging.instance;

await messaging.requestPermission(
  alert: true,
  badge: true,
  sound: true,
);

Why is this important?

Starting from Android 13, Android requires explicit notification permission, similar to iOS.

If permission is not granted, notifications won't appear.

Android Notification Channel (Must for Android)

Without this, notifications may not show or may appear silently.

const AndroidNotificationChannel channel = AndroidNotificationChannel(
  'high_importance_channel',
  'High Importance Notifications',
  description: 'This channel is used for important notifications.',
  importance: Importance.high,
);

final FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin =
    FlutterLocalNotificationsPlugin();

await flutterLocalNotificationsPlugin
    .resolvePlatformSpecificImplementation<
        AndroidFlutterLocalNotificationsPlugin>()
    ?.createNotificationChannel(channel);

iOS Foreground Notification Setup

iOS requires this to properly show notifications in foreground:

await FirebaseMessaging.instance
    .setForegroundNotificationPresentationOptions(
  alert: true,
  badge: true,
  sound: true,
);

👉 Without this, notifications may not appear even if everything else is correct.

Foreground Notifications (Most Common Confusion)

The problem

You send a notification and nothing shows when the app is open.
Feels like it's broken, right?

The reality

FCM does NOT display notifications in foreground.

The fix

You must show it manually using local notifications:

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  showLocalNotification(message);
});

💡 This is where most developers get stuck initially.

Background Notifications

This is where things start working automatically, but only if you do it right.

Works automatically IF your payload includes:

{
  "notification": {
    "title": "Hello",
    "body": "World"
  }
}

⚠️ Using data-only payload?

Then you MUST handle it manually:

FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp(); // Required in background isolate
  print("Handling background message");
}

👉 Also, this function must be top-level.
(Not inside a class - easy mistake.)

Terminated State (Most Confusing Part)

This is where most implementations fail.

The issue

User taps notification → app opens → but nothing happens.

The fix

Handle the initial message:

RemoteMessage? initialMessage =
    await FirebaseMessaging.instance.getInitialMessage();

if (initialMessage != null) {
  handleNotificationClick(initialMessage);
}

Also listen when app is opened from background:

FirebaseMessaging.onMessageOpenedApp.listen((message) {
  handleNotificationClick(message);
});

👉 Without this, deep linking or navigation won't work.

Navigation Tip

handleNotificationClick() should:

Read payload data
Navigate to a specific screen

Local Notification Setup (Required for Foreground)

Without this, your foreground notifications will never show.

FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin =
    FlutterLocalNotificationsPlugin();

void showLocalNotification(RemoteMessage message) async {
  var androidDetails = AndroidNotificationDetails(
    'channel_id',
    'channel_name',
    importance: Importance.max,
    priority: Priority.high,
  );

  var generalNotificationDetails =
      NotificationDetails(android: androidDetails);

  await flutterLocalNotificationsPlugin.show(
    0,
    message.notification?.title,
    message.notification?.body,
    generalNotificationDetails,
  );
}

Common Mistakes (From Real Experience)

Not asking notification permission (Android 13+ especially)
Expecting foreground notifications to show automatically
Using only data payload and expecting UI
Background handler inside a class (won't work)
Forgetting getInitialMessage()

👉 We've personally hit almost all of these 😅

Final Thoughts

Push notifications in Flutter are not plug-and-play.
They require:

Proper setup
Understanding of app states
Correct payload structure

Key Takeaway

If your notifications are not working, 90% of the time:
👉 You didn't handle foreground manually
👉 OR your payload is wrong

If your notifications are not working on iOS or APNs token is not generating, check this:
👉 Flutter APNs Token Not Generating (Complete Fix Guide)

If this saved you hours of debugging, consider following for more Flutter deep dives.