zodern:aurorae

v0.1.1Published last year

Aurorae

Development environment for UI components, built for Meteor.

Auroae is similar to Storybook, with only the basic features.

Features:

  • Create stories for React, Blaze, Svelte, and Vue
  • Updates stories and components with HMR (Requires Meteor 2)
  • Use Meteor packages, API's, and build plugins with your stories
  • Runs as part of your Meteor app

Meteor 2 or newer is recommended.

Getting Started

Add zodern:aurorae with

meteor add zodern:aurorae
meteor npm install --save svelte

Start your app and navigate to /__meteor-aurorae to view the stories in your app. For some apps, you might need to adjust the router used by the app to prevent redirecting away from /__meteor-aurorae.

Stories are defined in files with the .stories.js, .stories.html, or .stories.svelte extensions. These files are handled differently than other files in an app:

  • These files are always eagerly loaded on the client in development
  • In production builds or on the server, the files are only loaded if they are imported by another file
  • .stories.html files are compiled using Blaze
  • .stories.js files are compiled the same way the ecmascript package compiles .js files
  • .stories.svelte files are compiled with the zodern:melte package

UI Frameworks

React

Add story:

1import { addStory } from 'meteor/zodern:aurorae/react';
2import Button './Button.jsx';
3
4// addStory(name, component, props)
5addStory(
6  'Button - dark',
7  Button,
8  { title: 'Explore', theme: 'dark' }
9);
10
11// Or you can create a function component
12addStory(
13  'Button - dark',
14  () => <Button title='Explore' theme='dark' />
15);

If you want to wrap your component with another component, for example if it consumes react context or needs a parent element styled a certain way, you can add a wrapper by:

1addStory(
2  'Button - light',
3  Button,
4  { title: 'Hide', theme: 'light' }
5)
6  // The wrapper function is given the children that should be rendered, and returns a react element
7  .wrap(({ children }) => <DarkContainer>{children}</DarkContainer>);

Svelte

Add story:

1import { addStory } from 'meteor/zodern:aurorae/svelte';
2import Button './Button.svelte';
3
4// addStory(name, component, props)
5addStory(
6  'Button - dark',
7  Button,
8  { title: 'Explore', theme: 'dark' }
9);

Or you can add stories in files with the .stories.svelte extension (for example, button.stories.svelte):

1<script>
2  import { Story } from 'meteor/zodern:aurorae/svelte';
3  import Button from './Button.svelte';
4</script>
5
6<Story name="button - dark">
7  <Button theme='dark'>Next</Button>
8</Story>
9
10<Story name="button - light">
11  <Button theme='light'>Next</Button>
12</Story>

If you want to wrap your component with another component, you can add a wrapper by:

1import Wrapper from './Wrapper.svelte';
2addStory(
3  'Button - light',
4  Button,
5  { title: 'Hide', theme: 'light' }
6)
7  // The wrapper component
8  .wrap(Wrapper);

The wrapper component receives two props: component with the story component, and props with the props that should be passed to the component. For example, the wrapper could look like:

1<script>
2  export let component;
3  export let props;
4</script>
5
6<div>
7  <svelte:component this={component} {...props}></svelte:component>
8</div>
9
10<style>
11  div {
12    max-width: 400px;
13    padding: 20px;
14    background: #EEE;
15  }
16</style>

Blaze

Add story:

1import { addStory } from 'meteor/zodern:aurorae/blaze';
2import './button.html';
3
4// addStory(name, template/Blaze view, data)
5addStory(
6  'Button - dark',
7  Template.button,
8  { title: 'Explore', theme: 'dark' }
9);

Or you can add stories in files with the .stories.html extension (for example, button.stories.html). Templates that start with story-- are added as Aurorae stories.

1<template name="story--Button - dark">
2  {{> button title="Explore" theme="dark"}}
3</template>
4
5<template name="story--Button - light">
6  {{#button theme="light"}}
7    Explore
8  {{/button}}
9</template>

If you want to wrap your template with another template, you can add a wrapper by:

1import Wrapper from './Wrapper.svelte';
2addStory(
3  'Button - light',
4  Template.button,
5  { title: 'Hide', theme: 'light' }
6)
7  // The wrapper template
8  .wrap(Template.storyWrapper);

The wrapper template should have an element with the story-blaze-content id. The story's template is rendered inside of that element. For example, the wrapper could look like:

1<template name="storyWrapper">
2  <div id="story-blaze-content" style="background: black; padding: 100px;"></div>
3</template>

Vue

Add story:

1import { addStory } from 'meteor/zodern:aurorae/vue';
2import Button from './button.vue';
3
4// addStory(name, component, props)
5addStory(
6  'Button - dark',
7  Button,
8  { title: 'Explore', theme: 'dark' }
9);

If you want to wrap your component with another component, you can add a wrapper by:

1import Wrapper from './wrapper.vue';
2addStory(
3  'Button - light',
4  Button,
5  { title: 'Hide', theme: 'light' }
6)
7  // The wrapper component
8  .wrap(Wrapper);

The wrapper template should have a default slot. For example:

1<template>
2  <div style="background: black; padding: 100px;">
3    <slot></slot>
4  </div>
5</template>
6
7<script>
8  export default {};
9</script>
10

Group Stories

To group stories in the sidebar, you can include the group in the story name in the format Group Name - Story Name. For example, Button - light and Button - dark would both be in the Button group.

Show Aurorae

Aurorae will automatically show itself if when the page loads the url is /__meteor-aurorae. You can also show Aurorae with:

1import { showStories } from 'meteor/zodern:aurorae';
2
3showStories();

Keyboard shortcuts

  • j go to the next story
  • k go to the previous story