DEV Community: Ayesha Iftikhar

A Flutter App Startup That Never Waits on the Network

Ayesha Iftikhar — Mon, 02 Nov 2026 16:08:00 +0000

What runs before runApp() in Mindleau, in what order, and why every one of those awaits is local.

Short answer: In Mindleau, everything awaited before runApp() reads only from the device: Firebase's local config, the .env file, SharedPreferences and the SQLite database. Anything that needs the network, such as sync, ads, purchases and account cleanup, is started afterwards with unawaited() or a post-frame callback, and none of it can throw out of main(). The result is an app that opens the same way on a train with no signal as it does on Wi-Fi.

Most Flutter apps grow their main() one await at a time. Each line is reasonable on its own: initialize Firebase, load config, set up analytics, sign in, fetch remote config, start the ad SDK. Then one day someone opens the app in a lift and stares at the splash screen for twenty seconds.

Mindleau is a journaling app. People open it when their head is crowded, which is often when they're somewhere inconvenient. So the startup has one rule:

Nothing before runApp() is allowed to wait on the network.

Here's how the startup is structured to keep that rule, line by line.

The whole startup

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

  FlutterError.onError = ...;               // crash routing (below)
  PlatformDispatcher.instance.onError = ...;
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(false);

  await dotenv.load();
  final screenshotMode = dotenv.getBool('MINDLEAU_SCREENSHOT_MODE', fallback: false);

  final analytics = AnalyticsService(FirebaseAnalytics.instance, screenshotMode: screenshotMode);
  final purchases = await PurchaseService.initialize(screenshotMode: screenshotMode, analytics: analytics);
  final ads = await AdService.initialize(adsRemoved: purchases.adsRemoved);
  purchases.addListener(() => ads.adsRemoved.value = purchases.adsRemoved);
  final notifications = NotificationService();
  await notifications.initialize();

  final syncService = await FirebaseSyncService.initialize();
  final database = AppDatabase();
  final repository = SanctuaryRepository(database, syncService: syncService);
  await repository.initialize();

  purchases.bindIdentity(...);
  runApp(App(repository: repository, analytics: analytics, ads: ads, ...));
}

Here's what each await in that function actually touches:

Await	Touches
`Firebase.initializeApp`	Bundled config only. No network round trip.
`setCrashlyticsCollectionEnabled`, `dotenv.load`	Local files and flags.
`PurchaseService.initialize`, `AdService.initialize`, `FirebaseSyncService.initialize`	SharedPreferences, plus SDK setup that is either local or explicitly not awaited.
`notifications.initialize`, `repository.initialize`	Local plugins and the SQLite database.

The network work happens, but none of it is on this list.

Rule 1: optional SDKs initialize to "disabled", never to an exception

Ads, purchases and cloud sync are all optional from the user's point of view. Journaling works without any of them. So their initializers are written to never throw:

