DEV Community: Twilight

Why Many Design Systems Only Need ~4 Text Sizes (And Why That’s Totally Fine)

Twilight — Sat, 07 Mar 2026 14:09:07 +0000

When working with UI typography, many developers and designers get confused about one thing:

If something is a “higher level” in the information structure, shouldn’t it use bigger and bolder text?

This assumption usually comes from document design (articles, blogs, documentation). But product interfaces—like settings screens, menus, and forms—follow a different logic.

This article explains why many design systems only need about four text sizes to cover most UI cases, and why elements like setting titles often use body text instead of headings.

1. Document Hierarchy vs UI Hierarchy

The first important concept is that document hierarchy and UI hierarchy are different.

Document hierarchy (content-heavy layouts)

Used in:

Articles
Blogs
Documentation
Landing pages

Typical structure:

H1
H2
H3
Body
Caption

Example:

TRANSLATION
Source Language
Japanese

Here, higher-level information uses larger typography. This helps readers understand the structure of a long piece of content.

UI hierarchy (interface layouts)

Used in:

Settings screens
Menus
Lists
Forms

Instead of emphasizing structure, the goal is fast scanning.

Typical pattern:

Section label   → small
Item title      → most readable
Item detail     → smaller

Example:

TRANSLATION
Source Language
Japanese

In this case:

Source Language is the most important thing to read.
TRANSLATION is only a grouping label.

So the visual hierarchy becomes:

Item title > Item detail > Section label

This is why section labels are often smaller than the items inside them.

2. Why Setting Titles Usually Use Body Text

A common question is:

If a setting item has a title, why isn’t it a heading?

Because a settings screen is essentially a list of items, not a document.

Each row is a list item, not a section of content.

So design systems typically use:

UI Element	Typography
Screen title	Display / Large title
Section label	Caption / Overline
Setting title	Body
Supporting text	Body Small

This pattern is widely used across major platforms like:

Material Design
Apple Human Interface Guidelines
Fluent Design System

3. The Real Meaning of “Body Text”

Another common misconception is:

Body text is only for paragraphs.

In UI design systems, Body doesn’t mean paragraph. It means:

The default readable text size for the interface.

That default size (usually 16–17px on mobile) is used for many UI elements:

Examples:

List items

Source Language
Target Language
Auto-translate on open

Form labels

Email
Password
Phone number

Menu items

Profile
Settings
Logout

Even buttons often use body-sized text.

So in UI design:

Body = the standard reading size of the interface

4. Why Most Design Systems Only Need ~4 Text Sizes

Many teams discover that most interfaces only require about four typography sizes.

A typical scale might look like:

Display
Title
Body
Caption

There are several reasons for this.

1. Humans only perceive a few clear size differences

When reading an interface, users typically distinguish only a few categories:

Large
Normal
Small

If you introduce too many sizes like:

most users won’t understand the hierarchy. The UI will just look inconsistent.

2. Product UI is usually simple

Most product screens contain only a few types of text:

Screen title
Section label
Item title
Supporting text

That’s why four sizes usually cover almost everything.

Example settings layout:

Settings        (Display)

TRANSLATION     (Caption)

Source Language (Body)
Japanese        (Body Small)

3. Fewer sizes create better consistency

When a design system has too many text tokens, people start choosing randomly.

For example:

Designer A uses 16px
Designer B uses 15px
Designer C uses 17px

Even though the differences are small, the UI begins to feel messy.

A smaller typography scale encourages consistent decisions.

4. Development becomes simpler

From a development perspective, fewer tokens make implementation easier.

Example design tokens:

display
title
body
caption

Instead of something like:

titleXL
titleLG
titleMD
titleSM
bodyLG
bodyMD
bodySM
captionLG
captionMD
captionSM

Fewer tokens make components more reusable and predictable.

5. Size Isn’t the Only Way to Create Hierarchy

Another important principle:

Typography hierarchy is often created with weight and color, not just size.

Example:

16px Medium   → primary text
16px Regular  → secondary text
16px Semibold → emphasis

Even with the same size, the interface still has a clear hierarchy.

This technique is widely used in modern UI design because it keeps interfaces clean and balanced.

6. A Simple Mental Model

A helpful way to think about typography in UI is:

Display  → screen titles
Title    → major sections
Body     → default interface text
Caption  → supporting or metadata text

Most screens in an app can be built entirely using these four roles.

Final Takeaway

If your design system looks something like this:

Display   → Screen title
Caption   → Section label
BodyMd    → Setting title
BodySm    → Supporting text

That is completely normal and widely used in modern UI design.

Remember:

UI hierarchy is not the same as document hierarchy.
Body text is the default interface text, not just paragraphs.
Most product interfaces only need about four text sizes.

A smaller typography scale usually leads to cleaner, more consistent, and easier-to-maintain interfaces.

Why Your Domain Entities Should Keep Their Own Secrets

Twilight — Wed, 26 Feb 2025 10:33:55 +0000

Imagine you're at a party, and someone claims to be your friend Sarah's boyfriend. You've never met him before. To verify his identity, you have two options:

Scenario 1: The Wrong Way

You call Sarah and ask, "Hey, what's your Facebook password?"

Sarah reluctantly tells you, then you log into her account to check her relationship status.

This approach is problematic because:

Sarah had to reveal sensitive information
You now have access to information you shouldn't
The process required an uncomfortable breach of privacy

Scenario 2: The Right Way

You text Sarah: "There's a guy here claiming to be your boyfriend. Can you confirm?"

Sarah simply replies with a yes or no.

This is clearly better because:

Sarah's password remains private
You got the information you needed
The responsibility stayed with the right person

Back to Code

This everyday example perfectly illustrates what's happening in our API code:

The Wrong Approach

// Service layer peeks at private data
async login(credentials: LoginRequestDto): Promise<LoginResponseDto> {
  const user = await this.repository.findUserByEmail(email);

  // Breaking abstraction to get the password
  const rawUserData = await this.repository['prisma'].users.findUnique({
    where: { email }
  });

  // Checking the password ourselves
  if (!CryptoUtil.verifyPassword(
    credentials.password, 
    rawUserData.password, 
    rawUserData.salt
  )) {
    throw new UnauthorizedError();
  }
}

The Better Approach

// User entity class
class UserEntity {
  private password: string;
  private salt: string;

  // The user keeps their own secrets
  verifyPassword(attemptedPassword: string): boolean {
    return CryptoUtil.verifyPassword(
      attemptedPassword, 
      this.password, 
      this.salt
    );
  }
}

// Service simply asks the user
async login(credentials: LoginRequestDto): Promise<LoginResponseDto> {
  const user = await this.repository.findUserByEmail(email);

  // Just like texting Sarah - we ask without seeing the secrets
  if (!user.verifyPassword(credentials.password)) {
    throw new UnauthorizedError();
  }
}

Real-World Benefits

This approach isn't just academically satisfying - it has practical benefits:

Easier to maintain: When password hashing algorithms need updating, you change code in one place, not everywhere passwords are checked.
Fewer bugs: The service layer doesn't need to know how passwords are stored or verified.
Better security: Sensitive data stays encapsulated and isn't passed around unnecessarily.
Cleaner code: Your authentication logic lives where it belongs.

Just like in real life, good boundaries make for better relationships. When each part of your system maintains responsibility for its own data, your code becomes more intuitive, maintainable, and secure.

The next time you're writing authentication logic, ask yourself: am I asking for someone's password, or am I simply asking them to verify something only they should know?

Ever Wonder How Flutter Powers a Smooth, Live Price List for Stocks and Crypto?

Twilight — Sun, 23 Feb 2025 06:51:19 +0000

Have you ever scrolled through a list of live prices—stocks 📈 (like Apple or Tesla), crypto pairs 💰 (like BTC/USDT or ETH/BUSD)—and wondered how it stays smooth with all that data flying in? I’ve been curious about that too. Showing hundreds or even thousands of assets updating in real time, whether it’s the steady pace of stocks or crypto’s wild swings, feels like a big challenge.

I decided to take a stab at it in Flutter, using Binance’s crypto ticker stream as my sandbox. I’m not saying I’ve cracked the perfect solution, but here’s how I tried to answer that question—hopefully it’s helpful to someone out there. 🙏

Step 1: Selective Updates That Don’t Break the App

Why It’s Tricky: Don’t Redraw Everything

Imagine a list of 2000 crypto pairs, and every price tick—say, 10 per second—redraws the whole thing. In Flutter, a naive setState would tank performance faster than you can say “lag.” I needed updates to hit only what changed, not the entire screen.

How I Approached It: Targeting Specific Changes

