Forem: Adrien Gras

I built Saloon PHP for Dart — because build_runner shouldn't be the price of clean API calls

Adrien Gras — Thu, 19 Feb 2026 12:33:59 +0000

Ten years of Symfony. Dozens of API integrations. Then I switched to Flutter — and suddenly, making a clean API call felt like a chore.

If you've ever used Saloon PHP, you know the feeling: one class per API, one class per endpoint, everything typed, testable, readable. No magic annotations. No generated files. Just clean OOP.

I went looking for the Dart equivalent. I didn't find it. So I built it.

The itch

In the PHP/Laravel world, Saloon gives you this kind of structure:

// One connector per API
class ForgeConnector extends Connector {
    public function resolveBaseUrl(): string {
        return 'https://forge.laravel.com/api/v1';
    }
}

// One request per endpoint
class GetServersRequest extends Request {
    protected Method $method = Method::GET;
    public function resolveEndpoint(): string {
        return '/servers';
    }
}

It's boring. It's explicit. It's wonderful to maintain six months later when you've forgotten everything about that API.

When I moved to Flutter, I expected something similar to exist. What I found instead was either scattered http.get() calls everywhere, or solutions that demand code generation.

What Dart has today

The two main options for structured API clients in Dart are Retrofit and Chopper. Both work. Both are mature. And both require build_runner.

Here's a typical Retrofit setup:

@RestApi(baseUrl: 'https://api.example.com')
abstract class ApiClient {
  factory ApiClient(Dio dio) = _ApiClient;

  @GET('/users')
  Future<List<User>> getUsers();

  @POST('/users')
  Future<User> createUser(@Body() CreateUserRequest request);
}

You annotate, you run dart run build_runner build, you wait, you get a _ApiClient class generated in a .g.dart file. It works.

But there's friction. The kind that compounds over time.

Every time you change a request, you re-run the generator. In CI, build_runner adds minutes. In large projects with multiple API clients, it adds many minutes. The generated files create noise in diffs. You can't just read the code — you have to read the code and the generated code and understand the annotation magic that connects them.

For some teams, that trade-off is fine. Code generation gives you compile-time safety and zero boilerplate for serialization. If your project already uses Freezed or json_serializable everywhere, adding Retrofit barely changes your workflow.

But I didn't want that workflow. I wanted the Saloon workflow.

What I wanted

The requirements were simple:

One class per API (Connector) — holds base URL, default headers, auth.
One class per endpoint (Request) — defines method, path, body, query params.
Zero code generation. No annotations, no .g.dart, no build step.
Type-safe body handling via mixins, not inheritance spaghetti.
Pluggable auth that I can swap at runtime (set the token after login).
My error handling, not Dio's. I decide when to throw.

That last point matters more than it seems. Dio throws DioException.badResponse for any 4xx/5xx by default. If you want to handle a 422 validation error differently from a 401, you're fighting the library instead of working with it.

Lucky Dart

Lucky Dart is what came out of it. Named after Lucky Luke — the cowboy who shoots faster than his shadow.

Here's the same API integration, Lucky-style:

import 'package:lucky_dart/lucky_dart.dart';

// 1. One Connector for the entire API
class ForgeConnector extends Connector {
  final String _token;
  ForgeConnector({required String token}) : _token = token;

  @override
  String resolveBaseUrl() => 'https://forge.laravel.com/api/v1';

  @override
  Authenticator? get authenticator => TokenAuthenticator(_token);
}

// 2. One Request per endpoint
class GetServersRequest extends Request {
  @override String get method => 'GET';
  @override String resolveEndpoint() => '/servers';
}

class CreateServerRequest extends Request with HasJsonBody {
  final String name;
  final String region;
  CreateServerRequest({required this.name, required this.region});

  @override String get method => 'POST';
  @override String resolveEndpoint() => '/servers';

  @override
  Map<String, dynamic> jsonBody() => {
    'name': name,
    'region': region,
  };
}

// 3. Use it
final forge = ForgeConnector(token: myToken);
final servers = await forge.send(GetServersRequest());
print(servers.jsonList());

No annotations. No generated files. No build step. You write it, it compiles, it works.

The body mixin pattern

