Quick Start

Bootstrap

The first step to start using Widgetbook is to create a new separate Flutter app for your widget catalog.

  1. Create a new Flutter project inside your app's directory:

    ## All platforms
    flutter create widgetbook --empty
    
    ## Certain platforms
    flutter create widgetbook --empty --platforms=web,macos
    
  2. To avoid naming conflict with the Widgetbook pub package, change the project name to widgetbook_workspace inside the widgetbook/pubspec.yaml file:

    - name: widgetbook
    + name: widgetbook_workspace
    
  3. Add the following dependencies to your widgetbook project:

    flutter pub add widgetbook widgetbook_annotation dev:widgetbook_generator dev:build_runner
    
  4. Add your app as a path dependency to the widgetbook/pubspec.yaml file:

    dependencies:
      your_app:
        path: ../
    

After finishing the setup, the folder structure should look something like this:

your_app/
├── pubsepc.yaml
├── lib/
├── ...
└── widgetbook/
    ├── pubsepc.yaml
    ├── lib/
    └── ...

And the widgetbook/pubspec.yaml file should look like this:

name: widgetbook_workspace
# ...

dependencies:
  widgetbook_annotation: ^3.2.0
  widgetbook: ^3.9.0
  your_app:
    path: ../

dev_dependencies:
  build_runner:
  widgetbook_generator: ^3.9.0

Your First Use-case

In this section, you will create a simple use-case and show it inside your Widgetbook app.

  1. Choose a widget from your_app that you want to catalog. For this example, we will use the imaginary CoolButton widget.

  2. Create a file inside your widgetbook app at widgetbook/lib/cool_button.dart

    If your widget needs some parameters, you can pass some constants for now for simplicity. Later you can check how to use Knobs.

    import 'package:flutter/material.dart';
    import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;
    
    // Import the widget from your app
    import 'package:your_app/cool_button.dart';
    
    @widgetbook.UseCase(name: 'Default', type: CoolButton)
    Widget buildCoolButtonUseCase(BuildContext context) {
      return CoolButton();
    }
    
  3. Create a file inside your widgetbook app at lib/main.dart

    import 'package:flutter/material.dart';
    import 'package:widgetbook/widgetbook.dart';
    import 'package:widgetbook_annotation/widgetbook_annotation.dart' as widgetbook;
    
    // This file does not exist yet,
    // it will be generated in the next step
    import 'main.directories.g.dart';
    
    void main() {
      runApp(const WidgetbookApp());
    }
    
    @widgetbook.App()
    class WidgetbookApp extends StatelessWidget {
      const WidgetbookApp({super.key});
    
      @override
      Widget build(BuildContext context) {
        return Widgetbook.material(
          // The [directories] variable does not exist yet,
          // it will be generated in the next step
          directories: directories,
        );
      }
    }
    
  4. Run the following command to generate the main.directories.g.dart file that has the directories variable:

    dart run build_runner build -d
    
  5. Now you can run your Widgetbook app and see your use-case in action:

    flutter run
    
  6. Add some Addons to your Widgetbook app to customize the appearance of your use-case.