<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Fiona Hopkins on Medium]]></title>
        <description><![CDATA[Stories by Fiona Hopkins on Medium]]></description>
        <link>https://medium.com/@fionawhim?source=rss-30408d1a9c9------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*J5xY58uqhfmHfOlTThLDfg.jpeg</url>
            <title>Stories by Fiona Hopkins on Medium</title>
            <link>https://medium.com/@fionawhim?source=rss-30408d1a9c9------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 08:52:45 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@fionawhim/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Building a Tide Clock Weather Thing]]></title>
            <link>https://medium.com/@fionawhim/building-a-tide-clock-weather-thing-833acc945b5a?source=rss-30408d1a9c9------2</link>
            <guid isPermaLink="false">https://medium.com/p/833acc945b5a</guid>
            <category><![CDATA[making]]></category>
            <category><![CDATA[arduino]]></category>
            <category><![CDATA[crafting]]></category>
            <category><![CDATA[raspberry-pi]]></category>
            <category><![CDATA[laser-cutting]]></category>
            <dc:creator><![CDATA[Fiona Hopkins]]></dc:creator>
            <pubDate>Wed, 22 Aug 2018 02:09:26 GMT</pubDate>
            <atom:updated>2018-08-22T02:30:02.535Z</atom:updated>
            <content:encoded><![CDATA[<p>I built this thing! It’s a device for showing current temperature and weather conditions, as well as high temp, low temp, hourly forecast, and the low tides for the day.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FSy-2U57YTM8%3Ffeature%3Doembed&amp;url=http%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DSy-2U57YTM8&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FSy-2U57YTM8%2Fhqdefault.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/9dc4e5a31695f7e8fca1d85a8be6af30/href">https://medium.com/media/9dc4e5a31695f7e8fca1d85a8be6af30/href</a></iframe><p>I made this as a gift for my in-laws, who are watching the kids a ton this summer at their cottage in Maine. Up in Maine, one is only <em>approximately</em> interested in the weather: “Is it a good day to take the kids to the beach?” “When is the best time to take a kayak out?” “Can we have dinner at the picnic table or will it rain?”</p><p>So, this kinda shows the temperature, kinda what the weather will be, and kinda when the tides will happen. Which is perfect for summer vacation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*htG2GF8PfiO9TNaB" /><figcaption>Sunny all day, with highs in the upper 80s.</figcaption></figure><h3>What am I looking at exactly?</h3><p>I purposely didn’t include any instructions on the case. I’ll leave it to the reader to decide if that’s delightfully enigmatic or frustratingly inscrutable.</p><p>The large wheel is showing the current weather conditions on top. As they change, it rotates to bring a new icon to the top. The icon gears themselves rotate as they move. It looks cool. <a href="https://www.youtube.com/watch?v=Sy-2U57YTM8">Watch the video</a>.</p><p>The middle of that wheel has lights along the top to show the forecasted temperature range for the day. It runs in 5° increments from 30° to 90°, with 60° in the middle. The pointer points at the current temperature.</p><p>The five lights below the temperature gauge light up blue for impending rain, filling up to show when it’s 60, 45, 30, 15, or 5 minutes away.</p><p>Along the front are LEDs for each hour of the day, from midnight to 11pm. They show the forecast for each hour, with a color that’s equivalent to one of the “current conditions” icons. (Sunny is bright yellow, rain is blue. Partially sunny is sort of less yellow, and cloudy is dim white. Snow is kind of pink? The night ones are a bit dim blue and hopefully don’t get confused with rain. Windy is green, because what are even the options at that point.)</p><p>The bar right above the hours is pointing at when the two low tides of the day will occur.</p><h3>Building the device</h3><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FjAUcGrvoLBM%3Ffeature%3Doembed&amp;url=http%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DjAUcGrvoLBM&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FjAUcGrvoLBM%2Fhqdefault.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/691229a0c2de7341c133353355ae6ca6/href">https://medium.com/media/691229a0c2de7341c133353355ae6ca6/href</a></iframe><h3>Planetary gears</h3><p>The current conditions wheel is what’s known as a “planetary gear” arrangement. There is a center, “sun” gear, eight “planet” gears (with the icons), and an outer ring. When the ring gear rotates, the planet gears rotate and “orbit” the sun.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FsDQq5ULZEfg%3Ffeature%3Doembed&amp;url=http%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DsDQq5ULZEfg&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FsDQq5ULZEfg%2Fhqdefault.jpg&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/ff4660d6e4cea7c40b42cb7de5cf9b42/href">https://medium.com/media/ff4660d6e4cea7c40b42cb7de5cf9b42/href</a></iframe><p>I first stumbled upon planetary gears when putting together some <a href="https://community.glowforge.com/t/magic-the-gathering-life-tracker/25358">Magic: the Gathering life trackers</a>. There’s something really appealing about how the planets spin around and come back to line up. Ever since doing the counters I’ve been looking for more ways I could use these gears, and the weather icons seemed like a great chance.</p><p>All the weather data for this device comes from the <a href="https://darksky.net/">Dark Sky API</a>, which specifies a representative icon for the current conditions and each of its forecasts. There are actually ten different icons in the API, but I was worried that ten planets would be too small relative to the rest of the wheel. I therefore collapsed “sleet” into “snow” and “fog” into “cloudy” to bring the count down to eight.</p><p>Those <a href="https://thenounproject.com/acondiff/collection/weather/">weather icons</a> are by Austin Condiff from the Noun Project, used under a Creative Commons CCBY license.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*dhPMRiiARRpp7OG0" /><figcaption>Prototype to figure out how the planets need to be oriented so that they’re right-side-up when they reach the top.</figcaption></figure><p>The Woodgears.ca site (“an engineer’s approach to woodworking”) has a very useful <a href="https://woodgears.ca/gear/planetary.html">guide for calculating the right planetary gear ratios</a>. The outer ring has to have as many teeth as the sun gear plus two planet gears.</p><p>Since we also want the planet positions to line up consistently as they rotate, the ring teeth must be divisible by the number of planets.</p><p>That led me to use 64, 32, and 16 teeth for the ring, sun, and planets, respectively.</p><p>With the Magic counters, the ring gear is fixed (because you’re holding it) and the sun gear rotates with the pointer. For the tide clock, I decided to fix the sun—so that I could use it to show temperature information—and rotate the outer gear. To do that, I chose a stepper motor.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-ItizsuDz0Cq3eDkuE5bbw.jpeg" /><figcaption>Stepper motor, mount, and gear.</figcaption></figure><p>Stepper motors are motors—meaning they have a bit that spins around using electricity—but, unlike a traditional, two-wire brush motor, their electromagnetic coils are directly controlled from the outside. You move the motor forward and backward by powering them on and off in a specific sequence. With each of these steps the motor moves a very specific distance, which makes them very precise. You always know exactly how far you’re rotating in either direction.</p><p>Steppers share some similarities with servo motors, as both are used for accurate positioning, but servo motors can only position within a 180° arc. They can’t go around and around. (“Continuous rotation” servo motors <em>can</em> go around and around, but you only have control over their speed, not their position.)</p><p>The stepper motor I used takes 1024 four-sequence steps for a revolution, so if I know what the current icon is, I can move exactly to any other icon just by going a certain number of steps. 384 per icon, it turns out; consistently using powers of two in the gears helped out.</p><p>My biggest regret with the design of this device is that you don’t actually see the wheel moving all that often. Weather conditions just aren’t that fluid. I ended up adding a feature to rotate the wheel all the way around (back to the same icon) at the top of every hour just to show it off.</p><p>In retrospect, I also wish that I had kept the spokes behind the wheel. You can see them one of the prototypes in the development video. They highlight how the ring and icons are moving at different rates. I axed them because they were getting in the way of the back of the temperature display mechanism, but they did look cool.</p><h4>The tide indicator</h4><p>Showing accurate tides was the impetus for making this device. I had it in mind to replace a flaky, hard-to-set, hard-to-read tide clock I had given as a present a few years ago. I initially started out with very ambitious goals on this front.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*_4KxsQrBQW7CldCu" /><figcaption>MDF prototype of the final tide indicator mechanism.</figcaption></figure><p>I wanted to not only visualize both low <em>and</em> high tides for a day, but to control those four indicators independently. On the East coast, tides only <em>average</em> a 12h 25m cycle. The actual time between tides can be up to a half an hour in either direction. I could one-up that other tide clock by having per-tide precision, based on up-to-date tide forecasts from the NOAA.</p><p>Unfortunately, as I worked through the design, I ran into trouble getting everything to fit, given my materials and constraints. Not only would the servos and their gears take up a lot of space, it was a challenge to devise a system so the gear racks wouldn’t bump into each other or stick off the side. Every surface having a fixed thickness of 3.3mm didn’t make it any easier.</p><p>In the end, I pared the tides down to the bare minimum. As fun as a servo party would be, it would also be fragile. And really, at this scale, and at the vague way the hours are marked, there was no way someone could notice a 15 minute difference in where the arrow pointed (if the servo could be that accurate anyway). A single servo with a fixed 12h 25m interval was definitely good enough for vacation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*dGgsr5dkNCRoBTaI" /><figcaption>Iterations on driving the gear rack for a tide indicator. Top: an indicator for a 12 hour range. You can imagine how the rack would stick off the edge as the indicator moves to the right. Bottom: Prototype for putting the drive gear on the top of the box. My goal was to have the indicators then dangle over to point at the hour track.</figcaption></figure><p>The first thing I had to consider when making this work was that servo motors only give you 180° of motion. Without the added complexity of a gear train, which I was trying to avoid, that meant that the linear distance I could move a gear rack was half the circumference of whatever gear was attached to the motor.</p><p>This meant that the drive gear had to be pretty big, with a diameter of almost a third of the width of the hour track (around or about 31.415%, you might say). At the same time, the gear rack had to be driven from the center so that it could have an equal range of motion in each direction without hanging over either edge. I put the drive gear off to the right, to visually balance (and stay out of the way of) the big wheel, then centered a smaller gear that could directly move the rack.</p><p>Putting the gear flat on top would have been a neat effect, and I prototyped it, but laser-cut gears don’t mesh well at 90° angles. That would be an interesting problem to try and solve on a future device.</p><p>Looking at the end result, I actually did end up with the gear train I was trying to avoid, because I needed to transfer the motion sideways to the center, and then also from the middle of the box to the front. Nevertheless, I like the look of the large drive gear. I still would have liked to have included the high tide, but I ran out of time to figure out how it would fit.</p><h4>Designing the parts</h4><p>The case and gears and everything are all made on my <a href="https://glowforge.com/">Glowforge</a>. I prototyped with Proofgrade <a href="https://shop.glowforge.com/products/medium-draftboard?taxon_id=52">Draftboard</a> MDF, and the final project is <a href="https://shop.glowforge.com/products/medium-cherry-plywood-finished">medium cherry</a> and <a href="https://shop.glowforge.com/products/medium-maple-plywood-finished">medium maple</a> plywood.</p><p>I made all the plans in <a href="https://inkscape.org/en/">Inkscape</a>, a free, open source, SVG-native vector editor. Inkscape has a lot of good tools for manipulating vector shapes, joining paths together, arranging things, and doing precise measurement and positioning.</p><p>Inkscape has a built-in plugin to generate spur gears (that’s what I used for the Magic trackers), but for this project I relied on the <a href="https://github.com/jnweiger/inkscape-gears-dev">inkscape-extensions-gears-dev</a> plugin. It has better controls and slightly nicer-looking teeth, and could handle making both the ring gear and the gear rack.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8_wK1KsToOaElQ8m924h-Q.jpeg" /><figcaption>Top-down view shows the TrayLayout dividers supporting the motors.</figcaption></figure><p>For the case, I started with a custom “TrayLayout” built with the excellent <a href="https://www.festi.info/boxes.py/index.html">boxes.py</a> site. This gave me an outside box and two dividers running from left to right. I took those basic shapes into Inkscape, where I modified them to support the motors and gears by adding holes and extending parts of them upwards.</p><p>I did do a little bit of visualization in Fusion 360, and also threw together a scale model in cardboard to get a sense of the size. Laser cutting MDF is fast and fairly cheap, though, so most of my prototyping was done with that.</p><h3>Technical implementation</h3><h4>Brains of the device</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jUXY1gVoN2B0xYxRaekwlw.jpeg" /><figcaption>Speaker pHAT with the Raspberry Pi W underneath. To the right is the Darlington array that drives the stepper motor.</figcaption></figure><p>Driving this whole thing is a <a href="https://www.raspberrypi.org/products/raspberry-pi-zero-w/">Raspberry Pi Zero W</a>. Raspberry Pis are tiny computers that boot off of micro SD cards and can run Linux. Unlike the flagship Raspberry Pi, the Zero line does not have full-size HDMI or USB ports or any size Ethernet port, and it has a slower chip and half the memory. But by giving those up it can come in at a smaller size and a $10 price point. The Zero W does still have wi-fi, which was necessary.</p><p>The software on the Pi is a Python script that runs as a service on startup. It periodically queries for weather and tide data, and then controls the various outputs to display that information.</p><p>At my spouse Cait’s suggestion, I added chiming for when the high and low tides happened. The Zero W unfortunately does not have any direct audio out, however. I considered using <a href="https://learn.adafruit.com/adding-basic-audio-ouput-to-raspberry-pi-zero/overview">this guide</a> to get audio from the Pi’s pins, but in the end I bought a <a href="https://shop.pimoroni.com/products/speaker-phat">Pimoroni Speaker pHAT</a> because I knew it would just work.</p><h4>Controlling the lights</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YEwXJVVSwLU02SJGUwxyGw.jpeg" /><figcaption>The Raspberry Pi (back left) connected to the Trinket (right) to control the NeoPixels and servo of a prototype temperature display. Thing on the left of the breadboard is a level shifter to bring the Trinket’s 3.3v output up to the 5v that NeoPixels require.</figcaption></figure><p>Because it’s running Linux, a non-realtime operating system, the Raspberry Pi can’t control the <a href="https://learn.adafruit.com/adafruit-neopixel-uberguide/">NeoPixel</a> LEDs that I’m using. NeoPixels are RGB LEDs that are all chained together with just 3 wires (5v, GND, and data), but you can control the colors of each of them individually. The protocol for communicating those colors has very precise timing requirements that require a microcontroller.</p><p>I turned to the <a href="https://www.adafruit.com/product/3500">Adafruit Trinket M0</a>, a very small and inexpensive microcontroller, to serve as a NeoPixel-driving breakout board for the Pi. I also ended up hooking the servos up to it as well. Using the <a href="https://www.arduino.cc/en/Reference/Wire">Wire</a> Arduino library I was able to make the Trinket into an <a href="https://learn.sparkfun.com/tutorials/i2c">I2C</a> device that the Pi could talk to. I wrote a simple protocol with commands to set pixel colors and servo positions.</p><p>If I needed something similar in the future, I would use an Arudino Nano (or cheap knockoff equivalent) instead of the Trinket. Nanos run natively at 5v, eliminating the need for a level shifter.</p><h4>Data from the cloud</h4><p>I wanted to be defensive against API changes from the data providers, so I wrote a quick server to go between them and the client running on the device. You can <a href="https://glitch.com/~pi-weather">check it out on Glitch</a>, though it’s not a whole lot to look at.</p><p>The weather data is from the very nice (and free for the minuscule traffic I’m using) <a href="https://darksky.net/dev">Dark Sky API</a>. Tide data comes from the NOAA’s <a href="https://tidesandcurrents.noaa.gov/">Tides and Currents site</a>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kuj4dYQIjP-TIUPDKLuFgg.jpeg" /><figcaption>This happened a lot during final assembly.</figcaption></figure><h3>Miscellaneous lessons learned</h3><ul><li><strong>Wander around, but then step back.</strong> I had a great time iterating on the design and features of this, going where it led me, but I didn’t always look at where I ended up. For example, when I was going to have five servos I knew I needed a separate servo breakout board. When that went down to two I was still thinking “breakout board” and so I put them on to the Trinket. Nevertheless, the Raspberry Pi can control two servos by itself with hardware PWM. I just didn’t think to go back to it.</li><li><strong>Wax is really good for gears.</strong> I was able to eliminate a lot of friction by waxing the planetary gears and the tide indicator. Thanks to members of the Glowforge community for pointing out that crayons are an excellent source of wax.</li><li><strong>LEDs take electricity.</strong> Right towards the very end, the Raspberry Pi started acting kooky. I thought that I might have fried it by accidentally shorting something when I was doing final wiring, but I swapped it out for another Pi and the problem persisted. My problem ended up being that I had all 48 of the LEDs on full blast to do a wiring test. This was using so much of the power supply’s power that the poor Pi was browning out. When I reduced the LEDs to the reasonable brightness I actually wanted, the problem went away.</li><li><strong>Save space for the wires.</strong> I went by the measurements of my circuit boards to design the case, but didn’t make enough accounting for the wires. I ended up having to custom crimp all of the jumper wires just to fit the lid on. Making it ¾” taller and deeper would have saved a lot of work, and would not have been noticeable.</li><li><strong>Time is money.</strong> Sometimes it makes sense to just buy an off-the-shelf solution that will save not-fun effort. (<em>Fun</em> effort is what hobbies are all about, of course.) For example, my original plan was to use individual NeoPixels for the temperature range. I could get 10 of them for just $6! I got as far as connecting two together before I realized that soldering 5mm jumper cables on to surface-mount components was going to be a giant fragile pain in the ass. Since my goal was to put them in an arc anyway, I swallowed my pride and bought the <a href="https://www.adafruit.com/product/2861">24 pixel ring</a>. It worked great, will hold up better, and with more LEDs I was able to go from 10° increments to 5° increments, and add in the rain indicator.</li><li><strong>Servos are pretty fragile.</strong> Especially the cheap micro servos I was using. I think I stripped two of them on the tide indicator, since during testing it kept getting set to a position farther than the gear rack would go. It’s worth tweaking your program to make it move gently.</li><li><strong>I should learn about tools and stuff. </strong>Right now I’m doing everything with the laser, and what I can’t friction-fit I’ve been gluing down. I’d like to consider doing more woodworking in my designs to achieve things that a laser cutter alone can’t do.</li><li><strong>Hot glue comes off with rubbing alcohol. </strong>And Krazy Glue comes off with acetone.</li><li><strong>Adafruit is the best. </strong>Their stuff can be on the pricey side (especially compared with getting generic components directly from China), but what you’re paying for is quality, reliability, documentation, fast delivery (next day UPS Ground to Cambridge!) and supporting a cool small business that supports the creativity and education.</li></ul><p>So that’s my thing! It was a ton of fun to make and kept me very busy in the evenings and weekends for a few weeks. I learned a lot about the practical side of putting electronic components together into a project.</p><p>I’ve got some more devices planned, so keep an eye out here for future posts.</p><p>Oh, and if you want a Glowforge for yourself, you can get a small discount (and send me a kickback) by using my <a href="https://glowforge.us/1MR4or">referral link</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=833acc945b5a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Deciphering TypeScript's React errors]]></title>
            <link>https://medium.com/innovation-and-technology/deciphering-typescripts-react-errors-8704cc9ef402?source=rss-30408d1a9c9------2</link>
            <guid isPermaLink="false">https://medium.com/p/8704cc9ef402</guid>
            <category><![CDATA[jsx]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[typescript]]></category>
            <category><![CDATA[react]]></category>
            <dc:creator><![CDATA[Fiona Hopkins]]></dc:creator>
            <pubDate>Thu, 28 Jun 2018 15:23:36 GMT</pubDate>
            <atom:updated>2019-05-02T17:07:59.476Z</atom:updated>
            <cc:license>https://creativecommons.org/publicdomain/mark/1.0/</cc:license>
            <content:encoded><![CDATA[<h3>Deciphering TypeScript’s React errors</h3><p>Static type checking is one of my favorite engineering guard rails, which is why I made adopting a typechecker a priority when <a href="https://medium.com/innovation-and-technology/bringing-death-certificates-to-life-with-agile-tools-dcb0174cdc1a">choosing the toolset</a> for webapp development on the <a href="https://www.boston.gov/digital">City of Boston’s Digital team</a>.</p><p>Static type checking de-risks software maintenance, since it reveals places where you need to update code to accommodate changes you’re making. It’s equally good for new development since, with good editor support, it ensures you’re calling functions that exist and are giving them the arguments they expect.</p><p>But, last Friday, I got a DM from my co-worker John, who has been writing some React components:</p><blockquote>I hate those errors, I was going to say dislike but naaaaahhh I hate them lol</blockquote><p>John’s a recent bootcamp grad, working with me for the summer as a fellow. He’s also super-chill, so seeing this strong reaction really woke me up.</p><p><em>I had thrown John into a type-checking world without preparation.</em> He fell victim to a <strong>paradox of guard rails</strong>: it can take more effort to deal with a checker’s “helpful” error messages than it would ever be to debug the problems it’s warning you against.</p><p>The combination of React, JSX, and the DOM make for some hairy TypeScript types. When TypeScript complains, its error messages are verbose, with a lot of names you don’t recognize from your own code. So, for John and everyone else new to this environment, I present my guide to decoding your React / TypeScript error messages.</p><p>(You might notice that the Registry webapp was written with <a href="https://flow.org/">Flow</a>. For new development we’re working in <a href="https://www.typescriptlang.org/">TypeScript</a>.)</p><h3>Why even typecheck React?</h3><p>Let’s see what we hope to get out of using TypeScript with React in the first place. When things go smoothly, we’ll be catching these bugs:</p><ul><li>Trying to pass a prop that a component doesn’t want</li><li>Forgetting to pass a prop that a component requires</li><li>Getting a prop’s type wrong, such as passing a string when it expects a number</li></ul><p>If we write these bugs, TypeScript will show an error in our editor right away. Without TypeScript, we’d have to catch these bugs later during testing, and it might be tedious debugging to figure out where they come from.</p><p>(Whether or not it’s worth it to use a tool to catch these bugs is a question for your team. I find it valuable, which is why we’re here.)</p><h3>Errors with DOM elements</h3><p>For starters, let’s look at using standard DOM elements in JSX. TypeScript will check to make sure that every attribute you put on an HTML tag exists and is of the right type. For example:</p><pre>render() {<br>  return &lt;input type=&quot;text&quot; name=&quot;color&quot; /&gt;;<br>}</pre><p>The above React/JSX code type checks fine, because &lt;input&gt;s have both type and name attributes! You won’t see any errors. TypeScript can do this because there’s a React library (@types/react ) that defines all HTML elements and what attributes they each take.</p><p><strong>Note:</strong> In this guide I use “attribute” and “property” pretty much interchangeably. “Attribute” is what they’re called in HTML, but on React components they’re “props.” And, when they’re on a JavaScript Object, TypeScript calls them “properties.”</p><h4>Using a property that doesn’t exist</h4><p>Now let’s mis-spell “name” and see what happens:</p><pre>render() {<br>  return &lt;input type=&quot;text&quot; <strong>nmae</strong>=&quot;color&quot; /&gt;;<br>}</pre><p>If you have TypeScript support in your editor, you should get a red underline on that line, and the following error message:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XDmLfWXuRKhTkjFjV9HjuQ.png" /><figcaption>“Property ‘nmae’ does not exist on type ‘DetailedHTMLProps&lt;InputHTMLAttributes&lt;HTMLInputElement&gt;, HTMLInputElement&gt;’”</figcaption></figure><p>That looks a little daunting, but we can break it down piece-by-piece:</p><ul><li>Property &#39;nmae&#39; — The “properties” are the attributes on the &lt;input&gt; tag. So this error is about “nmae=”…&quot;”.</li><li>does not exist on type — There’s a “type,” a definition somewhere of what is allowed to be on &lt;input&gt;, and “nmae” isn’t on the list.</li><li>&#39;DetailedHTMLProps&lt;InputHTMLAttributes&lt;HTMLInputElement&gt;, HTMLInputElement&gt;&#39; — OK, this is a doozy. This describes how TypeScript thinks of&lt;input&gt;’s attributes. All of these names (DetailedHTMLProps, InputHTMLAttributes, and HTMLInputElement) are defined in that React library. DetailedHTMLProps means attributes that any HTML element can have (like id, tabIndex, and style) and InputHTMLAttributes are for ones specific to &lt;input&gt; elements ( name, value, <em>&amp;c.</em>). This is boilerplate you can typically gloss over, but the HTML***Element part can be a useful clue in deciphering this.</li></ul><p><strong>The fix: </strong>When you see “Property XXX does not exist on type,” it means you’re adding an XXX=&quot;…&quot; to an element that doesn’t want an XXX on it. While that is not itself a problem—the element would just ignore attributes it doesn’t recognize—it’s usually a sign of a bug. In this case, it’s not a problem to add a nmae, but it is a problem that we <em>thought </em>we were adding a name but didn’t actually.</p><p>When you see this, check for typos, and check the HTML docs to make sure you’ve got the attribute or element right for what you’re trying to do.</p><h4>Getting a property’s type wrong</h4><p>There’s another error that can come up with HTML: using the wrong type for an attribute. Let’s add a size to the &lt;input&gt; and see what happens:</p><pre>render() {<br>  return &lt;input type=&quot;text&quot; name=&quot;color&quot; <strong>size=&quot;6&quot;</strong> /&gt;;<br>}</pre><p>This is exactly how you’d write it in an HTML page, but TypeScript shows an error:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mEy2LH0UmjN17kSsm64chw.png" /><figcaption>Types of property ‘size’ are incompatible. Type ‘string’ is not assignable to type ‘number | undefined’.</figcaption></figure><ul><li>Types of property &#39;size&#39; are incompatible. — We’re talking about size now. Note how it says “types” with a plural. That’s because <em>all type errors are </em><strong><em>inconsistencies</em></strong><em>.</em> This error is between two types: the one from our code, and the one from React’s &lt;input&gt; definition (remember theDetailedHTMLProps&lt;…&gt; bit we saw in the last error).</li><li>Type &#39;string&#39; — This is the first of the types, the one for the argument that we wrote. &quot;6&quot; <em>is</em> a string, because <em>all</em> quoted JSX attributes are strings.</li><li>is not assignable to— This is a nuanced way of saying “isn’t.” It’s clarifying what is “incompatible” about the two types.</li><li>type &#39;number | undefined&#39; — This is the second of the two types, the one that the React library said is right for &lt;input&gt;’s size attribute. The | is known as a “union” operator, but you can read it as “or”: “size must be a number or undefined.”</li></ul><p><strong>The fix:</strong> We need to change one or the other of the types to make them consistent. Since we can’t change the React library to accept a string, we have to change our code to pass a number:</p><pre>render() {<br>  &lt;input type=&quot;text&quot; name=&quot;color&quot; size={6} /&gt;<br>}</pre><p>Remember that {} is the way to make a JavaScript expression in JSX. Now instead of a string, we’re providing a number, and the TypeScript error goes away.</p><p>The error message said that the type from the React library was &#39;number | undefined&#39;. “Undefined” is the same as leaving it off, which is why our previous examples typechecked without a size. But this explains why the error message said “is not assignable to” instead of “isn’t.” 6 is a number, not a “number or undefined.” But, a number is <em>assignable</em> to a “number or undefined,” because of the “or.”</p><p>The React type library doesn’t require any attributes on HTML elements, so there’s no “forgetting to pass a prop that a component requires” error in this section. That will come up when we deal with custom components.</p><h3>All type errors are inconsistencies</h3><p>I mentioned this above in the breakdown of the size bug, but it’s an important enough concept that I want to call it out:</p><blockquote><em>All type errors are </em><strong><em>inconsistencies</em></strong><em>.</em></blockquote><p>What I mean by this is those red TypeScript squiggles are there because one part of your code doesn’t agree with another part. Which part is right? Your job is to figure that out by thinking about what you’re trying to make your code do.</p><p>One of the reasons that type errors can be confusing to interpret is that TypeScript will only underline <em>one </em>of the places where the inconsistency is happening. The first example below is an error where TypeScript calls out something in the JSX, but that part is actually right and it’s the type definition that we decide is wrong.</p><h3>Errors with custom React components</h3><p>The principles of typechecking custom components are basically the same as DOM elements, but the names of the types get more confusing.</p><p>For this section, we’ll use the following sample component:</p><pre>class CustomInput extends React.Component {<br>  render() {<br>    return &lt;input /&gt;;<br>  }<br>}</pre><h4>Using your own props</h4><p>Say we’re using this to build a form, so we need to pass in a name that can go on that &lt;input&gt;. In React, that means adding a prop. Here’s the new render method:</p><pre>render() {<br>  return &lt;input <strong>name={this.props.fieldName}</strong> /&gt;<br>}</pre><p>Which might get used by another component like this:</p><pre>render() {<br>  return (<br>    &lt;form&gt;<br>      &lt;CustomInput fieldName=&quot;colorField&quot; /&gt;<br>    &lt;/form&gt;<br>  );<br>}</pre><p>Seems straightforward, and in plain JavaScript this case would totally work, no bugs. But TypeScript has found something to complain about:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*a3gaehQXBm739VbNZ1sDQw.png" /><figcaption>Property ‘fieldName’ does not exist on type ‘Readonly&lt;{ children?: ReactNode; }&gt; &amp; Readonly&lt;{}&gt;’.</figcaption></figure><ul><li>Property &#39;fieldName&#39;— We saw this language before with the &lt;input&gt;’s nmae attribute, but now it’s referring to a “property” on the this.props object, rather than one on an HTML tag.</li><li>does not exist on type — This is also the same language. TypeScript has an opinion about what properties are and are not on this.props, and fieldName is in the “not” pile.</li><li>&#39;Readonly&lt;{ children?: ReactNode; }&gt; &amp; Readonly&lt;{}&gt;&#39;— OK, this is hard to read. This is the type that TypeScript thinks of when we say this.props.</li></ul><p>That last bit needs a more detailed explanation:</p><ul><li>The Readonlys mean that you can’t change this.props. You shouldn’t be doing that with React, so TypeScript enforces it.</li><li>{ children?: ReactNode; } is there because all React components <em>can</em> have a this.props.children value. ReactNode is anything that React knows how to render: strings, components, and so on. The ? means that this property is optional—you don’t need to pass children to CustomInput.</li><li>&amp; in TypeScript makes an “intersection” between two types, which is kind of like an object that has all the properties from each of them merged together. So, this.props has a type that’s made up of all the properties of { children?: ReactNode; } combined with all the properties of {}. Which doesn’t have any.</li></ul><p>That comes together to mean that this.props has an optional children property, but no fieldName property.</p><p><strong>The fix:</strong> To fix this, we actually have to make a choice. Say it with me now:</p><blockquote><em>All type errors are </em><strong><em>inconsistencies</em></strong><em>.</em></blockquote><p>Two things don’t agree. In your render method you’re trying to use this.props.fieldName. But when you declared your component, you didn’t give it a fieldName prop. Which is right? The render method or the component declaration?</p><p>With DOM elements, we knew that the expected attributes were correct because they came from a library we trust. But this is our own code, so it’s up to us to pick what to change to make the error go away. That means either stop trying to use this.props.fieldName, or add fieldName to our component’s declaration.</p><p>By default, all React.Components have a this.props type of {}, which we saw in the &amp; statement in the error. Since we really do want to have a fieldName prop, we have to add it:</p><pre><strong>interface CustomInputProps {<br>  fieldName: string;<br>}</strong></pre><pre>class CustomInput extends React.Component<strong>&lt;CustomInputProps&gt;</strong> {<br>  render() {<br>    return &lt;input name={this.props.fieldName} /&gt;;<br>  }<br>}</pre><p>What’s going on here? We start with interface, which is how we make a new “object type” in TypeScript. We’re saying that any object of type CustomInputProps must be “an object with a fieldName property, which must be a string.”</p><h4>Aside: Why are we talking about object types?</h4><p>CustomInputProps is an object type, which means that it describes the “shape” of a JavaScript object. For example:</p><pre>const obj: CustomInputProps = {<br>  fieldName: &#39;myInput&#39;,<br>};</pre><p>That’s a const called obj, and : CustomInputProps tells TypeScript that its value needs to match the CustomInputProps shape. We initialize it with an object literal that has the necessary fieldName property, so it typechecks!</p><p>Let’s leave off the fieldName property and see what happens:</p><pre>const obj: CustomInputProps = <strong>{}</strong>;</pre><p>{} doesn’t match CustomInputProps, so here’s how TypeScript complains:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*L04lT463InLLj3gWGt1sWA.png" /><figcaption>Type ‘{}’ is not assignable to type ‘CustomInputProps’. Property ‘fieldName’ is missing in type ‘{}’.</figcaption></figure><ul><li>Type &#39;{}&#39;— This is TypeScript describing the type of the value that we’re trying to assign to obj: an object with no fields.</li><li>is not assignable to— Our old friend “is not assignable to.” We’re trying to make an assignment: assigning {} to obj, but TypeScript is saying we can’t do it.</li><li>type &#39;CustomInputProps&#39;.— This is here because it’s what we declared obj to be. Therefore it’s the type that’s being assigned <em>to</em>.</li><li>Property &#39;fieldName&#39; is missing in type &#39;{}&#39;.— Now TypeScript is being specific about why an object of type {} is not assignable to something of type CustomInputProps: There’s no fieldName, and, because of the interface declaration from above, all CustomInputProps objects must have a fieldName.</li></ul><p>Now let’s see what happens when we put back fieldName, but also add a field that’s not part of the CustomInputProps type:</p><pre>const obj: CustomInputProps = {<br>  fieldName: &#39;myInput&#39;,<br>  <strong>placeholder: &#39;Type something here&#39;,</strong><br>};</pre><p>That’s not allowed:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4yxfnrzn640KhdGX33YxWw.png" /><figcaption>Type ‘{ fieldName: string; placeholder: string; }’ is not assignable to type ‘CustomInputProps’. Object literal may only specify known properties, and ‘placeholder’ does not exist in type ‘CustomInputProps’.</figcaption></figure><ul><li>Type &#39;{ fieldName: string; placeholder: string; }&#39;— This is the new type of our object literal. See how it now has the placeholder property.</li><li>is not assignable to type &#39;CustomInputProps&#39;. — Same as before. TypeScript thinks this assignment is illegal.</li><li>Object literal may only specify known properties, and &#39;placeholder&#39; does not exist in type &#39;CustomInputProps&#39;. — This is the explanation for why this case is “not assignable.” CustomInputProps doesn’t have a placeholder property declared in its interface block.</li></ul><p>This is a similar case to when we put nmae on an &lt;input&gt;. Adding the extra placeholder property is not in itself a bug, since code working on CustomInputProps would ignore it, but it’s a <em>sign </em>that there’s probably a bug.</p><p>Back to why we’re even talking about object types in the first place. What do they have to do with React props? Objects have {} squiggly braces, not the &lt;&gt; angle brackets of JSX. To explain this, let’s go back to our DOM element example and talk a bit about JSX.</p><pre>&lt;input name=&quot;color&quot; size={6} /&gt;</pre><p>Browsers can’t understand this JSX on their own, they only understand plain JavaScript. We typically use the TypeScript compiler or a tool like <a href="https://babeljs.io/">Babel</a> to take the JSX and make JavaScript out of it. Here’s what that code looks like as JavaScript:</p><pre>React.createElement(&#39;input&#39;, {<br>  name: &#39;color&#39;,<br>  size: 6,<br>});</pre><p>Hey, those name=&quot;color&quot; and size={6} attributes are an object literal now! The first argument to createElement is what we’re creating—a class for custom components, a tag name for HTML elements—and the second argument are the props to pass to it.</p><p>This is why TypeScript is always talking about props as object types. When it type checks the React code, it makes sure that that second argument to createElement has a type that matches (“is assignable to”) the declared type of the component’s props.</p><p>(Because it just transforms things into plain JavaScript, JSX is sometimes referred to as “syntactic sugar.” It’s not actually necessary—we could write those createElement statements ourselves—but it makes the code sweeter.)</p><h4>Now back to declaring props types</h4><p>Let’s remember where we were:</p><pre><strong>interface CustomInputProps {<br>  fieldName: string;<br>}</strong></pre><pre>class CustomInput extends React.Component<strong>&lt;CustomInputProps&gt;</strong> {<br>  render() {<br>    return &lt;input name={this.props.fieldName} /&gt;;<br>  }<br>}</pre><p>Now that we’ve declared the interface we want—the “shape” of our component’s props—we need to actually tell TypeScript to use it for CustomInput. That’s where the theReact.Component&lt;CustomInputProps&gt; comes in. The &lt;…&gt; bits let us pass a <em>type parameter</em>. Think of it as a way of tweaking React.Component, kind of like how you use (…)s to pass arguments to functions. ReactComponent uses its first type parameter as the type for this.props, replacing the default {}.</p><p>We can go back to our render method and see what this.props is now. In Visual Studio Code, you can hover over it:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bUAo19cXzh4ycUKvLW93xQ.png" /><figcaption>React.Component&lt;CustomInputProps, {}, any&gt;.props: Readonly&lt;{ children?: React.ReactNode; }&gt; &amp; Readonly&lt;CustomInputProps&gt;</figcaption></figure><ul><li>React.Component&lt;CustomInputProps, {}, any&gt;— This is Visual Studio telling us what this is. It closely matches the extends React.Component&lt;CustomInputProps&gt; from our class declaration, just with the default values for CustomInputProps’s 2 additional type parameters written out explicitly.</li><li>.props:— Because that’s what we’re hovering over.</li><li>Readonly&lt;{ children?: React.ReactNode; }&gt; &amp; Readonly&lt;CustomInputProps&gt;— Remember this Readonly stuff from before? Now it has CustomInputProps instead of {}.</li></ul><p>Cool! With this change, this.props keeps the previous children property, but now also has everything from CustomInputProps, in particular the fieldName property.</p><h4>There’s also state</h4><p>Using this.state is nearly identical to this.props, so I won’t go into it in depth. The errors you get from it should be basically the same. To give a component’s state a type, use the second type parameter to React.Component, like so:</p><pre>interface Props {<br>  fieldName: string;<br>}</pre><pre><strong>interface State {<br>  error: string | null;<br>}</strong></pre><pre>class CustomInput extends React.Component&lt;Props, <strong>State</strong>&gt; {<br><strong>  state = {<br>    error: null;<br>  };<br></strong>}</pre><p>The above example also shows initializing state with a default value. You could also do this with this.state = {…} in the constructor() method. I’ve also shortened the interface names to “Props” and “State” so they don’t wrap. They can actually be anything, as long as you’re consistent between the interface and the React.Component&lt;…&gt;.</p><h4>Required props on a custom component</h4><p>Let’s go back to using our CustomInput component. This will be similar to when we were making &lt;input&gt; elements.</p><p>Remember where we left off with CustomInput:</p><pre>interface CustomInputProps {<br>  fieldName: string;<br>}</pre><pre>class CustomInput extends React.Component&lt;CustomInputProps&gt; {<br>  …<br>}</pre><p>Let’s make one!</p><pre>render() {<br>  return (<br>    &lt;form&gt;<br>      &lt;CustomInput /&gt;<br>    &lt;/form&gt;<br>  );<br>}</pre><p>And the error is…</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n9ulcUhM2uSzo4-7yq2ZJg.png" /><figcaption>Type ‘{}’ is not assignable to type ‘IntrinsicAttributes &amp; IntrinsicClassAttributes&lt;CustomInput&gt; &amp; Readonly&lt;{ children?: ReactNode; }&gt;…’. Type ‘{}’ is not assignable to type ‘Readonly&lt;CustomInputProps&gt;’. Property ‘fieldName’ is missing in type ‘{}’.</figcaption></figure><p>It just keeps getting more complicated, doesn’t it?</p><ul><li>Type &#39;{}&#39;— To explain this, remember how JSX works. Our above line of code turns into React.createElement(CustomInput, {}). {} because we didn’t write any props in the JSX. Type &#39;{}&#39; is TypeScript describing that second, props argument.</li><li>is not assignable to — The old standby. There’s an inconsistency in the types!</li><li>&#39;IntrinsicAttributes &amp; IntrinsicClassAttributes&lt;CustomInput&gt; &amp; Readonly&lt;{ children?: ReactNode; }&gt;...&#39; — This is such a mess that TypeScript literally gives up and stops before it gets to the end. The “intrinsic” bits cover common React props like key and ref. You can see the Readonly&lt;{ children?: ReactNode; }&gt; at the end, which is the start of the this.props type we saw before. The complete type here is: IntrinsicAttributes &amp; IntrinsicClassAttributes&lt;CustomInput&gt; &amp; Readonly&lt;{ children?: ReactNode; }&gt; &amp; Readonly&lt;CustomInputProps&gt;, but honestly you can glaze over this line.</li><li>Type &#39;{}&#39; is not assignable to type &#39;Readonly&lt;CustomInputProps&gt;&#39;— Here TypeScript calls out what part of the IntrinsicAttributes &amp; … &amp; … it’s having trouble with. {} is perfectly assignable to IntrinsicAttributes, IntrinsicClassAttributes, and Readonly&lt;{ children?: ReactNode; }&gt; because all of their fields are optional. What it’s not assignable to is our CustomInputProps.</li><li>Property &#39;fieldName&#39; is missing in type &#39;{}&#39;.— This is the most useful part of the error message. The type &#39;{}&#39; is calling back to that second createElement argument, the type of the props from the JSX.</li></ul><p><strong>The fix: </strong>Once again, type errors are flagging <em>inconsistencies</em> in the code. As written, CustomInput wants a fieldName prop, but you’re not giving it one. So, either give it one, or make it not want one in the first place. Let’s look at how we would do each.</p><p>To pass fieldName, we do this:</p><pre>&lt;CustomInput <strong>fieldName=&quot;myField&quot;</strong> /&gt;</pre><p>After the JSX translation, that turns into:</p><pre>React.createElement(CustomInput, <strong>{ fieldName: &quot;myField&quot; }</strong>);</pre><p>The type of that second, props argument is { fieldName: string } which <em>is</em> assignable to CustomInputProps.</p><p>Here’s the other case, making fieldName optional. For this, we need to change the interface where CustomInputProps was declared.</p><pre>interface CustomInputProps {<br>  <strong>fieldName?</strong>: string;<br>}</pre><p>See how there’s a ? there now? That tells TypeScript that this property is optional. Now both { fieldName: string } and {} are assignable to CustomInputProps.</p><p>This does mean that this.props.fieldName now has the type &#39;string | undefined&#39;, so TypeScript will make you take that into account in the rest of your code. No calling this.props.fieldName.length without checking that it’s defined first!</p><h4>Passing unknown props</h4><p>Finally, let’s look at the error messages you get when you give a prop to a custom component that isn’t in its props type. TypeScript has two different error messages, depending on what other props you pass.</p><pre>&lt;CustomInput fieldName=&quot;myField&quot; placeholder=&quot;Type here&quot; /&gt;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4Lrl6y6lXyXmUWjenXCOLg.png" /><figcaption>Property ‘placeholder’ does not exist on type ‘IntrinsicAttributes &amp; IntrinsicClassAttributes&lt;CustomInput&gt; &amp; Readonly&lt;{ children?: ReactNode; }&gt;…’.</figcaption></figure><p>This error message is the same one we got with nmae in the early example, just with CustomInput’s longer props type at the end. It is <strong>very unfortunate </strong>that this is cut off before it says CustomInputProps, because that’s a piece of information that would <em>really </em>help track down what’s going on. Just remember that when you see this, it’s most likely that the prop you’re passing it isn’t defined in the component’s own props interface.</p><p>Curiously, if we leave off fieldName, the error message is different:</p><pre>export interface CustomInputProps {<br>  fieldName?: string;<br>}</pre><pre>&lt;CustomInput placeholder=&quot;Type here&quot; /&gt;;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WUSmPn_ycbXMtfQRXSI6HA.png" /><figcaption>Type ‘{ placeholder: string; }’ has no properties in common with type ‘IntrinsicAttributes &amp; IntrinsicClassAttributes&lt;CustomInput&gt; &amp; Readonly&lt;{ children?: ReactNode; }&gt;…’.</figcaption></figure><p>We can see the { placeholder: string; } type from the createElement statement that’s behind the scenes, and the IntrinsicAttributes &amp; … type for CustomInput’s props. It’s just for a reason I don’t know TypeScript says “has no properties in common” rather than “does not exist.”</p><p><strong>The fix:</strong> Resolve the inconsistency! Either add placeholder to CustomInputProps or remove it from &lt;CustomInput … /&gt;.</p><h3>Whew!</h3><p>There we go. Explanations for the most common TypeScript errors you run into in your React JSX, and how you might solve them. Hopefully that will reduce any future rage when programming.</p><p>I will admit that finding new ways for type checking to catch errors is one of my favorite programming exercises. In the new <a href="https://github.com/CityOfBoston/commissions">Boards and Commissions codebase</a>, we’re using <a href="https://github.com/convoyinc/ts2gql">ts2gql</a> to turn TypeScript interfaces into a GraphQL schema, which means we can use those TypeScript interfaces to <a href="https://github.com/CityOfBoston/commissions/blob/develop/modules-js/graphql-typescript/src/graphql-typescript.ts">very precisely typecheck our resolvers</a>. Just as with the Registry webapp, we’re using <a href="https://github.com/apollographql/apollo-codegen">apollo-codegen</a> to generate argument and output types for GraphQL queries, and we’ve also added <a href="https://github.com/rmp135/sql-ts">sql-ts</a> to make TypeScript types from SQL Server tables.</p><p>It’s a good reminder to me, and anyone else who’s putting tooling together, that a guard rail is only as good as whether or not you can tell what it’s guarding against.</p><h3>Acknowledgements</h3><p><a href="http://gmarceau.qc.ca/">Guillaume Marceau</a>, way back in his grad school days, helped me understand how type errors arise from two conflicting parts of a program. James Duffy proofread this article.</p><p>And of course to John, for powering through all of this like a champ.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8704cc9ef402" width="1" height="1" alt=""><hr><p><a href="https://medium.com/innovation-and-technology/deciphering-typescripts-react-errors-8704cc9ef402">Deciphering TypeScript&#39;s React errors</a> was originally published in <a href="https://medium.com/innovation-and-technology">Innovation and Technology</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Bringing death certificates to life with agile tools]]></title>
            <link>https://medium.com/innovation-and-technology/bringing-death-certificates-to-life-with-agile-tools-dcb0174cdc1a?source=rss-30408d1a9c9------2</link>
            <guid isPermaLink="false">https://medium.com/p/dcb0174cdc1a</guid>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[civictech]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[react]]></category>
            <dc:creator><![CDATA[Fiona Hopkins]]></dc:creator>
            <pubDate>Wed, 28 Mar 2018 14:49:58 GMT</pubDate>
            <atom:updated>2018-03-28T14:51:17.056Z</atom:updated>
            <content:encoded><![CDATA[<p>The City of Boston’s <a href="https://www.boston.gov/departments/digital-team">Digital Team</a> is very excited this week for the launch of our <a href="https://registry.boston.gov/death">death certificates web app</a>. This project is a collaboration among ourselves, the Enterprise Applications team, and the Registry and Treasury departments. We’ve written <a href="https://www.boston.gov/news/death-certificates-now-have-online-option">a blog post all about the new app</a> and how it makes buying a death certificate from the City more convenient than ever before.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RaowtZuzSTKaTnj4q2yTEQ.png" /><figcaption>Home page for the new death certificates web app</figcaption></figure><p>We’re particularly proud of the software engineering behind this launch. This is the first site that uses our new tech stack and production infrastructure for web applications. These tools have let us build a site that is fast, accessible, and (we hope!) maintainable for years to come.</p><p>In this post, we’re going to take you through how we chose to build the death certificates site. We’ll explain how the tools we picked helped us work agilely, with quick iterations leading to a solid first release.</p><h3>Why we picked death certificates</h3><p>The Digital Team is a part of the City of Boston’s <a href="https://www.boston.gov/departments/innovation-and-technology">Department of Innovation and Technology</a>. To quote our mission statement: “<em>We build digital experiences designed around the needs of our constituents. We work to make these tools beautiful, welcoming, and highly useful.”</em></p><p>Our most important responsibility is <a href="https://www.boston.gov/">Boston.gov</a>, the City’s website. Though it’s written by people from all over the City, we handle content editing, maintenance, and development of new content management features. Our team also oversees design and branding for the entire City.</p><p>We also build web apps! We have an ongoing project to modernize the services hosted on the legacy cityofboston.gov website, but we also make brand new things, like an upcoming rewrite of the 311 web portal and this death certificates app for the Registry Department.</p><p>Before this app, the only options to buy a death certificate from the City were by mail or by coming to City Hall in person. The only online option was a third-party service that partnered with the Commonwealth of Massachusetts. We knew that if we offered death certificates online ourselves, we could make an easier-to-use site and provide them at a lower price.</p><h3>How do we want to build?</h3><p>We started working on the death certificates app at about the same time as we started our rewrite of the 311 web portal (coming later this year). We knew that if we built the two apps similarly that we could share best practices between them and make long-term maintenance more consistent. We would also lay a solid groundwork for how to develop more apps in the future. Since we’re only planning to grow our portfolio of apps, we knew that taking advantage of economies of scale would be essential for our small team to keep on top of everything.</p><p>There are a huge number of options out there today for building a web app. To narrow down our choices, we set out looking for tools that met these criteria:</p><ul><li><strong>A big, active community.</strong> If a lot of people are using something then there will be tons of tutorials and places to go to get help, and tons of libraries we could re-use rather than build ourselves.</li><li><strong>Generally useful.</strong> If we want those economies of scale, what we pick for 311 and death certificates also needs to be adaptable to apps we work on in the future.</li><li><strong>Provides guard rails.</strong> We want tools that will catch our bugs or keep us from writing them in the first place.</li><li><strong>Lets us iterate quickly.</strong> We want to be able to make incremental improvements and ship them—either to staging or production—as soon as they’re ready.</li></ul><p>That last point, iterating quickly, consistently guided our choices. We like to work in an agile manner, continuously delivering incremental improvements. Though “agile” is often talked about around team process, we’ve found it’s critical that the software libraries, frameworks, and tools that a team uses support and reinforce an agile workflow. If you take a look at the <a href="http://agilemanifesto.org/principles.html">Principles behind the Agile Manifesto</a>, you’ll see that the first three points, around rapid continuous, rapid delivery and handling changing requirements, are directly affected by a team’s development tools.</p><p>When we think about rapidly delivering changes, we often think in terms of “cycle time”: the time between starting a piece of work and shipping it out, either to a pre-release staging environment or to production. We want our cycle time to be short; the sooner that a change gets released, the sooner it’s providing value to someone and the sooner we can get the feedback we need to make it even better.</p><p>One way to reduce cycle time is to keep each individual change to the site as small as possible. Smaller changes can be written, tested, and reviewed faster, and are less risky to release. If we need to do something big, we’ll still try to break it down into separate pieces that can be shipped one at a time. This is often called working in “small batches.” You’ll see below that we settled on tools that encourage making those small changes.</p><h3>Tools for a changing UI</h3><h4>React for building our interfaces</h4><p>Our first choice was a framework for building a user interface. Though the UI for death certificates is fairly modest (search results, details page, shopping cart, checkout flow), the one we were designing for 311 was shaping up to be a lot more complex, with dynamic forms and interactive maps. For a JavaScript-heavy site like that, we knew we wanted <a href="https://reactjs.org/"><strong>React</strong></a>.</p><p>React is hugely popular, with good reason. It could handle what we wanted for 311 but still scale down to death certificates’ straightforward UI without being overly complex. We love React’s declarative rendering and especially how it just uses JavaScript (with <a href="https://reactjs.org/docs/introducing-jsx.html">JSX</a> syntactic sugar) as a template language.</p><p>With the help of a CSS-in-JS solution (we’ve used both <a href="https://github.com/zeit/styled-jsx">styled-jsx</a> and <a href="https://emotion.sh/">Emotion</a>), our UI changes can often be done one file at a time, instead of to a separate JavaScript file, template file, and CSS file. Not only does this mean the changes are smaller, it’s less code that needs to be kept in sync. That helps reduce bugs.</p><h4>Next.js for setting things up</h4><p>Using React became much easier by adding in <a href="https://learnnextjs.com/"><strong>Next.js</strong></a>,<strong> </strong>a Node library specifically for running React apps. The death certificates site feels so fast because Next.js gives us <strong>server-side rendering</strong> of the initial page, <strong>code splitting</strong> for smaller JavaScript files that download faster, and <strong>prefetching</strong> so that the browser is all ready to render the next page before you even click to it.</p><p>You can see this in action by clicking around on the site. Other than when loading search results or actually submitting an order at the end, each page appears instantaneously. In fact, we had to take out the “loading” progress bar from most pages because they appeared so fast that it was just a distracting flash.</p><p>Next.js makes an engineer’s day-to-day development faster as well. It enables <strong>hot module reloading</strong> so that when you change code in a text editor you can see it immediately in your browser. This speeds up both building and debugging.</p><p>Next.js is a great example of a tool that gives us guard rails. Though we could have set up the configurations and architectures for all of the above features ourselves, doing so is notoriously tricky. So is keeping them working as the development environment changes. With Next.js, that becomes somebody else’s problem. In agile terms, for us, it’s “maximizing work not done.” We can just focus on our app.</p><h4>Storybook for getting it right</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZrdYQ6PKjy3hh85hDYGARw.png" /><figcaption>A Storybook story that shows just our “order details” component, with some sample certificates.</figcaption></figure><p>Our third tool for developing UIs rapidly is <a href="https://storybook.js.org/">Storybook</a>. Storybook renders the UI components of our app in isolation. You can browse the <a href="https://registry.boston.gov/storybook/">Registry app’s Storybook</a> to see what we mean.</p><p>With Storybook, we can get pieces of the UI looking and working the way we want them to before plugging them into the rest of the app. We can test them in different situations, such as when errors pop up, without having to reproduce those conditions over and over again. For example, you can see what the certificate page looks like <a href="https://registry.boston.gov/storybook/?selectedKind=CertificatePage&amp;selectedStory=normal%20certificate">normally</a>, when it’s <a href="https://registry.boston.gov/storybook/?selectedKind=CertificatePage&amp;selectedStory=certificate%20in%20cart">already in the cart</a>, when it’s <a href="https://registry.boston.gov/storybook/?selectedKind=CertificatePage&amp;selectedStory=pending%20certificate">pending</a>, or when the certificate ID <a href="https://registry.boston.gov/storybook/?selectedKind=CertificatePage&amp;selectedStory=missing%20certificate">isn’t found</a>.</p><p>Storybook is even more valuable because we can automatically use it with <a href="https://percy.io/"><strong>Percy</strong></a> for visual regression testing. This is a guard rail that tells us if a code change will make things look different in someone’s browser. If we had to configure Percy separately, it would eventually fall out of sync and lose its usefulness. But, since these tools overlap, the more we use Storybook because it makes development easier, the better our Percy coverage becomes. We’re always on the lookout for times when our tools can reinforce each other like this.</p><h4>Keeping a tight development loop</h4><p>The concept of cycle time applies not only to a product’s overall process, as we described above, but also to how a developer does their day-to-day work. As we code, we’re changing files in a text editor, going to a browser to make sure everything works, and repeating. With React, Next.js, and Storybook, we have tools that let us make small changes and see them immediately.</p><p>With a different set of tools, we might have to wait for a long compilation process, for a slow site to load up, or to click our way back to the part of the app we were working on. Even delays of a minute or two would encourage us to batch up several changes before testing them. Larger batches means longer cycle time, which means our fixes and features take longer to write.</p><h3>Continuous delivery to staging</h3><p>Code just sitting on an engineer’s laptop isn’t doing anyone any good. We need to “deliver [our] working software frequently” to our product managers, designers, and stakeholders in Registry and Treasury. To do that, we need to be able to ship painlessly.</p><p>Our <a href="https://github.com/CityOfBoston/registry-certs/commit/cdee59b787a8d8e4e5f115c124086fec826b9c81">first commit</a> to source control initialized the repository with GitHub’s default README. Our <a href="https://github.com/CityOfBoston/registry-certs/commit/d0f8ea7303c73fb2a92e670b1f669ab85ca6ffd3">second commit</a> was a bare-bones app, based on the structure of the 311 web portal. By our <a href="https://github.com/CityOfBoston/registry-certs/commit/79ea087a61f97ecf4bc27e7590c85b5d892de4f9">third commit</a>, we were automatically deploying from <a href="https://travis-ci.org/"><strong>Travis CI</strong></a> to <a href="https://www.heroku.com/"><strong>Heroku</strong></a>.</p><p>We like these tools because they’re easy to set up, integrate well with GitHub, and, for our open-source, low-traffic use, free.</p><p>From the very beginning of death certificates, any change that was committed went to staging <em>within minutes, without any further action</em>. Our tools supported us when we made small changes. Since there was no cost to deployment, there was no reason not to check things in as soon as they were ready and see them live.</p><p>If getting new code out were a long, manual process, as is sometimes the case, we’d probably wait until several changes were ready before pushing one out. That lengthens cycle time: the earliest change is just inventory, not providing any value, until a fixed schedule or critical mass of other changes prompts a new release. With continuous deployment, our product managers and designers can see their feedback implemented by lunch, not batched up with a bunch of other things that goes out sometime next week.</p><h3>Developing with and without data</h3><h4>Fetching with GraphQL</h4><p>The death certificates app needs to show search results, individual certificate records, and write orders to a database. To communicate this data between the React app running in the browser and the backend server, we turned to <a href="https://graphql.org/"><strong>GraphQL</strong></a>.</p><p>Since our first experiences with GraphQL, we’ve never wanted to go back to the <a href="https://en.wikipedia.org/wiki/Representational_state_transfer">REST</a> model for client/server communication. REST typically makes you choose between generalized endpoints —which either return too much data (slow) or require multiple network requests to get everything (also slow)—and view-specific endpoints, which can be tedious to maintain.</p><p>With GraphQL and the <a href="http://graphql.org/graphql-js/">graphql-js library</a>, our server code connects to the database and returns data in a general way, independent of any UI designs. Since it’s not coupled to the client’s needs, it can be tested in isolation and is fairly straightforward to maintain.</p><p>On the browser side, our app makes GraphQL queries for the data it needs for the particular page the user is on. If we decide to change the UI in a way that displays different data, we just modify the query on the browser side and don’t have to touch the server at all. Here’s the GraphQL we use to do a search, which returns individual certificates (under results) as well as the info needed for pagination:</p><pre>query SearchDeathCertificates($query: String!, $page: Int!, $startYear: String, $endYear: String) {<br>  deathCertificates {<br>    search(query: $query, page: $page, startYear: $startYear, endYear: $endYear) {<br>      page<br>      pageSize<br>      pageCount<br>      resultCount<br>      results {<br>        id<br>        firstName<br>        lastName<br>        deathYear<br>        deathDate<br>        pending<br>        age<br>        birthDate<br>      }<br>    }<br>  }<br>}</pre><p>How to get data is the sole concern of the server. Which data is needed is the sole concern of the client. The lack of coupling between the two speeds us up. Just as React let us make isolated changes to our UI, GraphQL lets us make isolated changes to how we get data. Those isolated changes? They’re small! Small is good.</p><p>GraphQL nicely leverages Node’s native concurrency, and Promises especially. For example, when you visit your cart and the client makes a <a href="https://github.com/CityOfBoston/registry-certs/blob/production/client/queries/FetchDeathCertificates.graphql">GraphQL query for all the certificates</a> in it, fetching them all in parallel is as straightforward as <a href="https://github.com/CityOfBoston/registry-certs/blob/0295686404f54175670da1e36cbf6c2d76e9558d/server/graphql/death-certificates.js#L313">using </a><a href="https://github.com/CityOfBoston/registry-certs/blob/0295686404f54175670da1e36cbf6c2d76e9558d/server/graphql/death-certificates.js#L313">Promise.all and </a><a href="https://github.com/CityOfBoston/registry-certs/blob/0295686404f54175670da1e36cbf6c2d76e9558d/server/graphql/death-certificates.js#L313">map</a>.</p><p>Admittedly, a full GraphQL backend is slight overkill just for the Registry app. It provides some benefits over a more ad-hoc solution, but requires a bit of boilerplate and a level of conceptual complexity as well. Nevertheless, GraphQL is invaluable for the 311 web portal. Being consistent between the two reduces the conceptual burden somewhat.</p><h4>Safely iterating on data with Flow</h4><p>Early on, we didn’t have any data because we were still setting up our connection to the Registry’s database. We wanted to get started on our UI though, so we introduced fake data (mostly <a href="https://github.com/CityOfBoston/registry-certs/blob/production/fixtures/client/death-certificates.js">based on comic book characters</a>) to have something to show as we iterated with product and design.</p><p>One real danger when working with fake data is that it might be formatted differently than the eventual real data, leading to wasted work and possible bugs adapting to the database once it’s in place. We guarded against that risk in two ways:</p><ul><li>First, we had GraphQL as a layer between our UI and the database. We wrote a GraphQL schema that we knew we could eventually fulfill with live data, so all we needed to do was <a href="https://github.com/CityOfBoston/registry-certs/blob/09beb8af478fb96a74c0e5f7cf916f077782335b/server/graphql/death-certificates.js#L68">have the GraphQL endpoint return fake data</a> directly. The UI code we wrote against the GraphQL schema wouldn’t have to change once the database was available.</li><li>Second, we used <a href="https://flow.org/"><strong>Flow</strong></a> to statically type-check our code. We used <a href="https://github.com/apollographql/apollo-codegen"><strong>apollo-codegen</strong></a> to generate <a href="https://github.com/CityOfBoston/registry-certs/blob/production/client/queries/graphql-types.js">types from our GraphQL queries</a>. Flow made sure that every piece of data used by our UI was actually going to be returned by our GraphQL queries. As we iterated and tweaked the schema or the queries, Flow would tell us everywhere that needed updating to match.</li></ul><p>Once we did have database access, Flow helped us yet again. Based on talking to the Enterprise Applications team and inspecting the responses to our SQL queries, we were able to write Flow types for the <a href="https://github.com/CityOfBoston/registry-certs/blob/production/server/services/RegistryData.js#L15">SQLServer response structure</a> and <a href="https://github.com/CityOfBoston/registry-certs/blob/production/server/services/RegistryData.js#L22">death certificates table specifically</a>. With those in place, we could confidently write the code that converted from the database to the GraphQL schema the UI code was already using, knowing that Flow would ensure we were using field names that existed and matched our expectations for their types.</p><p>Static type checking is one of the best guard rails we have. It’s useful during early development when everything is changing a lot and it’s easy to forget where you need to update. It pays off again down the road when you need to update things without breaking pieces of the app you’ve completely forgotten about.</p><p>We chose Flow early on because we knew it had good support for React, and, since it acted as a linter, we didn’t have to integrate it into our JavaScript bundling (which is handled by Next.js). We may experiment with <a href="http://www.typescriptlang.org/"><strong>TypeScript</strong></a> in the future—we already use it for our web components, since it’s built into <a href="https://stenciljs.com/"><strong>Stencil</strong></a>—if third-party library or editor support reaches a tipping point in its favor. The <a href="https://github.com/zeit/next-plugins/tree/master/packages/next-typescript">next-typescript</a> plugin integrates it into Next.js.</p><h3>Shipping to production early and often</h3><h4>Getting started on AWS</h4><p>Up to this point, we had been doing all of our staging deployments to Heroku. We like Heroku because it has tight GitHub integration and takes care of all of the complexities of deployment for us. It worked great right up until the point where we needed to connect to the Registry database, which is safely behind a firewall in a City data center.</p><p>We liked having a cloud-based deployment, but exposing a SQLServer cluster to the Internet just so we could access it from Heroku seemed like a bit of a security risk. So, we followed the lead of the Analytics and Data team and got up and running on <a href="https://aws.amazon.com/"><strong>Amazon Web Services</strong></a>.</p><p>Unlike with Heroku, we could set up a VPN tunnel from our AWS VPC’s private subnets back to the City data center. Now our apps could be deployed to the cloud but still securely connect to the Registry database.</p><h4>Shipping with Docker</h4><p>Without Heroku, we had to find a new way to continuously deploy our code. We tested out Amazon’s <a href="https://aws.amazon.com/elasticbeanstalk/">Elastic Beanstalk</a> tool, but the way it put our apps on separate EC2 instances was a waste of resources. By tech industry standards, City web services do not get very much traffic.</p><p>Instead, we looked for a way to pack just a handful of instances with as many apps as could fit into memory, which led us to choose <a href="https://www.docker.com/"><strong>Docker</strong></a> containers. Each container is an isolated environment for a single app, so—within the limits of the machine’s resources—they can co-exist without interfering with each other.</p><p>To deploy, we have our Travis CI job build a container image, upload it to Amazon’s <a href="https://aws.amazon.com/ecs/">Elastic Container Service</a>, and create a <a href="https://aws.amazon.com/cloudformation/">CloudFormation</a> change set to push it out. We then get a message in Slack with the exact command line to paste into a terminal to trigger the release. (For security reasons, the AWS users we use for Travis don’t have permissions to change production directly.)</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*P9MSj008Nan9u5TS5ZLjtA.png" /><figcaption>Shippy-Toe, our very own shipit squirrel, lets us know in Slack how to push the new release out.</figcaption></figure><p>Amazon’s <a href="https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html">Application Load Balancers</a> give us zero-downtime deploys. They check to make sure new container instances are up and healthy before draining connections from the old ones. This eliminates any user-visible cost to deployments (no one’s use of the app is interrupted) and de-risks them at the same time (if the new version won’t launch then the old, working one will safely stay in place). Since there’s no downside to making a release, we can do it whenever we want, with as small a batch as we want.</p><p>Though we like the functionality that we have built on AWS, we’re not satisfied with what it takes to do it. CloudFormation does not have a very friendly language for defining infrastructure. We had to write a lot of hard-to-understand templates to make this work. We also had to write some deployment scripts ourselves, which means we have to maintain them as well. For example, EC2 + ECS has no built-in feature to prevent auto-scaling instances from shutting down (such as during system updates) while they have containers running on them. We had to adapt code from <a href="https://aws.amazon.com/blogs/compute/how-to-automate-container-instance-draining-in-amazon-ecs/">a blog post</a> to keep from dropping traffic when we need to update our AMIs.</p><p>Migrating this to something that’s friendlier (we hear <a href="https://www.terraform.io/"><strong>Terraform</strong></a> is good, and the Data and Analytics team is already using it) and more industry-standard (<a href="https://kubernetes.io/"><strong>Kubernetes</strong></a> for container orchestration, which is now directly supported by AWS) is something we’re interested in, though we would have to prioritize it against building new apps.</p><h3>Other tools for going fast</h3><p>As part of the new branding that launched with Boston.gov, we developed the <a href="https://patterns.boston.gov/"><strong>Fleet pattern library</strong></a> of CSS and HTML components. We use this across all of our websites and apps to keep the UIs looking stylish and consistent.</p><p><a href="https://prettier.io/"><strong>Prettier</strong></a> is the best. Auto-formatting means that we don’t have to spend any time editing spaces and indents to conform to a style guide. The noticeable productivity benefits of having code just jump into place when you press save have to be experienced to be believed.</p><p>For unit testing, we’ve adopted <a href="https://facebook.github.io/jest/"><strong>Jest</strong></a>. It can run tests in parallel for speed, and its snapshot feature saves the effort of writing tedious test assertions when what you really want to say is, “this is fine now, just give me a heads-up if it changes.” These days, the code that gets exercised by unit tests doesn’t tend to be affected by differences among our supported browsers, so we don’t miss not being able to run them directly in a browser. We much prefer the stability and speed of Jest’s <a href="https://github.com/jsdom/jsdom">jsdom</a>-based approach.</p><h3>Looking ahead</h3><p>We’re proud of what we’ve built so far with the death certificates app. If you do happen to need it, we hope that you find it fast and easy to use. We’re looking forward to bringing more Registry services online as well, with marriage and birth certificates on our roadmap.</p><p>We’re also excited to keep working in the tech stack described above because of how happy and productive we feel when we can be agile and quickly make new improvements. As we evolve it over time, we’ll balance the value of staying consistent with any gains we can get from a different tool.</p><p>Does this sound like a way you’d like to work? Do you want to bring beautiful, welcoming, and highly-usable tools to the people of Boston? We’re hiring a full-time software engineer to join the team in City Hall. <a href="https://city-boston.icims.com/jobs/14272/web-developer-%28prin.-dp-systems-analyst%29/job?hub=8&amp;mobile=false&amp;width=1200&amp;height=500&amp;bga=true&amp;needsRedirect=false&amp;jan1offset=-300&amp;jun1offset=-240&amp;hootPostID=42b7b5616a777032fd99cd71b70a2a65">Apply now</a>!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dcb0174cdc1a" width="1" height="1" alt=""><hr><p><a href="https://medium.com/innovation-and-technology/bringing-death-certificates-to-life-with-agile-tools-dcb0174cdc1a">Bringing death certificates to life with agile tools</a> was originally published in <a href="https://medium.com/innovation-and-technology">Innovation and Technology</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Hulk Smash Board Game]]></title>
            <link>https://medium.com/cards-and-cardboard/hulk-smash-board-game-d6dd33375b52?source=rss-30408d1a9c9------2</link>
            <guid isPermaLink="false">https://medium.com/p/d6dd33375b52</guid>
            <category><![CDATA[board-games]]></category>
            <dc:creator><![CDATA[Fiona Hopkins]]></dc:creator>
            <pubDate>Wed, 17 Aug 2016 19:14:59 GMT</pubDate>
            <atom:updated>2016-08-17T19:14:59.189Z</atom:updated>
            <content:encoded><![CDATA[<p>Over the past three days, my children have become quite taken with the <a href="http://boardgamegeek.com/boardgame/9776/godzilla">Incredible Hulk Smash board game</a> from Milton Bradley. What’s been fun for me is that this is the first game that our whole family is playing together: two parents and our soon-to-be 3- and 6-year-olds.</p><p>That a 3-year-old can play this game tells you how simple of a game it is underneath, on the order of Candy Land or Snakes and Ladders. But, Hulk Smash has some delightful layers that keep both kids engaged and even keep the adults from getting bored. Even better, I see it helping my kids <strong>take setbacks in stride</strong>,<strong> have fun even when they don’t win</strong>, and just<strong> have a good time together around the table</strong> as a family.</p><p>At its core, Hulk Smash is a roll-and-move race game. (<a href="http://tableflipsyou.com/">Surprise!</a>) Your goal is to get both of your pawns from one end of the track to another. This what makes it essentially Candy Land, though with two 6-sided dice for the movement.</p><p>The “Hulk” part comes from a deck of cards. If you roll the equivalent of a 6 on your turn, you draw a card and get the opportunity to “Hulk smash” pawns on the board.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*0qfxsp4n7KX57dkm69DTog.jpeg" /><figcaption>This is literal: the pawns are molded out of Play-Doh and there’s a green plastic fist in the box to squish them with.</figcaption></figure><p>If your pawn gets squished, you get out your can of Play-Doh and mold another one, starting it back at the beginning of the track. Your smudged piece remains on the board, occupying a space that you’ll be able to skip over when you pass through again.</p><p>Let’s go deep on the Hulk smash mechanism because there are a lot of great aspects to it to unpack.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qpe5OaW5bTJnhqTUwL_uWw.jpeg" /><figcaption>The mold for the pawns and the smasher</figcaption></figure><p>For starters, there’s the toy value. Play-Doh, molded cars, the fist, the cardboard buildings. “Hulk smashing” the little cars with the fist is just fun, game or no game!</p><p>This taps into something that I, as a not-very-competitive person, need to see in games: the act of actually playing needs to be fun, regardless of the final score. Executing a “winning strategy” has no particular joy for me. The meat of each turn has to have something that’s interesting and satisfying to do.</p><p>I find this in my favorite titles: <a href="http://boardgamegeek.com/boardgame/48726/alien-frontiers">Alien Frontiers</a> has its manipulation of the dice, moving a pip from here to there and flipping that one over to get the pattern that you need. <a href="http://boardgamegeek.com/boardgame/172818/above-and-below">Above and Below</a> has a book of random encounters, each a paragraph long adventure that you can try to beat. <a href="http://boardgamegeek.com/boardgame/31260/agricola">Agricola</a> has — if you don’t starve to death—your own little farm that grows right in front of you.</p><p>Hulk Smash has the kid-friendly equivalent. <strong>No matter how you’re doing in the race to the finish, several times during the game you’re going to get to be the Hulk.</strong> You’ll shout “smash!” and bring down that green fist and it will be fun. It’s not fun because it’s helping you win (you may even be smashing your own pawn) or getting back at someone else (though you may be) it’s simply enjoyable, in and of itself.</p><p>If, when you got the opportunity to smash, you could pick any target you wanted, the game would be much less interesting and would easily devolve into petty back-and-forth between siblings. Instead, knowingly or not, <strong>Hulk Smash borrows from the legendary </strong><a href="https://boardgamegeek.com/boardgame/39463/cosmic-encounter"><strong>Cosmic Encounter</strong></a> by making the target of your fist not entirely up to you. Some of the cards match one of the four colors of board spaces, and you’re obligated to smash any pawns on that color, regardless of who owns them. An equal number are “wild,” meaning you get to choose the color, but you still have to smash everyone on that color. A third set of cards let you choose an entire building to demolish, and you smash all the pawns adjacent to that building.</p><p>I love this system.</p><p>First, it diffuses the responsibility for what amounts to a “take that” setback to another player. If you draw the red card, you have to smash pawns on red spaces. There’s no malice because it’s mandated. Even when you can choose, you’re choosing a color and not a player, which softens it from being a direct attack against someone else. (The leader of the race is also pretty easy to spot, so smashing them is objectively a reasonable move that should garner few complaints.)</p><p>Especially with young kids, it’s worth avoiding any mean-spirited interactions at the table. Going by colors lets them knock someone back, or get knocked back, in a way that threads a bearable middle ground between being arbitrarily chosen (which can be frustrating) and being specifically targeted (which can be hurtful).</p><p>Second, there are times when it can be really funny. Drawing the color that both of your own pawns happen to be on is funny. Choosing to stop the leader but also having to squash one of your own pawns is funny. Knocking over a building that’s surrounded by everyone but you is funny. It’s in this way that the game enhances the direct joy of Play-Doh squashing: what that squashing means in game terms is often delightful.</p><p>My oldest talks about when my spouse’s first car got squashed right before the safety of the end of the track. She remembers when a building took out both my pawns at once. She’s learning that it’s the unique moments within the games that stay with you, not the score at the end. (Though she does keep track of where the last winner was in player order, and wants to be in that “lucky spot” in the next game.)</p><p>Finally, going by colors opens strategy doors by having risk that’s possible to mitigate. I’ve gotten my oldest to notice when she leaves both of her pawns on the same color, making her extra vulnerable, or when she’s on the same color as an opponent, meaning smashing them would smash her as well. In Hulk Smash, choosing which of your pieces to move is not an arbitrary choice; there are consequences you can weigh in making that decision.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2xoXN7c9ew0f4U1Fv4ggJQ.jpeg" /><figcaption>The end of a 4-player game. Note the volume of smashing.</figcaption></figure><p>I’m excited for how Hulk Smash is making my kids better board game players. The youngest is able to experience the fun of actually playing with his family, not just being on someone’s “team” at the table. He’s also getting practice adding small numbers together from the two dice, and — since this is a luck-heavy roll-and-move—even has a shot at winning some times. Our oldest is learning basic strategies, but is also getting experience in how to lose while still having fun. After all, regardless of won, everyone got to smash little Play-Doh cars and trucks with a plastic fist while shouting like the Hulk.</p><p><em>Copies of Incredible Hulk Smash seem to be on Ebay for as low as $10. You may have to provide your own Play-Doh, but trust me it’s worth it. The 2008 version is actually a straight re-theme of a 1998 Godzilla board game, if you like giant lizards more than superheroes.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d6dd33375b52" width="1" height="1" alt=""><hr><p><a href="https://medium.com/cards-and-cardboard/hulk-smash-board-game-d6dd33375b52">Hulk Smash Board Game</a> was originally published in <a href="https://medium.com/cards-and-cardboard">Cards and Cardboard</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Wash Your Board Games]]></title>
            <link>https://medium.com/cards-and-cardboard/wash-your-board-games-b06f006c0e66?source=rss-30408d1a9c9------2</link>
            <guid isPermaLink="false">https://medium.com/p/b06f006c0e66</guid>
            <dc:creator><![CDATA[Fiona Hopkins]]></dc:creator>
            <pubDate>Sun, 08 Dec 2013 20:13:22 GMT</pubDate>
            <atom:updated>2013-12-08T20:13:37.641Z</atom:updated>
            <content:encoded><![CDATA[<h4>One weird old trick for improving the look of your plastic bits.</h4><p>Many board games come with wonderfully detailed plastic pieces, but a lot of those details are lost when rendered in a uniform shade of plastic. Case in point, <a href="http://boardgamegeek.com/boardgame/126163/tzolkin-the-mayan-calendar">Tzolk’in: The Mayan Calendar</a>, pictured above. Here’s how it comes in the box:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*74F4-dpycjEBivaePqJP9w.jpeg" /><figcaption>Tzolki’n: The Mayan Calendar as you would buy it in a store</figcaption></figure><p>None of the intricate design of the center wheel is visible. It’s a smear of dull, generic beige. This presentation is not just a waste of such a nice piece, it’s actively unappealing. As you can see from the header, we can do a lot better.</p><p>Tzolk’in is an extreme example, but any game with molded plastic bits can suffer from the same sort of blandness. The spaceships from <a href="http://boardgamegeek.com/boardgame/39463/cosmic-encounter">Cosmic Encounter</a> might as well be poker chips for all you can see of their designs.</p><p>How can you make this better? While you could fully paint the plastic pieces to your game, that can take a lot of time and requires skill not to end up with something that looks worse than when you started. I overestimated my own stamina and got started on <a href="http://boardgamegeek.com/boardgame/25417/battlelore">BattleLore</a>, which never hit the table after I gave up painting halfway through.</p><p>Instead, I’d like to introduce to you a single technique from miniatures painting that is both fast and easy, which you can use to give an extra dimension to your board games. It’s called an <strong>ink wash</strong>.</p><p>The primary purpose of an ink wash is to simulate shadows, enhancing the definition of a piece’s features. The mechanism by which it operates is rather clever, and, even better for us, quite forgiving.</p><p>An ink wash is simply liberally spreading (“washing”) a dark ink over the piece with a brush. Being watery, the ink will naturally run off raised portions of the figure. Surface tension will cause it to outline those elements, and gravity will make it pool in recesses. This means that physics is doing the intricate work for you. Your only job is to guide it around a bit.</p><p>Since you don’t have to be particularly careful, a figure will only take a few minutes to do. You just slather the ink on, poke it around so that it flows into the right crevices, and then repeat until the whole thing’s covered.</p><blockquote>This means that physics is doing the intricate work for you.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*7gi45f7M_xv1JTyNfm5zgA.jpeg" /><figcaption>Washed and unwashed figures from Flash Point: Fire Rescue’s Extreme Danger expansion</figcaption></figure><p>The end result is that those little invisible details of the sculpt will now become visible, the lines inked in. Your pieces will feel more alive on the table and make the game that much more fun to play.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F2EUAHy9S7N5BedPMa5-3Q.jpeg" /><figcaption>Washing is great for organics. This li’l guy was a Kickstarter bonus in the Extreme Danger campaign.</figcaption></figure><p>I have no talent with any kind of brush, which should give you a sense of how easy it would be for you to give this a try and achieve good results.</p><p>The materials are cheap, the process is fast, and, if things go pear-shaped during your first go, you can always Simple Green your pieces back to their original condition.</p><p>You can find inks and finish in the miniatures section of your friendly local game shop. Let me know on Twitter if my encouragement has prompted you to improve any of your own games, or if you have any tips to share with a novice like me.</p><h4>Tips for getting started:</h4><ul><li>Use dish soap first to clean the pieces and remove any manufacturing chemicals that will affect adherence.</li><li>Prime the piece only if the underlying color isn’t what you want, such as with Tzolk’in. Otherwise it’s fine to wash unprimed plastic.</li><li>Choose an ink color that’s close to the color of the plastic to stay true to the “shadow” effect.</li><li>Don’t let the ink pool so much that it becomes opaque. You can use a depleted brush to wick excess ink back up if it gets too thick.</li><li>If you’re not happy with how a piece looks, soak it in Simple Green for a few hours to reset it back to factory conditions.</li><li>Spray on a matte finish when you’re all done. Otherwise the ink will feel gritty and it will scratch off.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b06f006c0e66" width="1" height="1" alt=""><hr><p><a href="https://medium.com/cards-and-cardboard/wash-your-board-games-b06f006c0e66">Wash Your Board Games</a> was originally published in <a href="https://medium.com/cards-and-cardboard">Cards and Cardboard</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>