This is the part that maps most directly from Saloon. Instead of one giant base class that tries to handle every content type, Lucky uses mixins:

// JSON body — sets Content-Type: application/json automatically
class CreateUser extends Request with HasJsonBody { ... }

// Form body — sets Content-Type: application/x-www-form-urlencoded
class LoginRequest extends Request with HasFormBody { ... }

// Multipart — sets Content-Type: multipart/form-data
class UploadAvatar extends Request with HasMultipartBody { ... }

// Also: HasXmlBody, HasTextBody, HasStreamBody

Each mixin does exactly two things: overrides body() to return your data, and overrides buildOptions() to set the correct Content-Type. That's it. No deep inheritance chain, no abstract factories. You mix in what you need.

The HasMultipartBody mixin returns a Future<FormData>, so you can read files from disk before the request fires. The HasStreamBody mixin requires a contentLength getter for the Content-Length header. Each one is a single-purpose module that does its job without affecting the others.

Auth that works at runtime

This was a real pain point. In many Flutter apps, you don't have a token when the app starts. You get it after login. Saloon handles this elegantly, and Lucky copies the approach:

class ApiConnector extends Connector {
  Authenticator? _auth;

  // Public setter — set the token after login
  set authenticatorOverride(Authenticator? auth) => _auth = auth;

  @override
  Authenticator? get authenticator => _auth;

  @override
  String resolveBaseUrl() => 'https://api.example.com';
}

// Login flow
final api = ApiConnector();
final login = await api.send(LoginRequest(email: email, password: password));
api.authenticatorOverride = TokenAuthenticator(login.json()['token']);

// All subsequent requests are authenticated
final profile = await api.send(GetProfileRequest());

authenticator is a getter, re-evaluated on every send() call. Swap it, and the next request picks it up. No need to rebuild the connector or reinitialize Dio.

You can also disable auth per request — essential for the login endpoint itself:

class LoginRequest extends Request with HasFormBody {
  @override bool? get useAuth => false; // skip auth for this one
  @override bool get logRequest => false; // don't log credentials
  // ...
}

Why validateStatus matters

This is the most important design decision in Lucky, and the one that took the longest to get right.

By default, Dio throws a DioException.badResponse for any HTTP response with a status code >= 400. This means your catch block receives a generic Dio exception that you then have to unwrap to figure out what actually happened. Was it a 401? A 422 with validation errors? A 500? You're back to if/else chains on the status code.

Lucky configures Dio with validateStatus: (_) => true. This tells Dio: "let everything through. I'll handle it."

_dio = Dio(BaseOptions(
  baseUrl: resolveBaseUrl(),
  validateStatus: (_) => true, // Lucky handles errors, not Dio
));

Then, in Connector.send(), Lucky checks the status code and throws typed exceptions:

try {
  final response = await connector.send(GetUserRequest(42));
  print(response.json()['name']);

} on NotFoundException catch (e) {
  // 404 — typed, specific
} on UnauthorizedException catch (e) {
  // 401 — handle token refresh
} on ValidationException catch (e) {
  // 422 — e.errors has the field-level details
  e.errors?.forEach((field, messages) {
    print('$field: $messages');
  });
} on LuckyException catch (e) {
  // Anything else — e.statusCode, e.response available
}

If you'd rather handle status codes manually, set throwOnError to false on the connector and check response.isSuccessful yourself.

The consequence: DioException.badResponse is never emitted. Only network failures and timeouts reach the catch (DioException) block. HTTP errors are Lucky's domain.

The endpoint pattern

For large APIs, Lucky supports grouping related requests into endpoint classes. This gives you a namespace-based API that reads like English:

class ApiConnector extends Connector {
  // ...
  late final users = UsersEndpoint(this);
  late final posts = PostsEndpoint(this);
}

// Usage
final api = ApiConnector(token: myToken);
await api.users.list();
await api.users.get(42);
await api.posts.create(title: 'Hello', content: 'World', userId: 1);

It's just a thin wrapper that groups send() calls. No new concepts, no new abstractions.

Logging without opinions

Lucky doesn't ship a logger. No dependency on logger, talker, or any third-party logging package. Instead, you wire callbacks:

class MyConnector extends Connector {
  @override bool get enableLogging => true;

