Forem: kanta13jp1

Dart Concurrency Deep Dive — Isolates, Structured Concurrency, and Async Patterns

kanta13jp1 — Sun, 03 May 2026 13:17:43 +0000

Dart's concurrency model is unusual: single-threaded event loop by default, with explicit Isolates for true parallelism. No shared memory, no race conditions, no mutex locks. This guide covers everything from the simple compute() helper to long-lived Isolate workers, structured concurrency patterns, and Stream-based reactive flows.

The Mental Model: Isolates vs Threads

Concept	Dart Isolates	JavaScript Workers	Java Threads
Memory sharing	No — message passing only	No	Yes (with sync overhead)
Startup cost	~1-5ms	~1ms	~0.1ms
Communication	SendPort/ReceivePort	postMessage	Shared memory
Good for	CPU-heavy tasks	Background compute	I/O + CPU mix

Dart's lack of shared memory is a feature: it makes concurrent code dramatically safer by eliminating data races entirely.

compute() — The 80% Solution

For one-off heavy operations, compute() handles Isolate lifecycle automatically:

// Top-level or static function only — closures capture state and can't cross Isolate boundaries
List<Product> _parseProductsSync(String json) {
  return (jsonDecode(json) as List)
      .map((e) => Product.fromJson(e as Map<String, dynamic>))
      .toList();
}

// Offload to an Isolate automatically
Future<List<Product>> fetchAndParseProducts() async {
  final response = await http.get(Uri.parse('https://api.example.com/products'));
  return compute(_parseProductsSync, response.body);
}

When to use: JSON parsing > 5ms, image processing, cryptography, regex on large strings.
When not to use: I/O operations (network, disk) — those are async and don't block the main thread.

Long-Lived Isolate Worker

For repeated heavy work, spawning a new Isolate per call is wasteful. Use a persistent worker:

class IsolateWorker {
  late final SendPort _toWorker;
  final _pending = <int, Completer<dynamic>>{};
  int _msgId = 0;

  Future<void> init() async {
    final inbox = ReceivePort();
    await Isolate.spawn(_entryPoint, inbox.sendPort);

    _toWorker = await inbox.first as SendPort;

    inbox.listen((msg) {
      final response = msg as Map<String, dynamic>;
      final id = response['id'] as int;
      final completer = _pending.remove(id);
      if (response.containsKey('error')) {
        completer?.completeError(response['error']!);
      } else {
        completer?.complete(response['result']);
      }
    });
  }

  Future<T> send<T>(String command, dynamic payload) {
    final id = _msgId++;
    final completer = Completer<T>();
    _pending[id] = completer;
    _toWorker.send({'id': id, 'command': command, 'payload': payload});
    return completer.future;
  }

  static void _entryPoint(SendPort replyTo) {
    final inbox = ReceivePort();
    replyTo.send(inbox.sendPort);

    inbox.listen((msg) {
      final request = msg as Map<String, dynamic>;
      final id = request['id'] as int;
      try {
        final result = _dispatch(request['command'] as String, request['payload']);
        replyTo.send({'id': id, 'result': result});
      } catch (e) {
        replyTo.send({'id': id, 'error': e.toString()});
      }
    });
  }

  static dynamic _dispatch(String command, dynamic payload) {
    return switch (command) {
      'reverse' => (payload as String).split('').reversed.join(),
      'sum' => (payload as List<int>).reduce((a, b) => a + b),
      _ => throw ArgumentError('Unknown command: $command'),
    };
  }
}

Structured Concurrency

Parallel Fetch with Future.wait

// All succeed or all fail fast
final (users, posts) = await (fetchUsers(), fetchPosts()).wait;

// Pre-Dart 3 equivalent
final results = await Future.wait([fetchUsers(), fetchPosts()]);

// Wait for all regardless of failures, collect errors
final settled = await Future.wait(
  [fetchA(), fetchB(), fetchC()],
  eagerError: false,
);

Race Pattern (First to Finish Wins)

Future<String> fetchWithFallback(String url) {
  return Future.any([
    http.get(Uri.parse(url)).then((r) => r.body),
    Future.delayed(
      const Duration(seconds: 3),
      () => throw TimeoutException('Primary timeout'),
    ),
    http.get(Uri.parse('$url?fallback=true')).then((r) => r.body),
  ]);
}

Cancellation Token Pattern

class CancellationToken {
  var _cancelled = false;
  bool get isCancelled => _cancelled;

  void cancel() => _cancelled = true;

  void throwIfCancelled() {
    if (_cancelled) throw CancelledException();
  }
}

class CancelledException implements Exception {}

Future<void> processPages(
  List<String> pages,
  CancellationToken token,
) async {
  for (final page in pages) {
    token.throwIfCancelled();
    await processPage(page);
  }
}

// UI usage: cancel previous operation when search changes
CancellationToken? _currentSearch;

void onSearchChanged(String query) {
  _currentSearch?.cancel();
  final token = _currentSearch = CancellationToken();

  searchDatabase(query, token).then(setState).catchError((e) {
    if (e is! CancelledException) rethrow;
  });
}

Streams for Reactive Data Flows

Broadcast Stream with Backpressure

class MarketDataService {
  final _controller = StreamController<Quote>.broadcast();

  // Buffer strategy: drop stale quotes
  Stream<Quote> get quotes => _controller.stream
      .where((q) => q.timestamp.isAfter(
          DateTime.now().subtract(const Duration(seconds: 5))));

  void _onNewQuote(Quote q) {
    if (_controller.hasListener) {
      _controller.add(q);
    }
  }
}

async* Generator Streams

Stream<SearchResult> streamSearch(String query) async* {
  for (final source in [localDb, remoteApi, cacheService]) {
    yield* source.search(query).map((r) => r.copyWith(sourceLabel: source.label));
    await Future.delayed(Duration.zero); // Yield control between sources
  }
}

Flutter Web Isolate Caveats

Flutter Web compiles Isolates to Web Workers. Constraints:

Can only transfer Transferable types: Uint8List, Int32List, primitive values
No direct dart:io access inside Isolates
compute() works but has higher overhead in debug mode

// Safe cross-platform compute wrapper
Future<T> safeCompute<T, M>(ComputeCallback<M, T> fn, M message) {
  if (kDebugMode && kIsWeb) {
    // In web debug, run synchronously to avoid Worker overhead
    return Future.value(fn(message));
  }
  return compute(fn, message);
}

Performance Rules of Thumb

Operation	Threshold for Isolate	Preferred approach
JSON parse	> 50KB	`compute()`
Image decode	Always	`compute()`
Regex on string	> 1MB	`compute()`
Network request	Never	`async/await` (non-blocking)
DB query	Never	`async/await` (non-blocking)
Encryption	Always	`compute()` or Isolate worker

Summary

Dart's concurrency model rewards understanding the right tool for each job: compute() for one-shot heavy work, persistent Isolate workers for repeated tasks, Future.wait for parallel coordination, cancellation tokens for interruptible operations, and Streams for reactive data flows. The absence of shared memory makes reasoning about correctness dramatically simpler — embrace it.

This concludes Phase 54 of the T-1 blog series. Next phase: Flutter Testing Deep Dive / Supabase pgvector / Indie Dev Community Building / Dart Macros.

Indie Dev SaaS Launch — Pricing Strategy, Stripe Integration, and Freemium-to-Paid Design

kanta13jp1 — Sun, 03 May 2026 13:17:03 +0000

Monetization is where most indie SaaS apps die. Not because the product is bad, but because the pricing is wrong, the freemium tier is too generous, or the upgrade path is invisible. This guide covers the full stack: value-based pricing principles, freemium architecture, Stripe + Supabase implementation, and conversion optimization.

Pricing Principle: Charge for Value, Not Features

The classic mistake: pricing based on features ("get 5 exports per month for $5"). The right framing: what outcome does your tool deliver?

Feature-based (weak)	Value-based (strong)
5GB storage → $5	Save 10 hours/month → $29
Export to CSV → $10	Automated reporting → $49
API access → $20	Eliminate manual data entry → $99

Van Westendorp Price Sensitivity Test

Interview 20-30 target users before launch:

"At what price is this too expensive?"
"At what price is this getting expensive, but you'd still consider it?"
"At what price is this a bargain?"
"At what price is this so cheap you'd question the quality?"

The overlap of answers 2 and 3 is your Acceptable Price Range.

Freemium Design: The Right Constraints

The goal of a free tier is to let users experience your core value — not to give away everything.

What to Gate

Gate Type	Example	Conversion Impact
Volume cap	100 records → 1,000	High — users hit wall naturally
Feature flag	Team/collaboration	Medium — solo users may not care
Data retention	30 days → unlimited	Medium — matters after 30 days
Integrations	1 webhook → unlimited	Low-Medium

Rule of thumb: Free tier should cover the first meaningful use case, not the full product.

Stripe + Supabase: Full Implementation

Edge Function: Create Checkout Session

// supabase/functions/billing-hub/index.ts
import Stripe from 'https://esm.sh/stripe@12'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!, {
  apiVersion: '2023-10-16',
  httpClient: Stripe.createFetchHttpClient(),
})

export async function createCheckout(userId: string, priceId: string): Promise<string> {
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  // Get or create Stripe customer
  const { data: profile } = await supabase
    .from('profiles')
    .select('stripe_customer_id, email')
    .eq('id', userId)
    .single()

  let customerId = profile?.stripe_customer_id
  if (!customerId) {
    const customer = await stripe.customers.create({ email: profile?.email })
    customerId = customer.id
    await supabase
      .from('profiles')
      .update({ stripe_customer_id: customerId })
      .eq('id', userId)
  }

  const session = await stripe.checkout.sessions.create({
    customer: customerId,
    mode: 'subscription',
    payment_method_types: ['card'],
    line_items: [{ price: priceId, quantity: 1 }],
    subscription_data: { trial_period_days: 14 },
    success_url: `${Deno.env.get('APP_URL')}/billing/success?session={CHECKOUT_SESSION_ID}`,
    cancel_url: `${Deno.env.get('APP_URL')}/billing`,
  })

  return session.url!
}

Webhook Handler for Subscription Sync

export async function handleStripeWebhook(req: Request) {
  const body = await req.text()
  const sig = req.headers.get('stripe-signature')!
  const event = stripe.webhooks.constructEvent(
    body, sig, Deno.env.get('STRIPE_WEBHOOK_SECRET')!
  )

  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  if (['customer.subscription.created', 'customer.subscription.updated']
       .includes(event.type)) {
    const sub = event.data.object as Stripe.Subscription
    await supabase.from('subscriptions').upsert({
      stripe_subscription_id: sub.id,
      stripe_customer_id: sub.customer as string,
      status: sub.status,
      plan_id: sub.items.data[0].price.id,
      current_period_end: new Date(sub.current_period_end * 1000).toISOString(),
      cancel_at_period_end: sub.cancel_at_period_end,
    }, { onConflict: 'stripe_subscription_id' })
  }

  if (event.type === 'customer.subscription.deleted') {
    const sub = event.data.object as Stripe.Subscription
    await supabase
      .from('subscriptions')
      .update({ status: 'canceled' })
      .eq('stripe_subscription_id', sub.id)
  }

  return new Response('ok')
}

Flutter: Plan-Gated UI

// Domain model
enum UserPlan { free, pro, team }

extension UserPlanX on UserPlan {
  bool get isPro => this == UserPlan.pro || this == UserPlan.team;
  bool get isTeam => this == UserPlan.team;
  int get exportLimit => switch (this) {
    UserPlan.free => 100,
    UserPlan.pro => 10000,
    UserPlan.team => 0, // unlimited
  };
}

// Gate widget
class PlanGate extends StatelessWidget {
  final Widget child;
  final String featureName;
  final bool Function(UserPlan) allowed;

  const PlanGate({
    required this.child,
    required this.featureName,
    required this.allowed,
    super.key,
  });

  @override
  Widget build(BuildContext context) {
    final plan = context.watch<UserPlanNotifier>().plan;
    if (allowed(plan)) return child;
    return _UpgradePrompt(featureName: featureName);
  }
}

// Usage
PlanGate(
  featureName: 'Team collaboration',
  allowed: (p) => p.isTeam,
  child: const TeamInviteButton(),
)

Usage Limit Banner

class UsageLimitBanner extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final usage = context.watch<UsageNotifier>();
    final plan = context.watch<UserPlanNotifier>().plan;
    final limit = plan.exportLimit;
    if (limit == 0) return const SizedBox.shrink();

    final pct = usage.exportsThisMonth / limit;
    if (pct < 0.8) return const SizedBox.shrink();

    return Container(
      color: pct >= 1.0 ? Colors.red.shade100 : Colors.orange.shade100,
      padding: const EdgeInsets.all(12),
      child: Row(children: [
        Icon(pct >= 1.0 ? Icons.lock : Icons.warning_amber),
        const SizedBox(width: 8),
        Expanded(child: Text(
          pct >= 1.0
            ? 'Monthly limit reached (${usage.exportsThisMonth}/$limit). Upgrade to continue.'
            : '${(pct * 100).round()}% of monthly limit used.',
        )),
        TextButton(onPressed: () => context.push('/billing'), child: const Text('Upgrade')),
      ]),
    );
  }
}

Conversion Rate Optimization Checklist

[ ] Upgrade CTA visible within 3 clicks from any screen
[ ] Show upgrade prompt at the moment the user hits a limit
[ ] Trial → paid automated email sequence: day 0, day 7 ("how's it going?"), day 12 ("trial ends soon")
[ ] Annual pricing at 20% discount shown by default (increases LTV)
[ ] Cancellation flow with personalized save offer (e.g., "Pause for 3 months?" or "50% off next 3 months?")
[ ] Stripe Customer Portal for self-serve plan changes and billing

Indie Dev Pricing Reference Points (2026)