First, I modeled each crypto pair and its live data. Here’s the MarketSymbol for structure:

class MarketSymbol {
  final String id; // e.g., "BTCUSDT"
  final String baseAsset; // "BTC"
  final String quoteAsset; // "USDT"
  final SymbolSnapshot? snapshot; // Live price stats
  MarketSymbol({required this.id, required this.baseAsset, required this.quoteAsset, this.snapshot});
}

And SymbolSnapshot for the latest stats:

class SymbolSnapshot {
  final String symbol;
  final double lastPrice; // Latest price
  final double priceChangePercent; // 24hr change
  // ... openPrice, highPrice, etc.
}

Binance sends updates via a ticker stream, captured in SymbolTickerEvent:

class SymbolTickerEvent {
  final String eventType; // "24hrTicker"
  final int eventTime; // Timestamp
  final String symbol; // "BTCUSDT"
  final double closePrice; // Latest price
  final double openPrice;
  final double highPrice;
  final double lowPrice;
  final double totalTradedBaseAssetVolume; // Base volume
  final double totalTradedQuoteAssetVolume; // Quote volume

  SymbolSnapshot get snapshot => SymbolSnapshot(
    symbol: symbol,
    lastPrice: closePrice,
    priceChangePercent: (closePrice - openPrice) / openPrice * 100,
    // ... other fields
  );
}

Using Riverpod in Flutter, I stored symbols in a Map and updated only what changed:

void _onSymbolTickerEvent(SymbolTickerEvent event) {
  final symbol = state.symbolMap[event.symbol];
  if (symbol != null && symbol.snapshot?.lastPrice != event.snapshot.lastPrice) {
    state = state.copyWith(
      symbolMap: {
        ...state.symbolMap,
        symbol.id: symbol.copyWith(snapshot: event.snapshot),
      },
    );
  }
}

In the UI, I hook into Riverpod’s select to watch just that symbol:

class MarketSymbolRow extends ConsumerWidget {
  const MarketSymbolRow({required this.symbolId});
  static const double height = 60;

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final symbol = ref.watch(marketVMProvider.select((state) => state.symbolMap[symbolId]!));
    // Returns fancy UI with a height of 60 px
  }
}

It’s not fancy—just a way to keep updates small. When “BTCUSDT” or "ETHUSDT” changes, only its row refreshes, which felt like a decent start.

Step 2: Just Listen to What You See

Why It’s Tricky: Too Much Data

Binance streams data for every pair, but why grab “XRPUSDT” if it’s 300 rows off-screen? Subscribing to all 2000+ pairs would choke the network. I needed to focus on what’s visible.

How I Approached It: Watching the Viewport

In Flutter, I used a ScrollController and a GlobalKey to figure out what’s visible:

void _updateVisibleSymbols() {
  final symbolIds = ref.read(marketVMProvider.select((state) => state.symbolIds));

  final viewportSymbolRows = (_viewportKey.height / MarketSymbolRow.height).ceil(); // Visible rows
  final firstIndex = max(_scrollController.offset ~/ MarketSymbolRow.height, 0); // Top row
  final lastIndex = min(firstIndex + viewportSymbolRows, symbolIds.length - 1); // Bottom row
  final newVisibleSymbolIds = symbolIds.toList().sublist(firstIndex, lastIndex + 1).toSet();

  if (newVisibleSymbolIds.difference(_visibleSymbolIds).isNotEmpty) {
    _visibleSymbolIds = newVisibleSymbolIds;
    ref.read(marketVMProvider.notifier).syncPriceTracking(_visibleSymbolIds);
  }
}

The view model handles subscriptions, unsubscribes from symbols that are no longer needed and subscribes only to new ones. Overlapping symbols (already subscribed) are ignored to avoid redundant operations.:

void syncPriceTracking(Set<String> symbolIds) async {
  final symbolIdsToUnsubscribe = _currentSubscribedSymbolIds.where((s) => !symbolIds.contains(s)).toList();
  final symbolIdsToSubscribe = symbolIds.where((s) => !_currentSubscribedSymbolIds.contains(s)).toList();

  if (symbolIdsToUnsubscribe.isNotEmpty) _marketRepository.unsubscribeSymbolMiniTickerStream(symbols: symbolIdsToUnsubscribe);
  if (symbolIdsToSubscribe.isNotEmpty) {
    await _marketRepository.subscribeSymbolMiniTickerStream(symbols: symbolIdsToSubscribe);
    _currentSubscribedSymbolIds = symbolIds;
  }
}

This kept it simple—streaming maybe 15-20 assets instead of 500. It’s not perfect, but it worked for my little experiment. (WebSocket details? See my other post)

Step 3: Scroll Without the Stutter

Why It’s Tricky: Laggy Scrolling

Even with those tweaks, scrolling felt rough because I was checking the viewport too often. I wanted it to feel smooth, even with all that live data.

How I Approached It: Giving It a Breather and Fixed Sizes

I added a debounce timer to calm things down:

void _onScroll() {
  _debounceTimer?.cancel();
  if ((_scrollController.offset - _lastOffset).abs() < 30) return; // Skip small nudges

  _debounceTimer = Timer(Duration(milliseconds: 300), () {
    _lastOffset = _scrollController.offset;
    _updateVisibleSymbols(); // Update after a breather
  });
}

And built the list with a fixed itemExtent in Flutter’s ListView.builder:

ListView.builder(
  key: _viewportKey,
  controller: _scrollController,
  itemExtent: MarketSymbolRow.height, // Locked at 60px
  itemCount: symbolIds.length,
  itemBuilder: (context, index) {
    final symbolId = symbolIds[index];
    return MarketSymbolRow(symbolId: symbolId);
  },
)

The debounce waits 300ms after scrolling stops, and itemExtent keeps layout quick. It’s a small trick, but it made scrolling nicer for me.

What I Took Away

This was just my attempt to wrestle with real-time data in Flutter—Riverpod for small updates, viewport checks to cut data, and a few tweaks for smoother scrolling. Binance’s stream was a fun testbed, and while it’s not the ultimate answer, it got the job done for me. If you’re tackling live lists in Flutter, maybe these bits can help—or spark a better idea. Let me know what you think! You can read more at: 7wilight Blog

Building a WebSocket Client in Flutter: From Zero to Hero

Twilight — Sat, 22 Feb 2025 09:59:33 +0000

This article guides you through creating a WebSocket client in Flutter for real-time data. We’ll start with the basics and improve it step by step until it’s solid and reliable. We’re using Binance Market WebSocket as an example (think of it like a live crypto price feed), but the real focus is WebSocket—connecting, fixing errors, and managing data streams. Let’s dive in!

Part 1: Starting with a Basic Connection

