
> **TL;DR** This is an article about stumbling into an interesting syntax for describing graphs. If you want to see it in action you can [head straight for the demos!](http://graph-selector-syntax.vercel.app/)

## Some Context

About 18 months ago I created [Flowchart Fun](https://flowchart.fun): an app for generating flowcharts from text.

To create your flowchart, the app determines the nodes and edges from the input text according to a set of rules:

- text creates a node
- an indent creates an edge
- text before a colon `:` labels an edge

```plaintext
Node A
  edge to: Node B
```

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1661117132/tone-row-2021/kw29haya3igd7w2j7bgv.png"
  width="443"
  alt="Flowchart Node A edge to Node B"
/>

Simple! Elegant! Chic!

But as with all things, over time some complexity crept in.

## #1 - Too Many Parents

As long as nodes have zero or one parent, creating edges with indentation works great, e.g. a tree 🌳 or document outline; however, pretty often flowcharts contain at least one node with multiple parents.

<img
  src="https://cacoo.com/wp-app/uploads/2018/12/5-Are-you-hungry-flowchart.jpg"
  alt="Cake flowchart"
/>

In our syntax a node only "lives" on one line, so we added the pointer syntax `()` to reference nodes elsewhere in the document.

```plaintext
Are you hungry?
  yes: Do you want to eat healthy?
    yes: No you don't
      oh right: CAKE!
    hell no: (CAKE!)
  no: yes you are
    (CAKE!)
```

✨ [You can open this example in Flowchart Fun](https://flowchart.fun/c#IIJwpgBAng9grhAFnAdgcxFA-AKAtMAZwC4IARGaeCAdwEMUAXCRysO5xdgG0cWzz4CJCADlKsBABMYKAOSNBQiDEQQQASzSJGpAMLAA0gFEAhEqRhu3CChikAFAZOmAlILukoRKgjrgLJyMzdwAewGTSQBtSAG8AIjspMAAFGEINRg1ZQljiONEARgAWMBy4gA8cgFp8gFYAOhrCgA4ATgAmADYAZhaABkKAdi6BjraAGlioKvrWjqaagfyBpvzutpaOgF8JgsKAM1LYiuJ8rvq+wraupraam5X5ianiSoG6jsKi05aV5saWgbbWIFGq9Q7HNoDFp1Qq9fItBaFGqjdpDJ5VN4bYb5OFnS4tdpAkH5cE5U5NOpFAa3dpwuYdGro4htZp1JpnfLw-JtFmdXo1Im1Lqkl6nSkDJEtQotWotLpI6VMzlvLodU5IrrrM4AlqbPVAA)

## #2 - Long Labels

When the label is short, like `CAKE!`, creating pointers is as easy as... pie, but what about when the label is a college essay?

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1661099327/tone-row-2021/wnbqcpxp0iuxato16ckf.png"
  width="443"
  alt="Extremely long label for flowchart node"
/>

Typing long labels twice (once for the node and once for the pointer) would be time consuming and clutter the document- not to mention the label could change and cause the pointer to break. 😕

To solve this problem we use the concept of ID's. We can give our node an ID `[a]` and reference the ID in the pointer `(a)`. Crisis averted!

```plaintext
[a] This is an extraordinarily long label that will flow onto many lines and ultimately cause a lot of heartache for this otherwise simple graph.
  b
    (a)
```

✨ [You can open this example in Flowchart Fun](https://flowchart.fun/c#NoQwugBAKgFglgZwoiIB2ECmAPALgJxAHt8ATONEfOAGwE8Iai0BzRkAI0xolxhFwQA7rR4AzJkIjNcRCAFt0DGhUxJ0pCAFcauOItzcGAYxBaEmVIyKCiYiDExVcIY44hiSveEhuP8IhYQCPoADjSWLIShMAB0AFAQEByJSRAAFCAAlAA9gMmkgDakAN4AvkA)

## #3 - Adding Styles

[Flowchart Fun](https://flowchart.fun) is built using [Cytoscape.js](https://js.cytoscape.org/) which uses the concept of CSS selectors to style nodes and edges.

As a frontend developer, I love this solution. After all, the DOM is a tree of nodes too.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1661371828/fy4p0qexfzyine2pecqy.png"
  width="350"
  alt="If it's good enough for the DOM it's good enough for me!"
/>

To add colors and shapes, I brought Cytoscape's concept of classes into the syntax.

```plaintext
[a.blue] This is an extraordinarily long label that will flow onto many lines and ultimately cause a lot of heartache for this otherwise simple graph.
  [.star.yellow] b
    (a)
```

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1661099327/tone-row-2021/wr77s2b8fvcbugjqlcgz.png"
  width="443"
  alt="Flowchart with Styles"
/>

✨ [You can open this example in Flowchart Fun](https://flowchart.fun/c#NoQwdARgNgrgpgXQAQBUAWBLAzk7SQB2ScAHgC4BOIA9hQCYYEgUZQCeSU1BA5pyBDhQkZNCDJIA7q2EAzLpKTcy1JAFtCHKIzg5CdJDChkMGskI4BjEDCxx8nahOqykaOMzIhL7pLNoimDhO7hTSdkhYpgAOUPY8VNFoYABQSEjAYFheFGBsQgrIEGnpSAAUIACUAD2AyaSANqQA3gBEBNR0cAAK1FEm3FjNAFwtIEMtJEMATJNgAMyTAOyTAAwAnIsAHACMk6tbqwBsADTNbEMALDOT58sHB+sbCwuHqwsHAL4nAHJb57JjzQmg32BzACw2AFYDstlpNZuclhtVhCTmdBucIWADhtZsstgtZlsIatlhsyed3pSgA)

## Not bad&hellip; could it be better?

This is how Flowchart Fun works today, but I’ve always felt it missed the opportunity of piggy-backing on a more well-known syntax: CSS Selectors.

Many people are familiar with `#` representing id’s, `.` representing classes, and being able to string them together to refer to specific elements in the DOM. Consider this alternative:

```plaintext
#a.blue This is an extraordinarily long label that will flow onto many lines and ultimately cause a lot of heartache for this otherwise simple graph.
  .star.yellow b
    (#a)
```

With that, we have something that looks a little more familiar! For my frontends, it may even remind you of [Pug](https://github.com/pugjs/pug) or [Jade](https://github.com/dscape/jade). The familiarity is already a win, but after staring at this revised syntax for a bit something else clicked.

## Storytime

Once upon a time, someone wrote to me asking how they could use the syntax to create Bayesian Decision Trees. Naturally, being a very intelligent smart person, I immediately knew what they were talking about- but in case you do not, some internet searching reveals that it's something like this:

<img
  src="https://i.stack.imgur.com/LP10c.jpg"
  alt="bayesian decision tree"
  width="443"
/>

The idea is that each edge stores a probability. Then, the probability of arriving at a node can be determined by walking up the tree and multiplying the edges on the way.

I built a crude version of this idea and eventually moved on, but one thing always stuck with me- **being able to associate arbitrary data to nodes and edges would be really powerful.** 🪄

## 💡

I eventually had the galaxy brain moment. CSS Selectors. Specifically, the attribute syntax for CSS selectors (i.e., `[key=value]`) is a known way to target- or in our case express- auxiliary data about a node.

```plaintext
#id.class1.class2[key=value][key2=value2] Node Label
```

Now, in addition to capturing the relationship between data points (nodes, edges) we can also store information about our data points; effectively storing tabular data. _Look ma, I'm a CSV!_

```plaintext
[population=12396372] São Paulo
[population=6775561] Rio de Janeiro
[population=3094325] Distrito Federal
[population=2900319] Bahia
[population=2703391] Ceará
```

<img
  src="https://media0.giphy.com/media/9V1F9o1pBjsxFzHzBr/giphy.gif?cid=ecf05e47kei7k1k05pxt7snqva7ip3fdb49enl3ss4ai3fgg&rid=giphy.gif&ct=g"
  width="443"
  alt="but wait, there's more"
/>

Taking it a step further, rather than just being descriptors, we could turn around and use our selectors the way Håkon Wium Lie (the myth, the legend, the inventor of CSS) originally intended: to **target** a set of nodes in our graph. For example:

```plaintext
.color red
.color blue
.color yellow

// create edges from node 'paintbrush' to 'red', 'blue', and 'yellow'
// with the label 'paints'
paintbrush
	paints: (.color)
```

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1661534823/tone-row-2021/okixel38w3rcmxmxrwd7.png"
  width="443"
  alt="Paintbrush Flowchart"
/>

## _Okay, and...?_

If you've read this far, then you're either great at procrastinating or you have the same burning passion for quirky domain-specific languages as I do. Either way, I promise I'm at the point.

This is what I think is cool about this— instead of just describing a flowchart, this syntax can be used to describe a ton of different types of data visualizations. It can be used to produce [bar charts](https://graph-selector-syntax.vercel.app/bar-graph), [area charts](https://graph-selector-syntax.vercel.app/tabular-data), or even [Sankey diagrams](https://graph-selector-syntax.vercel.app/sankey).

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1661536356/tone-row-2021/zhzjqdhrvvjnbyicglsc.png"
  width="443"
  alt="Sankey Diagram"
/>

We can even use the same document to produce multiple types of graphs to illustrate different properties of the data. Wowowow!

<img src="https://c.tenor.com/qAKRIiLIsXgAAAAM/cotton-candy-girl.gif" />

## A CSS-Inspired Syntax for Flowcharts?

Sure, why not! This is what I've done so far:

- created a [website of examples](https://graph-selector-syntax.vercel.app/)
- created a [repository](https://github.com/tone-row/graph-selector-syntax) with a parser

## What do you think? 👀

I'm really interested in getting some feedback, especially for these questions:

- What could people see this being used for?<br/>What other examples should I add to the site?
- I named the repo **Graph Selector Syntax**, but that's not very fun. Can anyone suggest a name?
- Should I migrate [Flowchart Fun](https://flowchart.fun) to this syntax?

Thank you for reading! Find me at [@tone_row\_](https://twitter.com/tone_row_) on Twitter


A CSS-Inspired Syntax for Flowcharts


At the time of this writing the number of themes available on [flowchart.fun](https://flowchart.fun) is 9.

In the beginning this was all she wrote:

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658171418/tone-row-2021/dxlxua8j70sh9ax5rbuf.png"
  alt="the original flowchart theme"
  width="500"
/>

Next came a <code>dark mode</code> theme because, you know, developers.

Around October of last year, 7 months after releasing the app, I realized having a variety of themes might be a good idea.

<div style={{ marginInline: "auto", width: 548 }}>
  <blockquote className="twitter-tweet" style={{ marginInline: "auto" }}>
    <p lang="en" dir="ltr">
      Today&#39;s feature is THEMES!
      <br />
      <br />I want users to be able to make more polished graphs faster – so
      I&#39;ve adding the concept of themes. <br />
      <br />
      The first 2 themes come from Light + Dark Mode. <br />
      <br />
      The 1st new theme reminds me of eggs 🍳🤷‍♂️
      <br />
      <br />
      What kind of theme should I add next?
      <a href="https://t.co/LNnfeg6jms">pic.twitter.com/LNnfeg6jms</a>
    </p>
    &mdash; Tone Row (@tone_row_)
    <a href="https://twitter.com/tone_row_/status/1445427386594598922?ref_src=twsrc%5Etfw">
      October 5, 2021
    </a>
  </blockquote>
  <script async src="https://platform.twitter.com/widgets.js" charSet="utf-8" />
</div>

Now the total is up to 9:&nbsp; 6 available to the public and 3 more to the sponsors. It's hard to know how I'm doing but the analytics suggest that all the themes are seeing at least _some_ use. That's good, no flops.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658173466/tone-row-2021/g4v2vs0vd78tmiltnqik.png"
  alt="theme usage by percentage of users"
  width="360"
/>

Still, it's difficult coming up with new themes. It's a combination of not knowing what my users want and being limited in what's visually possible that makes it difficult to design themes that are interesting and attractive without being too oddly-specific _(no shade to the beautiful [eggs theme](https://flowchart.fun/f#H4hQBcAsFMFtoFwAJoHNUGdQmKAKpAJYZICGADuUgO4D2ATgNYkBGAnkuG+YQHaqgkSAJK8AJtF7g+qJAGN60UuGglSSADZ9GnWpxjyArvUVTNfaILK8OKgB7hkLaADMG0MvNobaveYuVVTw1SZw0rAGEAlWDtJDFCRTlwDQ5DDBl9D2g7UmTNUOgNThzwKyEtRg8oYmQACgJiMkoaBmYkdk5uGQBKcqQAbTl08FpYEQARAF0kBn6hTtIxBP5rJABSAFYAIWEJrYnrMSRFF2hTOUyoZXmhcyr9WqQ64YxR8b2epAB6b6QATVohnkpD8pA0GD06Q8GX4GmgAFotLwPHIxvApFhvgAqUBzWCGDTSZGWNGwDHgLCgAASpAAbh4XIZeABCJCAHg3AJH7oGx31AQA)... I'm sure loads of people want a flowchart that reminds them of scrambled eggs)_

## Time to do my work for me, computer!

I finally got my invite to DALL-E 2 last week. In case you haven't heard of it, _"DALL-E 2 is a new AI system that can create realistic images and art from a description in natural language."_ You can check it out [here](https://openai.com/dall-e-2/).

After a healthy amount of generating portraits of my two cats in the styles of celebrated artists I started thinking, maybe I could use this as a tool for design... it's been a while since I've added any themes to flowchart fun. Los geht's!

## How do we know a good theme when we find it?

As I mentioned before, we're a little bit limited in the number of visual knobs we can turn to produce a theme. I thought it was a good idea to remind myself of the limitations before I started generating images. The list boils down to something like this:

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658196046/tone-row-2021/erpa2okcwisuxq3fuv7i.png"
  alt="theme options"
  width="500"
/>

So we're looking for something aesthetically interesting that **remains** interesting when boiled down to these 8 options. A tall order to be sure.

## Help me, DALL-E 2, you're my only hope!

I wasn't sure where to begin. I didn't want to ask for too much, so I started with <span className="dalle2">the most beautiful flowchart ever made</span>.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658238872/tone-row-2021/ircy5ow2xumhguhb6mlr.png"
  alt="the most beautiful flowchart ever made"
  width="500"
/>

That's not underwhelming at all. However, upon closer look there's a nice selection of accent colors and the graph is pretty legible. I dig it.

If I'm talking to a robot, maybe I should talk _like_ a robot. I tried <span className="dalle2">authentic design style of flowchart on internet application</span>

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658238872/tone-row-2021/mov2h5r68kvkxgm8dnnx.png"
  alt="authentic design style of flowchart on internet application"
  width="500"
/>

Well that's _something_. Returning to my original approach, I decided to get specific: <span className="dalle2">pretty flowchart with legible type and clear connections</span>.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658238872/tone-row-2021/pbobi6enmodqzkztkeng.png"
  alt="boxes of information and lines showing relationship"
  width="500"
/>

Look at you! I don't know who invited the swimlanes but the default hexagon shape 💯.

Then I was like, let's get Meta™. Instead of asking for a flowchart, what if I described a flowchart as if I were speaking to an alien. In that category we have <span className="dalle2">boxes of information and lines showing relationship</span> followed by the slightly better <span className="dalle2">organized nodes of textual information connected by lines</span>.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658238871/tone-row-2021/kmhuadvbhuqdwyww7qkb.png"
  alt="boxes of information and lines showing relationship"
  width="779"
/>

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658238871/tone-row-2021/cqhjmnb9hwj9fq6uvv24.png"
  alt="organized nodes of textual information connected by lines"
  width="779"
/>

These are fun, but given the styling limitations I don't think three-dimensional flowcharts or shallow depth-of-field blurs are in the budget.

It felt like I was getting off track so I decided to follow DALL-E's instructions and reference known artists. Sadly [Piet](https://en.wikipedia.org/wiki/Piet_Mondrian), [Maurits Cornelis](https://en.wikipedia.org/wiki/M._C._Escher), and even [Salvador](https://en.wikipedia.org/wiki/Salvador_Dal%C3%AD) let me down.

The next success was <span className="dalle2">glow in the dark flowchart</span>. The results were consistent and interesting. Definitely a candidate for a theme.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658241198/tone-row-2021/xqobzddivyarkq1kxfo4.png"
  alt="glow in the dark flowchart"
  width="779"
/>

Without being able to put my finger on _why_ the results for <strong>_glow in the dark_</strong> were so good, I continued without much success through the names of contemporary designers and then specific printed materials:

- _1940's cookbook flowchart_
- _1960's magazine ad with flowchart_
- _1980's newspaper ad with flowchart_
- ...and so on.

One place I've got to give DALL-E credit is the <span className="dalle2">soviet poster with flowchart</span>.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658242336/tone-row-2021/vuxg5a7qqpdfipypptx3.png"
  alt="soviet poster with flowchart"
  width="500"
/>

\*chef's kiss\*

## Okay, timeout.

After a couple days of trying I can't say I'm in love with the results so let's check in. DALL-E 2 excels with prompts like _"Tuxedo Cat in the style of Gustav Klimt"_&nbsp; but gets uncertain when asked for things like _"cyberpunk flowchart"_. Why? Let's look at how the model was trained. According to [this article](https://openai.com/blog/dall-e-2-pre-training-mitigations/#:~:text=In%20particular%2C%20DALL%C2%B7E%202,change%20what%20the%20model%20learns.) on OpenAI's website:

<strong>
  "DALL·E 2 is trained on hundreds of millions of captioned images from the
  internet, and we remove and reweight some of these images to change what the
  model learns."
</strong>

So in our first example (Tuxedo Cat Klimt), it's clear the model has seen enough captioned images of Klimt's work and enough images of a tuxedo cat to suggest both to us in one image. In fact, it isn't too hard to imagine that color palettes and localized geometric patterns are iconic to Klimt, whereas the shape, silhouette and posture help us identify an image of a cat. In other words, the identifying traits of our disparate subjects don't contradict each other.

A flowchart is a funky thing. It's not a physical object that has a distinctive global shape, like a cat. It's also not an artistic style, or something that can be described with a specific local affect, like a Klimt painting.

I keep returning to <strong>_glow in the dark flowchart_</strong> because in my mind it produced some of the best, most consistent results. It's like DALL-E's understanding of <strong>_glow in the dark_</strong> didn't conflict at all with its understanding of a <strong>_flowchart_</strong>, so it was able to express both in a complimentary way.

<div className="note">
  👋 Hey, this is a good time to mention that I am <strong>not</strong> a
  machine learning researcher. If you are (or even if you aren't) please forgive
  my "vibes" 🔮 interpretation of DALL-E. We do the best we can, alright pal!
</div>

Another interpretation is that <strong>_glow in the dark_</strong> had an answer for each of our 8 style parameters (colors, typography, line styles), but didn't have answers for the questions <strong>_flowchart_</strong> answered. What are some other phrases that might fit the bill, keeping in mind that we need to think in terms of image caption text?

&nbsp;<span className="dalle2" style={{textAlign: "center", display: "block" }}>retro flowchart</span>

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658249661/tone-row-2021/idth4pzeyrjaklgf9cui.png"
  alt="retro flowchart"
  width="779"
/>

&nbsp;<span className="dalle2" style={{textAlign: "center", display: "block" }}>futuristic flowchart</span>

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658249661/tone-row-2021/yj1vqzwsehkscz94zats.png"
  alt="futuristic flowchart"
  width="779"
/>

&nbsp;<span className="dalle2" style={{textAlign: "center", display: "block" }}>comic-book flowchart</span>

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658249661/tone-row-2021/srxxxfjcc0hwrigqjwyh.png"
  alt="comic-book flowchart"
  width="779"
/>

&nbsp;<span className="dalle2" style={{textAlign: "center", display: "block" }}>street art graffiti flowchart</span>

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658249662/tone-row-2021/qiu0ixhdspei3urppuoy.png"
  alt="street art graffiti flowchart"
  width="779"
/>

&nbsp;<span className="dalle2" style={{textAlign: "center", display: "block" }}>cartoon flowchart</span>

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1658250028/tone-row-2021/bvxk8djx78qphpsbni3e.png"
  alt="street art graffiti flowchart"
  width="779"
/>

These are perfect, but it's a leap forward in terms of consistency in colors, typography and shapes.

## Next Steps

Considering I'm getting inspiration for some flowchart themes and not saving the planet I think 2 days is probably long enough to deep dive into this. I'm going to pick several directions, convert them to themes, and then show the end result.

## [8 Hours Later]

It's a good thing I chronically underestimate how long things will take otherwise I would never attempt anything.

From the options above I chose three specific results to move forward with and built themes to mimic them as closely as possible.

<div
  style={{
    display: "grid",
    gridTemplateColumns: "minmax(0, 1fr) minmax(0, 1.73fr)",
    justifyContent: "center",
    justifyItems: "center",
    maxWidth: 800,
    marginInline: "auto",
    gap: "1rem",

}}

>

  <span className="slang-type size-2">DALL-E-2</span>
  <span className="slang-type size-2">Theme: retro</span>
  <img
    src="https://res.cloudinary.com/tone-row/image/upload/v1658324020/tone-row-2021/parggphsjr9acp9x1pjt.png"
    width="500"
    alt="retro flowchart inspiration"
  />
  <img
    src="https://res.cloudinary.com/tone-row/image/upload/v1658324675/tone-row-2021/m0lgzelcxhpby7maoxqm.png"
    width="500"
    alt="retro flowchart theme"
  />
</div>

<div
  style={{
    display: "grid",
    gridTemplateColumns: "minmax(0, 1fr) minmax(0, 0.845fr)",
    justifyContent: "center",
    justifyItems: "center",
    maxWidth: 800,
    marginInline: "auto",
    gap: "1rem",
  }}
>
  <span className="slang-type size-2">DALL-E-2</span>
  <span className="slang-type size-2">Theme: futuristic</span>
  <img
    src="https://res.cloudinary.com/tone-row/image/upload/v1658325009/tone-row-2021/relrkcpxgrrsey2lwhvf.png"
    width="500"
    alt="futuristic flowchart inspiration"
  />
  <img
    src="https://res.cloudinary.com/tone-row/image/upload/v1658325065/tone-row-2021/mvdvg5affmsd7njqo0yi.png"
    width="500"
    alt="futuristic flowchart theme"
  />
</div>

<div
  style={{
    display: "grid",
    gridTemplateColumns: "minmax(0, 1fr) minmax(0, 1.75fr)",
    justifyContent: "center",
    justifyItems: "center",
    maxWidth: 800,
    marginInline: "auto",
    gap: "1rem",
  }}
>
  <span className="slang-type size-2">DALL-E-2</span>
  <span className="slang-type size-2">Theme: comic-book</span>
  <img
    src="https://res.cloudinary.com/tone-row/image/upload/v1658325374/tone-row-2021/afwarjrqproeis7rg2kj.png"
    width="500"
    alt="comic-book flowchart inspiration"
  />
  <img
    src="https://res.cloudinary.com/tone-row/image/upload/v1658325333/tone-row-2021/pw03znnucoivwjmcvvub.png"
    width="500"
    alt="comic-book flowchart theme"
  />
</div>

I bumped up against various problems for each theme. Mainly choosing typography and the necessary accent colors.

## Takeaways

There is no doubt this was a roundabout approach and possibly a competitor for the "lengths people will go instead of hiring a designer" hall of fame.

Maybe no one will use any of these themes. Or, maybe users will instantly relate to and use these themes because they're made from traces of robot brains and internet ether. Only time will tell.

If there is anything that merits this long-winded exercise, it's that the line between what we deem creative work for humans and automatable work for machines is always drifiting in the direction of machines, i.e. creativity as it's traditionally thought-of is becoming more automatable, and because humans are cosmically-incapable of "doing less", we'll need to learn to be creative (whatever that means) _with_ more creative (whatever that means) machines at our disposal.

"Sir this is a wendy's"

Thanks for reading! You can try out these themes on [flowchart.fun](https://flowchart.fun/). Tell me what you think on twitter at [@tone_row\_](https://twitter.com/tone_row_).


Using DALL-E-2 as a creative tool to inspire new themes for flowchart.fun

New flowchart themes courtesy of DALL-E-2


[Vercel Serverless Functions](https://vercel.com/docs/concepts/functions) are an an indispensable tool for building apps on Vercel, and the only way to test them locally is with the CLI.

`vercel dev` works perfectly with Next.js and create-react-app, but recently I came across a strange bug when using `vercel dev` with my vite application.

Let's walk through the bug and then walkthrough the solution.

## The Bug

Imagine you have a vite app with client-side routing and a few routes deployed to Vercel, [like this one](https://routing-vite-vercel-serverless-miv42i8n3-tone-row.vercel.app/).

Navigating with the links works great, but if you try to load a page other than the index Vercel gets confused. Try going directly to the [about page](https://routing-vite-vercel-serverless-miv42i8n3-tone-row.vercel.app/about).

There's no file at `/about.html`, so instead we see an error from vercel.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1652373156/tone-row-2021/cunqqnyx6aqsasabacqu.png"
  width="443"
  alt="Vercel error"
/>

This is a common stumbling block for client-side routing. To fix it, we need to make sure any requests to our domain are redirected to `/index.html`. That way our application will load, which in turn loads our router, which in turn loads the correct page.

To do this on vercel we use a `vercel.json` file with the following contents:

```json
{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}
```

If we deploy this, we can now load our pages directly. [Try it out!](https://routing-vite-vercel-serverless-kiocsreua-tone-row.vercel.app/about)

## Vercel Dev

Now, instead of running your app locally with `yarn dev`, try running `vercel dev`.

You'll need to have have the [Vercel CLI](https://vercel.com/docs/cli) installed. The first time you run `vercel dev` you'll need to connect it to your deployment.

When you see something like this in your console you'll know it's running as intended.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1652376162/tone-row-2021/ie3qr750vh5aknker3dz.png"
  width="359"
  alt="Vercel dev running vite"
/>

However, when you visit the address on localhost, you'll see our app is broken! 😱

## What's the problem?

Using `vercel.json` to fix routing on our deploys breaks our routing locally. I reached out to Vercel about this problem. They confirmed it's an issue and they also said it wasn't on their roadmap to fix it.

But I love vite too much to give up!

## The Quick Solution

Rename `vercel.json` to `_vercel.json` then run `vercel dev` again and everything will be working.

For about a week I attempted to remember to keep `vercel.json` renamed locally– but to avoid committing that change so as not to break routing.

Lo and behold... I broke my app a few times. So then the question became: how can I prevent myself from accidentally committing the `vercel.json → _vercel.json` change?

## Git Hooks: The Sustainable Solution

If you’re not familiar with git hooks, they let you run code whenever you run git commands. They have names like “pre-commit” (i.e., before the code is committed) or “post-receive”, and they live inside your hidden `.git` directory along with all the other git guts.

My idea was to:

- Prevent `_vercel.json` from being committed using `.gitignore`
- Prevent the deletion of `vercel.json` from being committed by using a `pre-commit` hook:

The git ignore part is easy. We just add `_vercel.json` to the `.gitignore` file.

```bash
# Don't commit unused routing file
_vercel.json
```

For the pre-commit hook, we can add a small script in the root of our project called `prevent-delete.sh` (or whatever you like) with the following contents:

```bash
# Prevent deletion of vercel.json from being committed

#D       vercel.json
REGEXP="^D[[:space:]]+vercel.json$"

if git diff --cached --name-status | grep -qE $REGEXP; then
  git reset -- vercel.json
  exit 0
fi
```

This script looks for a line that starts with `D` and then checks if it contains `vercel.json`. If it does, it resets the file to its original state, which in our case is deleted but not staged.

We need to make sure our script is executable by git so we run:

```bash
chmod +x prevent-delete.sh
```

Then we create a symlink from the git hooks directory to our script. Note– Don't do this if your app is already setup with `husky`; see below.

```bash
ln -s ../../prevent-delete.sh .git/hooks/pre-commit
```

Now if we add all our changes with `git add -A` and run `git status` we can see that `_vercel.json` is being ignored, and the delete of `vercel.json` is staged to be committed.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1652377996/tone-row-2021/wrqprr2uifzjjzwsr23w.png"
  width="377"
  alt="Git status after add"
/>

But, when we run `git commit -m "Add prevent-delete.sh"` we get the following output:

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1652378121/tone-row-2021/oqaxkibbr4ft2qh12g89.png"
  width="356"
  alt="Git commit output"
/>

Success! If you check `git status` again you'll see that the deletion of vercel.json wasn't committed. We can safely push this code knowing the deployment vercel creates won't have broken routing because of a missing `vercel.json` file.

## If you are using husky

Many apps use [husky](https://github.com/typicode/husky) to automatically run git hooks. This is the recommended pathway for things like linting staged files.

If you're using husky, instead of symlinking the script, just run

```bash
npx husky add .husky/pre-commit "./prevent-delete.sh"
```

This will add the script to the `pre-commit` hook.

## In conclusion

That's it! Now you can `git add -A` and `git commit` to your heart's content without being worried about breaking your application. 🎉🎉🎉

Thanks for reading! If you have questions reach out to me on [Twitter](https://twitter.com/tone_row_)


Getting vercel dev to work with vite locally so serverless functions and client-side routing play nicely.

Vite, Vercel Serverless, and Client-Side Routing


The year was 2018. Assert Conference was held in the La Orilla Del Rio Ballroom in San Antonio, Texas. During one of the presentations, Ex-Paypal-Employee-Turned-Remix-Evangelist Kent C. Dodds presents a "Testing Trophy"; a spin off from a tweet by Guillermo Rauch.

The gist was simple: integration tests.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1625165663/tone-row-2021/kcd-testing-trophy.png"
  alt="Kent Dodds Testing Trophy"
  width="443"
  height="291"
/>

> ["It's so much faster to run a node process than to pull up a full browser and run that... hopefully that will get faster with our tools"](https://www.youtube.com/watch?v=Fha2bVoC8SE&t=796s)

_Hopefully..._

Fast forward to 2021. With deploy previews à la Netlify and Vercel, Github Actions, and Playwright we may be one step closer to E2E tests that are just as cheap as integration tests.

Let's assume we're working on a website or app hosted on netlify with deploy previews on pull-requests. [Here is an example application](https://github.com/tone-row/easy-e2e), forged in the flames of create-react-app, that stores some text in local storage.

<img
  src="https://res.cloudinary.com/tone-row/image/upload/c_crop,g_west,w_472/v1625166486/tone-row-2021/demo-app-gif.gif"
  alt="Demo App - user enters text and it's displayed"
  width="473"
  height="246"
/>

When I make PR's I end up with a fancy netlify preview like so:

<img
  src="https://res.cloudinary.com/tone-row/image/upload/v1625167916/tone-row-2021/netlify%20deploy%20preview.png"
  alt="Example netlify deploy preview"
  width="1254"
  height="570"
/>

## Goal

- grab the netlify preview url
- run some end-to-end tests with playwright
- sleep better at night!

## Step 1

We'll use a globally installed version of `playwright` so the only package we need to add to our repo is the test runner.

```shell
yarn add -D @playwright/test
```

## Step 2

Add an `e2e` npm script to run it.

```json
"e2e": "npx playwright test --browser=all e2e"
```

This is going to run any tests in our `e2e` folder in Chrome, Firefox, Safari.

## Step 3

Create the folder we referenced above and add one test file.

```bash
mkdir e2e && touch e2e/app.spec.ts
```

## Step 4

Let's test that our page has the correct title:

```tsx
// app.spec.ts
import { test as base, expect } from "@playwright/test";

const test = base.extend<{ url: string }>({
  url: process.env.E2E_START_URL ?? "http://localhost:3000",
});

const { describe, beforeEach } = test;

describe("App", () => {
  beforeEach(async ({ page, url }) => {
    await page.goto(url as string);
  });

  test("Correct Page Title", async ({ page }) => {
    const title = await page.title();

    // Replace this with your app's page title
    //                 ⤵
    expect(title).toBe("Save Some Text");
  });
});
```

We use `base.extend` to pass fixtures (in our case `url`) to each of our test runs.

## Step 5 – Test Locally

In one shell, start your app (`yarn start` for create-react-app).

In another shell, try `yarn e2e`. You may need to install some playwright dependencies the first time you run it, but you should see 3 tests run and pass.

For a little added spice, try `yarn e2e --headed`. This will open the browser window and give you some good insight into what the test runner does behind the scenes.

## Step 6 – Continuous Integration with Github Actions

If you don't already have any github actions running, create the directory `.github/workflows` in the root of your repo. Then add the following code a file called `e2e.yml`

```yaml
# .github/workflows/e2e.yml
name: E2E Tests

on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12.x
      - name: Setup Playwright
        run: npx playwright install-deps
      - name: Install
        run: yarn install
      - name: Waiting for 200 from the Netlify Preview
        uses: jakepartusch/wait-for-netlify-action@v1.2
        id: waitFor200
        with:
          site_name: "reverent-joliot-43ca55" # <-- replace with your site url
      - name: Run E2E Tests on Netlify URL
        run: E2E_START_URL="${{ steps.waitFor200.outputs.url }}" yarn e2e
```

If you haven't seen a github action before, this yaml file is saying, "On pull requests, run each of these steps in order". You can learn more about writing github actions [here](https://docs.github.com/en/actions).

Individual steps can actually reference other github actions. The magic ingredient of our e2e tests is an action created by [Jake Partusch](https://twitter.com/JakePartusch), which waits for and returns the netlify deploy preview url. Afterwards we store the url on an environment variable and run our end-to-end script.

Don't forget to change the `site_name` to your netlify site's ID. You can
find that by logging into netlify and looking at your project.

## Bada Bing Bada Boom

That's it! You should now be able to open up a pull requests on your app, and GitHub will run end-to-end tests on the netlify deploy preview url.

---

## Writing Better Tests

Obviously testing the page's title isn't going to give you much confidence in your app. Here are a few more tests I added to the demo app, to give you an idea of what playwright tests look like.

```ts
import { test as base, expect } from "@playwright/test";

type Fixtures = { url: string };

const test = base.extend<Fixtures>({
  url: process.env.E2E_START_URL ?? "http://localhost:3000",
});

const { describe, beforeEach } = test;

describe("App", () => {
  beforeEach(async ({ page, url }) => {
    await page.goto(url as string);
  });

  test("Correct Page Title", async ({ page }) => {
    const title = await page.title();
    expect(title).toBe("Save Some Text");
  });

  test("Displays user input", async ({ page }) => {
    await page.click("input");
    // Fill input
    await page.fill("input", "This is working");

    const display = await page.innerText("span.display");

    expect(display).toEqual("This is working");
  });

  test("Retains text on refresh", async ({ page }) => {
    await page.click("input");
    // Fill input
    await page.fill("input", "This is working");

    let display = await page.innerText("span.display");

    expect(display).toEqual("This is working");

    await page.reload();

    display = await page.innerText("span.display");

    expect(display).toEqual("This is working");
  });
});
```

One of the amazing features of playwright is the ability to generate code for your tests via the [codegen CLI command](https://playwright.dev/docs/cli#generate-code). You'll definitely want to have a look at that.

This tutorial was meant to be as bare-bones as possible, but if you think I left something important out please let me know on twitter ([@tone_row\_](https://twitter.com/tone_row_)) or for typos make a PR on [this article's source code](https://github.com/tone-row/tone-row.com/blob/main/content/e2e-ci-testing-netlify-playwright-github-actions/index.mdx).

Thanks for reading!


E2E continuous integration testing might be closer than you think! 😃

E2E Testing in Minutes with Playwright and Github Actions


I’m **really** proud of what [TRACTOR Food & Farms](/partnerships/tractor-food-and-farms) and Tone Row built together.

TRACTOR Executive Director [Dru Zucchino](https://tractorfoodandfarms.com/about-us/staff/) and I have been collaborating on creative projects since we were 14 years old. Now in our early thirties, we found an opportunity to collaborate on something- equally as creative- but that will help improve food ecosystems in Western North Carolina 🤯

I just patched up what I’m sure won’t be the last bug to creep into the machine, and while doing so I noticed that some of the food pantries had already begun entering the foods that work best for the people they serve. I immediately had a big grin on my face. This thing might actually work!

---

I'm really grateful that Dru conceived of and was willing to explore this app idea with me, and that TRACTOR was willing to invest the time and trust in Tone Row to design and build it.

It has already been an amazing learning experience, and I know there's only more to learn as it heads into production. I can't wait to get feedback from TRACTOR and the food pantries.

This is an awesome first partnership and I'm excited to see where it leads!

<div style={{ textAlign: "center" }}>
  [Read more about how the app works here](/partnerships/tractor-food-and-farms)
</div>


Our first non-profit partnership app is headed into production

Launching Healthy Harvest


Howdy!

Person here 👋

Been building websites since 2011. Been React'n since 2017 or so.

I want to make cool tools for people to use, like [flowchart.fun](https://flowchart.fun), and I want to make apps that help people, like the one I'm working on with [TRACTOR Food & Farms](/partnerships/tractor-food-and-farms).

Tone Row is an experiment in putting both of those pursuits under one roof.

This blog is a document of that experiment.

Thanks for visiting!


Creativity / Productivity

Nonprofit Partnerships

Blog

Connect