Notion competitor: $8-16/month (task management — high willingness to pay)
Developer tools: $15-30/month (productivity ROI is calculable)
AI features: Charge based on usage or flat $10-20/month add-on
Team plans: 3-5x individual price per seat (justifiable by collaboration value)

Summary

Indie SaaS monetization is a loop: define value → design freemium constraints → integrate Stripe → optimize conversion. Flutter + Supabase + Stripe delivers this with minimal backend complexity. The biggest leverage point: show the upgrade prompt at the exact moment users hit a limit, not buried in a settings menu.

Next: Dart Concurrency deep dive — Isolates 2.0, structured concurrency patterns, and async best practices.

Supabase Edge Functions Advanced — Streaming, WebSockets, and Background Jobs

kanta13jp1 — Sun, 03 May 2026 13:16:17 +0000

Supabase Edge Functions run on Deno Deploy and are far more capable than simple REST handlers. This guide covers three advanced patterns every indie developer should know: streaming responses (for LLM integrations), WebSocket upgrades (for real-time features), and background jobs using EdgeRuntime.waitUntil.

Pattern 1: Streaming Responses (SSE)

The most common use case is streaming LLM output without blocking the client.

// supabase/functions/stream-ai/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'

serve(async (req) => {
  const { prompt } = await req.json()

  const upstream = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'x-api-key': Deno.env.get('ANTHROPIC_API_KEY')!,
      'anthropic-version': '2023-06-01',
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      model: 'claude-haiku-4-5',
      max_tokens: 1024,
      stream: true,
      messages: [{ role: 'user', content: prompt }],
    }),
  })

  // Pipe the upstream SSE stream directly to the client
  return new Response(upstream.body, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
      'Access-Control-Allow-Origin': '*',
    },
  })
})

Flutter Client for SSE

Stream<String> streamAiResponse(String prompt) async* {
  final request = http.Request(
    'POST',
    Uri.parse('$supabaseUrl/functions/v1/stream-ai'),
  )
    ..headers['Authorization'] = 'Bearer $anonKey'
    ..headers['Content-Type'] = 'application/json'
    ..body = jsonEncode({'prompt': prompt});

  final response = await request.send();

  await for (final line in response.stream
      .transform(utf8.decoder)
      .transform(const LineSplitter())) {
    if (!line.startsWith('data: ')) continue;
    final data = line.substring(6).trim();
    if (data == '[DONE]') return;

    try {
      final json = jsonDecode(data) as Map<String, dynamic>;
      final delta = json['delta']?['text'] as String?;
      if (delta != null) yield delta;
    } catch (_) {
      // skip malformed chunks
    }
  }
}

Pattern 2: WebSocket Upgrades

Edge Functions can be upgraded to full WebSocket connections, enabling real-time bidirectional communication without Supabase Realtime channels.

// supabase/functions/ws-relay/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'

// In-memory room registry (per isolate)
const rooms = new Map<string, Set<WebSocket>>()

serve((req) => {
  if (req.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
    return new Response('WebSocket upgrade required', { status: 426 })
  }

  const url = new URL(req.url)
  const room = url.searchParams.get('room') ?? 'default'

  const { socket, response } = Deno.upgradeWebSocket(req)

  socket.onopen = () => {
    if (!rooms.has(room)) rooms.set(room, new Set())
    rooms.get(room)!.add(socket)
  }

  socket.onmessage = (event) => {
    const peers = rooms.get(room) ?? new Set()
    for (const peer of peers) {
      if (peer !== socket && peer.readyState === WebSocket.OPEN) {
        peer.send(event.data)
      }
    }
  }

  socket.onclose = () => rooms.get(room)?.delete(socket)

  return response
})

Important Caveat

Each Edge Function invocation runs in its own Deno isolate. The in-memory rooms map is local to one instance. For production multi-room chat, use Supabase Realtime or a Redis-backed pub/sub.

Pattern 3: Background Jobs with waitUntil

Return a fast response to the client while doing heavy work asynchronously:

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const { user_id, event_type } = await req.json()

  // Kick off background work — fires-and-forgets after response is sent
  EdgeRuntime.waitUntil(
    runAnalyticsPipeline(user_id, event_type)
  )

  // Respond immediately — client doesn't wait for pipeline
  return new Response(JSON.stringify({ queued: true }), {
    headers: { 'Content-Type': 'application/json' },
  })
})

async function runAnalyticsPipeline(userId: string, event: string) {
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  // Heavy operations: aggregation, external API calls, email sending
  await supabase.rpc('update_user_metrics', { p_user_id: userId, p_event: event })
  await notifySlack(`User ${userId} triggered ${event}`)
}

Scheduled Execution via pg_cron

Run an Edge Function on a schedule using Supabase's built-in pg_cron extension:

SELECT cron.schedule(
  'morning-digest',
  '0 9 * * *',
  $$
  SELECT net.http_post(
    url        := current_setting('app.supabase_url') || '/functions/v1/morning-digest',
    headers    := jsonb_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || current_setting('app.service_role_key')
    ),
    body       := '{}'::jsonb
  );
  $$
);

Retry with Exponential Backoff

For external API calls inside Edge Functions:

async function fetchWithRetry(
  url: string,
  init: RequestInit,
  maxAttempts = 3
): Promise<Response> {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(url, init)
    if (res.ok || res.status < 500) return res

    if (i < maxAttempts - 1) {
      const jitter = Math.random() * 1000
      await new Promise(r => setTimeout(r, (2 ** i) * 1000 + jitter))
    }
  }
  throw new Error(`All ${maxAttempts} attempts failed for ${url}`)
}

Key Limitations to Know

Constraint	Value	Workaround
CPU time limit	400ms (free) / 2s (pro)	Use `waitUntil` for heavy work
Memory per invocation	150MB	Stream large payloads
WebSocket in-memory state	Per isolate only	Use Realtime for multi-node
Max response size	6MB	Stream or paginate

Indie Dev Cost Profile

On Supabase Free: 500K invocations/month. Streaming 1K tokens via Claude Haiku costs ~$0.001. For a 1,000-user app with 10 AI queries/day: ~10M tokens/month = $10 on Haiku. Edge Function invocations: ~10M/month — well within the Pro plan limits.

Summary

Three patterns unlock the full power of Supabase Edge Functions for production apps: SSE streaming for LLM output, WebSocket upgrades for real-time features, and EdgeRuntime.waitUntil for fire-and-forget background work. Combined with pg_cron scheduling, Edge Functions can replace a significant chunk of traditional backend infrastructure.

Next up: Indie Dev SaaS Launch — pricing strategy, Stripe integration, and freemium-to-paid conversion design.

Flutter Web Accessibility Guide — WCAG 2.2, Semantics, and Screen Reader Support

kanta13jp1 — Sun, 03 May 2026 13:13:34 +0000

Accessibility is not an afterthought — it's a quality signal. For Flutter Web, getting WCAG 2.2 compliance right requires understanding how Flutter's Semantics tree maps to browser accessibility APIs. This guide walks through practical implementation: contrast ratios, keyboard navigation, screen reader support, and automated testing.

Why Flutter Web Accessibility Is Tricky

Flutter Web uses a hybrid rendering approach (CanvasKit or HTML), meaning the DOM accessibility tree is not automatically generated the way it is in traditional web apps. You must explicitly annotate the widget tree using the Semantics widget.

CanvasKit mode: Flutter generates its own accessibility tree overlay
HTML mode: Some native HTML elements get ARIA attributes automatically — but complex custom widgets still need explicit annotation

Semantics Widget Fundamentals

Semantics(
  label: 'Submit button',
  hint: 'Submits the contact form',
  button: true,
  child: ElevatedButton(
    onPressed: _submit,
    child: const Text('Submit'),
  ),
)

WCAG 2.2 Compliance Checklist for Flutter Web

Criterion	Flutter Approach	Implementation
1.1.1 Non-text Content	`Semantics(label:)`	Required for all images and icons
1.4.3 Contrast (4.5:1)	`ThemeData` color design	Define via `ColorScheme`
2.1.1 Keyboard	`Focus` widget	`FocusTraversalGroup`
2.4.7 Focus Visible	`focusColor` styling	Border indicator
4.1.2 Name, Role, Value	Full `Semantics` props	Explicit `role`, `value`

Contrast Ratio Implementation

// Lock down contrast-safe tokens in your design system
const Color _bodyText = Color(0xFF1A1A1A);    // ratio 17.1:1 on white (AAA)
const Color _secondaryText = Color(0xFF767676); // ratio 4.54:1 on white (AA)

ThemeData buildAccessibleTheme() {
  return ThemeData(
    colorScheme: const ColorScheme.light(
      onSurface: _bodyText,
      onSurfaceVariant: _secondaryText,
    ),
    textTheme: const TextTheme(
      bodyMedium: TextStyle(color: _bodyText),
      bodySmall: TextStyle(color: _secondaryText),
    ),
  );
}

Keyboard Navigation with FocusTraversalGroup

FocusTraversalGroup(
  policy: OrderedTraversalPolicy(),
  child: Column(
    children: [
      FocusTraversalOrder(
        order: const NumericFocusOrder(1.0),
        child: const TextField(decoration: InputDecoration(labelText: 'Email')),
      ),
      FocusTraversalOrder(
        order: const NumericFocusOrder(2.0),
        child: const TextField(
          decoration: InputDecoration(labelText: 'Password'),
          obscureText: true,
        ),
      ),
      FocusTraversalOrder(
        order: const NumericFocusOrder(3.0),
        child: ElevatedButton(
          onPressed: _login,
          child: const Text('Sign In'),
        ),
      ),
    ],
  ),
)

Screen Reader Support (NVDA, VoiceOver, TalkBack)

Live Regions for Dynamic Content

// Announce status changes to screen readers
Semantics(
  liveRegion: true,
  child: Text(_statusMessage), // e.g., "Saved successfully"
)

Image Descriptions

Image.asset(
  'assets/revenue_chart.png',
  semanticLabel: 'Revenue chart: 2024 vs 2023, up 20% year-over-year',
)

Icon Buttons — Always Add Tooltip

IconButton(
  icon: const Icon(Icons.delete_outline),
  tooltip: 'Delete item', // becomes the accessible label automatically
  onPressed: _deleteItem,
)

Excluding Decorative Elements

ExcludeSemantics(
  child: Row(
    children: [
      Icon(Icons.star, color: Colors.amber),
      Icon(Icons.star, color: Colors.amber),
      Icon(Icons.star_half, color: Colors.amber),
    ],
  ),
)
// Pair with a text label: Semantics(label: 'Rating: 3.5 out of 5')

Programmatic Announcements

// Announce transient messages without changing focus
SemanticsService.announce(
  'Your message has been sent',
  TextDirection.ltr,
);

Automated Accessibility Testing

testWidgets('Login form meets basic WCAG requirements', (tester) async {
  final SemanticsHandle handle = tester.ensureSemantics();
  await tester.pumpWidget(const MaterialApp(home: LoginPage()));

  // Email field has accessible label
  expect(
    tester.getSemantics(find.byType(TextField).first),
    matchesSemantics(label: 'Email'),
  );

  // Submit button has accessible role
  expect(
    tester.getSemantics(find.byType(ElevatedButton)),
    matchesSemantics(
      label: 'Sign In',
      isButton: true,
      hasEnabledState: true,
      isEnabled: true,
    ),
  );

  handle.dispose();
});

Indie Dev Perspective: Why This Matters Now

For solo founders, accessibility is increasingly a legal and market requirement:

EU Web Accessibility Directive (2025 deadline for private sector apps)
Apple App Store prioritizes accessible apps in search rankings
Screen reader users represent 7% of the global internet population

Adding Semantics wrapping takes 15 minutes per screen and prevents costly retrofits later.

Summary

Flutter Web accessibility requires intentional work: the Semantics widget for annotations, ColorScheme for contrast, FocusTraversalGroup for keyboard navigation, and SemanticsService for live announcements. The automated testing hooks in Flutter's test framework let you catch regressions before they reach users.

Next up: Supabase Edge Functions advanced patterns — streaming responses, WebSocket upgrades, and background job scheduling.

Publishing a Dart Package to pub.dev — pubspec, dartdoc, and Automated CI

kanta13jp1 — Sun, 03 May 2026 11:28:00 +0000

Publishing an open-source Dart package is one of the highest-leverage things an indie developer can do: it builds your reputation, drives traffic, and forces you to write cleaner code. This guide walks you through every step — package structure, pubspec setup, API docs, testing, and a fully automated GitHub Actions publish pipeline.

1. Package Structure

my_package/
  lib/
    my_package.dart          # Main export barrel file
    src/
      feature_a.dart         # Implementation (not for direct import)
      feature_b.dart
  example/
    lib/
      main.dart              # Shown on pub.dev
  test/
    feature_a_test.dart
    feature_b_test.dart
  CHANGELOG.md               # Required — follows keep-a-changelog format
  LICENSE                    # Required — MIT or BSD-3 recommended
  README.md                  # pub.dev landing page
  pubspec.yaml               # Package metadata

2. pubspec.yaml

name: my_flutter_utils
description: >-
  Flutter utilities for debounced search, infinite scroll,
  form validation, and common UI patterns.
version: 1.0.0
homepage: https://github.com/your-org/my_flutter_utils
repository: https://github.com/your-org/my_flutter_utils
issue_tracker: https://github.com/your-org/my_flutter_utils/issues

# Explicitly list supported platforms (affects pub.dev score)
platforms:
  android:
  ios:
  linux:
  macos:
  web:
  windows:

environment:
  sdk: '>=3.3.0 <4.0.0'
  flutter: '>=3.19.0'

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^4.0.0
  pana: ^0.21.0

Semantic Versioning Rules

MAJOR.MINOR.PATCH  e.g. 2.1.3

MAJOR — breaking changes (removed/renamed public APIs)
MINOR — backward-compatible new features
PATCH — bug fixes and internal improvements