  @override
  void Function({required String message, String? level, String? context})
    get onLog => ({required message, level, context}) {
      print('[$level] $message'); // or talker.log(), or Logger.d(), or whatever
    };
}

Your app, your logger, your rules. Lucky's LoggingInterceptor formats the output and respects per-request opt-out (logRequest: false for sensitive requests like login).

What it's not

Lucky is not a replacement for Retrofit if you need:

Automatic JSON serialization/deserialization to model classes. Lucky doesn't generate model mappings for you — but it's not raw either. The as<T>() helper maps responses into your models in a single expression:

// Single object
final user = response.as((r) => User.fromJson(r.json()));

// List of objects
final users = response.as(
  (r) => r.jsonList().map((e) => User.fromJson(e as Map<String, dynamic>)).toList(),
);

If you want zero manual mapping — not even a one-liner — Retrofit + json_serializable is the better choice. But if one line per endpoint feels like a fair trade for dropping build_runner entirely, Lucky is enough.

Code generation for dozens of endpoints. If your API has 200 endpoints and you'd rather annotate than write classes, Retrofit saves time. Lucky trades automation for readability — that's a conscious choice, not an oversight.
GraphQL. Lucky is REST-focused by design.

Lucky is a good fit when you want to understand your API layer by reading it. When you want to add a new endpoint without running a build command. When you're coming from PHP, Ruby, or Python and the OOP-first approach feels natural.

The numbers

The package ships with 112 tests (89 unit + 13 integration using a real dart:io HTTP server). dart analyze passes clean. Single runtime dependency: dio ^5.4.0. Dart SDK >=3.0.0 <4.0.0, Flutter-compatible.

It's published on pub.dev and the source is on GitHub.

Try it

dependencies:
  lucky_dart: ^1.0.0

import 'package:lucky_dart/lucky_dart.dart';

class MyApiConnector extends Connector {
  @override
  String resolveBaseUrl() => 'https://jsonplaceholder.typicode.com';
}

class GetPostsRequest extends Request {
  @override String get method => 'GET';
  @override String resolveEndpoint() => '/posts';
}

void main() async {
  final api = MyApiConnector();
  final posts = await api.send(GetPostsRequest());
  print('Got ${posts.jsonList().length} posts');
}

If you've ever used Saloon PHP and wished it existed in Dart, this is it. If you've never used Saloon but you're tired of build_runner, give it a spin.

Feedback, issues, and PRs welcome on GitHub.

Built by OwlNext, a worker cooperative in Dijon, France. We build custom software and break into systems for a living (legally).

"Please Clear Your Cache" — How I Finally Fixed Flutter Web Caching for Good

Adrien Gras — Fri, 13 Feb 2026 09:17:02 +0000

You know the drill. You deploy a shiny new version of your Flutter Web app. You ping the client: "It's live!" They open the app, and… nothing changed. Same old version. You sigh, and type the magic words:

"Could you please clear your browser cache?"

If you've shipped a Flutter Web app to real users, you've been there. I've been there more times than I'd like to admit. After months of fighting this, I finally built a solution that actually works in production. No more "clear your cache" messages. Ever.

Let me walk you through the journey.

Why Flutter Web Caching Is So Painful

Before diving into solutions, let's understand why this happens. It's not random — there's a very specific chain of failures.

When you run flutter build web, Flutter generates several files:

index.html — the entry point that loads everything
main.dart.js — your compiled Dart application
flutter_service_worker.js — a service worker that caches assets
canvaskit/ — the rendering engine
assets/ — your fonts, images, etc.

Flutter does generate content hashes for some of these files. So in theory, when you deploy a new build, the browser should detect the new hashes and fetch fresh files. In practice? It doesn't work reliably, and here's why:

The root cause is index.html itself. The browser caches index.html, which contains references to all other files. If the browser serves a stale index.html, it loads stale references, which point to stale assets. Even if you deployed new files, the user never sees them.

The service worker makes it worse. Once installed, the Flutter service worker aggressively caches everything. Even if index.html changes on your server, the service worker intercepts the request and serves the cached version. It's a cache guarding a cache.

Think of it like this:

