flutter-widget-previewer

name	flutter-widget-previewer
description	>- Use when this capability is needed.

Flutter Widget Previewer

Purpose

Enable live widget previews (Chrome or IDE “Flutter Widget Preview” tab) separate from a full app, using the @Preview annotation and the flutter widget-preview CLI.

Official reference: Flutter Widget Previewer

When this skill applies

• Adding @Preview to functions or widgets.
• Running flutter widget-preview start from a project root.
• Designing package UI so previews stay web-safe (no dart:io / dart:ffi in the previewed tree).
• Customizing previews (size, brightness, theme, wrapper, MultiPreview).

Prerequisites

• Flutter 3.38+ (IDE integration); docs target recent stable (see site footer on the doc page).
• Import: package:flutter/widget_previews.dart and package:flutter/material.dart (or Cupertino) as needed.

Start the previewer

From the Flutter package or app root:

flutter widget-preview start

Launches a local server and opens a Widget Preview environment in Chrome; updates follow project changes.

IDE: Android Studio / IntelliJ / VS Code can show “Flutter Widget Preview” in the sidebar (may auto-start on launch per doc).

Define a preview

@Preview applies to:

• Top-level functions returning Widget or WidgetBuilder.
• Static methods on a class returning Widget or WidgetBuilder.
• Public Widget constructors or factories with no required arguments.

Minimal example:

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

@Preview(name: 'My Sample Text')
Widget mySampleText() {
  return const Text('Hello, World!');
}

Grouping and layout

• name: Label in the preview list.
• group: Groups related previews.
• size: Size(width, height) — prefer explicit constraints; unconstrained widgets may get ~half previewer size (behavior may change).

Light / dark

@Preview(name: 'Light', brightness: Brightness.light)
@Preview(name: 'Dark', brightness: Brightness.dark)
Widget myButtonPreview() => const ButtonShowcase();

Or use MultiPreview to reduce duplication (see doc: custom MultiPreview subclasses).

Theming and wrappers

• theme: PreviewThemeData via Preview (or custom annotation extending Preview).
• wrapper: Wrap the preview to inject InheritedWidgets or MaterialApp-like shells.
• textScaleFactor, localizations: Match accessibility / locale scenarios.

Restrictions (web / previewer)

Previews run in an environment built for Flutter Web constraints:

Topic	Rule
dart:io	Avoid in previewed code paths; if transitively imported, APIs throw when called.
dart:ffi	Widgets depending on FFI may fail to load entirely.
Plugins	Native plugins not supported; web plugins may work in Chrome but are not guaranteed in all environments.
Preview annotation callbacks	wrapper / similar parameters must use public names and be compatible with the previewer’s codegen (follow current doc).
Assets	Use package paths for dart:ui fromAsset-style loading, e.g. packages/<package>/<asset>.

Structure conditional imports if platform code must coexist with previews (Dart conditional imports).

Packages (session_insight_kit)

• Keep @Preview entry points under lib/ (e.g. lib/src/presentation/previews/…) so the previewer discovers them.
• Do not re-export preview-only files from the public barrel unless product requirements explicitly need it; previews can remain library-private imports.
• Prefer thin preview functions that wrap public widgets with fake / stub data—no real capture, speech, or filesystem calls.

Agent workflow

1. Implement or change a StatelessWidget / StatefulWidget with pure Flutter dependencies on the preview path.
2. Add a top-level Widget …() (or eligible constructor) with @Preview(name: …, group: …) and optional size / brightness.
3. Run flutter widget-preview start (or use the IDE preview tab) and confirm light/dark if relevant.
4. If a preview fails to load, check for dart:io, FFI, or native plugins in the transitive import graph and split stub UI.

Troubleshooting (IDE errors, daemon timeouts)

emulator.getEmulators / Flutter daemon timeout (e.g. 20000ms)

If the log shows:

Request "emulator.getEmulators" to daemon was not responded to within 20000ms

this is a Flutter daemon ↔ editor issue, not proof that @Preview code is wrong. The Dart & Flutter extension asks the daemon for the Android emulator list; if that call stalls (slow/hung Android SDK tools, first-run locks on flutter, or daemon load), the same daemon also backs Widget Preview in the IDE, so the preview panel can fail even though previews compile.

Mitigations (try in order):

1. CLI preview (bypasses the IDE panel) — from the package/app root:

   flutter widget-preview start
   

   Opens the preview environment in Chrome; use this when the sidebar preview is broken.

2. Restart Flutter tooling in the editor — e.g. Dart: Restart Analysis Server, Restart Extension Host, or reload the window; or use the prompt’s Restart Extension if shown.

3. Diagnose Android / emulator tools — ensure flutter doctor is clean; if emulator or sdkmanager hangs on your machine, fix PATH / Android SDK (stalled emulator enumeration can contribute to daemon backlog).

4. Separate daemon log (VS Code / compatible editors) — set dart.flutterDaemonLogFile to a path and restart; when the timeout happens, capture FlutterDaemon lines and see Dart-Code #5793.

Note: flutter create --platforms=web is not supported for the package template; rely on flutter widget-preview start and IDE support for packages as documented in current Flutter releases.

Preview widget fails to render / red error in preview frame

Then investigate web-only limits (see Restrictions above) and transitive imports of dart:io / FFI / native plugins.

Related

• API: Preview class
• MultiPreview for shared preview lists

---

Source: blendfactory/session-insight-kit — distributed by TomeVault.