Pre-release suffixes:
  1.0.0-beta.1   beta
  1.0.0-rc.1     release candidate
  2.0.0-dev.1    dev snapshot

Version constraints for dependencies:
  ^1.2.3           = >=1.2.3 <2.0.0  (recommended — pin MAJOR)
  >=1.0.0 <3.0.0   = allow two major versions

3. Writing dartdoc Comments

pub.dev scores heavily weight API documentation coverage. Every public member needs a /// doc comment with a code example.

/// A search service that delays execution until input settles.
///
/// When [search] is called repeatedly within [duration],
/// only the last call executes. Ideal for search-as-you-type UIs
/// where you don't want to fire an API request on every keystroke.
///
/// ```
{% endraw %}
dart
/// final service = DebouncedSearchService(
///   duration: const Duration(milliseconds: 300),
///   onSearch: (query) async {
///     final results = await api.search(query);
///     setState(() => _results = results);
///   },
/// );
///
/// // Wire up to a TextField
/// TextField(
///   onChanged: service.search,
/// );
///
{% raw %}

///
/// Remember to call [dispose] to cancel any pending timer:
/// ```

dart
/// @override
/// void dispose() {
/// service.dispose();
/// super.dispose();
/// }
///

///
/// See also:
///   - [ThrottledSearchService] for leading-edge execution
///   - [CachedSearchService] for memoized results
class DebouncedSearchService {
  /// How long to wait after the last [search] call before executing.
  ///
  /// Defaults to 300 milliseconds.
  final Duration duration;

  /// Called with the final query string after [duration] elapses.
  ///
  /// Must return a [Future]. Exceptions are forwarded to [onError].
  final Future<void> Function(String query) onSearch;

  /// Optional error handler.
  ///
  /// If omitted, errors from [onSearch] are silently swallowed.
  final void Function(Object error, StackTrace stack)? onError;

  Timer? _timer;

  /// Creates a [DebouncedSearchService].
  ///
  /// Both [duration] and [onSearch] are required.
  DebouncedSearchService({
    this.duration = const Duration(milliseconds: 300),
    required this.onSearch,
    this.onError,
  });

  /// Schedules a search for [query].
  ///
  /// If called again within [duration], the previous call is cancelled.
  void search(String query) {
    _timer?.cancel();
    _timer = Timer(duration, () async {
      try {
        await onSearch(query);
      } catch (e, s) {
        onError?.call(e, s);
      }
    });
  }

  /// Cancels any pending search and frees resources.
  ///
  /// After calling [dispose], do not call [search] again.
  void dispose() {
    _timer?.cancel();
    _timer = null;
  }
}

Barrel File with Library-level Docs

// lib/my_flutter_utils.dart
/// Utility toolkit for Flutter apps.
///
/// ## Features
///
/// - **Search**: [DebouncedSearchService], [ThrottledSearchService]
/// - **Forms**: [EmailValidator], [PasswordStrengthMeter]
/// - **Scroll**: [InfiniteScrollController], [PaginatedListView]
///
/// ## Quick start
///
/// ```
{% endraw %}
dart
/// import 'package:my_flutter_utils/my_flutter_utils.dart';
///
/// final search = DebouncedSearchService(
///   onSearch: (q) async { /* call your API */ },
/// );
///
{% raw %}

library my_flutter_utils;

export 'src/search/debounced_search_service.dart';
export 'src/search/throttled_search_service.dart';
export 'src/forms/email_validator.dart';
export 'src/forms/password_strength_meter.dart';
export 'src/scroll/infinite_scroll_controller.dart';
export 'src/scroll/paginated_list_view.dart';




## 4. Writing Tests



```dart
// test/debounced_search_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:my_flutter_utils/my_flutter_utils.dart';

void main() {
  group('DebouncedSearchService', () {
    late DebouncedSearchService sut;
    final calls = <String>[];

    setUp(() {
      calls.clear();
      sut = DebouncedSearchService(
        duration: const Duration(milliseconds: 100),
        onSearch: (q) async => calls.add(q),
      );
    });

    tearDown(sut.dispose);

    test('executes after delay', () async {
      sut.search('flutter');
      expect(calls, isEmpty);

      await Future.delayed(const Duration(milliseconds: 150));
      expect(calls, ['flutter']);
    });

    test('only executes the last call when debounced', () async {
      for (final q in ['f', 'fl', 'flu', 'flut', 'flutt', 'flutter']) {
        sut.search(q);
      }

      await Future.delayed(const Duration(milliseconds: 150));
      expect(calls, ['flutter']); // only the last one
    });

    test('resets timer on new call', () async {
      sut.search('first');
      await Future.delayed(const Duration(milliseconds: 60));
      sut.search('second'); // resets timer

      await Future.delayed(const Duration(milliseconds: 80));
      expect(calls, isEmpty); // neither has fired yet

      await Future.delayed(const Duration(milliseconds: 70));
      expect(calls, ['second']);
    });

    test('does not fire after dispose', () async {
      sut.search('query');
      sut.dispose();

      await Future.delayed(const Duration(milliseconds: 150));
      expect(calls, isEmpty);
    });

    test('routes errors to onError handler', () async {
      Object? caught;
      final errorSut = DebouncedSearchService(
        onSearch: (_) async => throw StateError('boom'),
        onError: (e, _) => caught = e,
      );

      errorSut.search('q');
      await Future.delayed(const Duration(milliseconds: 150));

      expect(caught, isA<StateError>());
      errorSut.dispose();
    });
  });
}

5. CHANGELOG.md Format

## Unreleased

## 1.1.0 — 2030-08-15

### Added
- `DebouncedSearchService`: `onError` callback parameter
- `EmailValidator`: internationalized domain names (IDN) support

### Fixed
- `InfiniteScrollController`: memory leak on dispose

## 1.0.1 — 2030-07-20

### Changed
- `PaginatedListView`: improved loading indicator styling

## 1.0.0 — 2030-07-01

- Initial release

6. GitHub Actions — Automated Publishing

# .github/workflows/pub-publish.yml
name: Publish to pub.dev

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+*'   # v1.0.0, v2.0.0-beta.1, etc.

permissions:
  id-token: write   # Required for pub.dev OIDC authentication

jobs:
  test:
    name: Test & Analyze
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: dart-lang/setup-dart@v1
        with:
          sdk: stable

      - name: Install dependencies
        run: dart pub get

      - name: Check formatting
        run: dart format --output=none --set-exit-if-changed .

      - name: Analyze
        run: dart analyze --fatal-infos

      - name: Run tests with coverage
        run: dart test --coverage=coverage

      - name: Enforce ≥80% coverage
        run: |
          dart pub global activate coverage
          dart pub global run coverage:format_coverage \
            --lcov --in=coverage --out=coverage/lcov.info \
            --report-on=lib
          total=$(grep -c "^DA:" coverage/lcov.info)
          hit=$(grep -cP "^DA:\d+,[^0]" coverage/lcov.info)
          pct=$(( hit * 100 / total ))
          echo "Coverage: $pct% ($hit/$total lines)"
          [ "$pct" -ge 80 ] || (echo "Coverage below 80%" && exit 1)

  score-check:
    name: pub.dev Score Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dart-lang/setup-dart@v1
        with:
          sdk: stable
      - run: dart pub get

      - name: Run pana
        run: |
          dart pub global activate pana
          dart pub global run pana --no-warning . | tee pana.txt
          score=$(grep -oP 'Points: \K\d+(?=/\d+)' pana.txt | head -1 || echo 0)
          echo "pub.dev score: $score / 140"
          [ "${score:-0}" -ge 120 ] || echo "::warning::Score below 120"

  publish:
    name: Publish
    needs: [test, score-check]
    runs-on: ubuntu-latest
    environment: pub-publish  # Require manual approval in GitHub Environments
    steps:
      - uses: actions/checkout@v4

      - uses: dart-lang/setup-dart@v1
        with:
          sdk: stable

      - run: dart pub get

      - name: Dry run
        run: dart pub publish --dry-run

      - name: Publish
        run: dart pub publish --force
        # No secrets needed — OIDC auth via id-token permission above

Tag and Release

# 1. Bump version in pubspec.yaml and update CHANGELOG.md
vim pubspec.yaml        # version: 1.1.0
vim CHANGELOG.md        # Add ## 1.1.0 section

# 2. Commit
git add pubspec.yaml CHANGELOG.md
git commit -m "chore: release v1.1.0"

# 3. Tag — this triggers the GHA workflow
git tag v1.1.0
git push origin main --tags

# 4. Watch the workflow
gh run watch

7. pub.dev Score Checklist

Check	Weight	Action
`dart analyze` passes	High	Add `flutter_lints`, fix all warnings
API docs ≥20% public members	High	`///` on every public API
LICENSE file present	Required	MIT or BSD-3
CHANGELOG.md present	Required	keep-a-changelog format
README.md (English)	High	Badges + quick start + screenshots
`example/` folder	High	Shown on pub.dev package page
All platforms declared	Medium	`platforms:` in pubspec.yaml
`--dry-run` passes	Required	Always check before tagging

Summary

A well-published Dart package needs:

pubspec.yaml — accurate platforms, SDK range, and description
dartdoc — every public API documented with runnable code samples
Tests — 80%+ coverage and edge cases covered
CHANGELOG.md — human-readable release notes
CI — pana score gate + OIDC automated publish on tag

Start small: publish one utility class you've already written. The process of making it package-worthy — good docs, tests, a clean API — will make you a better developer. Your pub.dev profile becomes part of your portfolio.

Indie Dev Growth Loops — Referral Mechanics, Analytics, and Viral Coefficient in Flutter

kanta13jp1 — Sun, 03 May 2026 11:26:18 +0000

"Build it and they will come" is a myth. Indie developers need to engineer growth into the product from day one. This guide covers growth loop design, referral mechanics with real Dart code, UTM attribution, and analytics setup — all things you can ship in a weekend.

1. Growth Loops vs Funnels

A funnel is linear and leaky: Ads → Landing page → Sign-up → Paid. When users drop off, growth stops.

A growth loop is self-reinforcing. User actions produce more users.

Content loop example:
  User creates content
  → Shares it publicly
  → New visitor sees the content
  → Signs up and creates content
  → Loop repeats

Loop Type	Example	Key Mechanic
Viral / Share	Figma share links	ShareCard, social posts
Content	Notion public pages	SEO, OGP previews
Referral	Dropbox "invite a friend"	Two-sided reward
Product-led	Slack free tier	Freemium + upgrade nudge

2. Viral Coefficient (K-factor)

import 'dart:math';

class ViralMetrics {
  /// K-factor = invites_sent_per_user * conversion_rate
  /// K > 1 → exponential growth; K < 1 → linear with ceiling
  static double kFactor({
    required double invitesSentPerUser,
    required double conversionRate,
  }) =>
      invitesSentPerUser * conversionRate;

  /// Project users after [cycles] viral cycles
  static int projectGrowth({
    required int initialUsers,
    required double k,
    required int cycles,
  }) {
    if (k >= 1) {
      // Geometric series: U_n = U_0 * (k^n - 1) / (k - 1)
      return (initialUsers * (pow(k, cycles) - 1) / (k - 1)).round();
    }
    // Convergent series: U_∞ ≈ U_0 / (1 - k)
    return (initialUsers / (1 - k)).round();
  }
}

// Even K = 0.3 means 43% organic amplification:
// 1000 users → invite 2 each → 30% convert = 600 extra users in one cycle
void main() {
  const k = 0.3;     // each user invites 2, 15% convert
  final projected = ViralMetrics.projectGrowth(
    initialUsers: 1000,
    k: k,
    cycles: 5,
  );
  print('Projected after 5 cycles: $projected users'); // ~2143
}

3. Referral System

Backend — Idempotent Reward Grant

-- migration: referral_codes + referral_events + grant function

CREATE TABLE referral_codes (
  code        TEXT PRIMARY KEY,
  user_id     UUID NOT NULL REFERENCES auth.users(id),
  created_at  TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE referral_events (
  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  code          TEXT REFERENCES referral_codes(code),
  referrer_id   UUID,
  new_user_id   UUID,
  type          TEXT NOT NULL, -- 'invite_sent' | 'converted'
  converted     BOOLEAN DEFAULT false,
  occurred_at   TIMESTAMPTZ DEFAULT now()
);

-- Idempotent: safe to call twice
CREATE OR REPLACE FUNCTION grant_referral_reward(
  p_referrer_id UUID,
  p_new_user_id UUID,
  p_code        TEXT
)
RETURNS void LANGUAGE plpgsql AS $$
BEGIN
  -- Prevent double-granting
  IF EXISTS (
    SELECT 1 FROM referral_events
    WHERE new_user_id = p_new_user_id AND type = 'converted'
  ) THEN RETURN; END IF;

  -- Mark conversion
  INSERT INTO referral_events (code, referrer_id, new_user_id, type, converted)
  VALUES (p_code, p_referrer_id, p_new_user_id, 'converted', true);

  -- Grant 30 days to both users
  UPDATE user_subscriptions
  SET trial_ends_at = GREATEST(trial_ends_at, now()) + INTERVAL '30 days'
  WHERE user_id IN (p_referrer_id, p_new_user_id);
END;
$$;

Flutter ReferralService

import 'package:share_plus/share_plus.dart';

class ReferralService {
  static const _appUrl = 'https://your-app.com';

  Future<String> getOrCreateCode(String userId) async {
    final row = await supabase
        .from('referral_codes')
        .select('code')
        .eq('user_id', userId)
        .maybeSingle();
    if (row != null) return row['code'] as String;

    final code = _buildCode(userId);
    await supabase.from('referral_codes').insert({
      'user_id': userId,
      'code': code,
    });
    return code;
  }

  String _buildCode(String userId) {
    final prefix = userId.replaceAll('-', '').substring(0, 6).toUpperCase();
    const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
    final r = Random.secure();
    final suffix = List.generate(4, (_) => chars[r.nextInt(chars.length)]).join();
    return '$prefix$suffix';
  }

  Future<void> shareInvite({
    required String code,
    required String senderName,
  }) async {
    final url = '$_appUrl/join?ref=$code';
    final text = '$senderName invited you!\n'
        'We both get 30 days free premium when you sign up.\n\n$url';

    await Share.share(text, subject: 'Join me on the app');

    // Track that an invite was sent
    await supabase.from('referral_events').insert({
      'code': code,
      'type': 'invite_sent',
    });
  }

  Future<void> processReferral({
    required String newUserId,
    required String code,
  }) async {
    final row = await supabase
        .from('referral_codes')
        .select('user_id')
        .eq('code', code)
        .maybeSingle();
    if (row == null) return;

    await supabase.rpc('grant_referral_reward', params: {
      'p_referrer_id': row['user_id'],
      'p_new_user_id': newUserId,
      'p_code': code,
    });
  }
}

ShareCard Widget

class ShareCard extends StatelessWidget {
  final String code;
  final String userName;

  const ShareCard({super.key, required this.code, required this.userName});

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(24),
      decoration: BoxDecoration(
        gradient: const LinearGradient(
          colors: [Color(0xFF6C63FF), Color(0xFF3B82F6)],
          begin: Alignment.topLeft,
          end: Alignment.bottomRight,
        ),
        borderRadius: BorderRadius.circular(16),
        boxShadow: [
          BoxShadow(
            color: const Color(0xFF6C63FF).withOpacity(0.3),
            blurRadius: 20,
            offset: const Offset(0, 8),
          ),
        ],
      ),
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            "$userName's invite",
            style: const TextStyle(color: Colors.white, fontSize: 18, fontWeight: FontWeight.bold),
          ),
          const SizedBox(height: 8),
          const Text(
            'Sign up and we both get\n30 days free premium',
            style: TextStyle(color: Colors.white70, height: 1.6),
          ),
          const SizedBox(height: 20),
          _CodeRow(code: code),
        ],
      ),
    );
  }
}

