Develop at the Speed of Thought!

You want your ideas to come to life as you think of them. The instant you write down those ideas, you demand instant gratification from instant functionality. nuxt-stories is a module that you can use to rapidly write stories, game-plans, notes, documentation, whatever for your Nuxt web application. Actually, if you think about it, even your collection of stories can be your app!

For the impatient, you may wish to fast-forward directly to the demos.

Disclaimer: I am the author of nuxt-stories.

Introduction

Almost a year ago, I introduced the world to nuxt-stories 1.x (Nuxt Storybooking: The Painless Way). My first AH-HA moment for simplifying the [traditionally tedious] storybooking workflow came then, when I realized I could simply use the features offered by the web framework: without completely starting from scratch, I could simply extend my application’s routes to show stories when desired and hide them otherwise. A one-line configuration change to save me from a weekend headache.

Many months later, I had my second AH-HA moment when I realized it was probably the stories I wanted all along to form the application itself, and to not just have them be mere application requirements. I thought stories that could be managed directly on the UI, instead of the filesystem, could allow for a much faster workflow.

This contrasts significantly to modern web development, where changes are usually made on the filesystem and then those changes are made visible on the UI. The inherent delay in waiting for the filesystem change to manifest itself onto the UI is what I’ve always felt to work against my speed of thought. I needed the arrow to be flipped: to instead have changes made on the UI get automatically saved back to the filesystem.

Mental Breakthrough: We never really wanted apps, we wanted functional stories

It occurred to me that perhaps even though we have all gotten accustomed to using apps, that maybe we never really wanted to use them, but rather functional stories. Stories written on our terms, not anyone else’s. Stories that work with our thought processes and look the way we want. Stories with components organized to our individual liking, instead of apps fragmented on a screen, requiring us to jump in and out of them.

All of human history has been built on stories: ideas we’ve had, lessons we’ve learned, times where we’ve pivoted, and unique calculations we’ve performed. With so much variation encountered by each individual, how can any one app completely satisfy the needs of any one person? And even if apps completely do what we want, why all the updates? The answer is they don’t and never will, precisely because our needs and wants will change as time goes on.

Instead, we need stories that we can write, stories that can then interpret what we write to visualize the knowledge we seek, and then adapt as we do. Having stories that contain not just ideas, but also functional components will potentially be the fastest way to bring thought to life. Moreover, when such stories can be written in a format that loosely looks likes most people’s PostIt® notes (i.e., Markdown), then the story writing and even pseudo-coding can be done by a world of people, not just software developers.

For example, a single story point might be:

* The weather in **{{ destination }}**:
<weather :location="destination" />

And it would be ideal to see that quickly transform into something like this:

The weather in San Francisco:

(Screenshot of Google Weather; this example would have “destination” set to “San Francisco” in the stories’ reserved data section)

And then from that point on, this functional widget would always be part of the story. There is complete control of where the widget goes and how it is styled. Ideally, this would all happen as the widget syntax is written down, without the need to go to some app store. The app store would probably be replaced by a component or stories “store”, so that instead of downloading entire apps, just the parts of interest are pulled. Or perhaps even better, widgets could probably have built-in “from” or “variant” attributes that would instantiate a specific widget on-demand:

<weather from=”google” location=”San Francisco” />

No store to go to, no waiting for downloads to finish, just retrieve the information of interest the instant the tag is closed with “/>”. No need to hit “Ctrl + Enter” or have some knowledge of keyboard shortcuts. Just type what you want to get what you want.

Important Characteristics of Stories

