Skip to main content

Install

Download Monarch​

  1. Make sure you have Xcode installed.

  1. Download the following bundle to get the latest release of the Monarch binaries, which include the Monarch CLI and desktop app.

    2. cd ~/development
    curl -O https://d148mrbia1nlbw.cloudfront.net/macos/monarch_macos_2.2.3.zip

  1. Extract the file:

    2. unzip monarch_macos_2.2.3.zip

  1. Add the monarch binaries to your path:

    2. export PATH="$PATH:`pwd`/monarch/bin"

    This command sets your PATH variable for the current terminal window only. To permanently add Monarch to your path, see Update your path.

Run: monarch init​

Go to one of your Flutter projects. Then, inside your project’s root directory run:

monarch init

The monarch init command sets up the dependencies needed to run monarch. It also creates a few sample stories in your project.

Run: monarch run​

Inside your project’s root directory run:

monarch run

The monarch run command prepares the stories in your project so they can be used by Monarch. It then launches the Monarch app where you can preview your stories.

Write your own stories​

You can write stories for the pieces of the user interface you want to isolate. Here is a simple story:

my_stories.dart
Widget foo() => MyWidget(...);

In Monarch, a story is a function which returns a Widget and which is inside a file that ends in _stories.dart. It's that simple. Monarch will then preview the stories you have written.

The monarch init command generates the 3 samples stories below.

stories/sample_button_stories.dart
Widget primary() => const Button('...', ButtonStyles.primary);

Widget secondary() => const Button('...', ButtonStyles.secondary);

Widget disabled() => const Button('...', ButtonStyles.disabled);

Each story returns a button, which is a Widget, in a specific visual state. There is the primary, secondary and disabled states of the Button widget. When you run monarch you will preview these stories.

my_project macOS sample stories

When you select a story on the left window, Monarch will render that story inside the Preview window on the right.

Where to put stories​

Monarch will look for stories in dart files that end with *_stories.dart.

You can place stories inside the stories directory or, if you prefer, you can place them inside your lib directory. The only requirement is that story files should end in *_stories.dart.

Stories for your own widgets​

Let's say your project has a couple of widgets files. One is inside lib and one inside lib\src.

- my_project
    - lib
        - my_fancy_button.dart
        - src
            - my_fancy_card.dart

To write stories for those widgets, you just need to import them into a *_stories.dart file, then you can write stories for those widgets.

stories/my_stories.dart
import 'package:my_project/my_fancy_button.dart';
import 'package:my_project/src/my_fancy_card.dart';

Widget someButton => MyFancyButton(...);
Widget anotherButton => MyFancyButton(...);

Widget someCard => MyFancyCard(...);
Widget anotherCard => MyFancyCard(...);

As you make changes Monarch will reload your stories so you can quickly see them in the Preview window.

Stories for prototypes​

You can write stories that use the Flutter widgets directly. It is a good way to prototype new views. For example, in a file that ends in *_stories.dart, you can add these stories:

Widget foo() => Text('foo', style: TextStyle(fontSize: 50));
Widget bar() => Icon(Icons.pets, size: 50);
Widget foobar() => Center(child: Column(children: [foo(), bar()]));

More​

Building from source​

If you prefer to build Monarch from source, you can follow this guide which will help you set up your local and build the Monarch source code.

Update your path​

Follow these instructions to update your path variable permanently, which will let you run monarch from any terminal window.

  1. Open your rc file, which may be  ~/.bash_profile,  ~/.bashrc or  ~/.zshrc.

  1. Add the following line and change [PATH_TO_MONARCH] to be the path where you unzipped Monarch:

    2. export PATH="$PATH:[PATH_TO_MONARCH]/monarch/bin"

  1. Run source ~/. <rc file> to refresh the current window, or open a new terminal window to automatically source the file.

  1. Verify that the monarch/bin directory is now in your PATH by running:

    2. echo $PATH

  1. Verify that the monarch command is available by running:

    2. monarch --version