class _CodeRow extends StatelessWidget {
  final String code;
  const _CodeRow({required this.code});

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
      decoration: BoxDecoration(
        color: Colors.white.withOpacity(0.15),
        borderRadius: BorderRadius.circular(10),
      ),
      child: Row(
        mainAxisAlignment: MainAxisAlignment.spaceBetween,
        children: [
          Text(
            code,
            style: const TextStyle(
              color: Colors.white,
              fontWeight: FontWeight.w700,
              letterSpacing: 3,
              fontSize: 20,
            ),
          ),
          GestureDetector(
            onTap: () {
              Clipboard.setData(ClipboardData(text: code));
              ScaffoldMessenger.of(context)
                  .showSnackBar(const SnackBar(content: Text('Code copied!')));
            },
            child: const Icon(Icons.copy_rounded, color: Colors.white),
          ),
        ],
      ),
    );
  }
}

4. UTM Attribution

import 'package:flutter_secure_storage/flutter_secure_storage.dart';

class UtmService {
  static const _storage = FlutterSecureStorage();
  static const _key = 'first_touch_utm';

  /// Call from your deep-link handler on first launch
  static Future<void> capture(Uri uri) async {
    final params = <String, String>{};
    for (final p in ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'ref']) {
      final v = uri.queryParameters[p];
      if (v != null) params[p] = v;
    }
    if (params.isNotEmpty) {
      // Only save first touch — don't overwrite
      final existing = await _storage.read(key: _key);
      if (existing == null) {
        await _storage.write(key: _key, value: jsonEncode(params));
      }
    }
  }

  static Future<Map<String, String>> getFirstTouch() async {
    final raw = await _storage.read(key: _key);
    if (raw == null) return {};
    return Map<String, String>.from(jsonDecode(raw) as Map);
  }

  static Future<void> attributeSignUp(String userId) async {
    final utm = await getFirstTouch();
    if (utm.isEmpty) return;
    await supabase.from('user_attributions').insert({
      'user_id': userId,
      ...utm,
      'attributed_at': DateTime.now().toIso8601String(),
    });
  }
}

5. Analytics — Lightweight Self-hosted

class Analytics {
  static String? _sessionId;
  static String get sessionId => _sessionId ??= _newSessionId();
  static String _newSessionId() =>
      DateTime.now().millisecondsSinceEpoch.toRadixString(36);

  static String _page = '/';
  static void setPage(String page) => _page = page;

  static Future<void> track(
    String event, {
    Map<String, dynamic>? props,
  }) async {
    try {
      await supabase.from('analytics_events').insert({
        'user_id': supabase.auth.currentUser?.id,
        'event': event,
        'page': _page,
        'session_id': sessionId,
        'properties': props ?? {},
        'occurred_at': DateTime.now().toIso8601String(),
      });
    } catch (_) {
      // Never crash the app because of analytics
    }
  }
}

// Usage throughout the app
await Analytics.track('referral_shared', props: {'code': code});
await Analytics.track('feature_used', props: {'feature': 'realtime_chat'});
await Analytics.track('upgrade_prompt_shown', props: {'location': 'settings'});
await Analytics.track('subscription_started', props: {'plan': 'pro', 'source': 'referral'});

6. App Store Optimization for Flutter PWA

// web/index.html additions for PWA discoverability
// Add to <head>:
// <meta name="theme-color" content="#6C63FF">
// <meta name="apple-mobile-web-app-capable" content="yes">
// <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
// <link rel="manifest" href="manifest.json">

// web/manifest.json
const manifest = {
  "name": "Your App Name",
  "short_name": "YourApp",
  "description": "One-line pitch for your app",
  "start_url": "/?utm_source=pwa_homescreen",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#6C63FF",
  "categories": ["productivity", "utilities"],
  "screenshots": [
    {"src": "screenshots/home.png", "sizes": "1280x720", "type": "image/png"}
  ]
};

Summary

Growth Lever	Impact	Time to Ship
Referral system	K-factor +0.1–0.3	1–2 days
UTM attribution	Identify best channels	2 hours
ShareCard widget	Lower sharing friction	2 hours
Analytics events	Measure and iterate	1 day

Even a K-factor of 0.3 gives you a 43% organic boost on top of paid acquisition. The secret is not one big growth hack — it's a dozen small optimizations that compound. Next week: publishing your first Dart package on pub.dev.

Supabase Realtime with Flutter — Postgres Changes, Presence, and Broadcast in Practice

kanta13jp1 — Sun, 03 May 2026 11:20:50 +0000

Supabase Realtime streams PostgreSQL changes to clients over WebSocket. Combine it with Flutter and you can ship live notifications, "who's online" indicators, and collaborative editing in dozens of lines of code. This guide covers all three channel types — Postgres Changes, Presence, and Broadcast — with production-ready examples.

The Three Channel Types

Type	Use Case	Data Source
Postgres Changes	React to INSERT/UPDATE/DELETE	PostgreSQL WAL
Broadcast	Client-to-client events	Realtime server
Presence	"Who's online" state sync	Realtime server

Setup

# pubspec.yaml
dependencies:
  supabase_flutter: ^2.5.0

// main.dart
import 'package:supabase_flutter/supabase_flutter.dart';

void main() async {
  await Supabase.initialize(
    url: 'https://<project>.supabase.co',
    anonKey: '<anon-key>',
    realtimeClientOptions: const RealtimeClientOptions(
      eventsPerSecond: 10,
      logLevel: RealtimeLogLevel.info,
    ),
  );
  runApp(const App());
}

final supabase = Supabase.instance.client;

1. Postgres Changes — Real-time DB Events

Enable Realtime on Your Table

-- Run in Supabase Dashboard or a migration file
ALTER TABLE notifications REPLICA IDENTITY FULL;
ALTER PUBLICATION supabase_realtime ADD TABLE notifications;

-- RLS: users see only their own notifications
CREATE POLICY "users can view own notifications"
  ON notifications FOR SELECT
  USING (user_id = auth.uid());

Subscribe in Flutter

class NotificationService {
  RealtimeChannel? _channel;

  void subscribe(String userId, void Function(Map<String, dynamic>) onNew) {
    _channel = supabase
        .channel('notifications:$userId')
        .onPostgresChanges(
          event: PostgresChangeEvent.insert,
          schema: 'public',
          table: 'notifications',
          filter: PostgresChangeFilter(
            type: PostgresChangeFilterType.eq,
            column: 'user_id',
            value: userId,
          ),
          callback: (payload) => onNew(payload.newRecord),
        )
        .onPostgresChanges(
          event: PostgresChangeEvent.update,
          schema: 'public',
          table: 'notifications',
          filter: PostgresChangeFilter(
            type: PostgresChangeFilterType.eq,
            column: 'user_id',
            value: userId,
          ),
          callback: (payload) {
            // Handle read-status updates
            debugPrint('Updated: ${payload.newRecord}');
          },
        )
        .subscribe();
  }

  void unsubscribe() {
    _channel?.unsubscribe();
    _channel = null;
  }
}

Notification Bell Widget

class NotificationBell extends StatefulWidget {
  const NotificationBell({super.key});

  @override
  State<NotificationBell> createState() => _NotificationBellState();
}

class _NotificationBellState extends State<NotificationBell> {
  final _service = NotificationService();
  int _unreadCount = 0;
  final _items = <Map<String, dynamic>>[];

  @override
  void initState() {
    super.initState();
    _loadInitial();
    _service.subscribe(supabase.auth.currentUser!.id, _onNew);
  }

  Future<void> _loadInitial() async {
    final data = await supabase
        .from('notifications')
        .select()
        .eq('user_id', supabase.auth.currentUser!.id)
        .eq('read', false)
        .order('created_at', ascending: false)
        .limit(20);

    if (!mounted) return;
    setState(() {
      _items.addAll(List<Map<String, dynamic>>.from(data));
      _unreadCount = _items.length;
    });
  }

  void _onNew(Map<String, dynamic> notification) {
    setState(() {
      _items.insert(0, notification);
      _unreadCount++;
    });
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(notification['message'] as String? ?? 'New notification')),
    );
  }

  @override
  void dispose() {
    _service.unsubscribe();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Badge(
      isLabelVisible: _unreadCount > 0,
      label: Text('$_unreadCount'),
      child: IconButton(
        icon: const Icon(Icons.notifications_outlined),
        onPressed: () => showModalBottomSheet(
          context: context,
          builder: (_) => _NotificationPanel(items: _items),
        ),
      ),
    );
  }
}

2. Presence — Track Who's Online

Presence syncs each client's arbitrary state object (online status, cursor position, active document…) to every subscriber in the channel.

class PresenceService {
  RealtimeChannel? _channel;
  final _users = <String, Map<String, dynamic>>{};

  void Function(Map<String, Map<String, dynamic>>)? onSync;

  void join({
    required String roomId,
    required String userId,
    required String displayName,
    String? avatarUrl,
  }) {
    _channel = supabase.channel('room:$roomId')
      ..onPresenceSync((_) {
        _users.clear();
        _channel!.presenceState().forEach((_, presences) {
          if (presences.isNotEmpty) {
            final p = presences.first;
            _users[p['user_id'] as String] = Map<String, dynamic>.from(p);
          }
        });
        onSync?.call(Map.unmodifiable(_users));
      })
      ..onPresenceJoin((payload) {
        for (final p in payload.newPresences) {
          debugPrint('${p['display_name']} joined');
        }
      })
      ..onPresenceLeave((payload) {
        for (final p in payload.leftPresences) {
          _users.remove(p['user_id']);
        }
        onSync?.call(Map.unmodifiable(_users));
      });

    _channel!.subscribe((status, _) async {
      if (status == RealtimeSubscribeStatus.subscribed) {
        await _channel!.track({
          'user_id': userId,
          'display_name': displayName,
          'avatar_url': avatarUrl,
          'online_at': DateTime.now().toIso8601String(),
        });
      }
    });
  }

  /// Update cursor position for live collaboration
  Future<void> updateCursor(double x, double y) async {
    await _channel?.track({'cursor': {'x': x, 'y': y}});
  }

  Future<void> leave() async {
    await _channel?.untrack();
    await _channel?.unsubscribe();
    _channel = null;
  }
}

Online Users Avatars Widget

class OnlineAvatarRow extends StatelessWidget {
  final Map<String, Map<String, dynamic>> users;
  final int maxVisible;

  const OnlineAvatarRow({
    super.key,
    required this.users,
    this.maxVisible = 5,
  });

  @override
  Widget build(BuildContext context) {
    final list = users.values.toList();
    return Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        ...list.take(maxVisible).map((u) {
          final name = u['display_name'] as String? ?? '?';
          final avatar = u['avatar_url'] as String?;
          return Padding(
            padding: const EdgeInsets.only(right: 4),
            child: Tooltip(
              message: name,
              child: CircleAvatar(
                radius: 14,
                backgroundImage: avatar != null ? NetworkImage(avatar) : null,
                child: avatar == null ? Text(name[0].toUpperCase()) : null,
              ),
            ),
          );
        }),
        if (list.length > maxVisible)
          Text(
            '+${list.length - maxVisible}',
            style: Theme.of(context).textTheme.labelSmall,
          ),
        const SizedBox(width: 6),
        Row(children: [
          Container(
            width: 8,
            height: 8,
            decoration: const BoxDecoration(
              color: Colors.green,
              shape: BoxShape.circle,
            ),
          ),
          const SizedBox(width: 4),
          Text('${list.length} online',
              style: Theme.of(context).textTheme.labelSmall),
        ]),
      ],
    );
  }
}

3. Broadcast — Low-latency Peer Messaging

Broadcast skips the database entirely — perfect for chat messages, emoji reactions, and live cursors.

class ChatBroadcastService {
  RealtimeChannel? _channel;

  void Function(ChatMessage)? onMessage;
  void Function(String userId, String emoji)? onReaction;

