Add Flutter widget preview support

- Add GetItPreviewWrapper helper widget in example
- Update README with Flutter previews section
- Add comprehensive preview examples showing both direct and wrapper approaches
- Document how to use get_it with Flutter's widget previewer

Author: escamoteur

README.md

@@ -141,6 +141,29 @@ tearDown(() async {
 
 [Read testing guide →](https://flutter-it.dev/documentation/get_it/testing)
 
+### Flutter Widget Previews
+
+`get_it` works seamlessly with Flutter's widget previewer. Since previews run in isolation, you need to initialize `get_it` within the preview itself:
+
+```dart
+@Preview()
+Widget myPreview() {
+  if (!getIt.isRegistered<MyService>()) {
+    getIt.registerSingleton<MyService>(MockService());
+  }
+  return const MyWidget();
+}
+```
+
+Or use a reusable wrapper for automatic cleanup:
+
+```dart
+@Preview(name: 'My Widget', wrapper: myWrapper)
+Widget myPreview() => const MyWidget();
+```
+
+[Read Flutter previews guide →](https://flutter-it.dev/documentation/get_it/flutter_previews)
+
 ## Ecosystem Integration
 
 **get_it works independently** — use it standalone for dependency injection in any Dart or Flutter project.

example/lib/main.dart

@@ -1,18 +1,24 @@
 import 'package:flutter/material.dart';
+import 'package:flutter/widget_previews.dart';
 import 'package:get_it/get_it.dart';
 import 'package:get_it_example/app_model.dart';
+import 'package:get_it_example/preview_wrapper.dart';
 
 // This is our global ServiceLocator
 GetIt getIt = GetIt.instance;
 
-void main() {
+void setupLocator() {
+  // Here you can register other dependencies if needed
   /// I use signalReady here only to show how to use it. In 99% of the cases
   /// you don't need it. Just use registerSingletonAsync
   getIt.registerSingleton<AppModel>(
     AppModelImplementation(),
     signalsReady: true,
   );
+}
 
+void main() {
+  setupLocator();
   runApp(const MyApp());
 }
 
@@ -105,3 +111,62 @@ class _MyHomePageState extends State<MyHomePage> {
     );
   }
 }
+
+// ==============================================================================
+// Flutter Widget Preview Examples
+// ==============================================================================
+//
+// Flutter's widget previewer renders widgets in isolation, without running
+// main() or your normal app initialization. This means `get_it` won't be
+// initialized automatically. Below are two approaches to handle this:
+
+// ------------------------------------------------------------------------------
+// Approach 1: Direct Registration with isRegistered() Check
+// ------------------------------------------------------------------------------
+//
+// Use this for simple, one-off previews where you want maximum control.
+// The previewer may call this function multiple times, so we check if
+// the service is already registered before registering it again.
+
+@Preview()
+Widget preview() {
+  // Guard against double registration since preview functions
+  // can be called multiple times during hot reload
+  if (!getIt.isRegistered<AppModel>()) {
+    getIt.registerSingleton<AppModel>(
+      AppModelImplementation(),
+      signalsReady: true,
+    );
+  }
+  return const MyApp();
+}
+
+// ------------------------------------------------------------------------------
+// Approach 2: Wrapper Widget with Automatic Cleanup
+// ------------------------------------------------------------------------------
+//
+// Use this when you want automatic cleanup or need to reuse the same setup
+// across multiple previews. The wrapper handles initialization in initState
+// and cleanup via reset() in dispose.
+//
+// Uncomment the @Preview annotation to enable this preview:
+
+// @Preview(name: 'With GetIt Wrapper', wrapper: wrapper)
+Widget previewWithWrapper() => const MyApp();
+
+// Wrapper function (must be top-level or static for @Preview)
+Widget wrapper(Widget child) {
+  return GetItPreviewWrapper(
+    init: (getIt) {
+      // Register all preview dependencies here
+      getIt.registerSingleton<AppModel>(
+        AppModelImplementation(),
+        signalsReady: true,
+      );
+    },
+    child: child,
+  );
+}
+
+// Note: GetItPreviewWrapper is defined in preview_wrapper.dart
+// See that file for full documentation on how it works.

example/lib/preview_wrapper.dart

@@ -0,0 +1,105 @@
+import 'package:flutter/material.dart';
+import 'package:get_it/get_it.dart';
+
+/// A wrapper widget for Flutter widget previews that initializes `get_it`.
+///
+/// Flutter's widget previewer renders widgets in isolation, separate from your
+/// app's normal initialization flow. This means `get_it` won't be initialized
+/// automatically. This wrapper handles `get_it` setup and cleanup for previews.
+///
+/// ## How to Use
+///
+/// ```dart
+/// Widget myWrapper(Widget child) {
+///   return GetItPreviewWrapper(
+///     init: (getIt) {
+///       // Register your preview dependencies
+///       getIt.registerLazySingleton<ApiService>(() => MockApiService());
+///       getIt.registerLazySingleton<UserRepo>(() => MockUserRepo());
+///     },
+///     child: child,
+///   );
+/// }
+///
+/// @Preview(name: 'My Widget', wrapper: myWrapper)
+/// Widget myWidgetPreview() => const MyWidget();
+/// ```
+///
+/// ## When to Use This vs Direct Registration
+///
+/// **Use this wrapper when:**
+/// - You want automatic cleanup (calls `reset()` on dispose)
+/// - You have complex setup logic
+/// - You want to reuse the same setup across multiple previews
+///
+/// **Use direct registration when:**
+/// - You have simple, one-off previews
+/// - You want maximum control over initialization
+///
+/// Example of direct registration:
+/// ```dart
+/// @Preview()
+/// Widget preview() {
+///   if (!getIt.isRegistered<MyService>()) {
+///     getIt.registerSingleton<MyService>(MockService());
+///   }
+///   return const MyWidget();
+/// }
+/// ```
+///
+/// ## How It Works
+///
+/// 1. **initState**: Calls your `init` function to register dependencies
+/// 2. **build**: Returns your child widget with GetIt ready to use
+/// 3. **dispose**: Calls `getIt.reset()` to clean up all registrations
+///
+/// The preview environment may call your preview function multiple times,
+/// so the wrapper ensures proper cleanup between renders.
+class GetItPreviewWrapper extends StatefulWidget {
+  const GetItPreviewWrapper({
+    super.key,
+    required this.init,
+    required this.child,
+  });
+
+  /// The child widget to render after `get_it` is initialized
+  final Widget child;
+
+  /// Initialization function that registers dependencies in `get_it`
+  ///
+  /// This is called once in `initState` before the widget is built.
+  /// Register all your preview dependencies here.
+  ///
+  /// Example:
+  /// ```dart
+  /// init: (getIt) {
+  ///   getIt.registerLazySingleton<ApiService>(() => MockApiService());
+  ///   getIt.registerSingleton<Config>(TestConfig());
+  /// }
+  /// ```
+  final void Function(GetIt getIt) init;
+
+  @override
+  State<GetItPreviewWrapper> createState() => _GetItPreviewWrapperState();
+}
+
+class _GetItPreviewWrapperState extends State<GetItPreviewWrapper> {
+  @override
+  void initState() {
+    super.initState();
+    // Initialize get_it with preview dependencies
+    widget.init(GetIt.instance);
+  }
+
+  @override
+  void dispose() {
+    // Clean up all get_it registrations when preview is disposed
+    GetIt.instance.reset();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return widget.child;
+  }
+}