First, we need a way to connect to a WebSocket server. Since real-time data can come from different tools (like WebSocket, MQTT,...), we define a StreamingService interface to keep things flexible. But here, we’ll use WebSocket with the web_socket_channel package, connecting to Binance’s endpoint (wss://stream.binance.com:9443/ws).

Here’s the simple starting code:

abstract class StreamingService {
  void connect();
}

class WebsocketService implements StreamingService {
  WebsocketService({required this.wsUrl});

  final String wsUrl;

  WebSocketChannel? _channel;

  bool get isConnected => _channel != null && _channel!.closeCode == null;

  @override
  void connect() {
    if (_channel != null) return;
    _channel = WebSocketChannel.connect(Uri.parse(wsUrl));
    _channel?.stream.listen(
      _onEvent,
      onError: _onError,
      onDone: _onDone,
    );
  }

  void _onEvent(dynamic event) {
    print("Event: $event");
  }

  void _onError(dynamic error) {
    print("Error: $error");
  }

  void _onDone() {
    print("Connection closed");
  }
}

This code connects and listens for data. _onEvent prints incoming messages, _onError logs errors, and _onDone notes when the connection stops. It’s simple—just enough to see Binance data flowing—but it’s fragile. If the connection drops or fails, it won’t recover. Let’s fix that next.

Part 2: Keeping the Connection Alive with Ping-Pong

The basic setup from Part 1 has a weakness: WebSocket connections can die if they’re idle too long. Binance helps us here by sending a “ping” message to check if we’re still alive. We’ll reply with a “pong” to keep the connection going—a bit like a heartbeat.

To improve this, we’ll:

Check incoming events for a ping.
Send a pong response. like saying, “Hey, I’m still here!”

Here’s the updated code:

class WebsocketService implements StreamingService {
  /* Same as before */

  void _onEvent(dynamic event) {
    if (event is! String) return;
    final decodedEvent = jsonDecode(event);

    if (decodedEvent is Map<String, dynamic>) {
      if (decodedEvent.containsKey('ping')) {
        _sendPong();
        return;
      }
    }
    print("Event: $event");
  }

  void _sendPong() {
    _channel?.sink.add(jsonEncode({'pong': DateTime.now().millisecondsSinceEpoch}));
  }
}

This is smart—it keeps the connection alive without extra work. But if it drops anyway, we’re still stuck. Let’s add reconnect logic next.

Part 3: Sending Requests

So far, we only listen. Let’s sending requests to subscribe to Binance’s Stream (Example: Individual Symbol Mini Ticker Stream)

Improvements:

Add _symbolMiniTickerStreamController lets us stream data to the app.
Add EventTypes keeps event names organized.
Add SubscribeStreamRequest and UnsubscribeStreamRequest classes for clean code.
Add _sendRequest() to send messages.

Here’s the code:

class WebsocketService implements StreamingService {
  /* Same as before */

  final _symbolMiniTickerStreamController = StreamController<SymbolMiniTickerEvent>.broadcast();

  void _onEvent(dynamic event) {
    if (event is! String) return;
    final decodedEvent = jsonDecode(event);

    if (decodedEvent is Map<String, dynamic>) {
      if (decodedEvent.containsKey('ping')) {
        _handlePingResponse();
        return;
      }

      final eventType = decodedEvent['e'];
      switch (eventType) {
        case EventTypes.symbolMiniTicker:
          _symbolMiniTickerStreamController.sink.add(SymbolMiniTickerEvent.fromMap(decodedEvent));
          break;
      }
    }
  }

  Future<bool> _sendRequest(Map<String, dynamic> request) async {
    if (!isConnected) {
      print("WebSocket is not connected. Cannot send request: $request");
      return false;
    }
    _channel?.sink.add(jsonEncode(request));
    return true; // Assume success
  }

 /// =============================== Individual Symbol Mini Ticker Streams ===============================

  Stream<SymbolMiniTickerEvent> get symbolMiniTickerStream => _symbolMiniTickerStreamController.stream;

  Future<bool> subscribeSymbolMiniTickerStream({required List<String> symbols}) async {
    final request = SubscribeStreamRequest(
      streamNames: symbols.map((symbol) => "${symbol.toLowerCase()}@miniTicker").toList(),
    );
    return _sendRequest(request.toMap());
  }

  Future<bool> unsubscribeSymbolMiniTickerStream({required List<String> symbols}) async {
    final request = UnsubscribeStreamRequest(
      streamNames: symbols.map((symbol) => "${symbol.toLowerCase()}@miniTicker").toList(),
    );
    return _sendRequest(request.toMap());
  }
}

class EventTypes {
  static const String symbolMiniTicker = '24hrMiniTicker';
}

class SubscribeStreamRequest {
  SubscribeStreamRequest({required this.streamNames});

  final List<String> streamNames;

  Map<String, dynamic> toMap() {
    return {
      "id": DateTime.now().millisecondsSinceEpoch,
      "method": "SUBSCRIBE",
      "params": streamNames,
    };
  }
}

class UnsubscribeStreamRequest {
    /* */
}

It’s cool, but _sendRequest() doesn’t confirm if it worked, and reconnects lose subscriptions. Let’s make it smarter.

Part 4: Making Requests Smarter with ACK and Stream Management

Part 3 sends requests, but it’s blind—we don’t know if Binance accepted them and we don't know which stream was subscribed to. Let’s fix that with:

Add _pendingRequests tracks requests with Completer — it waits for Binance’s ACK like “Hey, did this work?”
Add _activeStreams to remember active stream subscriptions.
Add _handleAckResponse() to process ack response.
Update _sendRequest() to check if the request was sent successfully to manage the active streams.

class WebsocketService implements StreamingService {
  /* Same as before */

  final Map<int, Completer<bool>> _pendingRequests = {};
  final Set<String> _activeStreams = {};

  void _onEvent(dynamic event) {
    if (event is! String) return;
    final decodedEvent = jsonDecode(event);

    if (decodedEvent is Map<String, dynamic>) {
      if (decodedEvent.containsKey('ping')) {
        _handlePingResponse();
        return;
      }

      if (decodedEvent.containsKey('id')) {
        _handleAckEvent(decodedEvent);
        return;
      }

      final eventType = decodedEvent['e'];
      switch (eventType) {
        case EventTypes.symbolMiniTicker:
          _symbolMiniTickerStreamController.sink.add(SymbolMiniTickerEvent.fromMap(decodedEvent));
          break;
      }
    }
  }

  void _handleAckEvent(Map<String, dynamic> event) {
    final requestId = event['id'];
    final completer = _pendingRequests.remove(requestId);
    if (completer != null) {
      if (event.containsKey('code')) {
        completer.complete(false);
        print("Error: ${event['msg']} (Code: ${event['code']})");
      } else if (event.containsKey('result')) {
        completer.complete(event['result'] == null);
      } else {
        completer.complete(false);
      }
    }
  }

  Future<bool> _sendRequest(Map<String, dynamic> request) async {
    if (!isConnected) {
      print("WebSocket is not connected. Cannot send request: $request");
      return false;
    }

    final completer = Completer<bool>();
    _pendingRequests[request['id']] = completer;
    _channel?.sink.add(jsonEncode(request));

    final isSuccess = await completer.future;
    if (isSuccess && request.containsKey('params')) {
      final streamNames = request['params'];
      if (request['method'] == 'SUBSCRIBE') {
        _activeStreams.addAll(streamNames);
      } else if (request['method'] == 'UNSUBSCRIBE') {
        _activeStreams.removeAll(streamNames);
      }
    }
    return isSuccess;
  }
}

Part 5: Adding Reconnect Logic

We have handled keep the connection alive during quiet times, but what if the network fails or Binance cuts us off? The old code just logs “Error” or “Connection closed” and gives up. We need it to fight back by reconnecting.

Here’s how we’ll improve it:

Add _reconnectAttempts to avoid infinite loop calls.
Add reconnect() for retry, waits longer each try and re-subscribe to previously subscribed streams if reconnection is successful
Add disconnect() to terminate the current connection, and also cancels all pending requests to avoid resubscribing to streams that are no longer needed.
Update _onError() and _onDone() to check error types and close codes to decide when to reconnect.

Here’s the code:

class WebsocketService implements StreamingService {
  /* Same as before */

  int _reconnectAttempts = 0;

  void _onError(dynamic error) {
    if (error is WebSocketChannelException || error is SocketException) {
      print("Temporary error detected");
      reconnect();
    } else if (error is HttpException && error.message.contains("403")) {
      print("Access denied (403 Forbidden). Check API permissions.");
    } else if (error is HttpException && error.message.contains("400")) {
      print("Bad request (400). Check the request format.");
    } else {
      print("Unknown error: $error");
    }
  }

  void _onDone() {
    print("Connection closed: ${_channel?.closeReason ?? 'Unknown reason'}");
    if (_channel?.closeCode == null || _channel?.closeCode != 1000) {
      reconnect();
    }
  }

  @override
  void reconnect() async {
    disconnect();

    if (_reconnectAttempts >= 5) {
      print("Maximum reconnection attempts reached");
      return;
    }

    print("Attempting to reconnect (${_reconnectAttempts + 1}/5)...");
    _reconnectAttempts++;
    await Future.delayed(Duration(seconds: 2 * _reconnectAttempts));
    connect();

    if (isConnected) {
      _reconnectAttempts = 0;
      if (_activeStreams.isNotEmpty) {
        final request = SubscribeStreamRequest(streamNames: _activeStreams.toList());
        await _sendRequest(request.toMap());
      }
    }
  }

  @override
  void disconnect() {
    for (final completer in _pendingRequests.values) {
      completer.complete(false);
    }
    _pendingRequests.clear();
    _channel?.sink.close();
    _channel = null;
  }
}

Wrapping Up

We’ve built a WebSocket client from scratch—starting with a basic connection, adding reconnect logic, keeping it alive with ping-pong, sending requests, and making them smart with ACKs and stream management. Binance Market WebSocket was just our example; the real star is the WebSocket setup. Use this code, tweak it for your needs, and handle real-time data like a pro! You can find the full source code at: Github

Mastering Auth in Flutter with Dio: From Simple Access Tokens to a Refresh Flow

Twilight — Sun, 19 Jan 2025 19:02:37 +0000

Authentication is a foundational requirement for most apps. In Flutter, a common pattern uses JWTs (JSON Web Tokens) or similar tokens to authenticate requests. At first, you might rely on a single access token—but as your app scales, you’ll quickly need a refresh token strategy to avoid forcing users to log in over and over.

In this article, we’ll move through three stages of an authentication flow:

A simple app with only an access token: Suitable for short-lived demos or backends that never expire tokens.
A refresh token flow with “One Future”: Ensures only one refresh request is triggered, but can get clunky with concurrency.
Drawbacks of “One Future” and how to optimize using a flag + queue approach for high concurrency.

Let’s dive in!

1) The Simplest Setup: Only an Access Token