  void connect(String roomId) {
    _channel = supabase.channel(
      'chat:$roomId',
      opts: const RealtimeChannelConfig(ack: false),
    )
      ..onBroadcast(
        event: 'message',
        callback: (payload) => onMessage?.call(ChatMessage.fromJson(payload)),
      )
      ..onBroadcast(
        event: 'reaction',
        callback: (payload) => onReaction?.call(
          payload['user_id'] as String,
          payload['emoji'] as String,
        ),
      )
      ..subscribe();
  }

  Future<void> sendMessage(ChatMessage msg) => _channel!.sendBroadcastMessage(
        event: 'message',
        payload: msg.toJson(),
      );

  Future<void> react(String userId, String emoji) =>
      _channel!.sendBroadcastMessage(
        event: 'reaction',
        payload: {'user_id': userId, 'emoji': emoji},
      );

  void disconnect() {
    _channel?.unsubscribe();
    _channel = null;
  }
}

class ChatMessage {
  final String id;
  final String userId;
  final String displayName;
  final String body;
  final DateTime sentAt;

  const ChatMessage({
    required this.id,
    required this.userId,
    required this.displayName,
    required this.body,
    required this.sentAt,
  });

  factory ChatMessage.fromJson(Map<String, dynamic> j) => ChatMessage(
        id: j['id'] as String,
        userId: j['user_id'] as String,
        displayName: j['display_name'] as String,
        body: j['body'] as String,
        sentAt: DateTime.parse(j['sent_at'] as String),
      );

  Map<String, dynamic> toJson() => {
        'id': id,
        'user_id': userId,
        'display_name': displayName,
        'body': body,
        'sent_at': sentAt.toIso8601String(),
      };
}

4. Rate Limits and Throttling

/// Throttle broadcasts to avoid hitting plan limits.
class ThrottledChannel {
  final RealtimeChannel _channel;
  final Duration _interval;
  Timer? _timer;
  Map<String, dynamic>? _pending;

  ThrottledChannel(this._channel, {Duration interval = const Duration(milliseconds: 50)})
      : _interval = interval;

  void send(String event, Map<String, dynamic> payload) {
    _pending = {'event': event, 'payload': payload};
    _timer ??= Timer(_interval, _flush);
  }

  void _flush() {
    if (_pending != null) {
      _channel.sendBroadcastMessage(
        event: _pending!['event'] as String,
        payload: _pending!['payload'] as Map<String, dynamic>,
      );
      _pending = null;
    }
    _timer = null;
  }

  void dispose() => _timer?.cancel();
}

// 30fps cursor broadcast
final _cursorChannel = ThrottledChannel(
  channel,
  interval: const Duration(milliseconds: 33),
);

void onPointerMove(PointerMoveEvent event) {
  _cursorChannel.send('cursor', {'x': event.position.dx, 'y': event.position.dy});
}

Plan Limits (as of 2030)

Plan	Connections	Messages/sec	Presence members
Free	200	10	100/channel
Pro	500	100	500/channel
Team	10,000	500	10,000/channel

Summary

The three Realtime channel types cover distinct needs:

Postgres Changes — database-driven notifications with RLS security
Presence — synchronized online state across all clients
Broadcast — low-latency peer events without a database round-trip

Combined with Flutter's reactive UI model, Supabase Realtime lets a solo developer ship collaborative features that would take a small backend team weeks to build from scratch. Next week we tackle indie dev growth loops.

Flutter Web Performance Optimization — CanvasKit, Lazy Loading, and Image Best Practices

kanta13jp1 — Sun, 03 May 2026 11:19:10 +0000

Shipping a production-ready Flutter Web app requires going beyond default settings. This guide covers renderer selection, deferred imports, image optimization, profiling, and build-time optimizations — all with practical code examples.

1. CanvasKit vs HTML Renderer

Flutter Web ships two renderers. Picking the right one is the highest-leverage decision you can make.

Aspect	CanvasKit	HTML
Rendering quality	High (Skia)	Medium (CSS/SVG)
Initial bundle size	+~1.5 MB	Smaller
Animation smoothness	Excellent	Limited
Text rendering	Consistent	OS font dependent
SEO friendliness	Hard	Easier

# Development — specify renderer
flutter run -d chrome --web-renderer canvaskit
flutter run -d chrome --web-renderer html

# Production builds
flutter build web --web-renderer canvaskit --release
flutter build web --web-renderer html --release

# auto: CanvasKit on desktop, HTML on mobile
flutter build web --web-renderer auto --release

# WASM compilation (Flutter 3.24+, experimental)
flutter build web --wasm --release

Rule of thumb: graphics-heavy apps → CanvasKit; content-heavy apps → HTML renderer. WASM compilation can further accelerate CanvasKit for CPU-bound workloads by 2–3×.

2. Deferred Imports for Code Splitting

Dart's deferred as keyword enables route-level code splitting, keeping the initial JS bundle minimal.

// main.dart — defer heavy pages
import 'pages/dashboard_page.dart' deferred as dashboard;
import 'pages/analytics_page.dart' deferred as analytics;
import 'pages/settings_page.dart' deferred as settings;

class AppRouter {
  static Route<dynamic> generateRoute(RouteSettings routeSettings) {
    switch (routeSettings.name) {
      case '/dashboard':
        return MaterialPageRoute(
          builder: (_) => FutureBuilder<void>(
            future: dashboard.loadLibrary(),
            builder: (context, snapshot) {
              if (snapshot.connectionState == ConnectionState.done) {
                return dashboard.DashboardPage();
              }
              return const LoadingScreen();
            },
          ),
        );

      case '/analytics':
        return MaterialPageRoute(
          builder: (_) => FutureBuilder<void>(
            future: analytics.loadLibrary(),
            builder: (context, snapshot) {
              if (snapshot.connectionState != ConnectionState.done) {
                return const LoadingScreen();
              }
              return analytics.AnalyticsPage();
            },
          ),
        );

      default:
        return MaterialPageRoute(builder: (_) => const HomePage());
    }
  }
}

Preload on hover — load the next page before the user clicks:

class NavItem extends StatelessWidget {
  final String label;
  final Future<void> Function() preload;
  final VoidCallback onTap;

  const NavItem({
    super.key,
    required this.label,
    required this.preload,
    required this.onTap,
  });

  @override
  Widget build(BuildContext context) {
    return MouseRegion(
      onEnter: (_) => preload(), // background load on hover
      child: GestureDetector(
        onTap: onTap,
        child: Padding(
          padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
          child: Text(label),
        ),
      ),
    );
  }
}

// Usage
NavItem(
  label: 'Dashboard',
  preload: dashboard.loadLibrary,
  onTap: () => context.go('/dashboard'),
)

3. Lazy Rendering with IntersectionObserver

Use the browser's IntersectionObserver API to avoid building widgets that are off-screen.

import 'dart:html' as html;
import 'package:flutter/widgets.dart';

/// Renders [child] only once it enters the viewport.
/// Shows [placeholder] until then.
class LazyWidget extends StatefulWidget {
  final Widget child;
  final Widget placeholder;
  /// Preload distance in pixels above the fold
  final int rootMarginPx;

  const LazyWidget({
    super.key,
    required this.child,
    this.placeholder = const SizedBox.shrink(),
    this.rootMarginPx = 200,
  });

  @override
  State<LazyWidget> createState() => _LazyWidgetState();
}

class _LazyWidgetState extends State<LazyWidget> {
  bool _visible = false;
  html.IntersectionObserver? _observer;

  @override
  void initState() {
    super.initState();
    _observer = html.IntersectionObserver(
      (entries, _) {
        if (entries.any((e) => e.isIntersecting)) {
          setState(() => _visible = true);
          _observer?.disconnect();
        }
      },
      {'rootMargin': '${widget.rootMarginPx}px'},
    );
    // Attach after the first frame so the DOM element exists
    WidgetsBinding.instance.addPostFrameCallback((_) => _attach());
  }

  void _attach() {
    // Real implementation uses PlatformViewRegistry to get the DOM node
    // This pattern works with HtmlElementView or flutter_web_plugins
  }

  @override
  void dispose() {
    _observer?.disconnect();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) =>
      _visible ? widget.child : widget.placeholder;
}

4. Image Optimization

ResizeImage — Decode at Display Resolution

/// Constrain decode resolution to the actual display size,
/// saving significant heap memory on mobile and high-DPI screens.
Widget optimizedNetworkImage(
  BuildContext context,
  String url, {
  double? displayWidth,
  double? displayHeight,
}) {
  final dpr = MediaQuery.devicePixelRatioOf(context);
  return Image(
    image: ResizeImage(
      NetworkImage(url),
      width: displayWidth != null ? (displayWidth * dpr).round() : null,
      height: displayHeight != null ? (displayHeight * dpr).round() : null,
    ),
    fit: BoxFit.cover,
  );
}

CachedNetworkImage with Memory + Disk Limits

import 'package:cached_network_image/cached_network_image.dart';

Widget cachedImage(String url) {
  return CachedNetworkImage(
    imageUrl: url,
    memCacheWidth: 800,       // px — limits decoded size in memory
    memCacheHeight: 600,
    maxWidthDiskCache: 1200,  // px — limits size written to disk
    fadeInDuration: const Duration(milliseconds: 200),
    placeholder: (_, __) => const ShimmerBox(),
    errorWidget: (_, __, ___) => const Icon(Icons.broken_image),
  );
}

Supabase Storage Image Transforms

/// Use Supabase's built-in image transformation API.
/// Automatically serves WebP when the browser supports it.
String supabaseImageUrl(
  String bucket,
  String path, {
  int width = 800,
  int quality = 80,
}) {
  const projectRef = 'YOUR_PROJECT_REF';
  return 'https://$projectRef.supabase.co'
      '/storage/v1/render/image/public/$bucket/$path'
      '?width=$width&quality=$quality&format=webp';
}

// Usage — responsive image for a card
Widget productCard(String imagePath) {
  return LayoutBuilder(
    builder: (context, constraints) {
      final url = supabaseImageUrl(
        'products',
        imagePath,
        width: constraints.maxWidth.round(),
      );
      return CachedNetworkImage(imageUrl: url, fit: BoxFit.cover);
    },
  );
}

5. Profiling with Flutter DevTools

# Run in profile mode — release optimizations, DevTools still works
flutter run -d chrome --profile

# Measure output bundle size
flutter build web --analyze-size --release

Finding jank in the Timeline:

// Instrument slow sections manually
import 'dart:developer' as developer;

Future<void> loadDashboardData() async {
  developer.Timeline.startSync('LoadDashboardData');
  try {
    final results = await Future.wait([
      _fetchMetrics(),
      _fetchNotifications(),
      _fetchRecentActivity(),
    ]);
    // process results...
  } finally {
    developer.Timeline.finishSync();
  }
}

Frame timing callback (debug builds only):

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  assert(() {
    WidgetsBinding.instance.addTimingsCallback((timings) {
      for (final t in timings) {
        final ms = t.totalSpan.inMilliseconds;
        if (ms > 16) debugPrint('Slow frame: ${ms}ms (build: ${t.buildDuration.inMilliseconds}ms)');
      }
    });
    return true;
  }());

  runApp(const App());
}

6. Build-time Optimizations

split-debug-info + obfuscate

flutter build web \
  --release \
  --web-renderer canvaskit \
  --split-debug-info=build/symbols \
  --obfuscate \
  --dart-define=FLUTTER_WEB_USE_SKIA=true

# Check output size
ls -lh build/web/main.dart.js
# Typical: 2–3 MB (CanvasKit), 1–1.5 MB (HTML renderer)

Avoid Breaking Tree-Shaking

// Bad — dynamic icon lookup defeats tree-shaking
IconData iconFromCode(int codePoint) =>
    IconData(codePoint, fontFamily: 'MaterialIcons');

// Good — static map keeps icons tree-shakeable
const _iconMap = {
  'home': Icons.home,
  'person': Icons.person,
  'settings': Icons.settings,
};
IconData? iconFor(String key) => _iconMap[key];

Service Worker Cache Strategy

// Customize web/flutter_service_worker.js or use Workbox

// Cache-first for images (long TTL)
workbox.routing.registerRoute(
  ({ request }) => request.destination === 'image',
  new workbox.strategies.CacheFirst({
    cacheName: 'images-v1',
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 150,
        maxAgeSeconds: 30 * 24 * 60 * 60, // 30 days
      }),
    ],
  })
);

// Network-first for API calls (freshness matters)
workbox.routing.registerRoute(
  ({ url }) => url.pathname.startsWith('/api/'),
  new workbox.strategies.NetworkFirst({ cacheName: 'api-cache' })
);

Summary

Optimization	Impact	Effort
Renderer selection	30–50% faster initial load	Low
Deferred imports	Smaller initial JS bundle	Medium
ResizeImage	40–60% less heap memory	Low
split-debug-info	~20% smaller binary	Low
WASM build	2–3× faster CPU-bound code	Medium

Always measure before optimizing. Use DevTools to find real bottlenecks — then apply targeted fixes. Next week we look at Supabase Realtime for live collaborative features.

Dart Metaprogramming — build_runner, Source Gen, and Dart 3 Macros Explained

kanta13jp1 — Sun, 03 May 2026 10:50:08 +0000

Dart Metaprogramming — build_runner, Source Gen, and Dart 3 Macros Explained

Every Flutter developer has used json_serializable or freezed, but few understand what actually happens when dart run build_runner build runs. Understanding Dart's code generation stack unlocks the ability to eliminate repetitive boilerplate in your own projects. This guide goes from "using existing generators" to "writing your own Builder" to a peek at the experimental Dart 3 Macros API.

The Dart Code Generation Stack

Your .dart source files
    │  @YourAnnotation decorates a class
    ▼
build_runner  ──────────────  watches for file changes
    │
    │  invokes Builder implementations
    ▼
source_gen  ─────────────────  convenience layer over build
    │
    │  GeneratorForAnnotation parses AST via `analyzer`
    ▼