• Stories are constantly changing. Computer code branches all the time precisely because our stories branch. Therefore, a storybooking tool will be most useful when used in conjunction with a version control system such as git, so that the branches can quickly be changed in and out.
• Stories that constantly change require dynamic hosts to listen for those changes. nuxt-stories uses nuxt-socket-io under the hood to accomplish this.
• Stories can constantly change, but sometimes the content is meant to be hosted statically so that others can’t change it. For example, instruction guides or documentation. nuxt-stories allows the static host options to be configured.
• Stories can either be uploaded to a central location or distributed to (and only to) a network of subscribers. The holochain (h-wiki) was the inspiration for the latter.
• Stories and the storybooking tool should be accessible to all, not just those who know how to code. Thus, editing directly on the UI is a non-negotiable requirement. Developing away from the UI in a preferred IDE should also be possible to satisfy those users too. This way, stories that get created on the UI can be saved back to the filesystem, and vice versa.
• All parts of the stories, including the functional ones, should be responsive, as in the instant we write them down. Just like a painter needs to see the stroke as she paints, story tellers need to see the UI widgets come to life as they are written, not 3–4 seconds after the fact. Even a 1 second delay becomes painfully distracting.
• Stories have to be automatically saved after being written down. Long before computers existed, “Ctrl + S” was never a requirement to secure one’s written thought, and, in my opinion, still shouldn’t be. Auto-distributing, on the other, has its own set of requirements.

Stories Organization

In nuxt-stories, stories are organized as follows:

• [app root] / [storiesDir; default: “stories”] / [lang; default: “en”]

For the demos presented in this article below, the following organization is used:

As shown above, it is seen that stories can either be written as “Vue-first” or “Markdown-first”. In my personal opinion, “Markdown-first” is much more intuitive and portable, and so all demos introduced here will use that approach. Also, from this point on, the nuxt-stories module will only support add/edit/delete operations on “Markdown-first” stories. I apologize to any version 1 users that got used to “Vue-first” but, I think you’ll like “Markdown-first” more.

Demos

For the rest of this article, I’ll let the videos do the talking. I composed them to help your reading pace keep up with my writing pace. You can pause/play/seek the controls to exactly the tidbits you want. This may be the best way to learn exactly what nuxt-stories is all about and what it plans to be.

Basic Usage

Automatically-Generated Table of Contents

Inputting Data

Reordering Stories

Auto-Importing Components

Auto-Updating Calculations

Fun with Videos

Important notes

1. Since the UI is allowing you to do live editing and real-time compiling, there is technically a lot of rule-breaking going on, but it’s ok, because this is simply a dev tool primarily used locally. Expect to see console log statements going haywire. As you type, naturally, compilation will fail as the component name is incomplete. My best recommendation is to temporarily mute console errors, or disable the “error” log level in dev tools.

2. For the markdown-based stories, first the stories get parsed by the markdown parser, and then compiled by the Vue compiler. Whatever is entered in the left pane gets parsed/compiled, so make sure you trust the input. Included with the nuxt-stories module is a DOMpurify package which you may wish to enable for sanitizing the markdown. However, this can impede your workflow. Choose how much speed you want to trade off for security or vice versa.

3. As each individual story grows, parsing and compilation will occur with as you type and this can result in a slower responsiveness if the story becomes too large. While there is a configurable debounce time help with this, a 300 ms delay between the keystroke and the parsing to be exact, think of this as a way to further improve the organization of your stories. The smaller they are, the easier it may be to organize your thoughts too. It may be planned in the future too to have UI controls that allow for pausing / resuming of live compilation.

4. In the UI, there are some features still unimplemented, such as the search box, language selector and user control. In fact, there is still much Todo.

Conclusion

While version 1 of nuxt-stories was pretty cool, in hindsight, it didn’t quite do all I wanted for a story-driven development. Version 2 has some major improvements, but there is still a lot of work to be done. The bigger takeaway, however, is providing concrete examples of story-driven development so that the concepts can easily be reused and improved upon. In fact, version 2 came about after not only brainstorming ideas for 5 months, but studying from others, such as ObservableHQ, bootstrap-vue, nuxt-content, h-wiki, and even storybookjs. So much respect goes to them too.

• Want to contribute? Code or no code, great ideas improve the project. It’s here: https://github.com/richardeschloss/nuxt-stories
• Want to connect? Find me on Linkedin here: https://www.linkedin.com/in/richardeschloss/