/// Never throws: a missing API key, unsupported platform or SDK failure
/// yields a disabled service, and the app keeps showing ads as before.
static Future<PurchaseService> initialize({...}) async {

Inside, every external call is wrapped, logged and turned into a state:

try {
  await Purchases.configure(PurchasesConfiguration(apiKey));
  service._configured = true;
  Purchases.addCustomerInfoUpdateListener(service._applyCustomerInfo);
  unawaited(service.refresh());   // network: not awaited
} catch (error, stackTrace) {
  log('RevenueCat configuration failed', name: 'mindleau.purchases',
      error: error, stackTrace: stackTrace);
}
return service;

The UI asks purchases.enabled and hides the buttons that can't work. A broken purchases SDK costs the business some revenue for a while. It never costs the user their journal.

The same pattern covers a missing .env key: dotenv.getBool(..., fallback: false) instead of the bare getBool, which throws when the key is absent.

Rule 2: heavy SDKs wait for the first frame

The Google Mobile Ads SDK is the heaviest thing Mindleau starts. Its initialization bootstraps a WebView-backed renderer that competes with Flutter for the GPU, and on a slow device or network it can take seconds. So AdService.initialize returns immediately and schedules the real work for after the first frame:

WidgetsBinding.instance.addPostFrameCallback((_) {
  unawaited(service._bootstrapSdk());
});
return service;

The launch screen dismisses, the first frame paints, and then ads warm up. And for users who bought Remove Ads, the SDK is never started at all, as I described in the in-app purchase article.

Rule 3: the database is the only thing the first screen needs

final database = AppDatabase();
final repository = SanctuaryRepository(database, syncService: syncService);
await repository.initialize();

AppDatabase opens SQLite lazily through Drift, running any pending schema migrations on first access. repository.initialize() seeds the bundled guided-session catalogue into the database, then starts the network work in the background:

Future<void> initialize() async {
  await _seedLearnSessions();                               // local

  unawaited(_syncService?.retryPendingAccountDeletion());   // network
  if (await _canAttemptCloudSync()) {
    unawaited(syncNow());                                   // network
  }
}

Because the UI only reads from the local database, the first screen is complete as soon as SQLite answers. When sync finishes later, Drift's query streams push the new rows to the screen on their own.

Rule 4: unfinished work is retried on every cold start

Some work can't finish when it's started. The clearest example is account deletion. If the connection is too slow when someone deletes their account, the local data is wiped immediately, and the server-side deletion is recorded as pending in SharedPreferences.

Every cold start retries it, unawaited, before anything else touches the server:

unawaited(_syncService?.retryPendingAccountDeletion());

Sync also checks it first, so new data is never pushed into an account that's supposed to be gone. (The details of that flow are in my Hashnode post on offline-first sync.) The general pattern: persist the intent locally, then retry until it succeeds, on startup and when connectivity returns. Don't make the user wait for the network to agree.

Rule 5: crash reporting is off until the user agrees, and quiet about the network

await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(false);

Crashlytics starts disabled. The welcome screen asks for consent, and Settings has a toggle. A journaling app shouldn't send anything anywhere before the user has said yes.

The error handlers are installed before anything else can fail, and they filter one specific kind of noise:

FlutterError.onError = (details) {
  if (isRecoverableFirebaseAuthError(details.exception)) {
    log('Ignored recoverable Firebase auth connectivity error.',
        name: 'mindleau.crashlytics');
    return;
  }
  FirebaseCrashlytics.instance.recordFlutterFatalError(details);
};

bool isRecoverableFirebaseAuthError(Object error) {
  return error is FirebaseAuthException &&
      error.code == 'network-request-failed';
}

Firebase Auth refreshes tokens in the background and reports network-request-failed as an unhandled error when the device is offline. For a local-first app that's expected behaviour, not a crash. Without the filter, the crash dashboard fills with "the user was on a plane", and the real crashes are harder to see. The filter is deliberately narrow: one exception type and one error code.

Rule 6: build-time modes are flags, not code branches

Store screenshots need deterministic data, no ads, no analytics and no review prompts. Rather than a separate build flavour, that's one .env flag read once in main():

final screenshotMode = dotenv.getBool('MINDLEAU_SCREENSHOT_MODE', fallback: false);

It's passed into the services that care: analytics turns itself off, purchases skip RevenueCat, and the repository seeds fictional fixture data. No service reads the flag on its own, so there's exactly one place to look when screenshots behave differently from the real app.

Rule 7: everything is passed in, so everything can be tested

Every service is constructed in main() and handed to App through its constructor, then exposed with provider. No service is a global singleton that reaches for FirebaseAuth.instance from inside a widget. The repository takes its SyncService as an interface:

final repository = SanctuaryRepository(database, syncService: syncService);

Tests construct the same repository with AppDatabase.forTesting(NativeDatabase.memory()) and a fake sync service that can be made slow, offline or failing on demand. The startup order in main() is the same dependency graph the tests build, just with real implementations.

How to check your own startup

Two quick tests show whether your startup has a network dependency hiding in it:

Cold start in flight mode. Force-quit, enable flight mode, open the app. It should reach a usable first screen as quickly as it does online.
Cold start on a terrible connection. Use the Network Link Conditioner (iOS) or an emulator's network throttling at "Very Bad Network" with packet loss. This is harsher than flight mode, because requests start and then hang instead of failing fast. Any await on the network before runApp() shows up here as a long splash screen.

If either one is slow, search main() for every await and ask what it touches. Usually it's one line, and the fix is an unawaited() and a state the UI can show.

You can read more about the app in the Mindleau case study, or see the related posts on one-time in-app purchases and offline-first sync failure cases. If you'd like your app's architecture reviewed, that's what my technical product consulting is for.

Encoding NDEF Records by Hand in Flutter — URIs, Text, vCards and Wi-Fi

Ayesha Iftikhar — Thu, 29 Oct 2026 05:59:34 +0000

Most Flutter NFC tutorials stop at "write a URL". When I built the encoding layer for an NFC app, I needed eleven record types, exact byte counts before writing, and records that every phone would read. Packages like nfc_manager give you the session and the tag; building the right bytes is still up to you.

This post walks through four record types — URI, text, vCard and Wi-Fi — at the byte level, with the Dart I ended up with.

A 30-second NDEF refresher

An NDEF message is a list of records. Each record has:

a TNF (Type Name Format): well-known (NFC Forum types like U and T), media (a MIME type), external, and so on
a type (e.g. U, or text/vcard)
an optional ID
a payload

With ndef_record/nfc_manager_ndef, building one looks like this:

ndef.NdefRecord(
  typeNameFormat: ndef.TypeNameFormat.wellKnown,
  type: Uint8List.fromList([0x55]), // 'U'
  identifier: Uint8List(0),
  payload: payloadBytes,
);

The interesting part is always the payload.

1. URI records: the one-byte prefix trick

The NFC Forum URI record (U, 0x55) starts its payload with a prefix code: one byte that stands for a common URI start. 0x04 means https://, 0x02 means https://www., 0x05 means tel:, 0x06 means mailto: — 36 entries in all, index 0 being "no prefix".

On an NTAG213 with 144 bytes of user memory, saving 12 bytes on https://www. matters.

const uriPrefixList = [
  '', 'http://www.', 'https://www.', 'http://', 'https://',
  'tel:', 'mailto:', /* … the rest of the NFC Forum table … */
];

static ndef.NdefRecord encodeUri(String uri) {
  var rest = uri;
  var prefixIndex = 0;
  for (var i = 1; i < uriPrefixList.length; i++) {
    if (rest.startsWith(uriPrefixList[i])) {
      prefixIndex = i;
      rest = rest.substring(uriPrefixList[i].length);
      break;
    }
  }
  return ndef.NdefRecord(
    typeNameFormat: ndef.TypeNameFormat.wellKnown,
    type: Uint8List.fromList([0x55]),
    identifier: Uint8List(0),
    payload: Uint8List.fromList([prefixIndex, ...utf8.encode(rest)]),
  );
}

Gotcha: order matters. https://www. must be checked before https://. The table's own order puts the www. variants first, so walking it in order does the right thing.

The same encoder handles phone (tel:), SMS (sms:), email (mailto:), social profiles and map locations (geo:lat,lng), because they're all just URIs.

2. Text records: a status byte you can't skip

Text records (T, 0x54) start with a status byte: bit 7 = encoding (0 for UTF-8), low 6 bits = length of the language code that follows. Then the language code, then the text.

static ndef.NdefRecord encodeText(String text) {
  final lang = utf8.encode('en');
  final status = lang.length; // bit 7 clear = UTF-8
  return ndef.NdefRecord(
    typeNameFormat: ndef.TypeNameFormat.wellKnown,
    type: Uint8List.fromList([0x54]),
    identifier: Uint8List(0),
    payload: Uint8List.fromList([status, ...lang, ...utf8.encode(text)]),
  );
}

If you forget the status byte, some readers show the first character of your text as garbage, and others drop the record entirely.

3. vCards: just a media record

Contact cards aren't an NFC Forum type. They're a media record whose type is the MIME string text/vcard and whose payload is the vCard text:

static ndef.NdefRecord encodeMedia(String mimeType, String data) {
  return ndef.NdefRecord(
    typeNameFormat: ndef.TypeNameFormat.media,
    type: Uint8List.fromList(utf8.encode(mimeType)),
    identifier: Uint8List(0),
    payload: Uint8List.fromList(utf8.encode(data)),
  );
}

That's simple to write, but vCards get big fast. A card with name, title, company, phone, email, website and a few social URLs easily passes 144 bytes, so it won't fit an NTAG213. NTAG215 (504 bytes) is the practical minimum. Because each record can be encoded before writing, the app can show the exact size and warn before a write fails halfway.

4. Wi-Fi: TLVs inside a MIME record

Wi-Fi credentials use the Wi-Fi Alliance's Simple Configuration format: a media record of type application/vnd.wfa.wsc whose payload is nested TLVs (2-byte type, 2-byte length, value, all big-endian).

The outer TLV is a Credential (0x100E) containing:

TLV	Type	Value
Network Index	`0x1026`	`1`
SSID	`0x1045`	network name, UTF-8
Auth Type	`0x1003`	`0x0020` WPA2-Personal, `0x0001` open
Encryption Type	`0x100F`	`0x0008` AES, `0x0002` WEP, `0x0001` none
Network Key	`0x1027`	password (omitted for open networks)
MAC Address	`0x1020`	`FF FF FF FF FF FF` (any)

static List<int> _u16(int v) => [(v >> 8) & 0xff, v & 0xff];
static List<int> _tlv(int type, List<int> value) =>
    [..._u16(type), ..._u16(value.length), ...value];

final credential = [
  ..._tlv(0x1026, [1]),
  ..._tlv(0x1045, utf8.encode(ssid)),
  ..._tlv(0x1003, _u16(0x0020)), // WPA2-Personal
  ..._tlv(0x100F, _u16(0x0008)), // AES
  ..._tlv(0x1027, utf8.encode(password)),
  ..._tlv(0x1020, List.filled(6, 0xff)),
];
final payload = _tlv(0x100E, credential);

Platform note: Android's NFC stack reads this record and offers to join the network. iPhones don't join Wi-Fi from NFC tags, so if your users include iPhone owners, pair the tag with a Wi-Fi QR code.

Count bytes before you write

Every encoder above returns a real NdefRecord, so NdefMessage(records: [...]).byteLength gives the exact size before you touch a tag. Compare that with the tag's capacity (the app reads it during the scan) and you can refuse an oversized write with a clear message, instead of a vague platform error halfway through.

Wrapping up

The NDEF spec is small enough to implement by hand, and doing so pays off. You control every byte, you can test encoders without hardware, and you can tell users exactly what fits on their tag.

I built this for NFC Wizard, an NFC toolkit for iPhone and Android - Coming Soon(disclosure: it's my app). If you're choosing tags for a project, I wrote a plain-language guide to NTAG213 vs NTAG215 vs NTAG216 and one on writing Wi-Fi to a tag.

Offline-First Sync Failures That Flight Mode Won't Show You

Ayesha Iftikhar — Mon, 26 Oct 2026 09:02:00 +0000

*Clock skew, deletes that come back, duplicate entries on a flaky connection, and old databases: the tests I added after auditing my own Flutter app.
*

Short answer: Testing offline-first sync by switching on flight mode only tests the polite case: the network is either there or it isn't. The bugs that lose people's data come from messier conditions: a device with the wrong clock, a delete on one phone while another phone edits the same entry, a connection that drops just after a write was sent, two syncs running at once, and a database created by an older version of the app. This post walks through each one in a real Flutter app, what goes wrong under last-write-wins, and the fix.

I build Mindleau, a brain dump journal and mood tracker. It's local-first: every entry is written to SQLite (via Drift) on the phone, and a sync layer pushes it to Firestore in the background. I've written about the local-first architecture and about anonymous auth, tombstones and timeouts.

Those posts describe the design. This one is about testing it against conditions that are worse than "offline". I went through my own sync code looking for the cases that would lose someone's journal entry, and found more than I expected.

The design under test

Briefly, so the failures make sense:

Every row has an updatedAt timestamp (set from the device clock), a syncStatus (synced, pending_create, pending_update) and, for deletes, a deletedAt tombstone.
A sync runs pull, then push. Pull fetches remote rows and merges them: the local row is kept only if its updatedAt is newer, otherwise the remote row replaces it. Push sends every non-synced row with set(..., merge: true).
Each row gets a remoteId (a UUID) the first time it's pushed.

That's last-write-wins (LWW), the default for most hand-rolled sync. It's simple and it's usually fine. Here's where it isn't.

1. The device with its clock ahead

LWW compares timestamps from two different clocks. If one phone's clock runs an hour fast, its edits beat every other device's edits for an hour, even edits made later in real time.

In code, the merge looks like this:

final remoteUpdatedAt = _parseRemoteDate(row['updated_at']) ?? now;
final existing = await (_database.select(_database.brainDumpRows)
      ..where((t) => t.remoteId.equals(remoteId)))
    .getSingleOrNull();
if (existing != null && existing.updatedAt.isAfter(remoteUpdatedAt)) return;
// otherwise: overwrite local with remote

Notice what it doesn't check: whether the local row has an edit that hasn't been pushed yet. Phone B edits an entry offline. Phone A (clock fast) edited it earlier. B reconnects, pulls first, sees A's "newer" timestamp, and overwrites its own unpushed edit. Nobody is told.

The test: inject the clock. Make DateTime.now() a dependency of the repository so tests can give each simulated device its own skew. Edit the same entry on both, sync both, and assert that both pieces of text still exist somewhere.

The fix: two parts. Use a server timestamp (Firestore's FieldValue.serverTimestamp()) as the ordering for remote writes, so the server orders writes instead of trusting phone clocks. And never overwrite a row that is still pending locally. That's a conflict, and conflicts get the treatment in section 3.

2. A delete on one phone, an edit on the other

Tombstones solve the classic problem of a deleted row being downloaded again. They don't solve this one:

Phone A, offline, deletes an entry: deletedAt = 10:00, updatedAt = 10:00.
Phone B, online, edits the same entry at 10:05 and syncs. Its push sends deleted_at: null.
Phone A reconnects. Pull sees remote updated_at = 10:05, which is newer, and replaces the local row, including deletedAt = null.

The entry the user deleted comes back. In a journal, that's worse than losing an edit. People delete entries because they don't want them to exist.

Reverse the order (edit first, delete later) and the edit is silently lost instead. Both orderings, and the case where the timestamps are equal, need a test.

The fix: treat delete-versus-edit as a conflict instead of letting a timestamp decide it. My rule is that an edit made after a delete keeps the entry alive, but as a conflict copy the user can see and delete again. Being asked twice is better than losing the text, and much better than the deleted text coming back unannounced.

3. Conflict copies before CRDTs

When two devices change the same entry, there are three options:

Pick a winner (LWW). Simple, and silently loses one side.
Merge automatically (CRDTs, operational transforms). Correct for collaborative editing, but heavy machinery for one person writing free text on two phones.
Keep both and let the person decide.

For a personal journal, option 3 is the right middle ground. Conflicts are rare, the user is the only author, and they know which version they meant. The rule:

If the local row is pending and the remote row changed since the last sync, don't overwrite. Save the local version as a new entry marked "conflicted copy", then accept the remote version.
Show conflicted copies plainly in the history so the user can keep, merge or delete them.

That's a few dozen lines in the merge function and no new dependencies. If the app ever becomes collaborative, that's the time for a CRDT.

4. The connection that comes back just long enough

Flight mode is binary. Real connections aren't: a train goes through a tunnel, a café's Wi-Fi accepts the request and drops the response. This is the case I found the most interesting, because it creates duplicates.

Here's the push for a new entry:

for (final row in rows) {
  final remoteId = row.remoteId ?? _uuid.v4();
  await service.upsertBrainDump({'id': remoteId, ...});
  // only now is remoteId saved locally:
  await (_database.update(_database.brainDumpRows)
        ..where((t) => t.id.equals(row.id)))
      .write(BrainDumpRowsCompanion(remoteId: Value(remoteId), ...));
}

Every network call has a 15-second timeout, which is right: without one, a flaky connection leaves the app stuck on a spinner. But a timeout only means we stopped waiting. Firestore may already have queued the write, and it lands later. The local row never saved its remoteId, so the next sync generates a new UUID and pushes the same entry again. On the user's other phone, it now appears twice.

The general rule: an operation that can be retried must be idempotent, and its identity has to exist before the first attempt. The fix is to assign the remoteId when the row is created (or save it before pushing), so a retry overwrites the same document instead of creating a new one.

The test: a fake sync service that applies the write and then throws a timeout. Run sync twice and assert one remote document, not two.

5. Two syncs at once

Sync starts after every save, and again whenever connectivity comes back. On a flapping connection those overlap. With no guard, two syncs can both read the same pending row, both generate a UUID, and both push. That's the same duplicate as above, through a different door.

The fix is a single in-flight sync that other callers wait on:

Future<void>? _inFlight;

Future<void> syncNow() {
  return _inFlight ??= _runSync().whenComplete(() => _inFlight = null);
}

If something changes while a sync is running, mark it dirty and run once more when it finishes, rather than starting a parallel one.

6. An old database that already holds someone's journal

A fresh install is the easiest test case and the least realistic one. The users who matter most have a database written by an older version of the app, with real entries in it.

Mindleau's schema is on version 5. The migration from version 1 added sync columns like this:

ALTER TABLE brain_dump_rows ADD COLUMN updated_at INTEGER NOT NULL DEFAULT 0

DEFAULT 0 is the Unix epoch, 1 January 1970. Every row that existed before the upgrade claims it was last edited in 1970, so under LWW any remote copy of it wins, including a stale one. Not a problem on a fresh install, and a real problem on an upgraded one.

The test: check in a real database file from each old schema version (Drift can generate schema snapshots for this with drift_dev schema dump), fill it with entries, run the migration, then run a sync against a remote that holds older versions of the same entries. Assert the local text survives. The backfill fix is one statement in the migration: set updated_at = created_at where it's 0.

7. "Saved on this phone" is not "backed up"

Not a sync bug, but a product one that the sync design creates. Local-first apps make two different promises:

Saved on this phone: written to SQLite, survives restarts and offline use.
Backed up: pushed to the server, and restorable if the phone is lost.

Mindleau shows a "pending changes" count in Settings, but nowhere near the entry itself. There's also a third state that's easy to miss: an entry synced to an anonymous account is on the server, but the user can't restore it on a new phone until they link an email. Calling that "backed up" promises something the app can't deliver.

The interface should say which promise has actually been kept, per entry or at least on the main screen: saved on this phone, backed up, or backed up, add an email to restore it anywhere.

The test list

If you're testing an offline-first app, flight mode is the first test, not the last. This is the list I'd start from:

An upgrade from every old schema version, with real data in it.
Two devices editing the same entry offline, then syncing in both orders.
A device with its clock ahead (and one behind).
A delete on one device while another edits the same entry, in both orders and with equal timestamps.
A write that succeeds on the server but times out on the client, then a retry.
Two syncs started at once.
The app killed between "pushed" and "marked as synced".

None of these show up in a demo. They're the difference between an app people trust with their private thoughts and one they quietly stop using.

You can read more about the app in the Mindleau case study. If you're building something local-first and want the sync reviewed against cases like these, that's part of my technical product consulting.

Adding a One-Time "Remove Ads" Purchase to a Local-First Flutter App

Ayesha Iftikhar — Mon, 19 Oct 2026 07:00:14 +0000

Short answer: Mindleau sells "Remove Ads" as a single non-consumable purchase through RevenueCat. A PurchaseService owns the entitlement and caches it on the device. A single ValueNotifier<bool> on the AdService gates every banner, interstitial and app-open ad. If the user has already paid, the Google Mobile Ads SDK is never started. The RevenueCat customer is tied to the app's Firebase user ID, so a purchase follows the person, not the install.

Mindleau is a free brain dump journal and mood tracker for iOS and Android. Every feature is free and there is no subscription. It's paid for by a small number of ads, kept out of writing and reflection moments. Some people would rather pay once than see any ads at all, so I added one in-app purchase: Remove Ads.

It sounds like a small feature. The purchase itself is one API call. The architecture around it is where the decisions are, and those decisions are what this post is about.

The requirements

I wrote these down before choosing anything:

One-time, not a subscription. Pay once, never see an ad again, nothing to cancel.
No account required to buy. Mindleau doesn't have a login wall, and the purchase shouldn't add one.
A paying user must never see an ad. Not on a cold start, not while offline, not for the half-second before the store SDK answers.
Restorable on a new phone, using the store's own restore flow.
The app must work if purchases are broken. A missing key, an unsupported platform or a store outage means "show ads as before", not a crash.
Deleting an account must remove the person from the purchase backend too.

Why RevenueCat instead of `in_app_purchase`

Flutter's official in_app_purchase plugin can do a non-consumable purchase. What it doesn't do is answer the question "does this user own it?" reliably. You either trust the device's purchase history or build receipt validation on a server.

RevenueCat validates receipts on its servers and gives you an entitlement: a named yes or no (ads_free) that you can check from any platform. Its free tier covers an app at Mindleau's scale, and it saves me from running a validation backend for an app that otherwise doesn't need one.

The cost is another third-party SDK that receives an identifier for the user. That has to be listed in the privacy policy and in the store privacy labels.

The shape of it

            ┌───────────────────┐
            │  PurchaseService  │  owns: adsRemoved (cached), the package, identity
            └─────────┬─────────┘
                      │ addListener
                      ▼
            ┌───────────────────┐
            │     AdService     │  adsRemoved: ValueNotifier<bool>
            └─────────┬─────────┘
          ┌───────────┼─────────────┐
          ▼           ▼             ▼
       banners   interstitials   app-open

Two services, one direction. PurchaseService knows about RevenueCat and nothing about ads. AdService knows about AdMob and nothing about purchases. main.dart connects them with one line:

final purchases = await PurchaseService.initialize(
  screenshotMode: screenshotMode,
  analytics: analytics,
);
final ads = await AdService.initialize(adsRemoved: purchases.adsRemoved);
purchases.addListener(() => ads.adsRemoved.value = purchases.adsRemoved);

The order matters. Purchases are initialized before ads, so AdService already knows on its first line whether this user has paid.

Requirement 3: no ad flash on a cold start

RevenueCat answers over the network. Ask it "does this user own ads_free?" at launch and you'll wait somewhere between 100 ms and forever, depending on the connection. If you show ads while you wait, paying users see ads, which is the one thing they paid to avoid.

So the last known answer is cached in SharedPreferences and read synchronously at startup:

final service = PurchaseService._(
  entitlementId: entitlementId,
  prefs: prefs,
  analytics: analytics,
  adsRemoved:
      !screenshotMode && (prefs?.getBool(_adsRemovedPrefsKey) ?? false),
);

RevenueCat is then configured, and the real answer is fetched in the background with unawaited(service.refresh()). Every time RevenueCat reports customer info, whether from a purchase, a restore, a refresh or its own update listener, it goes through one function:

void _applyCustomerInfo(CustomerInfo info) {
  final adsRemoved = info.entitlements.active.containsKey(entitlementId);
  if (adsRemoved == _adsRemoved) return;
  _adsRemoved = adsRemoved;
  unawaited(_prefs?.setBool(_adsRemovedPrefsKey, adsRemoved));
  notifyListeners();
}

There's one writer for the cached value and one place that notifies. The cache can't drift from what the UI shows.

The trade-off: the cache is trusted until RevenueCat says otherwise. If someone is refunded while offline, they keep an ad-free app until the device reconnects. For a "remove ads" product that's the right side to err on: the cost of a wrong "yes" is a few ad impressions, and the cost of a wrong "no" is a paying customer seeing ads.

Don't even start the ad SDK for paying users

Starting the Google Mobile Ads SDK isn't free. It spins up its own WebView-backed renderer, which competes with Flutter for the GPU during the first frame. If the user has paid, there's no reason to pay that cost:

if (!service.enabled || adsRemoved) {
  service._sdkReady.complete();
  return service;
}

_sdkReady is completed anyway, so any code awaiting it moves on. It just never gets an ad.

One gate for every ad format

Mindleau has three ad formats, and each one has its own load and show path. Every one of those paths checks the same notifier:

if (!enabled || !interstitialEnabled || adsRemoved.value) return;

When a purchase completes mid-session, ads that are already loaded have to go too, not only future ones:

void _onAdsRemovedChanged() {
  if (!adsRemoved.value) return;
  _pendingLaunchAppOpenShow = false;
  _interstitialAd?.dispose();
  _interstitialAd = null;
  _appOpenAd?.dispose();
  _appOpenAd = null;
}

Banners are widgets, so they listen to the same ValueNotifier and collapse when it flips. The user taps "Remove Ads", the store sheet closes, and the banner under their journal is gone, with no restart needed.

Note the asymmetry: removing ads takes effect immediately, while restoring ads after a refund only happens on the next cold start, because the SDK was never started. That's deliberate. It keeps the "never show a paying user an ad" path simple.

Requirement 2 and 4: identity without a login wall

Mindleau already has a user ID for everyone: the Firebase Auth UID, anonymous until the user links an email. RevenueCat lets you log in a customer with your own ID, so the purchase is attached to that UID.

The tricky part is when. The Firebase user can appear after RevenueCat is configured (first launch), change (email restore on a new phone) or disappear (account deletion). So PurchaseService doesn't take an ID. It takes a function that reads the current one, plus a stream that says "it might have changed":

purchases.bindIdentity(
  read: () async => (
    userId: repository.userId,
    displayName: await repository.displayName(),
  ),
  changes: repository.syncStateChanges,
);

syncIdentity() is idempotent and cheap. It remembers what it last sent and skips anything already in sync. That makes it safe to call often, and it's called in three places: at startup, on every identity change, and right before every purchase or restore. The last one matters. If the identity sync failed earlier because the user was offline, the purchase still lands on the right customer.

Future<PurchaseOutcome> purchaseRemoveAds() async {
  final package = _removeAdsPackage;
  if (!enabled || package == null) return PurchaseOutcome.unavailable;
  await syncIdentity();
  // ...
}

Restore uses the store's own mechanism (Purchases.restorePurchases()), which works from the App Store or Google Play account, so a user who never linked an email can still restore on a new phone.

Requirement 6: account deletion reaches the purchase backend

When someone deletes their Mindleau account, the RevenueCat customer shouldn't keep their Firebase ID and display name. After the Firebase account is deleted:

Future<void> clearIdentity() async {
  _syncedUserId = null;
  _syncedDisplayName = null;
  if (!enabled) return;
  try {
    if (await Purchases.isAnonymous) return;
    // An empty value deletes the reserved $displayName attribute.
    await Purchases.setDisplayName('');
    _applyCustomerInfo(await Purchases.logOut());
  } catch (error) {
    log('Identity reset failed: $error', name: 'mindleau.purchases');
  }
}

syncIdentity() also calls this on its own if it sees the Firebase UID go from a value to null, so deletion paths I haven't thought of are still covered.

One consequence to be honest about: after deleting their account, a paying user is a fresh anonymous customer with no entitlement, so ads come back until they tap Restore Purchases. The store account still owns the purchase, so nothing is lost.

Requirement 5: purchases must fail closed, to "ads as before"

PurchaseService.initialize never throws. A missing API key, an unsupported platform (web, desktop) or an SDK error produces a disabled service:

/// Never throws: a missing API key, unsupported platform or SDK failure
/// yields a disabled service, and the app keeps showing ads as before.

The settings tiles for Remove Ads and Restore Purchases are hidden when enabled is false, so nobody taps a button that can't work.

Purchase results are an enum, not a boolean or an exception:

enum PurchaseOutcome { success, cancelled, nothingToRestore, failed, unavailable }

A boolean can't tell "the user changed their mind" from "the store is down", and the UI should respond very differently to each: silence for a cancel, a gentle message for "nothing to restore", an error for a failure. The enum makes the UI handle every case, and the compiler checks the switch.

Measuring it

Purchase analytics are logged inside PurchaseService, not in the UI, so every path is counted the same way:

remove_ads_purchase_started, remove_ads_purchased (with price and currency), remove_ads_purchase_cancelled, remove_ads_purchase_failed (with error code)
purchases_restore_started, purchases_restored, purchases_restore_failed

One case is worth calling out: the store reports success but the entitlement isn't active (for example a misconfigured product in the RevenueCat dashboard). That's logged as a failure with entitlement_inactive, because from the user's point of view it is one.

What I'd do the same way again

Cache the entitlement and trust it at launch. It's the only way to guarantee no ad flash.
One notifier, checked by every ad path. Ad formats get added over time; a single gate keeps them honest.
Identity as a function plus a change stream, re-synced before every purchase.
Never-throwing initializers for every optional SDK. Monetization breaking should never break journaling.

If you're adding monetization to a Flutter app and want a second pair of eyes on the architecture, you can read the Mindleau case study or see how I help with technical product consulting.

Compressing PDFs entirely in the browser with pdf.js, OffscreenCanvas and a Web Worker

Ayesha Iftikhar — Wed, 30 Sep 2026 13:38:22 +0000

Most "free online PDF compressor" sites work the same way: you upload the file, a server shrinks it, and you download the result. When I built PDF Perfect, I wanted the opposite. The file should never leave the user's device, and you should be able to prove that by switching your Wi-Fi off halfway through.

Merging, splitting and rotating in the browser are fairly well-trodden: pdf-lib copies pages between documents without re-encoding anything. Compression was the interesting part, so this post covers how it works, the trade-offs I accepted, and what I'd do differently.

Why compression is hard in the browser

Desktop tools like Ghostscript compress a PDF by walking its object tree: they downsample embedded images, subset fonts and strip unused objects. That needs a full PDF rewriter with image codecs, and there's no small, well-maintained JavaScript library that does all of it.

What the browser does have is an excellent PDF renderer (Mozilla's pdf.js, the one inside Firefox) and a fast JPEG encoder (canvas.convertToBlob). So the approach is:

Render each page to a canvas at a chosen scale.
Encode the canvas as a JPEG at a chosen quality.
Build a new PDF where each page is just that image.

It's a rasterising compressor. For scans and photo-heavy PDFs, which are the files people actually need to shrink, it works very well. For text documents it has a real cost, which I'll come back to.

Keeping it off the main thread

Rendering 200 pages blocks the main thread for a long time, so it all runs in a Web Worker. Workers don't have a DOM, but they do have OffscreenCanvas, and pdf.js can render into one.

The core loop, simplified from the real worker:

const pdf = await pdfjsLib.getDocument({ data: arrayBuffer }).promise;
const outDoc = await PDFDocument.create(); // pdf-lib
const canvas = new OffscreenCanvas(1, 1);
const ctx = canvas.getContext("2d");

for (let i = 1; i <= pdf.numPages; i++) {
  const page = await pdf.getPage(i);
  const viewport = page.getViewport({ scale });

  canvas.width = viewport.width;
  canvas.height = viewport.height;
  await page.render({ canvas, viewport }).promise;

  const jpeg = await canvas
    .convertToBlob({ type: "image/jpeg", quality })
    .then((b) => b.arrayBuffer());

  const image = await outDoc.embedJpg(jpeg);
  outDoc
    .addPage([image.width, image.height])
    .drawImage(image, { x: 0, y: 0, width: image.width, height: image.height });

  postMessage({ type: "progress", progress: Math.round((i / pdf.numPages) * 100) });
}

const bytes = await outDoc.save();

A few details that matter more than they look:

One canvas, reused. The worker creates a single OffscreenCanvas and resizes it for each page, rather than allocating a new canvas per page, which keeps memory steadier on long documents.
Transfer, don't copy. The result goes back to the main thread as an ArrayBuffer in the transfer list, so a 300 MB output isn't duplicated.
A timeout. The main thread gives the worker 5 minutes. A tab that silently spins forever on a huge file is worse than a clear error.
The pdf.js worker inside my worker. pdf.js wants its own worker script. Importing it with Vite's ?url suffix and setting GlobalWorkerOptions.workerSrc works in both dev and production builds, but the server has to send .mjs files as text/javascript. My Apache host didn't, and the result was a very confusing production-only failure.

Quality levels and "compress to 1 MB"

The three presets are just (JPEG quality, render scale) pairs:

Preset	JPEG quality	Scale
High Quality	0.82	1.0
Balanced	0.6	0.85
Maximum	0.4	0.75

Users often don't care about presets, though. They have a job portal that says "max 2 MB". So there's a Target File Size mode, which walks a ladder of five settings from best to smallest and returns the first result that fits:

for (const settings of ladder) {
  const result = await attempt(settings);
  if (result.compressedSize <= targetBytes) return result;
  smallest = !smallest || result.compressedSize < smallest.compressedSize ? result : smallest;
}
return smallest; // couldn't hit the target; show how close we got

A binary search over quality would need fewer passes. But with only five meaningful steps and output size that doesn't change smoothly with quality, the linear ladder was simpler to reason about and gives the user the best-looking file that fits.

The trade-off I had to be honest about

Rasterising means text in the compressed file is no longer text. You can't select it, search it or have a screen reader read it, and at scale 1.0 very small print looks soft when you zoom in. For a scanned form that's irrelevant. For a 40-page contract exported from Word, it's a real loss, and the file can even get bigger, because vector text is tiny.

So the UI shows before and after sizes up front, the docs say plainly what happens, and the guides recommend re-exporting text documents from the source app instead. I'd rather lose a user to the right tool than hand them a worse file.

Proving the file never leaves

"We don't upload your files" is easy to claim, so I wanted it to be easy to check:

Offline test: load a tool, turn off Wi-Fi and process a file. It still works. (For compression, pdf.js is lazy-loaded, so run it once while online first.)
Network tab: process a file with DevTools open. You'll see the page, fonts and analytics, and no request with a body anywhere near your file's size.

The How it works page walks through both tests.

What I'd do next

A structural compressor for text PDFs: downsample only the embedded images with pdf-lib and leave the text alone. It's harder, but it's the right answer for Word exports.
A streaming approach for very large files, since the whole document is currently held in memory.

If you want to try it, the compressor is here. I'd love feedback from anyone who's fought pdf.js in a worker too.

I'm the developer of PDF Perfect.

How Uber Computes Estimated Time of Arrival (ETA)

Ayesha Iftikhar — Sat, 26 Sep 2026 17:05:43 +0000

Short answer: how does Uber compute ETA?
Uber snaps noisy GPS pings to the road network (map matching), finds candidate routes on a road graph, and predicts travel time for each road segment with machine-learning models fed by real-time traffic. It then sums and corrects the route estimate, models its uncertainty, and keeps refreshing the Uber ETA as the trip progresses.

For a ride-hailing platform like Uber, Estimated Time of Arrival (ETA) is not a cosmetic feature. It is a core real-time decisioning system that directly influences conversion, matching quality, pricing behavior, and user trust.

An inaccurate ETA increases cancellations, reduces marketplace liquidity, and weakens reliability perception. At scale, even small percentage errors can have measurable business impact.

1. Problem Definition

Uber must estimate two different time horizons:

Pickup ETA: Time for the driver to reach the rider
Trip ETA: Time from pickup to destination

This happens under hard constraints: real-time computation, global traffic variability, sparse-data regions, continuous driver movement, and noisy GPS streams.

2. System Architecture Overview

Uber's ETA stack is a multi-layer system where each layer solves a specific sub-problem:

Data ingestion for live GPS and traffic signals
Map matching to align noisy locations to roads
Routing to generate path candidates
Feature engineering for temporal and contextual signals
Machine learning for segment-level travel-time prediction
Online serving for low-latency ETA responses

3. Data Inputs that Drive Accuracy

ETA quality depends on combining real-time, historical, and context-rich features:

**Real-time: **driver GPS, speed vectors, congestion, live traffic feeds
Historical: time-of-day trends, weekday patterns, road speed distributions, weather and holiday effects
Contextual: city density, special events, roadwork, and construction zones

4. Map Matching and Graph Routing

Raw GPS is inherently noisy. Before route estimation, positions are snapped to likely road segments using probabilistic map-matching methods, often including Hidden Markov Model-style inference.

The road network is then represented as a weighted directed graph where intersections are nodes and road segments are edges. Edge weights represent traversal time, not just distance.

Routing engines apply optimized shortest-path methods such as Dijkstra, A*, and contraction hierarchies with real-time weight updates from live traffic.

5. Travel Time Estimation via Machine Learning

Uber does not rely purely on static shortest-path output. It predicts travel time at the road-segment level using machine learning.

Current speed and congestion
Historical average segment speed
Time bucket and day effects
Weather condition
Road type and intersection complexity

Model evolution typically progresses from linear models to gradient boosting and then to deep temporal architectures that better capture time-series traffic dynamics.

6. Pickup ETA Computation Logic

Pickup ETA is often harder than trip ETA because drivers may be moving, finishing another ride, or deviating in dense traffic.

Pickup ETA ≈ Remaining current segment time + optimal route time + intersection delay adjustments.

The system also computes uncertainty margins so user-facing predictions are robust under variance.

7. Real-Time Recalculation

ETA is continuously refreshed every few seconds using:

Live GPS deltas
Congestion updates
Route deviation detection
Dynamic re-routing logic If traffic spikes or route conditions shift, ETA is recomputed immediately.

8. Offline Training and Online Serving

The architecture is split into two stages for scale and latency:

Offline: train on billions of trips, build region-specific models, retrain continuously
Online: low-latency inference with feature store lookups, caching, and approximate serving optimizations Production latency targets are strict, commonly sub-100 ms for inference pathways.

9. Uncertainty and Confidence Modeling

ETA systems must model variance explicitly rather than output a single deterministic number.

Confidence intervals
Percentile ETAs (for example P50 and P90)
Error calibration curves
This enables messaging like "Arriving in 5–7 minutes" and improves perceived reliability.

10. Global Scaling Challenges

City diversity: each city has distinct traffic behavior requiring regionalized models
Sparse regions: cold-start geographies rely more on map priors, traffic APIs, and transfer learning
GPS distortion: urban canyons require smoothing with Kalman filters and trajectory correction

11. Continuous Improvement Loop

Uber improves ETA with a feedback cycle that combines A/B testing, prediction error pipelines, cancellation correlation analysis, and operational feedback from drivers and riders.

When ETA error patterns correlate with cancellation spikes, retraining and feature adjustments are prioritized.

12. Business Impact

Accurate ETA improves ride acceptance, reduces cancellations, raises driver utilization, and increases marketplace efficiency. Even small gains in ETA precision create significant revenue and trust impact at global scale.

13. Lessons for Engineers

Do not rely only on shortest-path algorithms
Predict at segment level instead of full-route level
Separate heavy offline ML from low-latency online serving
Model uncertainty explicitly, not optionally
Retrain continuously as traffic behavior shifts

Key Takeaway

Uber's ETA engine is far more than distance divided by speed. It is a distributed, real-time intelligence system combining graph theory, probabilistic modeling, deep learning, and infrastructure engineering under strict latency and reliability constraints.

How I Built a Local-First Journaling App with Flutter, Drift and Firebase

Ayesha Iftikhar — Wed, 23 Sep 2026 12:33:13 +0000

I build Mindleau, a free brain-dump journal and mood tracker for iOS and Android. From day one, it had one hard requirement: you should be able to open the app and start writing without creating an account or having an internet connection.

Journal entries are some of the most private things people type, and the moment someone needs to empty their head is probably the worst possible time to show them a sign-up form.

That requirement shaped the whole architecture. Here's how it's built, including the tradeoffs.

The stack

Flutter for iOS and Android from one codebase
Drift (typed SQLite) as the source of truth
Firebase Auth + Cloud Firestore for optional background sync
provider + ChangeNotifier / ValueNotifier for state. No Riverpod, no Bloc. The app is small enough that it didn't need them.

The central rule: the UI never talks to Firestore. Every screen reads and writes through a single repository, and the repository only writes to SQLite. Sync happens afterwards, in the background.

Screens ──► SanctuaryRepository ──► Drift (SQLite)   ◄── source of truth
                      │
                      └──(background)──► SyncService ──► Firestore

1. Every syncable table carries its own sync state

Instead of a separate outbox table, each syncable row records whether it has been pushed:

class BrainDumpRows extends Table {
  IntColumn get id => integer().autoIncrement()();
  TextColumn get remoteId => text().nullable()();
  TextColumn get content => text()();
  DateTimeColumn get createdAt => dateTime()();
  DateTimeColumn get updatedAt => dateTime().clientDefault(DateTime.now)();
  DateTimeColumn get deletedAt => dateTime().nullable()();   // soft delete
  TextColumn get mood => text()();
  TextColumn get focusTagsCsv => text()();
  TextColumn get syncStatus =>
      text().withDefault(const Constant('synced'))();       // pending_create | pending_update | synced
  DateTimeColumn get lastSyncedAt => dateTime().nullable()();
}

Four columns carry the sync logic:

remoteId maps the local autoincrement ID to the Firestore document ID.
updatedAt drives conflict resolution (more on that below).
deletedAt is a tombstone. Hard-deleting a row locally would leave nothing to tell the server it's gone.
syncStatus makes "what still needs pushing?" a single indexed query.

2. Writes are local and synchronous; sync is fire-and-forget

Saving a brain dump is a plain SQLite insert, marked as pending, followed by a sync attempt the UI doesn't wait for:

Future<int> saveBrainDump({
  required String content,
  required String mood,
  required List<String> focusTags,
}) async {
  final now = DateTime.now();
  final id = await _database.into(_database.brainDumpRows).insert(
        BrainDumpRowsCompanion.insert(
          content: content,
          createdAt: now,
          updatedAt: Value(now),
          mood: mood,
          focusTagsCsv: _encodeList(focusTags),
          syncStatus: const Value('pending_create'),
        ),
      );
  unawaited(syncNow()); // never blocks the save
  return id;
}

The user sees their entry immediately. Whether sync then succeeds, fails, or can't run because there's no signal changes nothing on screen.

3. Sync is pull-then-push, last-write-wins

syncNow() runs the same steps every time:

Future<void> syncNow() async {
  if (!await _canAttemptCloudSync()) return;
  try {
    if (!await service.ensureSignedIn()) return;
    await _pullRemoteChanges(service);
    await _pushPreferences(service);
    await _pushBrainDumps(service);
    await _pushMoodCheckIns(service);
    await _pushLearnProgress(service);
  } catch (error, stackTrace) {
    log('Sync failed', error: error, stackTrace: stackTrace);
  }
}

Pulling first means remote changes (from another device) are merged before local pending rows are pushed. The merge rule is plain last-write-wins on updatedAt:

final existing = await (_database.select(_database.brainDumpRows)
      ..where((t) => t.remoteId.equals(remoteId)))
    .getSingleOrNull();

// Local copy is newer: keep it; it'll be pushed next.
if (existing != null && existing.updatedAt.isAfter(remoteUpdatedAt)) return;

Tradeoff: LWW can lose an edit if the same entry is changed on two offline devices. For a personal journal, where one person is almost always on one device at a time, that's acceptable. A CRDT would add a lot of complexity to prevent a conflict that almost never happens here.

4. Anonymous auth first, email later

"No account required" and "sync across devices" pull in opposite directions. Firebase anonymous auth solves it:

On first sync, the app signs in anonymously. The user never sees a form, but their data has a stable users/{uid} path in Firestore.
If they later add an email, the anonymous account is linked to an email-link credential, so the same UID and data carry over.
On a new phone, the email link restores that account.

If anonymous auth is disabled or unreachable, ensureSignedIn() returns false and sync is skipped. The app keeps working from SQLite either way.

5. Bound every network call

This bug took me a while to understand. Firestore and Firebase Auth calls have no built-in timeout. On a flaky connection that isn't fully offline, an await can hang forever, leaving a spinner with no way out. Every network call now goes through one wrapper:

const _networkTimeout = Duration(seconds: 15);

Future<T> _withTimeout<T>(Future<T> action) => action.timeout(
      _networkTimeout,
      onTimeout: () => throw const NetworkTimeoutException(),
    );

Because the UI never awaits sync, a timeout just means "try again later". When connectivity comes back, a listener calls syncNow() and every row that isn't synced goes up.

6. Migrations are part of the product

Moving from "local only" to "local-first with sync" meant adding sync columns to tables that already held real user data. Drift's MigrationStrategy makes this explicit and versioned:

@override
int get schemaVersion => 5;

@override
MigrationStrategy get migration => MigrationStrategy(
      onUpgrade: (m, from, to) async {
        if (from < 2) {
          await m.addColumn(brainDumpRows, brainDumpRows.remoteId);
          await m.addColumn(brainDumpRows, brainDumpRows.syncStatus);
          // ...
        }
        if (from < 5) {
          await m.createTable(stillnessSessionRows);
        }
      },
    );

One lesson: SQLite won't add a NOT NULL column without a SQL-level default, and Drift's clientDefault only exists in Dart. So updated_at needed a raw ALTER TABLE ... ADD COLUMN updated_at INTEGER NOT NULL DEFAULT 0 for the rows already on users' phones.

7. Not everything has to sync

Guided stillness sessions (a timer-based breathing pause) are local-only on purpose. They only feed streaks and the 30-day heatmap, so syncing them wasn't worth the extra code and the extra data leaving the device. Deciding what not to sync is part of the privacy design.

What I'd do differently

Start with the sync columns. Adding them in migration v2 was avoidable.
Store tags as a JSON column, not CSV. CSV was quick at first and has been awkward to work with since.
Write the timeout wrapper on day one. Hanging awaits are the worst kind of offline bug because they only show up on bad networks, never at your desk.

Takeaways

If you're building anything personal (journals, habit trackers, notes), local-first is less work than it sounds:

Make SQLite the source of truth.
Put a syncStatus and updatedAt on every row.
Never let the UI wait for the network.
Use anonymous auth so "no account" and "sync" can coexist.

You can see the result in Mindleau. It's free on iOS and Android, and you can start writing without signing up. Questions about the sync design are welcome in the comments.

How to Generate a Secure JWT Secret Key in Node.js

Ayesha Iftikhar — Wed, 13 Aug 2025 10:35:52 +0000

When working with JWT (JSON Web Tokens) in a Node.js application, your secret key plays a critical role in signing and verifying tokens.

A weak or predictable key can compromise your application’s security, so it’s best to generate it randomly.

Here’s how you can easily create a strong JWT secret key using Node.js:

Add Script to package.json

Open your package.json and inside the "scripts" section, add:

"scripts": {
  "jwt-key": "node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\""
}

Run the script
In your terminal run:

npm run jwt-key

You will get:

a47f7c20e4f9a87c6d0af6e6c8c4bc25d2a8e7c4a9f5c30f72db7d9a48f1c3d2

Copy that string into your .env file.

If you use this often, you can even combine it with a direct write to .env so it replaces the JWT secret automatically:

"scripts": {
  "jwt-key": "echo JWT_SECRET=$(node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\") > .env"
}

This will overwrite .env with the new secret each time.