Generated .g.dart files  ──── included via `part` directives
    ▼
Final compiled Dart code

Key packages:

Package	Role
`build_runner`	Build system orchestrator
`build`	Low-level `Builder` interface
`source_gen`	Higher-level `GeneratorForAnnotation` wrapper
`analyzer`	Dart AST analysis (used inside generators)

Step 1: Master the Existing Tools First

Before writing your own generator, use the mainstream packages to understand what well-designed code generation looks like.

# pubspec.yaml
dependencies:
  json_annotation: ^4.9.0
  freezed_annotation: ^2.4.0

dev_dependencies:
  build_runner: ^2.4.0
  json_serializable: ^6.8.0
  freezed: ^2.5.0

json_serializable in practice

// lib/models/task.dart
import 'package:json_annotation/json_annotation.dart';

part 'task.g.dart';   // ← generated by build_runner

@JsonSerializable(
  fieldRename: FieldRename.snake,  // camelCase ↔ snake_case
  includeIfNull: false,
  explicitToJson: true,
)
class Task {
  const Task({
    required this.id,
    required this.title,
    required this.isDone,
    required this.createdAt,
    this.tags,
  });

  final String id;
  final String title;

  @JsonKey(name: 'is_done')
  final bool isDone;

  @JsonKey(name: 'created_at')
  final DateTime createdAt;

  final List<String>? tags;

  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);
  Map<String, dynamic> toJson() => _$TaskToJson(this);
}

# One-shot generation
dart run build_runner build --delete-conflicting-outputs

# Watch mode — keep running during development
dart run build_runner watch --delete-conflicting-outputs

What build_runner generates (task.g.dart):

// GENERATED CODE - DO NOT MODIFY BY HAND
// ignore_for_file: type=lint

part of 'task.dart';

Task _$TaskFromJson(Map<String, dynamic> json) => Task(
      id: json['id'] as String,
      title: json['title'] as String,
      isDone: json['is_done'] as bool,
      createdAt: DateTime.parse(json['created_at'] as String),
      tags: (json['tags'] as List<dynamic>?)
          ?.map((e) => e as String)
          .toList(),
    );

Map<String, dynamic> _$TaskToJson(Task instance) {
  final val = <String, dynamic>{
    'id': instance.id,
    'title': instance.title,
    'is_done': instance.isDone,
    'created_at': instance.createdAt.toIso8601String(),
  };
  void writeNotNull(String key, dynamic value) {
    if (value != null) val[key] = value;
  }
  writeNotNull('tags', instance.tags);
  return val;
}

Freezed for immutable data classes

// lib/models/auth_state.dart
import 'package:freezed_annotation/freezed_annotation.dart';

part 'auth_state.freezed.dart';
part 'auth_state.g.dart';

@freezed
sealed class AuthState with _$AuthState {
  const factory AuthState.loading() = _Loading;
  const factory AuthState.authenticated({required User user}) = _Authenticated;
  const factory AuthState.unauthenticated() = _Unauthenticated;
  const factory AuthState.error({required String message}) = _Error;
}

// Usage — exhaustive pattern matching
switch (state) {
  case _Loading()         => const CircularProgressIndicator(),
  case _Authenticated(:final user) => HomeScreen(user: user),
  case _Unauthenticated() => const LoginPage(),
  case _Error(:final message) => ErrorView(message: message),
}

Step 2: Write Your Own Builder

Let's build a @Loggable annotation that auto-generates a toLogString() extension on any annotated class.

Package structure

packages/
  loggable_gen/               ← separate package for the generator
    pubspec.yaml
    lib/
      src/
        loggable_annotation.dart
        loggable_generator.dart
      loggable_gen.dart
    build.yaml

lib/
  models/
    task.dart                 ← uses @loggable

The annotation

// packages/loggable_gen/lib/src/loggable_annotation.dart
class Loggable {
  const Loggable({this.tag = ''});
  final String tag;  // optional override for the log tag
}

const loggable = Loggable();

The generator

// packages/loggable_gen/lib/src/loggable_generator.dart
import 'package:analyzer/dart/element/element.dart';
import 'package:build/build.dart';
import 'package:source_gen/source_gen.dart';
import 'loggable_annotation.dart';

class LoggableGenerator extends GeneratorForAnnotation<Loggable> {
  @override
  String generateForAnnotatedElement(
    Element element,
    ConstantReader annotation,
    BuildStep buildStep,
  ) {
    if (element is! ClassElement) {
      throw InvalidGenerationSourceError(
        '@Loggable can only decorate classes.',
        element: element,
      );
    }

    final className = element.name;
    final customTag = annotation.read('tag').stringValue;
    final tag = customTag.isEmpty ? className : customTag;

    // Build a comma-separated field log expression
    final fieldExpressions = element.fields
        .where((f) => !f.isStatic && !f.isSynthetic)
        .map((f) => '${f.name}: \$${f.name}')
        .join(', ');

    return '''
extension \$${className}Logging on $className {
  String toLogString() => '[$tag] $fieldExpressions';

  // ignore: avoid_print
  void log() => print(toLogString());
}
''';
  }
}

Builder loggableBuilder(BuilderOptions options) =>
    SharedPartBuilder([LoggableGenerator()], 'loggable');

build.yaml

# packages/loggable_gen/build.yaml
builders:
  loggable:
    import: "package:loggable_gen/loggable_gen.dart"
    builder_factories: ["loggableBuilder"]
    build_extensions: {".dart": [".loggable.g.part"]}
    auto_apply: dependents
    build_to: source
    applies_builders: ["source_gen|combining_builder"]

Using the annotation

// lib/models/task.dart
import 'package:loggable_gen/loggable_gen.dart';
import 'package:json_annotation/json_annotation.dart';

part 'task.g.dart';

@loggable                    // ← our custom annotation
@JsonSerializable()
class Task {
  const Task({
    required this.id,
    required this.title,
    required this.isDone,
  });

  final String id;
  final String title;
  final bool isDone;

  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);
  Map<String, dynamic> toJson() => _$TaskToJson(this);
}

// After build_runner:
// task.log();
// prints: [Task] id: abc-123, title: Write blog post, isDone: false

Step 3: Type-Safe Routing with go_router_builder

Routing is another area where code generation eliminates an entire class of bugs (path typos, missing parameters).

// lib/routes/app_routes.dart
part 'app_routes.g.dart';

@TypedGoRoute<HomeRoute>(path: '/')
class HomeRoute extends GoRouteData {
  const HomeRoute();
  @override
  Widget build(BuildContext context, GoRouterState state) =>
      const HomePage();
}

@TypedGoRoute<TaskDetailRoute>(path: '/tasks/:taskId')
class TaskDetailRoute extends GoRouteData {
  const TaskDetailRoute({required this.taskId});
  final String taskId;
  @override
  Widget build(BuildContext context, GoRouterState state) =>
      TaskDetailPage(taskId: taskId);
}

@TypedGoRoute<SettingsRoute>(
  path: '/settings',
  routes: [
    TypedGoRoute<ThemeSettingsRoute>(path: 'theme'),
  ],
)
class SettingsRoute extends GoRouteData {
  const SettingsRoute();
  @override Widget build(_, __) => const SettingsPage();
}

class ThemeSettingsRoute extends GoRouteData {
  const ThemeSettingsRoute();
  @override Widget build(_, __) => const ThemeSettingsPage();
}

// Navigation — fully type-safe, no strings
// HomeRoute().go(context);
// TaskDetailRoute(taskId: task.id).push(context);
// ThemeSettingsRoute().push(context);

Step 4: Dart 3 Macros (Experimental Preview)

Dart Macros represent a fundamentally different approach — they run at compile time and modify the AST directly, with no .g.dart files at all.

// Requires Dart >=3.5 and --enable-experiment=macros
// pubspec.yaml: environment: { sdk: '>=3.5.0 <4.0.0' }

import 'package:macros/macros.dart';

/// Automatically adds fromJson/toJson to any class
macro class JsonCodable implements ClassDeclarationsMacro {
  const JsonCodable();

  @override
  Future<void> buildDeclarationsForClass(
    ClassDeclaration clazz,
    MemberDeclarationBuilder builder,
  ) async {
    final fields = await builder.fieldsOf(clazz);
    final name = clazz.identifier.name;

    // Generate fromJson factory
    final fromArgs = fields.map((f) {
      final fname = f.identifier.name;
      return "$fname: json['$fname'] as ${f.type.code}";
    }).join(',\n    ');

    builder.declareInType(DeclarationCode.fromString('''
  factory $name.fromJson(Map<String, dynamic> json) =>
      $name(
        $fromArgs,
      );
'''));

    // Generate toJson
    final toArgs = fields.map((f) {
      final fname = f.identifier.name;
      return "'$fname': $fname";
    }).join(',\n    ');

    builder.declareInType(DeclarationCode.fromString('''
  Map<String, dynamic> toJson() => {
    $toArgs,
  };
'''));
  }
}

// Usage — no `part` directive needed!
@JsonCodable()
class User {
  const User({required this.id, required this.email});
  final String id;
  final String email;
  // fromJson and toJson are injected at compile time
}

Current status of Dart Macros (as of 2030):

Aspect	Status
Availability	Experimental (`--enable-experiment=macros`)
IDE support	Partial — analysis server integration in progress
Production readiness	Not recommended yet for production apps
Timeline	Stable API targeted for Dart 4.x

CI Integration

# .github/workflows/codegen.yml
name: Code Generation
on: [push, pull_request]

jobs:
  codegen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.24.x'

      - name: Install dependencies
        run: flutter pub get

      - name: Run build_runner
        run: dart run build_runner build --delete-conflicting-outputs

      - name: Check for uncommitted generated files
        run: |
          git diff --exit-code || {
            echo "Generated files are out of date. Run build_runner locally."
            exit 1
          }

Best Practices

Practice	Reason
Commit `.g.dart` files	Enables IDE to work without running build_runner
Use `--delete-conflicting-outputs` in CI	Prevents stale generation errors
Keep annotations in a separate package	Avoids circular dependencies
Use `watch` only during development	Continuous build drains battery/CPU
Add `// coverage:ignore-file` to `.g.dart`	Prevents false coverage reports

Summary

Dart code generation evolves in three stages:

Use — json_serializable, freezed, riverpod_generator eliminate the most common boilerplate
Understand — Read a small generator's source to demystify source_gen and analyzer
Create — Write a domain-specific Builder for patterns unique to your codebase

Macros are the future, but build_runner is production-proven today. At Jibun Inc., go_router_builder + riverpod_generator + json_serializable together eliminate roughly 30% of what would otherwise be hand-written glue code.

Based on real implementation at Jibun Inc. (Flutter Web + Supabase).

Indie App Onboarding That Retains Users — Day 0 to Day 28 Engagement Design

kanta13jp1 — Sun, 03 May 2026 10:46:37 +0000

Indie App Onboarding That Retains Users — Day 0 to Day 28 Engagement Design

Every feature you've built is worthless if users quit in the first three minutes. At Jibun Inc. — a Flutter Web life management app competing with Notion, Evernote, and 19 others — improving onboarding increased Day-7 retention by 15% in a single sprint. This article covers the full onboarding stack: empty states, PageView carousels, progressive disclosure, and a Day 0–28 re-engagement sequence.

The Three Goals of Onboarding

Goal	Metric	Target
Time to Value	Minutes from sign-up to first "aha"	< 3 minutes
Activation	Users who complete core action on Day 0	> 60%
Day 7 Retention	Users who return within 7 days	> 40%

Getting these numbers right matters far more than shipping the next feature. Track them before you build anything else.

1. Empty State Design

The very first screen your user sees is an empty list with zero data. This moment makes or breaks activation.

Bad empty state: Just a message that says "No items yet."

Good empty state: Explains the value, shows what it will look like, and offers a clear next action.

// lib/widgets/empty_state_widget.dart
class EmptyStateWidget extends StatelessWidget {
  const EmptyStateWidget({
    super.key,
    required this.title,
    required this.subtitle,
    this.illustrationPath,
    this.sampleItems,
    this.primaryAction,
    this.secondaryAction,
  });

  final String title;
  final String subtitle;
  final String? illustrationPath;
  final List<String>? sampleItems;     // ghost items to set expectations
  final EmptyStateAction? primaryAction;
  final EmptyStateAction? secondaryAction;

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    return Center(
      child: ConstrainedBox(
        constraints: const BoxConstraints(maxWidth: 400),
        child: Padding(
          padding: const EdgeInsets.all(32),
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              if (illustrationPath != null)
                Image.asset(illustrationPath!, width: 140, height: 140)
              else
                Icon(
                  Icons.inbox_outlined,
                  size: 80,
                  color: theme.colorScheme.primary.withOpacity(0.3),
                ),
              const SizedBox(height: 24),
              Text(title,
                style: theme.textTheme.titleLarge,
                textAlign: TextAlign.center),
              const SizedBox(height: 8),
              Text(subtitle,
                style: theme.textTheme.bodyMedium?.copyWith(
                  color: theme.colorScheme.onSurface.withOpacity(0.55),
                ),
                textAlign: TextAlign.center),

              // Ghost items — show what the list will look like
              if (sampleItems != null) ...[
                const SizedBox(height: 20),
                ...sampleItems!.map((s) => _GhostItem(text: s)),
              ],

              const SizedBox(height: 28),
              if (primaryAction != null)
                FilledButton.icon(
                  onPressed: primaryAction!.onTap,
                  icon: Icon(primaryAction!.icon),
                  label: Text(primaryAction!.label),
                ),
              if (secondaryAction != null) ...[
                const SizedBox(height: 10),
                TextButton(
                  onPressed: secondaryAction!.onTap,
                  child: Text(secondaryAction!.label),
                ),
              ],
            ],
          ),
        ),
      ),
    );
  }
}