Imagine you have an API that doesn’t expire tokens—or your app’s token can be reissued manually. Your Dio interceptor might look like this:

class SimpleAuthInterceptor extends Interceptor {
  final Dio dio;
  final SecureStorage secureStorage; // or any storage

  SimpleAuthInterceptor(this.dio, this.secureStorage);

  @override
  Future<void> onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
    final token = await secureStorage.readToken();
    if (token != null && token.isNotEmpty) {
      options.headers['Authorization'] = 'Bearer $token';
    }
    handler.next(options);
  }
}

Here:

We read an access token from storage.
Attach it to every request in the Authorization: Bearer ... header.
If the token is invalid or expires, we rely on the backend to tell us (maybe a 401), at which point we might just fail gracefully or prompt the user to re-log in.

Pros:

Very simple—no refresh logic, no concurrency issues.

Cons:

The user must log in again every time the token expires. That’s extremely annoying if tokens expire frequently.
If the server can revoke your token unpredictably, you have no fallback other than a 401.

This works for minimal demos or local dev, but in real production apps, having only an access token is rarely enough.

2) Introducing a Refresh Token Using the “One Future” Approach

When your access token can expire, a refresh token is typically provided by the backend. This refresh token can be used to request a new access token without prompting the user for credentials again. In Flutter/Dio, we can code it like so:

In onRequest, attach the current access token.
If a request fails with 401, check if we’re already refreshing.
If no refresh is in progress, start a single refresh request (our “one future”).
If a refresh is already in progress, wait for that same future.
Once the refresh completes, retry the original request with the new token.

Sample Code

class OneFutureAuthInterceptor extends Interceptor {
  final Dio dio;
  Future<String?>? _refreshTokenFuture;
  final TokenStorage tokenStorage; // a class that reads/writes tokens

  OneFutureAuthInterceptor(this.dio, this.tokenStorage);

  @override
  Future<void> onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
    final accessToken = await tokenStorage.readAccessToken();
    if (accessToken != null && accessToken.isNotEmpty) {
      options.headers['Authorization'] = 'Bearer $accessToken';
    }
    handler.next(options);
  }

  @override
  Future<void> onError(DioException err, ErrorInterceptorHandler handler) async {
    if (_isUnauthorized(err) && _shouldRefresh(err.requestOptions)) {
      // Attempt refresh if not already happening
      _refreshTokenFuture ??= _refreshAccessToken();

      final newToken = await _refreshTokenFuture;
      if (newToken != null) {
        // Retry the original request
        final clonedRequest = _retryRequest(err.requestOptions, newToken);
        try {
          final response = await dio.fetch(clonedRequest);
          return handler.resolve(response);
        } catch (e) {
          return handler.next(e as DioException);
        }
      }
      // If refresh fails, newToken == null => pass the 401 up
    }
    return handler.next(err);
  }

  bool _isUnauthorized(DioException err) {
    return err.response?.statusCode == 401;
  }

  bool _shouldRefresh(RequestOptions requestOptions) {
    // Avoid refreshing again if it's the refresh token call
    return !requestOptions.path.contains('/refresh');
  }

  RequestOptions _retryRequest(RequestOptions requestOptions, String newToken) {
    final newHeaders = Map<String, dynamic>.from(requestOptions.headers);
    newHeaders['Authorization'] = 'Bearer $newToken';
    return requestOptions.copyWith(headers: newHeaders);
  }

  Future<String?> _refreshAccessToken() async {
    try {
      // Call your /refresh endpoint
      // final response = await Dio().post('https://your.api/refresh', data: {...});
      // final newAccessToken = response.data['accessToken'];
      final newAccessToken = 'FAKE_NEW_TOKEN';

      await tokenStorage.saveAccessToken(newAccessToken);
      return newAccessToken;
    } catch (e) {
      // If fail, remove token or force user to re-log
      await tokenStorage.clearTokens();
      return null;
    } finally {
      // Allow future refresh attempts next time 401 is encountered
      _refreshTokenFuture = null;
    }
  }
}

How It Works

_refreshTokenFuture ensures only one refresh call is triggered even if multiple requests fail with 401 simultaneously.
Once the refresh request completes, any other request that was also waiting for a new token will just await the same future.

Pros

Concise code: “One Future” is straightforward and easy to follow.
No complicated data structures: We rely on a single _refreshTokenFuture.

Cons

Concurrency edge cases: If 20 requests simultaneously get a 401, each one calls onError, you must be careful about setting _refreshTokenFuture quickly to avoid double refresh attempts.
No “batch control”: Each request effectively retries itself. If you want to reorder, skip, or handle certain requests differently, you’ll do it in multiple places (onError for each request).
All or nothing: If the refresh fails, every request that was waiting sees the error at once.

For many small to moderate apps, “One Future” is a nice balance of simplicity and concurrency control.

3) Drawbacks & the Flag + Queue Optimization

While “One Future” works well for moderate concurrency, it can get messy if you:

Fire lots of parallel API calls at once.
Need to conditionally drop or batch certain calls.
Want advanced concurrency controls, e.g. reordering requests or limiting the maximum concurrency.

In that scenario, the “One Future” approach can cause:

Repetitive Logic: Each request that hits onError(401) re-applies the same “clone & retry” code. If you need special handling (like changing request parameters before retry), that code can get scattered in multiple places.
Difficult “group management”: Suppose you want to say, “Cancel half of the requests if the user is no longer on that screen,” or “Retry these requests in a specific sequence.” You end up patching code in each individual onError.

The Flag + Queue Approach

Solution: Use a flag (like _isRefreshing) and a queue (_pendingRequests) to store all failing requests in one place. Then:

On 401, push that request into _pendingRequests.
If _isRefreshing == false, start the refresh flow; otherwise, keep queueing more requests.
After refreshing, loop through _pendingRequests and retry them all in one centralized method.
If refresh fails, fail them all at once and log out the user.

Yes, it’s more code to set up. But it:

Centralizes concurrency. You see exactly which requests are pending.
Lets you handle “group logic” easily (like partial cancellation, request ordering, or “one big retry batch”).
Minimizes race conditions because the moment you set _isRefreshing = true, you know no second refresh will start.

Quick Snippet

class AuthInterceptorQueue extends Interceptor {
  bool _isRefreshing = false;
  final List<_PendingRequest> _pendingRequests = [];

  // ...

  @override
  Future<void> onError(DioException err, ErrorInterceptorHandler handler) async {
    if (_isUnauthorized(err)) {
      _pendingRequests.add(_PendingRequest(err.requestOptions, Completer<Response>()));

      if (!_isRefreshing) {
        _isRefreshing = true;
        final refreshed = await _refreshToken();
        if (refreshed) {
          await _retryAllRequests();
        } else {
          _failAllRequests(err);
        }
        _isRefreshing = false;
      }

      // The request that triggered 401 waits on a completer
      try {
        final last = _pendingRequests.last;
        final response = await last.completer.future;
        return handler.resolve(response);
      } catch (e) {
        return handler.next(e as DioException);
      }
    }
    return super.onError(err, handler);
  }

  // ...
}

If you’re curious about the full example, check out other resources or see the “Flag + Queue” approach in detail. In many large apps, it’s a safer concurrency strategy.

Conclusion

We’ve walked through three authentication flows in Flutter with Dio:

Only Access Token: Simplest but forces re-login on token expiration.
Refresh Flow Using “One Future”: Short code, minimal overhead, good for moderate concurrency.
Shortcomings & “Flag + Queue”: More code but handles concurrency thoroughly, letting you batch or reorder requests.

Which approach you choose depends on your app’s complexity and concurrency needs:

For a small or medium-scale app, “One Future” might be perfect.
For heavy concurrency or advanced request management, a “Flag + Queue” approach might give you better control.

Either way, placing your token logic inside a Dio interceptor is a clean design, isolating authentication concerns from the rest of your app. Happy coding!

Mastering Nested Navigation in Flutter with `go_router` and a Bottom Nav Bar

Twilight — Sun, 12 Jan 2025 08:26:43 +0000

Managing multiple tabs, each with its own navigation history, can feel daunting. In this post, we’ll explore how to use go_router to set up nested navigation in Flutter—complete with a persistent BottomNavigationBar—while still being able to navigate into detail screens without losing the bottom bar.