User requests your app
        │
        ▼
   ┌─────────────┐      ┌──────────────────┐
   │   Browser    │────▶│  Service Worker    │
   │   Cache      │      │  Cache (stale)     │
   └──────┬──────┘      └────────┬─────────┘
           │                       │
           ▼                       ▼
   Stale index.html ──▶ Stale main.dart.js
                              │
                              ▼
                        User sees old app 😤

So how do you break this chain?

Attempt #1: The Query String Approach

The most common advice you'll find online is: "just add ?v=version to your script tags."

<script src="main.dart.js?v=1.2.3"></script>

It sounds logical. The browser sees a new URL, so it fetches a fresh file. And it works… sometimes.

The problems:

Some CDNs and proxies ignore query strings for caching purposes. Your Cloudflare, Varnish, or corporate proxy might serve the cached version regardless of ?v=.
You have to inject the version everywhere. Miss one reference and you get a Frankenstein app: half old, half new.
It doesn't solve the index.html problem. If index.html itself is cached, the browser never even sees your new ?v= parameter.

I used this for a while. It reduced complaints by maybe 50%. Not good enough.

Attempt #2: Nuking the Cache from JavaScript

My next idea was more aggressive: detect a new build from JavaScript, then wipe every cache before loading the app. Here's roughly what I wrote in flutter_bootstrap.js:

// Check version file, compare with stored build number
var xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", '/version.txt?v=' + Date.now(), true);

xmlhttp.onload = async function () {
  if (xmlhttp.status == 200) {
    var buildNumber = xmlhttp.responseText;
    var currentBuild = localStorage.getItem('buildNumber');

    if (!currentBuild || currentBuild !== buildNumber) {
      // Nuke all caches
      caches.keys().then((names) => {
        return Promise.all(names.map((name) => caches.delete(name)));
      });
      localStorage.setItem('buildNumber', buildNumber);
    }
  }
};

await xmlhttp.send(); // ← spot the bug?

setTimeout(() => { loadApp(); }, 200);

This worked better. On every page load, it fetches a version.txt file (with a timestamp to bypass cache), compares it to the stored version, and nukes the Cache API if there's a mismatch.

But it had a subtle and nasty bug: XMLHttpRequest.send() doesn't return a Promise. The await resolves immediately to undefined. That means setTimeout(loadApp, 200) starts running in parallel with the cache cleanup — not after it. On slow connections or large caches, loadApp() could fire before the caches were actually cleared.

It was a race condition hidden behind a 200ms prayer.

The Solution That Actually Works

After going through all this, I settled on a three-layer approach. Each layer handles a different part of the caching chain.

Layer 1: Path-Based Versioning (Build Script)

Instead of appending query strings, I change the actual path of every asset at build time. Every build gets its own unique directory name, and index.html references that directory.

The key part of the build script:

# Generate a unique version identifier
PACKAGE_VERSION="$(jq -r .version build/web/version.json)"
BUILD_NUMBER="$(jq -r .build_number build/web/version.json)"
RANDOM_SUFFIX="$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 12 | head -n 1)"
VERSION="build-${PACKAGE_VERSION}+${BUILD_NUMBER}-${RANDOM_SUFFIX}"

# Move all assets into the versioned directory
mkdir -p "$WEB_PATH/build"
rsync -a --exclude='build*/' "$WEB_PATH/" "$WEB_PATH/build/"

# Clean up non-build files from root (keep only HTML + build dir)
find "$WEB_PATH" -name 'build*' -prune -o \
     ! -path "$WEB_PATH" -exec rm -rf {} +

# Move HTML files back to root
mv "$WEB_PATH/build/"*.html "$WEB_PATH/"

# Rewrite all references in HTML to point to versioned path
find "$WEB_PATH" -type f -name "*.html" -exec sed -i \
  '/<base/! s|href="\([^"]*\)"|href="'"$VERSION"'/\1"|g' {} +

find "$WEB_PATH" -type f -name "*.html" -exec sed -i \
  's|src="\([^"]*\)"|src="'"$VERSION"'/\1"|g' {} +

# Create a symlink: version-name → build directory
ln -s "./build" "./$VERSION"

After this runs, your deployment looks like this:

web/
├── index.html          ← references build-1.2.0+42-a8f3b2c1d4e5/
├── build/              ← actual assets
│   ├── main.dart.js
│   ├── canvaskit/
│   ├── assets/
│   └── ...
└── build-1.2.0+42-a8f3b2c1d4e5 → ./build  (symlink)

Why is this better than query strings?

Every CDN and proxy respects path changes. A different URL path is always a cache miss. No exceptions.
Old cached index.html → old path → 404 → force refresh. If a user has a stale index.html, it references a path that no longer exists (or points to old files). The service worker can't serve what doesn't exist.
It's atomic. You don't need to remember to version each file individually. The entire build is under one versioned path.

Layer 2: Proper Cache Cleanup (Bootstrap JS)

Even with path versioning, there's one edge case: users who already have an installed service worker from a previous version. The old service worker might still intercept requests. So we still need the cache check — but done correctly this time:

async function checkAndClearCache() {
  if (!('serviceWorker' in navigator)) return;

  try {
    const response = await fetch('/version.txt?v=' + Date.now());
    if (!response.ok) return;

    const buildNumber = (await response.text()).trim();
    const currentBuild = localStorage.getItem('buildNumber');

    if (currentBuild && currentBuild === buildNumber) return;

    console.log('[CACHE] New build detected:', buildNumber);

    if ('caches' in window) {
      const names = await caches.keys();
      await Promise.all(names.map(name => caches.delete(name)));
      console.log('[CACHE] All caches cleared.');
    }

    localStorage.setItem('buildNumber', buildNumber);
  } catch (error) {
    console.warn('[CACHE] Version check failed:', error);
  }
}

window.addEventListener('load', async () => {
  await checkAndClearCache();
  loadApp();
});

function loadApp() {
  {{flutter_js}}
  {{flutter_build_config}}
  _flutter.loader.load();
}

The difference with my previous attempt: fetch() returns a real Promise, so await actually waits. No more race condition. loadApp() fires only after caches are confirmed cleared.

Layer 3: HTTP Headers (NGINX)

The final layer ensures the browser always checks for a fresh index.html and service worker, while caching everything else aggressively (since path versioning already handles invalidation):

location /app/ {
    # Always revalidate the entry points
    location ~ (index\.html|flutter_service_worker\.js)$ {
        add_header Cache-Control "no-cache, must-revalidate";
        try_files $uri =404;
    }

    # Versioned assets: cache forever (path changes on new builds)
    location ~* \.(js|css|woff2?|png|jpg|svg|ico)$ {
        add_header Cache-Control "public, max-age=31536000, immutable";
        try_files $uri =404;
    }
}

This is the simplest part, but also the most important. no-cache on index.html means the browser always checks with the server: "Is this still fresh?" If the server says yes (304 Not Modified), no download happens — it's just a lightweight HEAD request. But if there's a new build, the browser gets the new index.html, which points to the new versioned path, and everything flows.

The Three Layers Working Together

New deployment hits the server
        │
        ▼
  NGINX: "index.html? Always revalidate."
        │
        ▼
  Browser fetches fresh index.html
        │
        ▼
  index.html references build-1.3.0+43-x7k9m2p4q1w8/
        │
        ▼
  Path doesn't exist in cache → fresh download
        │
        ▼
  Bootstrap JS confirms new version → clears old caches
        │
        ▼
  User sees new app ✅

No query strings to manage. No race conditions. No stale service workers. No "please clear your cache."

Key Takeaways

Path-based versioning beats query strings. CDNs and proxies always respect path changes. Query strings? Not always.

XMLHttpRequest.send() does not return a Promise. If you're using await with XHR, you have a silent bug. Use fetch() instead.

Control your cache with HTTP headers, don't fight it. Let the browser cache aggressively for static assets (great for performance), but force revalidation on the two files that matter: index.html and the service worker.

Defense in depth. No single layer is bulletproof. Path versioning handles 95% of cases. The JS cleanup handles stale service workers. NGINX headers ensure the entry point is always fresh. Together, they cover every scenario I've encountered in production.

This setup has been running in production at OWLNEXT across multiple client projects for months, and we haven't heard "I don't see the update" since.

If you have a different approach or found edge cases I missed, I'd love to hear about it in the comments.