class EmptyStateAction {
  const EmptyStateAction({
    required this.label,
    required this.onTap,
    this.icon = Icons.add,
  });
  final String label;
  final VoidCallback onTap;
  final IconData icon;
}

class _GhostItem extends StatelessWidget {
  const _GhostItem({required this.text});
  final String text;

  @override
  Widget build(BuildContext context) => Padding(
    padding: const EdgeInsets.symmetric(vertical: 4),
    child: Row(
      children: [
        Icon(Icons.circle,
          size: 6,
          color: Colors.grey.withOpacity(0.4)),
        const SizedBox(width: 10),
        Expanded(
          child: Text(
            text,
            style: Theme.of(context).textTheme.bodySmall?.copyWith(
              color: Colors.grey.shade400,
              fontStyle: FontStyle.italic,
            ),
          ),
        ),
      ],
    ),
  );
}

Practical usage

EmptyStateWidget(
  illustrationPath: 'assets/illustrations/empty_tasks.png',
  title: 'No tasks yet',
  subtitle: 'Add your first task and let AI help\nyou decide what to tackle today.',
  sampleItems: const [
    'e.g. Write the product spec (today)',
    'e.g. Reply to investor emails',
    'e.g. Ship the auth page',
  ],
  primaryAction: EmptyStateAction(
    label: 'Add your first task',
    onTap: () => context.push('/tasks/new'),
  ),
  secondaryAction: EmptyStateAction(
    label: 'Try with sample data',
    icon: Icons.science_outlined,
    onTap: _loadSampleData,
  ),
)

2. Onboarding PageView Carousel

Show a 3-slide intro carousel only on first launch. Keep it under 4 slides — engagement drops sharply beyond that.

// lib/pages/onboarding_page.dart
class OnboardingPage extends StatefulWidget {
  const OnboardingPage({super.key});
  @override State<OnboardingPage> createState() => _OnboardingPageState();
}

class _OnboardingPageState extends State<OnboardingPage> {
  final _controller = PageController();
  int _page = 0;

  static const _steps = [
    _Step(
      title: '21 apps in one',
      body: 'Replace Notion, Evernote, MoneyForward and 18 others\nwith a single, unified workspace.',
      icon: Icons.auto_awesome,
      color: Color(0xFF6C63FF),
    ),
    _Step(
      title: 'AI does the thinking',
      body: 'Daily AI suggestions tell you what to focus on\nso you spend time doing, not deciding.',
      icon: Icons.psychology_outlined,
      color: Color(0xFF4ECDC4),
    ),
    _Step(
      title: 'Start with one task',
      body: 'Just add a single task right now.\nThat\'s all it takes to feel the difference.',
      icon: Icons.check_circle_outline,
      color: Color(0xFFFF6B6B),
    ),
  ];

  Future<void> _complete() async {
    final prefs = await SharedPreferences.getInstance();
    await prefs.setBool('onboarding_done', true);
    if (mounted) context.go('/');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: Column(
          children: [
            Align(
              alignment: Alignment.topRight,
              child: TextButton(
                onPressed: _complete,
                child: const Text('Skip'),
              ),
            ),
            Expanded(
              child: PageView.builder(
                controller: _controller,
                onPageChanged: (i) => setState(() => _page = i),
                itemCount: _steps.length,
                itemBuilder: (_, i) => _StepCard(step: _steps[i]),
              ),
            ),
            _ProgressDots(
              count: _steps.length,
              current: _page,
              activeColor: _steps[_page].color,
            ),
            Padding(
              padding: const EdgeInsets.fromLTRB(24, 16, 24, 32),
              child: SizedBox(
                width: double.infinity,
                height: 52,
                child: FilledButton(
                  onPressed: _page < _steps.length - 1
                      ? () => _controller.nextPage(
                            duration: const Duration(milliseconds: 300),
                            curve: Curves.easeInOut,
                          )
                      : _complete,
                  style: FilledButton.styleFrom(
                    backgroundColor: _steps[_page].color,
                  ),
                  child: Text(
                    _page == _steps.length - 1 ? "Let's go!" : 'Next',
                    style: const TextStyle(fontSize: 16, fontWeight: FontWeight.w600),
                  ),
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

class _ProgressDots extends StatelessWidget {
  const _ProgressDots({
    required this.count,
    required this.current,
    required this.activeColor,
  });

  final int count, current;
  final Color activeColor;

  @override
  Widget build(BuildContext context) => Row(
    mainAxisAlignment: MainAxisAlignment.center,
    children: List.generate(count, (i) => AnimatedContainer(
      duration: const Duration(milliseconds: 200),
      margin: const EdgeInsets.symmetric(horizontal: 4),
      width: i == current ? 24 : 8,
      height: 8,
      decoration: BoxDecoration(
        borderRadius: BorderRadius.circular(4),
        color: i == current ? activeColor : Colors.grey.shade300,
      ),
    )),
  );
}

3. Day 0–28 Engagement Sequence

After sign-up, a drip sequence keeps users coming back while they build the habit.

Day	Trigger	Message	Goal
0	Sign-up	Welcome email + "Add your first task" CTA	Activation
1	24h after first action	"How did yesterday's task go?"	Habit seed
3	No activity in 3 days	"3 features you haven't tried yet"	Re-activation
7	1-week mark	AI weekly summary of your progress	Value proof
14	2-week mark	"Power user unlock: export, API, advanced filters"	Upsell nudge
28	1-month mark	"Your first month in numbers" personalized report	Retention + social

Supabase Edge Function for the Day-3 re-engagement email

// supabase/functions/onboarding-day3/index.ts
import { serve } from 'https://deno.land/std@0.177.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async () => {
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!,
  )

  // Users created 3 days ago who haven't been active since signup
  const target = new Date()
  target.setDate(target.getDate() - 3)
  const window = new Date(target)
  window.setHours(window.getHours() - 1)

  const { data: users, error } = await supabase
    .from('profiles')
    .select('id, email, display_name')
    .gte('created_at', window.toISOString())
    .lte('created_at', target.toISOString())
    .eq('day3_email_sent', false)
    .is('last_active_at', null)

  if (error) return new Response(JSON.stringify({ error }), { status: 500 })

  let sent = 0
  for (const user of users ?? []) {
    const ok = await sendReEngagementEmail(user)
    if (ok) {
      await supabase
        .from('profiles')
        .update({ day3_email_sent: true })
        .eq('id', user.id)
      sent++
    }
  }

  return new Response(JSON.stringify({ sent }))
})

4. Progressive Disclosure

Reveal advanced features only after users are comfortable with basics.

// lib/services/feature_flags.dart
class FeatureFlags {
  FeatureFlags(this._client);
  final SupabaseClient _client;

  Future<int> _daysSinceSignup() async {
    final user = _client.auth.currentUser;
    if (user == null) return 0;
    return DateTime.now().difference(DateTime.parse(user.createdAt)).inDays;
  }

  Future<bool> canSee(String feature) async {
    final days = await _daysSinceSignup();
    return switch (feature) {
      'basic_tasks'     => true,
      'ai_suggest'      => days >= 1,
      'analytics'       => days >= 7,
      'bulk_export'     => days >= 14,
      'api_access'      => days >= 30,
      _                 => false,
    };
  }
}

// In a widget:
FutureBuilder<bool>(
  future: featureFlags.canSee('analytics'),
  builder: (context, snap) {
    if (snap.data != true) return const SizedBox.shrink();
    return const AnalyticsNavItem();
  },
)

Onboarding Checklist

[ ] Every empty state has a value explanation + single primary CTA
[ ] Onboarding slides are 3–4 max (5+ kills completion rate)
[ ] A "Skip" button is always visible
[ ] Welcome email is sent on Day 0 (test it yourself after sign-up)
[ ] Day 7 retention is being measured (Supabase Analytics or Mixpanel)
[ ] Sample data is available so users can explore without committing
[ ] First "win" is achievable in under 3 minutes

Summary

For indie developers, onboarding is often the highest-ROI place to invest time. A single well-designed empty state outperforms three new features in terms of retention impact. Start by measuring Day-7 retention, then work backwards: what needs to happen on Day 0 for users to come back on Day 7?

At Jibun Inc., we run a weekly retrospective on this single metric. Small, compounding improvements here beat big feature releases in long-term growth.

Based on real implementation at Jibun Inc. (Flutter Web + Supabase, competing with 21 apps).

Supabase Auth OAuth in Flutter — Google, GitHub, and Apple Sign-In End-to-End

kanta13jp1 — Sun, 03 May 2026 10:44:32 +0000

Supabase Auth OAuth in Flutter — Google, GitHub, and Apple Sign-In End-to-End

Social login is the single highest-leverage UX improvement you can make for a new product. At Jibun Inc., adding Google and GitHub OAuth tripled our sign-up conversion rate overnight. This guide covers the full implementation: provider setup in each developer console, Supabase dashboard config, Flutter auth flow, callback handling, and social button UI patterns.

How Supabase Auth OAuth Works

Supabase Auth acts as an OAuth 2.0 / OIDC proxy. Understanding this flow saves hours of debugging:

Flutter App
    │
    │ (1) supabase.auth.signInWithOAuth(provider)
    ▼
Supabase Auth  ──────────────────────────────►  Google / GitHub / Apple
                (2) redirect to provider                │
                                                        │ (3) auth code
                                        ◄───────────────┘
Supabase Auth
    │
    │ (4) exchange code → JWT + refresh token
    ▼
Flutter App  (via callback URL)

You need two callback URLs registered at every provider:

https://<project-ref>.supabase.co/auth/v1/callback — Supabase's server-side endpoint
io.supabase.<bundle-id>://login-callback/ — deep link for the native app (mobile only)

Project Setup

pubspec.yaml

dependencies:
  supabase_flutter: ^2.5.0
  app_links: ^6.1.0      # deep link handling on mobile
  url_launcher: ^6.2.0   # fallback browser launcher

Initialization

// lib/main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Supabase.initialize(
    url: const String.fromEnvironment('SUPABASE_URL'),
    anonKey: const String.fromEnvironment('SUPABASE_ANON_KEY'),
    authOptions: const FlutterAuthClientOptions(
      authFlowType: AuthFlowType.pkce,   // always use PKCE
      autoRefreshToken: true,
    ),
  );
  runApp(const MyApp());
}

final supabase = Supabase.instance.client;

Google OAuth Setup

Step 1: Google Cloud Console

Open Google Cloud Console → APIs & Services → Credentials
Create Credentials → OAuth Client ID → Web Application
Add authorized redirect URIs:

   https://<project-ref>.supabase.co/auth/v1/callback

Copy the Client ID and Client Secret

Step 2: Supabase Dashboard

Authentication → Providers → Google → Enable. Paste your Client ID and Secret.

Step 3: Flutter Implementation

// lib/services/auth_service.dart
class AuthService {
  final _client = Supabase.instance.client;

  String get _redirectUrl => kIsWeb
      ? 'https://my-web-app-b67f4.web.app/auth/callback'
      : 'io.supabase.jibun://login-callback/';

  Future<void> signInWithGoogle() async {
    await _client.auth.signInWithOAuth(
      OAuthProvider.google,
      redirectTo: _redirectUrl,
      queryParams: {
        'access_type': 'offline',  // get refresh_token
        'prompt': 'consent',
      },
    );
  }

  Future<void> signInWithGitHub() async {
    await _client.auth.signInWithOAuth(
      OAuthProvider.github,
      redirectTo: _redirectUrl,
      scopes: 'read:user user:email',
    );
  }

  Future<void> signInWithApple() async {
    await _client.auth.signInWithOAuth(
      OAuthProvider.apple,
      redirectTo: _redirectUrl,
    );
  }

  Future<void> signOut() => _client.auth.signOut();

  User? get currentUser => _client.auth.currentUser;

  Stream<AuthState> get authStateChanges =>
      _client.auth.onAuthStateChange;
}

GitHub OAuth Setup

Step 1: Create GitHub OAuth App

Settings → Developer Settings → OAuth Apps → New OAuth App:

Field	Value
Application name	Jibun Inc.
Homepage URL	`https://my-web-app-b67f4.web.app`
Authorization callback URL	`https://<project-ref>.supabase.co/auth/v1/callback`

Copy the Client ID and generate a Client Secret, then paste both into Supabase Dashboard → Providers → GitHub.

Why GitHub? Developer-users who sign in via GitHub have 20% better retention in Jibun Inc.'s data. If your app targets developers, GitHub login is worth the 15 minutes of setup.

Apple Sign-In Setup (Most Complex)

Apple Sign-In is mandatory for any iOS app distributed via the App Store that offers third-party login. Plan an extra hour for the Apple Developer Console steps.

Step 1: Apple Developer Console

App IDs → <Your App ID> → Capabilities:
  ☑ Sign In with Apple

Services IDs → New:
  Description: Jibun Inc. Web
  Identifier:  com.jibun.web           ← different from App ID
  ☑ Sign In with Apple → Configure:
    Primary App ID: <Your App ID>
    Domains:       my-web-app-b67f4.web.app
    Return URLs:   https://<project-ref>.supabase.co/auth/v1/callback

Keys → New:
  ☑ Sign In with Apple → Configure:
    Primary App ID: <Your App ID>
  → Download the .p8 file  (keep it safe — it cannot be re-downloaded)

Step 2: Supabase Dashboard

Field	Value
Service ID	`com.jibun.web`
Team ID	Your 10-character Apple Team ID
Key ID	The key ID from the Apple Developer portal
Private Key	Full contents of the `.p8` file

Social Login Button UI

A polished social login screen significantly reduces friction. Here is the pattern used in Jibun Inc.:

// lib/pages/login_page.dart
class LoginPage extends StatefulWidget {
  const LoginPage({super.key});
  @override State<LoginPage> createState() => _LoginPageState();
}

class _LoginPageState extends State<LoginPage> {
  final _auth = AuthService();
  bool _loading = false;

  Future<void> _login(Future<void> Function() fn) async {
    setState(() => _loading = true);
    try {
      await fn();
    } on AuthException catch (e) {
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
            content: Text(e.message),
            backgroundColor: Theme.of(context).colorScheme.error,
          ),
        );
      }
    } finally {
      if (mounted) setState(() => _loading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ConstrainedBox(
          constraints: const BoxConstraints(maxWidth: 380),
          child: Padding(
            padding: const EdgeInsets.symmetric(horizontal: 24),
            child: Column(
              mainAxisSize: MainAxisSize.min,
              children: [
                const _AppLogo(),
                const SizedBox(height: 40),
                if (_loading)
                  const CircularProgressIndicator()
                else
                  _LoginButtons(onLogin: _login, auth: _auth),
                const SizedBox(height: 24),
                const _LegalText(),
              ],
            ),
          ),
        ),
      ),
    );
  }
}