1. Why Nested Navigation?

In many apps (e.g., music or podcast apps), each bottom-tab (Home, Discover, Library, Profile, etc.) needs to maintain its own navigation history. When a user switches tabs, they should return to the previous screen within that tab, not reset to the root screen.

Key points:

Preserve each tab’s state when switching.
Allow deeper routes (Detail screens) inside each tab.
Keep the bottom bar visible even on detail pages.

2. Setting Up a `StatefulShellRoute.indexedStack`

go_router offers a StatefulShellRoute that behaves like an IndexedStack. Each tab corresponds to a StatefulShellBranch:

final router = GoRouter(
  routes: [
    StatefulShellRoute.indexedStack(
      builder: (context, state, navShell) => Scaffold(
        body: navShell,
        bottomNavigationBar: BottomNavigationBar(...), 
      ),
      branches: [
        // Branch 1: Home
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/home',
              builder: (context, state) => HomePage(),
              routes: [
                GoRoute(
                  path: 'podcast/:podcastId',
                  builder: (context, state) => PodcastDetailPage(),
                ),
              ],
            ),
          ],
        ),
        // Branch 2: Discover
        StatefulShellBranch(
          routes: [
            GoRoute(
              path: '/discover',
              builder: (context, state) => DiscoverPage(),
              routes: [
                GoRoute(
                  path: 'podcast/:podcastId',
                  builder: (context, state) => PodcastDetailPage(),
                ),
              ],
            ),
          ],
        ),
        // ...Other branches
      ],
    ),
  ],
);

Each branch has its own sub-routes.
Navigating to '/home/podcast/123' will push a detail page within the Home branch, so your bottom bar remains.

3. Making Detail Routes “Shared” Without Repetition

If you have the same detail screen (e.g., PodcastDetailPage) in multiple tabs, consider a helper function to generate shared routes:

List<GoRoute> buildPodcastRoutes(String branchName) => [
  GoRoute(
    name: '${branchName}PodcastDetail',
    path: 'podcast/:podcastId',
    builder: (context, state) => PodcastDetailPage(),
  ),
];

// Then in each branch:
GoRoute(
  path: '/home',
  routes: [
    ...buildPodcastRoutes('home'),
  ],
  builder: (context, state) => HomePage(),
),

This way, you “define once,” but attach them to each branch. Each detail route name is unique (homePodcastDetail, discoverPodcastDetail, etc.), allowing goNamed without clashing.

4. Navigating to Detail from Shared Widgets

You might have shared widgets (like PodcastCard) that shouldn’t hard-code which tab’s detail route to use. One clean approach is Inversion of Control:

Parent (e.g., HomePage) passes a callback to PodcastCard.
PodcastCard just calls onTap?.call() without knowing the route name.

class PodcastCard extends StatelessWidget {
  final String podcastId;
  final VoidCallback onTap; 
  // ...

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,
      child: ...
    );
  }
}

class HomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return PodcastCard(
      podcastId: '123',
      onTap: () => context.goNamed('homePodcastDetail', params: {'podcastId': '123'}),
    );
  }
}

This keeps routing logic in the page (which knows it’s the Home tab), not in the shared widget.

5. Best Practices at a Glance

Use StatefulShellRoute.indexedStack for bottom-tabs, ensuring each tab has a separate route branch and persistent state.
Keep detail routes as children of each tab’s branch, so the bottom bar never disappears.
Avoid repeating route definitions with helper methods that generate shared detail routes for each branch.
Leverage named routes (goNamed / pushNamed) to avoid hard-coding paths.
Separate your UI from navigation logic by passing callbacks or using a provider/DI approach.

6. Wrapping Up

With go_router, setting up nested navigation for multiple tabs is remarkably straightforward—once you know how to structure your routes! The StatefulShellRoute keeps each tab’s history intact, and sub-routes let you push detail pages without losing the bottom bar. Combine these techniques with consistent naming for a scalable, clean navigation system in Flutter.

Happy routing!

Understanding `context.push` vs `context.go` in Flutter's GoRouter

Twilight — Sun, 12 Jan 2025 08:17:13 +0000

Navigating between screens is a fundamental aspect of any Flutter application. With the advent of the GoRouter package, managing routes has become more streamlined and declarative. However, understanding the nuances between different navigation methods is crucial for maintaining a predictable navigation stack. In this article, we'll delve into the differences between context.push and context.go in GoRouter, focusing on their behaviors in various routing scenarios with concrete examples.

📚 Table of Contents

Introduction to GoRouter
context.push vs context.go
- Behavior with Sibling Routes
- Behavior with Nested Routes
Practical Examples
Conclusion

🚀 Introduction to GoRouter

GoRouter is a powerful routing package for Flutter that simplifies navigation and deep linking. It leverages Flutter's Navigator 2.0 API, providing a declarative approach to defining routes and handling navigation actions. Two primary methods for navigation in GoRouter are context.push and context.go. Understanding their differences is essential for effective route management.

`context.push` vs `context.go`

Both context.push and context.go are used to navigate between routes, but they behave differently depending on the routing structure and the desired navigation behavior.

`context.push`

Purpose: Adds a new route on top of the current navigation stack.
Equivalent To: Navigator.push in Flutter's native Navigator.
Use Case: When you want to navigate to a new screen without removing the current one, allowing the user to return to the previous screen.

`context.go`

Purpose: Replaces the current stack of screens with the screens configured for the destination route.
Equivalent To: Navigator.pushNamedAndRemoveUntil with a predicate that removes all existing routes (e.g., (Route<dynamic> route) => false).
Use Case: When you want to navigate to a new screen and remove all previous routes, such as navigating to a home screen after a successful login or redirecting to a splash screen.

📊 Key Differences

Aspect	`context.push`	`context.go`
Stack Behavior	Adds to the existing stack	Replaces the current stack with the destination route stack
Navigation Depth	Maintains history for back navigation	Clears history unless navigating to a nested route, which preserves parent routes
Use Cases	Navigating to detail screens, modals	Redirecting after authentication, resetting navigation, navigating to a new root screen
Equivalent Methods	`Navigator.push`	`Navigator.pushNamedAndRemoveUntil` with a predicate to remove all previous routes

👯‍♂️ Behavior with Sibling Routes

Scenario: You have two sibling routes, Login and Profile, both defined at the same hierarchical level.

Using `context.push`

Initial Stack: [Login]
Action: context.push('/profile')
Resulting Stack: [Login, Profile]
Behavior: Profile is added on top of Login, allowing the user to navigate back to Login.

Using `context.go`

Initial Stack: [Login]
Action: context.go('/profile')
Resulting Stack: [Profile]
Behavior: The entire stack is replaced with Profile, removing Login from the history.

🏠 Behavior with Nested Routes

Scenario: Route Settings is a subroute (child) of route Home.

Using `context.push`

Initial Stack: [Home]
Action: context.push('/home/settings')
Resulting Stack: [Home, Settings]
Behavior: Settings is added as a child of Home, maintaining the parent-child relationship. The user can navigate back to Home.

Using `context.go`

Initial Stack: [Home]
Action: context.go('/home/settings')
Resulting Stack: [Home, Settings]
Behavior: Since Settings is a subroute of Home, Home remains in the stack, and Settings is added on top. The overall stack structure preserves the parent-child relationship, allowing back navigation to Home.

🔍 Practical Examples

Let's solidify our understanding with practical code examples using concrete route names like /login, /home, /home/settings, and /profile.

📂 Route Configuration

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

final GoRouter router = GoRouter(
  initialLocation: '/login',
  routes: [
    GoRoute(
      path: '/login',
      name: 'Login',
      builder: (context, state) => const LoginScreen(),
    ),
    GoRoute(
      path: '/home',
      name: 'Home',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'settings',
          name: 'Settings',
          builder: (context, state) => const SettingsScreen(),
        ),
      ],
    ),
    GoRoute(
      path: '/profile',
      name: 'Profile',
      builder: (context, state) => const ProfileScreen(),
    ),
  ],
);

🛠️ LoginScreen with Navigation Buttons

class LoginScreen extends StatelessWidget {
  const LoginScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Simulate a successful login
    return Scaffold(
      appBar: AppBar(title: const Text('Login')),
      body: Center(
        child: ElevatedButton(
          onPressed: () {
            // Navigate to Home after login
            context.go('/home');
          },
          child: const Text('Login and Go to Home'),
        ),
      ),
    );
  }
}

🏠 HomeScreen with Navigation Buttons