class _LoginButtons extends StatelessWidget {
  const _LoginButtons({required this.onLogin, required this.auth});

  final Future<void> Function(Future<void> Function()) onLogin;
  final AuthService auth;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        _OAuthButton(
          label: 'Continue with Google',
          assetPath: 'assets/icons/google.png',
          bg: Colors.white,
          fg: Colors.black87,
          border: Colors.grey.shade300,
          onTap: () => onLogin(auth.signInWithGoogle),
        ),
        const SizedBox(height: 12),
        _OAuthButton(
          label: 'Continue with GitHub',
          assetPath: 'assets/icons/github.png',
          bg: const Color(0xFF24292E),
          fg: Colors.white,
          border: Colors.transparent,
          onTap: () => onLogin(auth.signInWithGitHub),
        ),
        const SizedBox(height: 12),
        _OAuthButton(
          label: 'Continue with Apple',
          assetPath: 'assets/icons/apple.png',
          bg: Colors.black,
          fg: Colors.white,
          border: Colors.transparent,
          onTap: () => onLogin(auth.signInWithApple),
        ),
      ],
    );
  }
}

class _OAuthButton extends StatelessWidget {
  const _OAuthButton({
    required this.label, required this.assetPath,
    required this.bg, required this.fg,
    required this.border, required this.onTap,
  });

  final String label, assetPath;
  final Color bg, fg, border;
  final VoidCallback onTap;

  @override
  Widget build(BuildContext context) => SizedBox(
    width: double.infinity,
    height: 48,
    child: ElevatedButton(
      onPressed: onTap,
      style: ElevatedButton.styleFrom(
        backgroundColor: bg,
        foregroundColor: fg,
        elevation: 0,
        shape: RoundedRectangleBorder(
          borderRadius: BorderRadius.circular(8),
          side: BorderSide(color: border),
        ),
      ),
      child: Row(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Image.asset(assetPath, width: 20, height: 20),
          const SizedBox(width: 12),
          Text(label, style: const TextStyle(fontWeight: FontWeight.w500)),
        ],
      ),
    ),
  );
}

Handling the Callback (Web)

On Flutter Web, the OAuth callback returns to your app as a URL. GoRouter handles it transparently if you add the callback route:

GoRoute(
  path: '/auth/callback',
  builder: (context, state) {
    // Supabase Flutter detects the URL params automatically.
    // Just redirect to home; the session is already set.
    return const Scaffold(
      body: Center(child: CircularProgressIndicator()),
    );
  },
  redirect: (context, state) {
    final isLoggedIn = supabase.auth.currentUser != null;
    return isLoggedIn ? '/' : null;
  },
),

Security Checklist

Item	Recommendation
PKCE flow	Always use `AuthFlowType.pkce` — never implicit
Redirect URL validation	Supabase restricts to the URL you register — no wildcards
Token storage	Supabase Flutter stores tokens in `SharedPreferences` (encrypted on iOS)
RLS policies	Always add `auth.uid() = user_id` to your Supabase tables
Scopes	Request minimum required scopes per provider

Summary

Supabase Auth abstracts away all OAuth complexity — no token exchange code, no manual JWT verification. The total implementation time for all three providers is roughly 2–3 hours, mostly spent in the Apple Developer Console. Start with Google (widest coverage), add Apple if you ship on iOS, and add GitHub if your user base skews technical.

Based on real implementation at Jibun Inc. (Flutter Web + Supabase).

Flutter Web SEO Guide — Meta Tags, Sitemaps, and Structured Data That Actually Work

kanta13jp1 — Sun, 03 May 2026 10:42:22 +0000

Flutter Web SEO Guide — Meta Tags, Sitemaps, and Structured Data That Actually Work

If you've shipped a Flutter Web app and wondered why Google isn't indexing it, you're not alone. At Jibun Inc. — a Flutter Web + Supabase life management app competing with 21 rivals including Notion, Evernote, and MoneyForward — SEO is a business-critical concern. This guide covers every layer of the SEO stack for Flutter Web, from the renderer choice down to dynamic meta tag updates.

Why Flutter Web SEO Is Uniquely Challenging

A traditional web page returns HTML that crawlers can parse immediately. Flutter Web defaults to the CanvasKit renderer, which paints everything into a <canvas> element. The resulting HTML contains almost no readable content:

<!-- What Googlebot sees with CanvasKit (nearly empty) -->
<body>
  <script src="main.dart.js"></script>
  <flt-glass-pane></flt-glass-pane>
</body>

You have two main escape routes:

Approach	Pros	Cons
Switch to HTML renderer	Crawlers read real DOM elements	Slightly lower graphics fidelity
SSR / Pre-rendering	Best-in-class SEO	High implementation cost
`--web-renderer html` build flag	Zero code change required	Some widget differences

Jibun Inc. uses HTML renderer + static meta tags as the pragmatic baseline, which covers 90% of SEO needs without major engineering effort.

Step 1: Nail the index.html Meta Tags

web/index.html is the first file any crawler fetches. Meta tags here are available before the Flutter engine even boots.

<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <!-- Core SEO -->
  <title>Jibun Inc. — AI Life Management</title>
  <meta name="description"
    content="One app replacing Notion, Evernote, MoneyForward and 18 more.
             AI-powered life management built with Flutter Web + Supabase.">
  <meta name="robots" content="index, follow">
  <link rel="canonical" href="https://my-web-app-b67f4.web.app/">

  <!-- Open Graph -->
  <meta property="og:title" content="Jibun Inc. — AI Life Management">
  <meta property="og:description"
    content="21 competing apps unified into one Flutter Web + Supabase product.">
  <meta property="og:image"
    content="https://my-web-app-b67f4.web.app/og-image.png">
  <meta property="og:url" content="https://my-web-app-b67f4.web.app/">
  <meta property="og:type" content="website">
  <meta property="og:locale" content="ja_JP">

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@kanta13jp1">
  <meta name="twitter:title" content="Jibun Inc. — AI Life Management">
  <meta name="twitter:image"
    content="https://my-web-app-b67f4.web.app/og-image.png">

  <!-- Force HTML renderer for SEO -->
  <script>window.flutterWebRenderer = "html";</script>
</head>

Pro tip: Generate a 1200×630 px og-image.png using your brand colors. This single image dramatically improves click-through rates on social shares.

Step 2: Build a Proper sitemap.xml

Provide Google with the complete URL map of your app. Jibun Inc. manages 22 URLs across landing, comparison, and feature pages.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

  <url>
    <loc>https://my-web-app-b67f4.web.app/</loc>
    <lastmod>2030-07-01</lastmod>
    <changefreq>weekly</changefreq>
    <priority>1.0</priority>
  </url>

  <url>
    <loc>https://my-web-app-b67f4.web.app/comparison</loc>
    <lastmod>2030-07-01</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.9</priority>
  </url>

  <url>
    <loc>https://my-web-app-b67f4.web.app/manual</loc>
    <lastmod>2030-06-01</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.7</priority>
  </url>

</urlset>

Auto-regenerate sitemap on route changes

# scripts/generate_sitemap.py
import re, datetime, pathlib

ROUTES_FILE = "lib/main.dart"
BASE_URL = "https://my-web-app-b67f4.web.app"
TODAY = datetime.date.today().isoformat()

# Extract GoRoute paths from main.dart
routes_text = pathlib.Path(ROUTES_FILE).read_text(encoding="utf-8")
paths = re.findall(r"path:\s*['\"](/[^'\"]*)['\"]", routes_text)

urls = []
for path in sorted(set(paths)):
    priority = "1.0" if path == "/" else "0.8"
    urls.append(f"""  <url>
    <loc>{BASE_URL}{path}</loc>
    <lastmod>{TODAY}</lastmod>
    <changefreq>monthly</changefreq>
    <priority>{priority}</priority>
  </url>""")

sitemap = f"""<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
{chr(10).join(urls)}
</urlset>
"""
pathlib.Path("web/sitemap.xml").write_text(sitemap, encoding="utf-8")
print(f"Generated {len(urls)} URLs")

Step 3: Add JSON-LD Structured Data

Structured data helps Google display rich snippets (star ratings, price info, breadcrumbs) directly in search results.

<!-- Embed in web/index.html <head> -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "SoftwareApplication",
      "name": "Jibun Inc.",
      "applicationCategory": "ProductivityApplication",
      "operatingSystem": "Web, iOS, Android",
      "description": "AI life management app unifying 21 competing tools.",
      "url": "https://my-web-app-b67f4.web.app/",
      "author": {
        "@type": "Person",
        "name": "kanta13jp1",
        "sameAs": "https://twitter.com/kanta13jp1"
      },
      "offers": {
        "@type": "Offer",
        "price": "0",
        "priceCurrency": "JPY",
        "availability": "https://schema.org/InStock"
      }
    },
    {
      "@type": "WebSite",
      "url": "https://my-web-app-b67f4.web.app/",
      "potentialAction": {
        "@type": "SearchAction",
        "target": {
          "@type": "EntryPoint",
          "urlTemplate": "https://my-web-app-b67f4.web.app/search?q={search_term_string}"
        },
        "query-input": "required name=search_term_string"
      }
    }
  ]
}
</script>

Step 4: Dynamic Meta Tags for SPA Routes

The static index.html approach works for the root URL but breaks per-page SEO in a SPA. Fix this by updating meta tags at the Dart layer on every navigation.

// lib/utils/seo_helper.dart
import 'dart:js_interop';
import 'package:web/web.dart' as web;

class SeoHelper {
  static void updatePage({
    required String title,
    required String description,
    String? canonicalPath,
    String? ogImage,
  }) {
    final fullTitle = '$title | Jibun Inc.';
    final canonical = canonicalPath != null
        ? 'https://my-web-app-b67f4.web.app$canonicalPath'
        : null;

    web.document.title = fullTitle;
    _setMeta('name', 'description', description);
    _setMeta('property', 'og:title', fullTitle);
    _setMeta('property', 'og:description', description);
    if (ogImage != null) _setMeta('property', 'og:image', ogImage);
    if (canonical != null) _setCanonical(canonical);
  }

  static void _setMeta(String attr, String value, String content) {
    var el = web.document.querySelector('meta[$attr="$value"]')
        as web.HTMLMetaElement?;
    if (el == null) {
      el = web.document.createElement('meta') as web.HTMLMetaElement;
      el.setAttribute(attr, value);
      web.document.head?.appendChild(el);
    }
    el.content = content;
  }

  static void _setCanonical(String href) {
    var link = web.document.querySelector('link[rel="canonical"]')
        as web.HTMLLinkElement?;
    if (link == null) {
      link = web.document.createElement('link') as web.HTMLLinkElement;
      link.rel = 'canonical';
      web.document.head?.appendChild(link);
    }
    link.href = href;
  }
}

Wire it into your GoRouter redirect

// lib/main.dart (router config)
GoRouter(
  observers: [SeoRouterObserver()],
  routes: [ ... ],
)

class SeoRouterObserver extends NavigatorObserver {
  static const _pageMeta = {
    '/': (
      title: 'Jibun Inc. — AI Life Management',
      description: 'Unified life management replacing 21 apps.',
    ),
    '/comparison': (
      title: 'App Comparison — Jibun Inc. vs Notion, Evernote & More',
      description: 'Feature-by-feature comparison with 21 competing apps.',
    ),
  };

  @override
  void didPush(Route route, Route? previousRoute) {
    final name = route.settings.name ?? '/';
    final meta = _pageMeta[name];
    if (meta != null) {
      SeoHelper.updatePage(
        title: meta.title,
        description: meta.description,
        canonicalPath: name,
      );
    }
  }
}

Step 5: robots.txt and Firebase Hosting Config

# web/robots.txt
User-agent: *
Allow: /
Disallow: /admin/
Disallow: /api/

Sitemap: https://my-web-app-b67f4.web.app/sitemap.xml

Ensure Firebase Hosting serves these files correctly:

// firebase.json (relevant snippet)
{
  "hosting": {
    "public": "build/web",
    "rewrites": [
      { "source": "/**", "destination": "/index.html" }
    ],
    "headers": [
      {
        "source": "/robots.txt",
        "headers": [{ "key": "Cache-Control", "value": "public, max-age=86400" }]
      },
      {
        "source": "/sitemap.xml",
        "headers": [{ "key": "Cache-Control", "value": "public, max-age=86400" }]
      }
    ]
  }
}

Measuring Results

Metric	Tool	Target
Index coverage	Google Search Console	100% of routes indexed
Core Web Vitals	PageSpeed Insights	LCP < 2.5s, CLS < 0.1
Rich snippets	Schema.org validator	No errors
Crawl errors	Search Console → Coverage	0 errors

Summary

Flutter Web SEO requires more intentional work than React or Vue, but it's entirely achievable. The key insight: separate what you can control statically (index.html) from what must be dynamic (per-route meta tags). Apply the HTML renderer, write complete meta tags, submit a sitemap, and add structured data — in that order of priority.

Based on real implementation at Jibun Inc. (Flutter Web + Supabase, competing with 21 apps).