class HomeScreen extends StatelessWidget {
  const HomeScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Buttons to navigate to Settings and Profile
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            ElevatedButton(
              onPressed: () => context.push('/home/settings'),
              child: const Text('Push to Settings (Nested)'),
            ),
            ElevatedButton(
              onPressed: () => context.go('/profile'),
              child: const Text('Go to Profile (Sibling)'),
            ),
          ],
        ),
      ),
    );
  }
}

⚙️ SettingsScreen with Back Navigation

class SettingsScreen extends StatelessWidget {
  const SettingsScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Button to navigate back to Home
    return Scaffold(
      appBar: AppBar(title: const Text('Settings')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.pop(),
          child: const Text('Go Back to Home'),
        ),
      ),
    );
  }
}

👤 ProfileScreen with Back Navigation

class ProfileScreen extends StatelessWidget {
  const ProfileScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Button to navigate back to Home (if possible)
    return Scaffold(
      appBar: AppBar(title: const Text('Profile')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => context.pop(),
          child: const Text('Go Back'),
        ),
      ),
    );
  }
}

🔎 Expected Behaviors

Login and Go to Home
- Method: context.go('/home')
- Stack Transition: [Login] → [Home]
- Back Navigation: 🚫 Disabled (cannot go back to Login)
Push to Settings (/home/settings)
- Method: context.push('/home/settings')
- Stack Transition: [Home] → [Home, Settings]
- Back Navigation: 🔙 Enabled (can go back to Home)
Go to Profile (/profile)
- Method: context.go('/profile')
- Stack Transition: [Home] → [Profile]
- Back Navigation: 🚫 Disabled (cannot go back to Home)
Go Back from Settings
- Method: context.pop()
- Stack Transition: [Home, Settings] → [Home]
- Back Navigation: 🔙 Enabled (can go back to Home)

✅ Conclusion

Understanding the distinction between context.push and context.go in GoRouter is essential for effective navigation management in Flutter applications:

Use context.push when you want to add a new route on top of the current stack, preserving the ability to navigate back. This is ideal for scenarios like navigating to detail screens or opening modals where the previous screen remains relevant.
Use context.go when you intend to replace the current navigation stack with a new route. This is particularly useful for actions like redirecting users after authentication, resetting navigation history, or navigating to a new root screen where returning to previous screens is not desired.

Happy Coding! 🚀

Best Practices for Managing Route Names and Paths with go_router in Flutter

Twilight — Sat, 11 Jan 2025 13:43:27 +0000

Are you tired of typing out long, hard-coded paths when navigating between screens in your Flutter app? Or worried about circular imports while organizing your routes across multiple features? In this post, we’ll explore how to manage route names and paths using go_router in a clean and maintainable way.

1. Why Avoid Hard-Coding Routes?

Using strings like context.go("/some/really/long/path/42") all over your codebase can be error-prone and difficult to maintain. If you ever decide to change "/some/really/long/path" to "/shorter/path", you’ll have to hunt down every place that calls it.

Instead, define named routes or centralized route constants. This helps you:

Avoid typos.
Keep the code DRY (Don’t Repeat Yourself).
Make future changes to your routes simpler.

2. Named Routes in `go_router`

go_router lets you define both a path and a name for your routes. You can then call context.goNamed() instead of context.go().

Here’s a quick example:

import 'package:go_router/go_router.dart';

final router = GoRouter(
  routes: [
    GoRoute(
      name: 'home',
      path: '/home',
      builder: (context, state) => const HomePage(),
    ),
    GoRoute(
      name: 'profile',
      path: '/profile/:userId',
      builder: (context, state) {
        final userId = state.pathParameters['userId'];
        return ProfilePage(userId: userId);
      },
    ),
  ],
);

// Navigate by route name
context.goNamed('profile', params: {'userId': '42'});

With named routes:

If you rename /profile/:userId to /users/:id, you only update one place (the route definition) instead of every go() call in the project.

3. Centralizing Route Names and Paths

Create a file or class that contains all of your route constants. For example:

// app_routes.dart
abstract class AppRouteName {
  static const home = 'home';
  static const profile = 'profile';
}

abstract class AppRoutePath {
  static const home = '/home';
  static const profile = '/profile/:userId';
}

Then, when defining routes:

GoRoute(
  name: AppRouteName.profile,
  path: AppRoutePath.profile,
  builder: (context, state) => ...
);

And when navigating:

context.goNamed(
  AppRouteName.profile,
  params: {'userId': '42'},
);

This approach makes it easy to manage changes in path structure and ensures a single source of truth for route definitions.

4. Organizing Routes in Larger Apps

If you’re following a feature-first approach:

Core Layer: Defines shared resources, services, or base classes.
Feature Layer: Each feature can define its own UI, logic, and route definitions.
App (Composition) Layer: Imports both the core and the features, then merges all routes in one central GoRouter.

This avoids circular imports:

Core doesn’t import features.
Features import core if needed.
App imports both core and features to assemble the final routes.

A typical folder structure might look like this:

lib/
 ├── core/
 |    └── app_routes.dart
 ├── features/
 |    ├── feature_a/
 |    └── feature_b/
 └── app/
      ├── app_router.dart
      └── main.dart

The app_router.dart then gathers routes from core and each feature, creating one unified router.

5. Final Tips

Use go_router_builder if you want generated, type-safe route navigation functions like context.goToProfile(userId: 42).
Keep route definitions minimal and avoid burying complex logic within them.
For dynamic screens, leverage pathParameters or queryParameters to parse IDs and flags.

By following these best practices—named routes, centralized constants, and a layered architecture—you’ll save yourself tons of headaches and ensure a more maintainable Flutter codebase. Happy coding!

Designing RESTful API Routes for Following Channels 🚀

Twilight — Sun, 05 Jan 2025 05:14:04 +0000

When building applications that allow users to follow channels or creators, designing clear and intuitive RESTful API routes is crucial. This guide explores the optimal API route structure for a "follow channel" feature, especially when the action is initiated from the channel's page.

📌 Scenario

Your application has two main frontend features:

👤 User Feature: Manages user profiles, settings, and user-specific data.
📺 Channel Feature: Displays content channels that users can follow, view, and interact with.

Users perform the follow action from within the Channel feature. This context influences the best approach for structuring your API routes.

🔍 API Route Options

1. Channel-Centric Route

POST /channels/:channelId/follow
DELETE /channels/:channelId/follow

Pros:

Contextual Alignment: Reflects that the action targets a specific channel.
Simplicity: Clear and concise, making it easy to understand and use.
Scalability: Simplifies adding similar actions (e.g., like, share) under the channel.

Cons:

Less User-Focused: Doesn't directly represent the relationship from the user's perspective, which might be needed for user-specific queries.

2. User-Centric Route

POST /users/:userId/followed-channels/:channelId
DELETE /users/:userId/followed-channels/:channelId

Pros:

User-Focused: Clearly shows the relationship from the user's side, beneficial for operations like fetching all followed channels.
Flexibility: Easier to manage user-specific follow operations and extend in the future.

Cons:

Verbosity: Longer and might seem less intuitive when the action is initiated from the channel context.

🏆 Recommendation

Use the Channel-Centric Route (/channels/:channelId/follow) because:

Context Matters: Actions are performed from the channel page, making the route intuitive and relevant.
Clarity: Directly indicates the target of the action, enhancing readability and maintainability.
Consistency: Simplifies adding similar actions in the future, maintaining a uniform API structure.

Implementation Overview

Follow a Channel:

  POST /channels/:channelId/follow

Unfollow a Channel:

  DELETE /channels/:channelId/follow

Supporting User-Centric Operations

While the primary routes are channel-centric, it's essential to provide user-centric endpoints for comprehensive functionality.

Get All Followed Channels by a User:

  GET /users/:userId/followed-channels

📝 Conclusion

Choosing the right API route structure depends on the context of the action within your application. Since users follow channels from the channel page, a channel-centric route (/channels/:channelId/follow) is more intuitive and maintainable. Additionally, providing user-centric endpoints ensures that all necessary operations are well-supported, offering flexibility and comprehensive functionality.

Happy Coding! 🎉

Feel free to share your thoughts or questions in the comments below! 💬

Understanding ShellRoute in go_router: Managing Shared Layouts Effectively

Twilight — Sat, 04 Jan 2025 09:48:15 +0000

The ShellRoute in the go_router package is a powerful tool for Flutter developers to manage shared layouts like BottomNavigationBar or AppBar across different routes. This article explains how ShellRoute works and demonstrates advanced usage, including handling embedded and full-screen navigation patterns.

What is ShellRoute? 🛤️

ShellRoute acts as a container for child routes, providing a consistent layout that persists across navigations. For example, it ensures that a Scaffold and its BottomNavigationBar remain intact while only the content of the body updates based on the active route.

Example 🧑‍💻:

ShellRoute(
  builder: (context, state, child) => Scaffold(
    body: child, // Dynamic content based on the active route
    bottomNavigationBar: BottomNavigationBar(
      currentIndex: _calculateIndex(state.location),
      onTap: (index) {
        if (index == 0) context.go('/home');
        if (index == 1) context.go('/settings');
      },
      items: const [
        BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'),
        BottomNavigationBarItem(icon: Icon(Icons.settings), label: 'Settings'),
      ],
    ),
  ),
  routes: [
    GoRoute(
      path: '/home',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'detail',
          builder: (context, state) => const HomeDetailScreen(),
        ),
      ],
    ),
    GoRoute(
      path: '/settings',
      builder: (context, state) => const SettingsScreen(),
      routes: [
        GoRoute(
          path: 'detail',
          builder: (context, state) => const SettingsDetailScreen(),
          parentNavigatorKey: _rootNavigatorKey, // Full-screen detail
        ),
      ],
    ),
  ],
);

In this example, navigating between /home and /settings updates the body while keeping the BottomNavigationBar visible. Nested routes like /home/detail allow finer control over navigation behavior.

How ShellRoute Maintains Layout 🏗️

Route Matching and Widget Diffing

Consistent Layout:
- The ShellRoute builder defines shared UI components like Scaffold and BottomNavigationBar.
- These components persist across navigations because Flutter’s widget diffing mechanism ensures unchanged widgets are reused.
Dynamic Content:
- The child parameter dynamically updates based on the active route. Only the child changes, keeping the rest of the layout intact.
Flexible Nesting:
- Sub-routes under ShellRoute inherit the layout, while routes outside the ShellRoute (like /profile) replace it entirely.

Combining Embedded and Full-Screen Navigation 🔀

Sometimes, you may want a route to behave differently depending on the context:

Embedded Navigation: The detail screen appears within the ShellRoute layout.
Full-Screen Navigation: The detail screen replaces the entire layout, including the BottomNavigationBar.

Solution: Using Navigator Keys

By assigning parentNavigatorKey to specific routes, you can control whether they are displayed within the ShellRoute or as full-screen overlays.

Updated Router Configuration:

final GlobalKey<NavigatorState> _rootNavigatorKey = GlobalKey<NavigatorState>();
final GlobalKey<NavigatorState> _shellNavigatorKey = GlobalKey<NavigatorState>();

final GoRouter router = GoRouter(
  navigatorKey: _rootNavigatorKey, // Root Navigator for full-screen routes
  routes: [
    ShellRoute(
      navigatorKey: _shellNavigatorKey, // Shell Navigator for embedded routes
      builder: (context, state, child) => Scaffold(
        body: child,
        bottomNavigationBar: BottomNavigationBar(
          currentIndex: _calculateIndex(state.location),
          onTap: (index) {
            if (index == 0) context.go('/home');
            if (index == 1) context.go('/settings');
          },
          items: const [
            BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'),
            BottomNavigationBarItem(icon: Icon(Icons.settings), label: 'Settings'),
          ],
        ),
      ),
      routes: [
        GoRoute(
          path: '/home',
          builder: (context, state) => const HomeScreen(),
          routes: [
            GoRoute(
              path: 'detail',
              builder: (context, state) => const HomeDetailScreen(),
            ),
          ],
        ),
        GoRoute(
          path: '/settings',
          builder: (context, state) => const SettingsScreen(),
          routes: [
            GoRoute(
              path: 'detail',
              builder: (context, state) => const SettingsDetailScreen(),
              parentNavigatorKey: _rootNavigatorKey, // Full-screen detail
            ),
          ],
        ),
      ],
    ),
  ],
);

Navigation Examples

Embedded Navigation:
- Navigate within the ShellRoute and keep the BottomNavigationBar visible:

   context.go('/home/detail');

Full-Screen Navigation:
- Navigate outside the ShellRoute and overlay the entire screen:

   context.go('/settings/detail');

Why Use Navigator Keys? 🗝️

Flexibility: Decide at runtime whether a screen should be embedded or full-screen.
Maintainability: Keep logical route hierarchies while supporting diverse navigation behaviors.
Performance: Flutter’s widget diffing ensures efficient updates to shared layouts.

Key Takeaways 📌

ShellRoute is ideal for managing shared layouts like BottomNavigationBar across routes.
Navigator keys allow fine-grained control over navigation, enabling hybrid behaviors within the same app.
Combining embedded and full-screen navigation patterns enhances user experience while keeping code maintainable.

By understanding and leveraging these techniques, you can create flexible, performant, and user-friendly navigation in your Flutter apps.

Understanding the Dart/Flutter Event Loop with a “Factory Conveyor Belt” Metaphor

Twilight — Thu, 02 Jan 2025 15:50:10 +0000

In Flutter, understanding how tasks are executed—especially asynchronous ones—is crucial for building responsive apps. In this article, we'll break down Dart's event loop using a relatable metaphor: a factory conveyor belt. This analogy simplifies the concepts for beginners while connecting them to real-world code examples.

⚙️ Setting the Scene: A One-Worker Factory

Imagine you manage a factory with:

One worker who processes tasks.
A conveyor belt that carries tasks to the worker.

This worker can only handle one task at a time. Every task is placed in one of three areas:

Immediate Processing Area for urgent, must-do-now tasks (synchronous tasks).
High-Priority Queue for small but important tasks (microtask queue).
Low-Priority Queue for everything else (event queue).

The worker (Dart runtime) picks tasks in this order of priority and processes them accordingly. Let’s explore each area.

🔧 The Three Areas of Task Management

1. Immediate Processing Area (Synchronous Tasks)

Description: This is where tasks that must be done "right now" are handled.
Behavior: The worker cannot stop or switch to another task until the current one finishes.
In Dart: Synchronous code runs immediately and blocks the main thread.

Example:

void main() {
  print('Task 1 - Start');
  print('Task 1 - End');
}

Output:

Task 1 - Start
Task 1 - End

Here, all tasks in the Immediate Processing Area are completed sequentially.

2. High-Priority Queue (Microtask Queue)

Description: Contains tasks that must run soon but can wait until synchronous tasks finish.
Behavior: The worker processes all microtasks before moving to lower-priority tasks.
In Dart: Microtasks are typically scheduled with scheduleMicrotask() or by Future completions.

Example:

import 'dart:async';

void main() {
  print('Task 1 - Start');

  scheduleMicrotask(() => print('Microtask 1'));
  Future(() => print('Event Queue Task 1'));

  print('Task 1 - End');
}

Output:

Task 1 - Start
Task 1 - End
Microtask 1
Event Queue Task 1

Microtasks (like Microtask 1) run before tasks in the event queue.

3. Low-Priority Queue (Event Queue)

Description: Holds tasks like user input, timers, or network responses.
Behavior: The worker only processes these tasks after all synchronous and microtask queue tasks are done.
In Dart: Examples include I/O callbacks, onTap events, and Timer callbacks.

Example:

import 'dart:async';

void main() {
  print('Task 1 - Start');

  Timer(Duration(seconds: 1), () => print('Event Queue Task 1'));
  Future(() => print('Event Queue Task 2'));

  print('Task 1 - End');
}

Output:

Task 1 - Start
Task 1 - End
Event Queue Task 2
Event Queue Task 1

Tasks in the event queue are processed in order but only after higher-priority tasks.

🚧 Async, Await, and the “External Machines”

Sometimes, a task is time-consuming (e.g., network requests, file I/O, heavy computations). In our factory metaphor, these tasks can be handed off to external machines 🏭:

The worker (Dart runtime) receives a box (an async function) that needs multiple steps to complete.
Midway through the process, the worker realizes that this step requires a machine (an asynchronous task, such as calling an API or reading a file).
The worker labels this step with "await machine" and hands the box over to the machine for processing.
At this point, the worker temporarily “sets aside” the box (pausing the async function at the await point) and continues working on other boxes on the conveyor belt (processing events or microtasks). This means the event loop continues running other tasks, not blocked by the paused task.
Once the machine finishes its work, the box is returned with a note saying “OK, it’s done!” Dart moves the code after the await into the microtask queue (or event queue) for the worker to pick up and finish processing.
At this point, the worker (event loop) resumes the paused box (continues the async function after the await) and runs it to completion.

Important:

await doesn’t block the whole app. It only suspends the current async function. Everything else continues running on the event loop.

Example:

void main() async {
  print('Task 1 - Start');

  await Future.delayed(Duration(seconds: 2), () => print('Async Task Complete'));

  print('Task 1 - End');
}

Output:

Task 1 - Start
Async Task Complete
Task 1 - End

Here’s how it works:

The worker starts "Task 1".
At await, the worker hands off the task to an external machine (like a timer).
While waiting, the worker handles other tasks (if any).
When the external machine finishes, the task returns to the worker, who resumes where it left off.

🏋️ Putting It All Together

The Event Loop’s Workflow

The worker processes all synchronous tasks first (Immediate Processing Area).
It then moves to the microtask queue and processes everything there.
Finally, it processes tasks from the event queue.
If new tasks appear in the microtask queue while processing the event queue, the worker goes back to the microtask queue first.

This prioritization ensures responsiveness and keeps your Flutter app smooth.

🎉 Wrapping Up

Understanding the Dart/Flutter event loop through this "factory conveyor belt" metaphor helps demystify how synchronous and asynchronous tasks are managed. By properly using async, await, and understanding task prioritization, you can write efficient and responsive Flutter apps.

Deploying an Existing Express API + Prisma + Supabase Project to Vercel

Twilight — Wed, 01 Jan 2025 05:21:41 +0000

Deploying an existing Express API integrated with Prisma and Supabase to Vercel can be straightforward if done correctly. In this guide, we’ll cover the steps to deploy your project using the Vercel CLI (instead of GitHub Connect), the necessary configurations, and potential pitfalls to avoid.

Prerequisites

Before we start, ensure you have:

An existing project using Express, Prisma, and Supabase.
A Vercel account.
The Vercel CLI installed:

  npm install -g vercel

Supabase database credentials.

Step 1: Prepare Your Project for Vercel

1.1 Ensure Your Entry Point is Serverless Compatible

Vercel’s serverless environment works differently from traditional Node.js servers. Modify your server.js or app.js to export the Express app as a module. For example:

const express = require('express');
const app = express();

// Your routes
app.get('/', (req, res) => {
  res.send('Hello, Vercel!');
});

module.exports = app;

Then create a vercel.json file to define the serverless configuration:

{
  "version": 2,
  "builds": [
    {
      "src": "server.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/server.js"
    }
  ]
}

1.2 Prisma Client Initialization

Ensure your Prisma Client is initialized correctly to avoid multiple instances in a serverless environment. Use a singleton pattern:

const { PrismaClient } = require('@prisma/client');

let prisma;

if (!global.prisma) {
  global.prisma = new PrismaClient();
}
prisma = global.prisma;

module.exports = prisma;

1.3 Add `prisma generate` to `postinstall`

To avoid runtime errors due to missing Prisma Client files in the serverless environment, add the prisma generate command to the postinstall script in your package.json:

{
  "scripts": {
    "postinstall": "prisma generate"
  }
}

This ensures Prisma Client is always generated after dependencies are installed.

Step 2: Configure Supabase Connection

2.1 How to Get Your Database URL from Supabase

To retrieve your DATABASE_URL and DIRECT_URL from Supabase:

Log in to your Supabase Dashboard.
Select your project.
Navigate to Project Settings > API > Connection string for Prisma.
Under this section, you will find:
- DATABASE_URL: This is the connection string for using Supabase's connection pooling.
- DIRECT_URL: This is the direct connection string to your database for administrative tasks like migrations.
Copy these values and store them securely.

2.2 Add `DATABASE_URL` and `DIRECT_URL`

In Vercel, environment variables are stored securely. Navigate to Project Settings > Environment Variables in your Vercel dashboard and add:

DATABASE_URL: This connects Prisma to Supabase using connection pooling.

  postgresql://<USER>:<PASSWORD>@<PROJECT>.pooler.supabase.com:6543/<DB_NAME>?pgbouncer=true

DIRECT_URL: This allows direct connections for migrations.

  postgresql://<USER>:<PASSWORD>@<PROJECT>.supabase.co:5432/<DB_NAME>

Ensure these variables match the ones defined in your schema.prisma file:

datasource db {
  provider   = "postgresql"
  url        = env("DATABASE_URL")
  directUrl  = env("DIRECT_URL")
}

Step 3: Deploy Using Vercel CLI

3.1 Login to Vercel CLI

Run the following command to log in:

vercel login

3.2 Deploy the Project

Run the deployment command from your project’s root directory:

vercel

Follow the interactive prompts to configure your project. Select the root folder and default settings if unsure.

3.3 Set Environment Variables via CLI

You can also set environment variables using the CLI:

vercel env add DATABASE_URL
vercel env add DIRECT_URL

Paste your Supabase credentials when prompted.

Step 4: Run Prisma Migrations

To apply your Prisma migrations, use the Vercel CLI to spawn a shell on your deployment and run migrations:

vercel --prod --exec "npx prisma migrate deploy"

This ensures your database schema is up to date without manual intervention.

Conclusion

Deploying an Express API with Prisma and Supabase to Vercel requires careful configuration of serverless patterns, environment variables, and database connections. By following the steps outlined here, you can ensure a smooth deployment process and avoid common pitfalls.

If you encounter any issues or have questions, feel free to share them in the comments below! 🚀

DEV Community: Twilight

Why Many Design Systems Only Need ~4 Text Sizes (And Why That’s Totally Fine)

1. Document Hierarchy vs UI Hierarchy

Document hierarchy (content-heavy layouts)

UI hierarchy (interface layouts)

2. Why Setting Titles Usually Use Body Text

3. The Real Meaning of “Body Text”

4. Why Most Design Systems Only Need ~4 Text Sizes

1. Humans only perceive a few clear size differences

2. Product UI is usually simple

3. Fewer sizes create better consistency

4. Development becomes simpler

5. Size Isn’t the Only Way to Create Hierarchy

6. A Simple Mental Model

Final Takeaway

Why Your Domain Entities Should Keep Their Own Secrets

Scenario 1: The Wrong Way

Scenario 2: The Right Way

Back to Code

The Wrong Approach

The Better Approach

Real-World Benefits

Ever Wonder How Flutter Powers a Smooth, Live Price List for Stocks and Crypto?

Step 1: Selective Updates That Don’t Break the App

Why It’s Tricky: Don’t Redraw Everything

How I Approached It: Targeting Specific Changes

Step 2: Just Listen to What You See

Why It’s Tricky: Too Much Data

How I Approached It: Watching the Viewport

Step 3: Scroll Without the Stutter

Why It’s Tricky: Laggy Scrolling

How I Approached It: Giving It a Breather and Fixed Sizes

What I Took Away

Building a WebSocket Client in Flutter: From Zero to Hero

Part 1: Starting with a Basic Connection

Part 2: Keeping the Connection Alive with Ping-Pong

Part 3: Sending Requests

Part 4: Making Requests Smarter with ACK and Stream Management

Part 5: Adding Reconnect Logic

Wrapping Up

Mastering Auth in Flutter with Dio: From Simple Access Tokens to a Refresh Flow

1) The Simplest Setup: Only an Access Token

2) Introducing a Refresh Token Using the “One Future” Approach

Sample Code

How It Works

Pros

Cons

3) Drawbacks & the Flag + Queue Optimization

The Flag + Queue Approach

Quick Snippet

Conclusion

Further Reading

Mastering Nested Navigation in Flutter with `go_router` and a Bottom Nav Bar

1. Why Nested Navigation?

2. Setting Up a StatefulShellRoute.indexedStack

3. Making Detail Routes “Shared” Without Repetition

4. Navigating to Detail from Shared Widgets

5. Best Practices at a Glance

6. Wrapping Up

Understanding `context.push` vs `context.go` in Flutter's GoRouter

📚 Table of Contents

🚀 Introduction to GoRouter

context.push vs context.go

context.push

context.go

📊 Key Differences

👯‍♂️ Behavior with Sibling Routes

Using context.push

Using context.go

🏠 Behavior with Nested Routes

Using context.push

Using context.go

🔍 Practical Examples

📂 Route Configuration

🛠️ LoginScreen with Navigation Buttons

🏠 HomeScreen with Navigation Buttons

⚙️ SettingsScreen with Back Navigation

👤 ProfileScreen with Back Navigation

🔎 Expected Behaviors

✅ Conclusion

2. Setting Up a `StatefulShellRoute.indexedStack`

`context.push` vs `context.go`

`context.push`

`context.go`

Using `context.push`

Using `context.go`

Using `context.push`

Using `context.go`

2. Named Routes in `go_router`

1.3 Add `prisma generate` to `postinstall`

2.2 Add `DATABASE_URL` and `DIRECT_URL`