DEV Community: Headway

useHug: Creating custom React Hooks 🥰

Chris Held — Sun, 14 Feb 2021 15:16:01 +0000

Building custom hooks is a great way to encapsulate behaviors and reuse them throughout your application. To demonstrate this, we're going to build out the idea of "hugging" elements of our UI. Our huggable behavior will:

Change the mouse cursor on hover (we want our user to know what needs a hug).
Scale the element down on click (this is a firm hug, some squishiness is expected).
Change the mouse cursor while clicking (to show our appreciation).

I find the first step to making something reusable is to use it once, so let's implement this in a component:

import React, { useState } from "react";
import { animated, useSpring } from "react-spring";

const Huggable = () => {
  const [hovering, setHovering] = useState(false);
  const [pressed, setPressed] = useState(false);
  const animationProps = useSpring({
    transform: `scale(${pressed ? 0.8 : 1})`
  });
  const onMouseEnter = () => setHovering(true);
  const onMouseLeave = () => {
    setHovering(false);
    setPressed(false);
  };
  const onMouseDown = () => setPressed(true);
  const onMouseUp = () => setPressed(false);

  let className = "huggable";

  if (pressed) {
    className += " hugging-cursor";
  } else if (hovering) {
    className += " huggable-cursor";
  }

  return (
    <animated.div
      className={className}
      onMouseEnter={onMouseEnter}
      onMouseLeave={onMouseLeave}
      onMouseDown={onMouseDown}
      onMouseUp={onMouseUp}
      style={animationProps}
            role="button"
    >
      Hug me!
    </animated.div>
  );
};

export default Huggable;

There are a few things going on here so we'll take a closer look:

const [hovering, setHovering] = useState(false);
const [pressed, setPressed] = useState(false);

There are two states that we want to track here, is the user hovering and have they pressed the button.

const animationProps = useSpring({
  transform: `scale(${pressed ? 0.8 : 1})`
});

We take advantage of react-spring's useSpring hook to create an animation. We could also use CSS transforms here but react-spring does a lot of math for us to give us really good looking animations without much work.

const onMouseEnter = () => setHovering(true);
const onMouseLeave = () => {
  setHovering(false);
  setPressed(false);
};
const onMouseDown = () => setPressed(true);
const onMouseUp = () => setPressed(false);

These event handlers will be used to manage our hovering / pressed state, which in turn will drive our behavior.

let className = "huggable";

if (pressed) {
  className += " hugging-cursor";
} else if (hovering) {
  className += " huggable-cursor";
}

We set a className here dynamically based on our pressed / hovering state. This is used to control some basic styles as well as custom cursors when hovering. This might have been a little easier had I used JSS or styled components, but this served my needs just fine and will hopefully make sense to a wider audience.

return (
    <animated.div
      className={className}
      onMouseEnter={onMouseEnter}
      onMouseLeave={onMouseLeave}
      onMouseDown={onMouseDown}
      onMouseUp={onMouseUp}
      style={animationProps}
            role="button"
    >
      Hug me!
    </animated.div>
  );

Finally, our markup. Not much to see here as we're just passing down the props we defined above, but it's worth pointing out the animated tag, which is required by react-spring.

Here's what we've got so far:

Not bad! Now let's try and isolate what we want to encapsulate in a hook. We know this should be applicable to any element, so we won't want to use any of the markup. That leaves the state management, event handlers, the animation, and our classes:

const [hovering, setHovering] = useState(false);
const [pressed, setPressed] = useState(false);
const animationProps = useSpring({
  transform: `scale(${pressed ? 0.8 : 1})`
});
const onMouseEnter = () => setHovering(true);
const onMouseLeave = () => {
  setHovering(false);
  setPressed(false);
};
const onMouseDown = () => setPressed(true);
const onMouseUp = () => setPressed(false);

let className = "huggable";

if (pressed) {
  className += " hugging-cursor";
} else if (hovering) {
  className += " huggable-cursor";
}

If we copy that into it's own function it looks something like this:

const useHug = () => {
  const [hovering, setHovering] = useState(false);
  const [pressed, setPressed] = useState(false);
  const style = useSpring({
    transform: `scale(${pressed ? 0.8 : 1})`
  });
  const onMouseEnter = () => setHovering(true);
  const onMouseLeave = () => {
    setHovering(false);
    setPressed(false);
  };
  const onMouseDown = () => setPressed(true);
  const onMouseUp = () => setPressed(false);

  let className = "";

  if (pressed) {
    className += "hugging-cursor";
  } else if (hovering) {
    className += "huggable-cursor";
  }

  //TODO: return...?
};

All that's left now is what we want to return. This is an important decision as it defines what consuming components can do with our hook. In this case, I really want a consumer to be able to import the hook as one object and spread it over an html element, like so:

const huggableProps = useHug();

return <a href="/contact" {...huggableProps}>Contact Us</a>

This makes our hook easy to consume and use while keeping some flexibility in case an element wants to pick and choose what events to use. In order to do that we have to leave off our state variables, since they aren't valid properties for html elements. This is what our return statement winds up looking like:

return {
  onMouseDown,
  onMouseEnter,
  onMouseLeave,
  onMouseUp,
  className,
  style
};

Now that we've got our hook, the only thing left to do is to use it:

export default function App() {
  const { className, ...hugProps } = useHug();
  const buttonHugProps = useHug();
  return (
    <div className="App">
      <animated.section className={`huggable ${className}`} {...hugProps}>
        I like hugs!
      </animated.section>

      <br />
      <br />
      <animated.button {...buttonHugProps} type="button">
        buttons need hugs too
      </animated.button>
    </div>
  );
}

In the above example we've implemented our useHug hook in two ways, by taking all of the props and spreading them out over an element, and another by separating out the className prop and using that to compose a css class with our consuming element's existing className. We also make use of the animated tag to ensure our app animates correctly with react-spring.

Although this example may seem kind of silly, a lot of the process for extracting logic into a custom hook would remain the same, no matter what you're building. As you identify patterns in your code it's a good practice to look for ways you can abstract application logic or behavior in the same way you would abstract a common UI element like a modal or input. This approach can help set you up for success as your application grows over time and prevent future developers (or future you) from reinventing the wheel on something you've already implemented a few times.

If you'd like to see the full code, here it is on codesandbox. Feel free to fork it and play around, I'd love to see what you come up with!

React: Prototyping with Apollo Client Schemas

Chris Held — Sun, 02 Aug 2020 19:04:41 +0000

Building a prototype is a great way to validate an idea, or to gather feedback from users without taking on the risk of having to build out an entire application. In this tutorial we'll take a look at Apollo Client and how we can leverage a client side schema to set us up for success when we're ready to build out an API to talk to our front end.

Apollo Client is a tool used to manage your client side data. It's typically paired with Apollo Server but it will work with any GraphQL server implementation, which makes it great for prototyping. Even if we choose a different GraphQL implementation for our server like Absinthe later, we can still keep our front end queries as long as the schema is defined the way we're expecting.

For our demo we're going to create an app that will return some information about our user's location based on their IP Address. Let's get started!

First we'll spin up a react app and install apollo:

npx create-react-app apollo-client-schema-demo
cd apollo-client-schema-demo
npm i
npm install @apollo/client graphql

First let's create a component to display our user's information. We don't really need to worry about where the data is coming from right now so we'll use static data. Create an IPInfo.js file that looks like this:

import React from "react";

const IPInfo = () => {
  const data = {
    ipAddress: "1.1.1.1",
    city: {
      name: "Sheboygan",
      population: 123456,
    },
    country: {
      name: "USA",
      population: 123456,
    },
  };

  return (
    <main className="App">
      <h1>Howdy!</h1>
      <p>Your IP Address is {data.ipAddress}</p>
      <p>
        {`Your city, ${data.city.name}, has a current population of
         ${data.city.population}`}
      </p>
      <p>
        {`Your Country, ${data.country.name}, has a current population of
         ${data.country.population}`}
      </p>
      <p>Cool, huh?</p>
    </main>
  );
};

export default IPInfo;

Let's also edit our App.js file to show this component:

[...]
function App() {
  return (
      <div className="container">
        <IPInfo />
      </div>
  );
}
[...]

...and edit our App.css file slightly to clean it up:

body {
  margin: 2rem;
}

.container {
  max-width: 800px;
  margin: auto;
}

If we run npm start, we should be greeted with something like this:

Now we need to set up an apollo client. Add the following to App.js:

import { ApolloClient, ApolloProvider, InMemoryCache } from "@apollo/client";

const client = new ApolloClient({
  uri: "https://48p1r2roz4.sse.codesandbox.io",
  cache: new InMemoryCache(),
});

This sets up an instance of ApolloClient. The uri we chose is from the Apollo Documentation and can be used as a placeholder until we have a real server to point to. The contents of the server don't really matter since we'll only be pointing at our client schema, but it is a required field when instantiating a client.

In order to tie our app to apollo, we need to wrap it in an instance of ApolloProvider. To do that we'll need to edit our App component:

function App() {
  return (
    <ApolloProvider client={client}>
      <div className="container">
        <IPInfo />
      </div>
    </ApolloProvider>
  );
}

If we refresh we shouldn't see any difference since we aren't actually querying for anything. To do that without having an actual server to call, we can define typeDefs in our app and pass them in to our client instantiation. Let's make some modifications to App.js:

import React from "react";
import "./App.css";

import {
  ApolloClient,
  ApolloProvider,
  InMemoryCache,
  gql,
} from "@apollo/client";
import IPInfo from "./IPInfo";

const typeDefs = gql`
  extend type Query {
    client: Client!
  }

  extend type Client {
    ipAddress: IPAddress!
  }

  extend type IPAddress {
    address: String!
    city: City
    country: Country
  }

  extend type City {
    name: String!
    population: Int
  }

  extend type Country {
    name: String!
    population: Int!
  }
`;

const client = new ApolloClient({
  uri: "https://48p1r2roz4.sse.codesandbox.io",
  cache: new InMemoryCache(),
  typeDefs,
});

function App() {
  return (
    <ApolloProvider client={client}>
      <div className="container">
        <IPInfo />
      </div>
    </ApolloProvider>
  );
}

export default App;

Here, we're defining typeDefs and creating a client query and some types to support it, then passing that in to our client constructor. Now we can use apollo's useQuery hook to fetch the results of that query, even though we still haven't written anything to resolve it and we haven't build out a server. Let's do that in IPInfo.js:

import React from "react";
import { useQuery, gql } from "@apollo/client";

const CLIENT_QUERY = gql`
  {
    client @client {
      ipAddress {
        address
        city {
          name
          population
        }
        country {
          name
          population
        }
      }
    }
  }
`;

const IPInfo = () => {
  const {
    data: {
      client: { ipAddress: { address, city = {}, country = {} } = {} } = {},
    } = {},
    loading,
    error,
  } = useQuery(CLIENT_QUERY);

  if (loading) {
    return (
      <p>
        Hmm...{" "}
        <span role="img" aria-label="thinking emoji">
          🤔
        </span>
      </p>
    );
  }

  if (error) {
    return (
      <p>
        Ruh Roh{" "}
        <span role="img" aria-label="sad emoji">
          😫
        </span>
      </p>
    );
  }

  return (
    <main className="App">
      <h1>Howdy!</h1>
      <p>Your IP Address is {address}</p>
      <p>
        {`Your city, ${city.name}, has a current population of
         ${city.population}`}
      </p>
      <p>
        {`Your Country, ${country.name}, has a current population of
         ${country.population}`}
      </p>
      <p>Cool, huh?</p>
    </main>
  );
};

export default IPInfo;

We've changed a lot here, so let's step through.

First we define our graphql query. Nothing very special there if you're familiar with graphql, but note the @client directive. That tells apollo that this doesn't exist on the server, so there's no need to ask the server for this.

In the actual component code we take advantage of apollo's useQuery hook to make our query:

  const {
    data: {
      client: { ipAddress: { address, city = {}, country = {} } = {} } = {},
    } = {},
    loading,
    error,
  } = useQuery(CLIENT_QUERY);

This gives us all the data we need to power our form, plus a few variables to manage different query states. Our markup has remained largely the same, though we did add a bit to handle loading and error states.

If we refresh our page, we'll see a whole lot of nothing:

Why is that? Well, in our client schema we only defined the shape of our data, but not it's contents. To do that we need to create a resolver. Let's add one right underneath our schema in App.js:

const resolvers = {
  Query: {
    client: () => ({
      ipAddress: {
        address: "172.220.20.36",
        city: {
          name: "Sheboygan",
          population: 48895,
        },
        country: {
          name: "United States of America",
          population: 325145963,
        },
      },
    }),
  },
};

const client = new ApolloClient({
  uri: "https://48p1r2roz4.sse.codesandbox.io",
  cache: new InMemoryCache(),
  typeDefs,
  resolvers,
});

Don't forget to add your resolvers object to your client.

In our resolver, we defined what should be returned when something calls the client query. We could make this more random if we wanted, but this will suit our prototype just fine. Now if we refresh we see the data from our resolver:

Let's say in parallel we did some research and found out there was a site, everbase.co, that had a schema that perfectly matched our client query. What a coincidence! All we have to do now is update our client url and remove the @client directive from our query and voila, we have an app connected to real data.

By doing the work of setting up our client and mocking our queries out up front, we wind up laying a lot of infrastructure necessary to complete our application when the time comes. If you'd like to see our demo in action it can be found here, or you can check out the source here. If you'd like to do some further research the Apollo docs are a great resource. Thanks for reading!

Global Styling with Material-UI Theme Overrides and Props

Kelsey Leftwich — Tue, 14 Jul 2020 14:12:24 +0000

This article was originally posted on the Headway blog. Visit us at headway.io to see how we're making waves. 🏄‍♀️

One of the easiest and most common approaches to customizing Material-UI components is using props and classes for one-time use. These one-time-use components often evolve into reusable brand components. However, there's an alternative way you might overlook if you always reach for brand components.

In this article, we'll use global CSS overrides and default props in our theme to customize all instances of a Material-UI component in a project.

3 key advantages of this approach

Our code will be more concise.
It will make our component styling consistent across our application and more portable across projects.
We will avoid breaking the Material-UI components' contracts.

Brand Components vs. Theme Overrides and Props

What is a Brand Component? When developing apps with Material-UI, we often want to customize the appearance and behavior of Material-UI components. In customizing a component, we can make a "brand" component - meaning a Material-UI component with a thin component wrapper, applying classes, and setting props.

const styles = () => ({ ... });

const BrandButton = ({ classes, color, children }) => {

  return (
    <Button classes={classes} variant="contained" color={color}>
        {children}
    </Button>
  );
};

export default withStyles(styles)(BrandButton);

Brand components allow for reusability - but utilizing theme overrides and props has additional advantages:

Less code and fewer files

Component props are set in the theme's props and styles are set in the theme's overrides. This eliminates the need for brand component code and files.

More portable

When using brand components, if we want to use our customized components in another project, we have to move our theme and all our brand component files. When using theme overrides and props, we can simply move our theme.

Leaves the component contract intact

In the example above, the props we intend to accept from the component's user are color and children. If the component's user is familiar with Material-UI components, they might expect to be able to pass in a component prop with the value "a" so the component is an anchor tag that looks like a button because component is a valid prop on the Material-UI Button. The BrandButton won't do anything with the component prop because it isn't in its props list. This could cause frustration for the user and result in your needing to update the brand component.

TypeScript consideration

Material-UI has TypeScript support. If you wrap a Material-UI component in a brand component, you lose the component's TypeScript typing!

With the BrandButton, the type is a generic React FunctionComponent type:

When using the component directly and applying styles via theme overrides and props, the component type from Material-UI remains intact:

Create the Theme with a Palette

To begin our example project, we'll create a Material-UI theme and set our primary color to deepPurple and our secondary color to amber.

import { createMuiTheme } from '@material-ui/core/styles';

import { grey, deepPurple, amber } from '@material-ui/core/colors';

const theme = createMuiTheme({
  palette: {
    primary: {
      main: deepPurple[500],
    },
    secondary: {
      main: amber[500],
      contrastText: deepPurple[900],
    },
  },
});

‍

These colors will be employed whenever a component's color prop is set to primary or secondary.

Learn more about the Material-UI theme palette here:

https://material-ui.com/customization/palette/

Now that we have a basic theme, we can begin customizing the Material-UI Button, TextField and Tooltip components. We'll start with brand components and then accomplish the same customization using theme overrides and props.

‍

Style Button component

In our first example, we want to tweak the styles of the Material-UI Button component with variant contained and color props default, primary, and secondary.

<Button
  variant="contained"
  color="primary" // or color="default" or color="secondary"
>
  Click me!
</Button>

‍

The buttons look like this without any modifications. They employ the colors we defined in our theme's palette, but no other customizations have been made.

‍

We want to customize our buttons to look like this:

‍

*Here are the changes we want to make to the buttons:*

Make the corners square
Remove the uppercase text transformation
Remove the drop shadow
Change the background and text color of our primary button on hover to purple and amber
Make the text on the secondary button bold

First we'll make these changes using classes and props - then we'll move these customizations to the theme.

‍

Style the buttons using classes

We'll define styles for each of our three button color options (default, primary, and secondary):

import { deepPurple, amber } from '@material-ui/core/colors'

const styles = () => ({
  default: {
    borderRadius: 0, // makes the corners square
    textTransform: 'none', // removes uppercase transformation
  },
  primary: {
    '&:hover': { // changes colors for button hover state
      backgroundColor: amber[500],
      color: deepPurple[900],
    },
  },
  secondary: {
    fontWeight: 700, // make the text bold
  },
});

‍

Using withStyles, the styles we defined become classes that we can access in the Button component's props:

‍

const Buttons = ({ classes }) => { // this `classes` prop is made available by using withStyles below
  // I've left out Grid components below to make this easier to read

  return (
    <div>
      <Button
        variant="contained"
        color="default"
        className={classes.default}
        disableElevation // this prop disables the drop shadow on our button
      >
        Default
      </Button>

      <Button
        variant="contained"
        color="primary"
        className={clsx(classes.default, classes.primary)} // clsx joins these two classes (.e.g. "default primary")
        disableElevation // this prop disables the drop shadow on our button
      >
        Primary
      </Button>

      <Button
        variant="contained"
        color="secondary"
        className={clsx(classes.default, classes.secondary)} // clsx joins these two classes (.e.g. "default secondary")
        disableElevation // this prop disables the drop shadow on our button
      >
        Secondary
      </Button>
    </div>
  );
};

export default withStyles(styles)(Buttons);

‍

The complete file looks like this:

‍

import React from 'react';
import { Button, Grid, withStyles } from '@material-ui/core';
import clsx from 'clsx';
import { amber, deepPurple } from '@material-ui/core/colors';

const styles = ({ theme }) => ({
  default: {
    borderRadius: 0,
    textTransform: 'none',
  },
  primary: {
    '&:hover': {
      backgroundColor: amber[500],
      color: deepPurple[900],
    },
  },
  secondary: {
    fontWeight: 700,
  },
});

const Buttons = ({ classes }) => {
  return (
    <Grid container spacing={3}>
      <Grid item>
        <Button
          disableElevation
          variant="contained"
          color="default"
          className={classes.default}
        >
          Default
        </Button>
      </Grid>

      <Grid item>
        <Button
          variant="contained"
          color="primary"
          className={clsx(classes.default, classes.primary)}
          disableElevation
        >
          Primary
        </Button>
      </Grid>

      <Grid item>
        <Button
          variant="contained"
          color="secondary"
          className={clsx(classes.default, classes.secondary)}
          disableElevation
        >
          Secondary
        </Button>
      </Grid>
    </Grid>
  );
};

export default withStyles(styles)(Buttons);

‍

While this works, these modifications won't apply anywhere else in the app where we use the Material-UI Button component. We could make a "brand" component - but remember the drawbacks to that approach outlined earlier.

‍

Customize the buttons using theme props

In addition to passing a palette prop into createMuiTheme, we can pass in props and overrides. These properties on our theme allow us to make customizations that apply globally. Instead of setting the disableElevation prop on each Button component we use, we can set it in the theme's props and it will be applied globally.

const theme = createMuiTheme({
  palette: {
    primary: {
      main: deepPurple[500],
    },
    secondary: {
      main: amber[500],
      contrastText: deepPurple[900],
    },
  },
});

theme.props = {
  MuiButton: { // `MuiButton` is the global class name for the <Button /> component
    disableElevation: true, // this prop disables the drop shadow on all Buttons
  },
};

‍

We know disableElevation is a Button prop by looking at the API documentation for the Button component. We also know the default value for the prop is false. In our overrides, we'll set the value to true.

‍

Style the buttons using theme overrides

We can move the styles we defined into the theme using overrides.

theme.overrides = {
  MuiButton: {
    root: {
      borderRadius: 0, // square corners
      textTransform: 'none', // removes uppercase transformation
    },
    containedPrimary: {
      '&:hover': { // changes colors for hover state
        backgroundColor: theme.palette.secondary.main,
        color: theme.palette.primary.dark,
      },
    },
    containedSecondary: {
      fontWeight: 700, // makes text bold
    },
  },
};

‍

We want all of our buttons to have square corners and no uppercase text transformation. Looking at the CSS section of the Button API documentation, we see we need to target the MuiButton global class and root within it.

‍

We also know we have styles we only want to apply when the variant is contained and the color is primary or secondary so we look for those global classes in the documentation as well. We need to target MuiButton and containedPrimary and containedSecondary.

‍
‍

The description helpfully points out what combination of prop values results in the global class being employed:

‍

Now we can use the Button component anywhere in our app and these styles will be applied. We can remove classes and the disableElevation prop from the buttons in the Buttons.js file:

const Buttons = () => {
    // Grid components removed to make this easier to read
  return (
    <>
      <Button variant="contained" color="default">
        Default
      </Button>

      <Button variant="contained" color="primary">
        Primary
      </Button>

      <Button variant="contained" color="secondary">
        Secondary
      </Button>
    </>
  );
};

‍

What we've gained by moving from classes to theme overrides and props:

We've made the Buttons.js file more concise and therefore easier to read.
We're assured that we have our styles wherever we use a Button component with variant="contained" and color "default", "primary" or "secondary".
We can use our theme across projects, knowing these Button styles are included - without having to move over any component files.

Let's walk through another example by customizing a labeled input.

‍

Style TextField component

In our next example, we want to tweak the styles of the Material-UI TextField component.

<TextField label="Role or Title" placeholder="Developer" fullWidth />

‍

The TextField looks like this without any modifications. It employs the colors we defined in our theme's palette, but no other customizations have been made:

‍

We want to customize our TextField to look like this:

Here are the changes we want to make to the TextField:

Remove the label shrinking on focus
Make the label text uppercase and increase the font size
Increase the space between the label and the input box
Add a border around the input that turns purple, and is thicker on focus

‍

Style the TextField using classes

First, we'll define styles for our label and input by using the $ruleName syntax to target the input's focused state.

import { grey, deepPurple } from "@material-ui/core/colors";

const styles = ({ spacing, palette: { primary } }) => ({
  label: {
    textTransform: "uppercase",
    fontSize: "1.5rem"
  },
  input: {
    top: spacing(2),
    border: `1px solid ${grey[500]}`,
    outline: `1px solid transparent`, // we use a transparent outline here so the component doesn't move when focused
    padding: spacing(1),
    "&$focused": {
      border: `1px solid ${deepPurple[500]}`,
      outline: `1px solid ${deepPurple[500]}` // this outline makes our "border" thicker without moving the component
    }
  },
  focused: {} // we have to pass in this focused class to make the focused state rule above work
});

‍

Using withStyles, the styles we defined become classes that we can access in the TextField component's props. We disable the label "shrinking" to keep it in the top left corner by adding shrink: true to InputLabelProps object. We can also disable the input box underline by adding disableUnderline: true to the InputProps object.

‍

const TextFields = ({ classes }) => {
  return (
    <div>
      <TextField
        label="Role or Title"
        placeholder="Developer"
        fullWidth
        InputLabelProps={{
          shrink: true, // keep the label in the top left corner and don't shrink on input focus
          classes: {
            root: classes.label
          }
        }}
        InputProps={{
          classes: {
            root: classes.input,
            focused: classes.focused // we can't forget to pass this in or &$focused in our input class won't work
          },
          disableUnderline: true // remove the underline
        }}
      />
    </div>
  );
};

export default withStyles(styles)(TextFields);

‍

This is a workable approach, but has the "brand component" drawbacks we outlined above. Let's use theme overrides and props to achieve the same end.

‍

Customize TextField using theme props

Instead of using the InputLabelProps and InputProps on the TextField to disable the label shrink and input underline, we can set these props in our theme override. Now anywhere we use TextField, the label will be shrunk into place and the underline will be disabled without our having to set these in the component.

theme.props = {
  MuiButton: {
    disableElevation: true,
  },
  MuiInputLabel: {
    shrink: true, <---------
  },
  MuiInput: {
    disableUnderline: true,  <---------
  }
};

‍

When we set the disableElevation prop on the Button component, we referenced the Button API documentation. TextField is a component composed of multiple Material-UI components including InputLabel and Input. In targeting these components, we'll reference the InputLabel and Input API documentation.

We know shrink is an InputLabel prop by looking at the API documentation for the InputLabel component. We also know the default value for the prop is false. So in our overrides, we'll set the value to true. Likewise, we can reference the Input API documentation to see disableUnderline is a prop on Input and the default value is false - so we'll also set it to true.

Next we'll move the styles to the theme overrides.

Style the TextField using theme overrides

‍

theme.overrides = {
    /* Button overrides not included to make this easier to read */
  MuiInputLabel: {
    root: {
      textTransform: 'uppercase',
      fontSize: '1.5rem',
    },
  },
  MuiInput: {
    root: {
      top: theme.spacing(2),
      border: `1px solid ${grey[500]}`,
      outline: `1px solid transparent`,
      padding: theme.spacing(1),
      '&$focused': {
        border: `1px solid ${theme.palette.primary.main}`,
        outline: `1px solid ${theme.palette.primary.main}`,
      },
    },
        // we don't need `focused: {}` with overrides
  },
}

‍

By looking at the API documentation for the InputLabel, we know the label styles should be nested in root which is nested in MuiInputLabel.

‍

Likewise, the input styles should be nested in the root (which is nested in MuiInput). When we target the focused state in overrides, we don't have to set focused in MuiInput like we have to when using classes.

‍
Now we can use the TextField component anywhere in our app and these styles will be applied. We can remove classes and the InputProps and InputLabelProps prop from the TextField in the TextFields.js file:

const TextFields = () => {
  return (
    <div>
      <TextField label="Role or Title" placeholder="Developer" fullWidth />
    </div>
  );
};

‍

What we've gained by moving from classes to theme overrides and props:

We've made the TextFields.js file more concise and therefore easier to read.
We're assured that we have our styles wherever we use a TextField component.
We can use our theme across projects, knowing these TextField styles are included - without having to move over any component files.

‍

Style Tooltip component

In our final example, we want to tweak the styles of the Material-UI Tooltip component.

<Tooltip title="Lorem ipsum dolor...">
  Hover here for tooltip
</Tooltip>

‍

The Tooltip looks like this without any modifications:

‍

We want to customize our Tooltip to look like this:

Here are the changes we want to make to the Tooltip:

Add an arrow
Change the background and text colors
Add a border

‍

Style the Tooltip using classes

First, we'll define styles for our tooltip and arrow.

const styles = ({ palette: { primary } }) => ({
  tooltip: {
    backgroundColor: "#fff",
    border: `2px solid ${primary.main}`,
    color: primary.main
  },
  arrow: {
    color: primary.main
  }
});

‍

Using withStyles, the styles we defined become classes that we can access in the Tooltip component's props. We'll add an arrow by adding arrow as a Tooltip prop.

‍

const Tooltips = ({ classes }) => {
  const loremIpsum =
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";
  return (
    <Tooltip
      arrow
      title={loremIpsum}
      classes={{ tooltip: classes.tooltip, arrow: classes.arrow }}
    >
      <Typography variant="subtitle1" align="center">
        Hover here for tooltip
      </Typography>
    </Tooltip>
  );
};

export default withStyles(styles)(Tooltips);

‍

We can instead refactor, using theme overrides and props to make our code more concise and ensure consistency across the application.

‍

Customize Tooltip using theme props

Instead of using the arrow prop on the Tooltip to add an arrow, we can set this prop in our theme props. Now anywhere we use Tooltip, the arrow will be visible without our having to set the prop in the component.

    theme.props = {
  MuiButton: {
    disableElevation: true,
  },
  MuiInputLabel: {
    shrink: true,
  },
  MuiInput: {
    disableUnderline: true,
  },
  MuiTooltip: {
    arrow: true, <-----------
  },
};

‍

Style Tooltip using theme overrides

Next, we'll add our styles to the theme overrides. Based on the Tooltip API documentation, we know the classes to target are tooltip and arrow.

theme.overrides = {
    MuiTooltip: {
        tooltip: {
        backgroundColor: '#fff',
        border: `2px solid ${theme.palette.primary.main}`,
        color: theme.palette.primary.main,
     },
     arrow: {
       color: theme.palette.primary.main,
     },
    },
}

‍

Now we can use the Tooltip component anywhere in our app and these styles will be applied. We can remove classes and the arrow prop from the Tooltip in the Tooltips.js file:

‍

const Tooltips = () => {
  const loremIpsum =
    'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.';
  return (
    <Tooltip title={loremIpsum}>
      <Typography variant="subtitle1" align="center">
        Hover here for tooltip
      </Typography>
    </Tooltip>
  );
};

‍

We enjoy the same benefits here that we saw in the previous two examples - the code is more concise, our component stays consistent throughout the application, and we can move this styling across projects by simply copying over the theme.

To learn more, check out the resources listed below 👇🏻

‍

Source code

https://github.com/kelseyleftwich/mui-overrides

‍

Learn more about Material-UI customization

‍

Contact Forms with Netlify Serverless Functions

Chris Held — Tue, 23 Jun 2020 12:30:11 +0000

In this tutorial we're going to go over how we can quickly and easily stand up a site to collect form data using Netlify Forms. Instead of having to set up our own database or lean on a 3rd party integration, we can add some tags in our html, deploy to Netlify, and watch the magic happen. We don't even have to write any javascript!

To get started, let's setup a folder with a basic index page for our site. Create a folder called netlify-demo and create an index.html file inside. We'll include the styles inline to keep things simple and in one file:

<!DOCTYPE html>
<html>
  <head>
    <title>Big Thing - Sign Up!</title>
    <meta charset="UTF-8" />
    <style>
      main {
        margin: auto;
      }
      body {
        display: flex;
      }
      form {
        display: flex;
        flex-direction: column;
        margin: auto;
      }
      input,
      button {
        padding: 15px 8px;
        margin: 4px 0px;
        font-size: 16px;
      }
      input {
        flex: 1;
      }
      button {
        flex: 1;
        background-color: #555555;
        border: none;
        color: white;
        text-align: center;
        text-decoration: none;
        display: inline-block;
        font-size: 16px;
        cursor: pointer;
      }
      h1 {
        text-transform: uppercase;
        text-align: center;
      }
    </style>
  </head>

  <body>
    <main>
      <h1>Big things are coming</h1>
      <form method="POST">
                <input required name="email" type="email" placeholder="Enter your email..." />
        <button type="submit">Subscribe for Updates</button>
      </form>
    </main>
  </body>
</html>

In order for Netlify to see our form and know to collect it's data, there are a few alterations we have to make to our form element:

      <form name="contact" method="POST" netlify>
        <input required name="email" type="email" placeholder="Enter your email..." />
        <button type="submit">Subscribe for Updates</button>
      </form>

Let's take a closer look at the form element:

<form name="contact" method="POST" netlify>

This is where the Netlify magic goo is. Adding netlify will tell the Netlify servers to store submissions for our form. We've also added a name attribute so Netlify knows what to call it, and in case we ever have multiple forms on this page.

Now that our site is ready to go, let's get set up on Netlify. From your dashboard on app.netlify.com, drag your netlify-demo folder into the dropzone. This will spin up your site on Netlify. It should go pretty fast since we're just sending one static file.

After your site is uploaded you'll be taken to the site's page, which will have the url for your deployed site:

Head over to your site and fill out the form. You'll notice after you submit you receive a generic success modal saying your submission was received. Back on Netlify, if you select the 'Forms' tab, you'll see a list of active forms, with your contact form the only one in the list. If you click into the contact form you should see your submission.

This is already a very useful tool to capture data, but you can also set up notifications on form submission. From the Forms tab, select Settings and Usage and scroll down to the Form Notifications section. From there you can add email, slack, or webhook notifications that will alert you when you receive new submissions.

If you'd like to learn more about using forms with Netlify, check out their docs on the subject. There are good resources there if you're using something like Gatsby or React and want to utilize the same technique.

Javascript Logging Tips and Tricks

Chris Held — Thu, 21 May 2020 00:21:16 +0000

console.log and debugger are probably the most common examples of debugging front end applications. Though log is the most common console function, there are a few others that you can leverage in your application for more descriptive and useful logging. In this post I'm going to cover a few extra functions you may not know about in the console object.

Styled Logging

In addition to console.log, there are a few functions to make your logging more semantic. console.info, console.warn, and console.error can apply some extra styles to your log statements and make your code a little bit more descriptive:

Assertions

If you need to conditionally log an error, console.assert takes an expression and will log an error if the assertion is false.

Tables

If you're logging table data, instead of using console.log(data), consider using console.table(data). console.table optionally accepts a second argument that lets you specify what columns you'd like displayed.

Custom Styles

Info, warn, and error are a nice way to add some canned styles to your logging statements, but if you're looking for a little more control, console.log accepts a second argument that allows you to style your log statements using CSS:

If you'd like to learn more, the full MDN reference is a great resource.

Explaining Javascript Reduce

Chris Held — Thu, 14 May 2020 16:07:51 +0000

The javascript reduce function is a great way to keep your code immutable to prevent (or "reduce", har har) surprises later on, but the syntax is kind of arcane looking and most of the examples online are for extremely simple cases like aggregating numbers.

Let's say we have an array of objects that need its ids mapped to an array:

const selected = rows.map(row => row.id)

Now let's add another wrinkle. These rows can have any number of children, and their ids have to be added as well (let's save children of children and recursion for another post). One thing we could do is keep the original selected array and loop through rows to push children ids onto it:

let selected = [];
rows.forEach(row => {
  selected.push(row.id);
  if (row.children) {
    row.children.forEach(child => {
      selected.push(child.id);
    });
  }
})

That'll work, but we've got a nested loop there, and mutating the array could introduce bugs. Another option is to use javascript's reduce function:

      const selected = [
        ...rows.map(row => row.id),
        ...rows.reduce((accum, row) => (
            row.children ? [...accum, ...row.children.map(c => c.id)] : accum
          ), 
          []
        )
      ];

There's a lot going on here, so let’s step through:

      const selected = [
        ...rows.map(row => row.id)

This part is pretty straightforward, we create a new array and use the spread operator to put our original array there (since we still want all of the parent rows):

        ...rows.reduce((accum, row) => (
            row.children ? [...accum, ...row.children.map(c => c.id)] : accum
          ), 
          []
        )

This line is where we make use of the reduce function. Reduce loops over our array of rows and calls a function for each one. The function has two arguments, the current row object and an accum or “accumulator” parameter that is whatever was passed from the last invocation of the function.

In our function we’re checking if this row has children, and if it does we’re using the spread operator again to return a new array containing what we’ve accumulated thus far plus the ids of any of this row’s children. If there are no children, we just return what we were passed in as the first argument, since we want to keep potentially adding to that value.

Something that is often overlooked is the last argument passed to the reduce function is the initial state of the accumulator (an empty array in our above example). If it’s not initialized it starts as undefined, which can result in some errors or bizarre behaviors.

One last important point about reduce is that it can be hard to read and process mentally, especially when either a new person is taking over a feature / codebase or you're coming back to it after a long break. In the case here reduce solves our problem without causing too much mental overhead, but sometimes opting for another solution will make life much easier for future you.

React: Optimize Components with React.memo, useMemo, and useCallback

Chris Held — Sun, 10 May 2020 14:41:55 +0000

This article was originally posted on the Headway blog. Visit us at headway.io to see how we're making waves. 🏄‍♀️

In most cases, React performance is not something you need to worry about. The core library does a ton of work under the hood to make sure everything is rendering efficiently. However, occasionally you can run into scenarios where your components are rendering more often than they need to and slowing your site down.

‍

Let's look at an example:

const ListPage = ({data, title}) => (  
  <div>  
    <Header title={title}/>  
    <List listItems={data}/>  
  </div>  
)

‍

In this example, any changes to data will cause ListPage to re-render all of it's child components, including the Header component, even if title didn't change. The Header will render the same result given the same props, so any render with the same props is not necessary. In this case it's probably not a big deal, but if <Header/> was performing some expensive computation every time it rendered we would want to make sure it was only rendering when necessary.

‍

Thankfully, there are a few ways to optimize for this scenario.

‍

When using class based components, PureComponent will return the last rendered value if the passed in props are the same. There is also a shouldComponentUpdate function for more fine tuned control. When using functional components, React provides three methods of optimization that this article will be focusing on: React.memo, useMemo, and useCallback.

‍

React.Memo

React.memo is a higher order component that memoizes the result of a function component. If a component returns the same result given the same props, wrapping it in memo can result in a performance boost. Take our <Header/> example earlier.

‍

Let's say it looks something like this:

const Header = ({title}) => <h1>{title}</h1>

export default Header;

‍

We can see that this component isn't going to need to be rendered unless title changes, so it would be safe to wrap it in React.memo.

‍

const Header = ({title}) => <h1>{title}</h1>

export default React.memo(Header);

‍

Now, whenever Header is rendered, it will do a shallow comparison on it's props. If those props are the same, it will skip rendering and instead return it's last rendered value.

‍

A quick note about using memo and react dev tools. At the time of this writing, wrapping your component like this...

‍

const Header = React.memo(({title}) => <h1>{title}</h1>));

export default Header;

‍

...will cause your component to show up as Unknown in react dev tools. To fix this, wrap your component in memo after defining it, like we did previously:

‍

const Header = ({title}) => <h1>{title}</h1>;

export default React.memo(Header);

‍

useMemo

useMemo allows you to memoize the results of a function, and will return that result until an array of dependencies change.

‍

For example:

const widgetList = useMemo(  
  () => widgets.map(  
    w => ({  
      ...w,  
      totalPrice: someComplexFunction(w.price),  
      estimatedDeliveryDate: someOtherComplexFunction(w.warehouseAddress)  
    }),  
  ),  
  [widgets],  
);

‍

In this example, a component receives a list of widgets. The widgets coming into the component need to be mapped to include total price and an estimated delivery date, which uses some kind of complex and expensive function. If this component renders and the value of widgets is the same, there is no need to run those expensive functions again.

‍

Using useMemo will memoize the result, so if widgets haven't changed since the component's last render it will skip the function call and return what it got last.

‍

useCallback

useCallback can prevent unnecessary renders between parent and child components.

‍

Take this example:

const Parent = () => {  
  const [showExtraDetails, setShowExtraDetails] = useState(false);  
  return (  
    [...]  
    <Child onClick={() => { showData(showExtraDetails); }/>  
    [...]  
  );  
}

‍

This component will cause Child to re-render every time Parent does, even if Child is a PureComponent or wrapped in React.memo, because the onClick will be different every render. useCallback can handle this situation like so:

‍

const Parent = () => {  
  const [showExtraDetails, setShowExtraDetails] = useState(false);  
  const handleClick = useCallback(  
    () => {  
    showData(showExtraDetails);  
  },  
  [showExtraDetails],  
);  
  return (  
    [...]  
    <Child onClick={() => {handleClick}/>  
    [...]  
  );  
}

‍

Now handleClick will have the same value until showExtraDetails changes, which will reduce the number of times Child renders.

‍

Things to consider with optimization in React

A word of caution around premature optimization. React is typically fast enough to handle most use cases without resorting to any of these techniques. I would advise you to build your components without any optimization first, and look into adding performance enhancements only when necessary.

‍

Resources to learn more

If you'd like to explore these APIs further, here are some resources to help give you a better understanding.

React.memo

useMemo

useCallback

If you're looking to further optimize your React application, the react docs contain a great section on performance.

Tips for Managing Projects with Remote Development Teams

Andrew Stuntz — Fri, 08 May 2020 17:17:51 +0000

This article was originally posted on the Headway blog. Visit us at headway.io to see how we're making waves.

In this article, we share guidelines and advice for remote software development teams to more effectively manage and complete projects. These guidelines help ensure that remote meetings, communication, and team projects are productive, even when they happen remotely.

In March of 2020, Headway held a live stream with our team to discuss how product teams can work remotely successfully. We planned on having this online event long before the world migrated to mostly online work environments in the spring of 2020.

Headway's remote-first approach to managing teams, holding meetings, and running projects eased our transition. We hope that sharing our experiences and advice will help others build best practices for creating more impactful remote teams.

What we'll cover

Best practices for remote meetings
Remote project management and task prioritization
Remote communication tools
Remote collaboration tools
Leading and managing your team

Best practices for remote meetings

Due to the nature of remote work, it can be frustrating for remote workers to be involved in meetings that happen "in-house". At Headway, all meetings are remote-friendly - even when there are folks in the office. Remote friendly meetings have a few things in common:

1. Cameras on

For complex conversations, having a voice conversation is better than using Slack. And having your camera on is even better. Humans are very in tune with body language, and that includes body language over video calls. Encourage your team, and any project partners, to turn their camera on. This builds trust and improves the overall relationship. And better relationships create better products.

2. Headsets on

Clear audio creates clear communication. The best calls happen when everyone has headsets. It results in less delay when talking into the mic and most headsets filter noise around you better than the mics on your laptops.

Our team uses Jabra headsets to improve audio communication.

3. Mute when not speaking

This is a great way to prevent any disruptions from your end while others are speaking. It can prevent you from butting in before they finish a thought and prevents everyone from hearing you sneeze or cough at random. This is especially helpful if you are in a busy environment. Whether your kids are at home or you're working from a coffee shop, be kind and mute your microphone when you're not speaking. When in doubt, mute yourself.

4. Face your camera

In today's age, many of us have multiple monitors - but if you can't see my face, you're probably not going talk to me in the same way. Don't be scared or nervous. It's a little unnerving watching yourself on the camera the first few times, but trust me, you'll get used to it. The more you engage with each other, the stronger your relationships become.

5. Better lighting

Being seen in the right light is important too. Don't be the creepy person backlit by your window. Try to have light sources in front of you. If there are bright lights behind you, turn them off or reposition your desk in the room so that your face is lit more than your back.

6. Stay on track

It can be really easy to get into the weeds and talk in circles. Just like any other meeting, hold each other accountable, and respect each other's time. You can do this by having an agreed agenda at the beginning of the meeting or designate someone to help lead the group if they notice the meeting is getting off track.

Remote project management for developers

As a remote-first consultancy, Headway works on a wide variety of projects. We work with new startups, established startups, and enterprise businesses. One of the most challenging things to do with a product team is handling project management. With the right tools, you can make the process easier.

Project and product documentation

Having a collaborative resource for documentation will make a big impact on remote teams. We use Notion for documenting everything we do. It keeps everything we need accessible, secure, and easy to share.

Benefits of project documentation

Templates create consistency
Creates alignment across the team
Provides a singular source of truth
Successful project hand-offs

Learn more about Notion

Prioritizing feature development

Headway uses MoSCoW prioritization to manage feature development for products that we build. It allows project stakeholders to clearly understand what work will happen, when it will happen, and why on their product at any given time.

Learn how Headway prioritizes feature work:

Prioritizing Your Product Features with the MoSCoW Method

Managing feature development with Stories on Board

We use a tool called Stories On Board for roadmap prioritization. It helps bring the product, design, and development together and is an excellent compliment to the MoSCoW method. It provides a clear view of what is getting done, when it is getting done, and compliments agile development methods.

This storyboard tool isn't an issue tracker. Translating storyboard cards into usable tickets for a developer takes work. We don't always work with project managers, and often the role of our lead developer or designer includes project management. This is why our tools and consistent process are imperative to our success. Providing consistency for one another is critical.

Learn more about Stories On Board

Managing development projects tasks

Across all our projects, we decompose storyboard items into more consumable tickets to work in and often use a separate tracker for issue tracking. Success starts with having the right tools to achieve your goals and stay on track. Every project has different needs either because of its nature or because of the client's requirements. Here are the tools we have used to manage tasks as a team.

Task management tools we recommend

Birdseye - We're building it

Understand your needs

Our projects use different issue trackers at Headway. Depending on the clients and partners involved, the tools can change. We have used Github issues, Trello, Asana, and Jira to track project work. The important thing here is not which issue tracker you decide to use. It's how you decide to use it.

It's important to keep issues up to date and as a remote developer. This is because I can't just stop by a PM's office or a teammate's desk to see how things are moving. The place we must look at is the issue tracker.

We often include it in our Github pull request templates to make sure you check off the ticket (or update the ticket to the appropriate state) in whatever issue tracker you are using. We rely mostly on the following states: "started", "doing", "done" and sometimes we will add in "confirmed" or something else to make sure it passes through QA without any issues. It's easy to share and see what other folks are doing that way.

Communication tools for remote developers

Tools we recommend

Slack

We use Slack as our main tool for asynchronous communication. It allows us to separate and track conversations for different projects and have quick questions answered with individuals as needed. You can even hop on a quick slack call if needed.

Learn how Slack works

Zoom

We use zoom when we schedule formal meetings or when we need to go into a deeper conversation about an issue together. We also record meetings to create accountability between project partners and document meetings in case they ever need to be revisited.

Learn more about Zoom

Asynchronous communication

Struggling to communicate decisions across members of different teams is a shared failure I've seen many times. Keeping each member up to date on what is happening when and where has always been a challenge. It's one place where remote work shines.

Creating a source of truth with Slack

Headway uses Slack to facilitate our asynchronous communication. There is no siloed communication about development, design, or process as we all make those decisions by working in Slack. Even if it's easier to have communication outside of Slack or using a Zoom room. Slack is the tool we use to broadcast those decisions.

When I take a day off, the first thing I do when I return is to read through Slack messages. This allows me to catch up on decisions that were made, work that is inflight, and issues that came up while I was gone.

https://youtu.be/pQcN1xO7RdA

Using channels in Slack

Since you are unable to have one-off conversations or "just stop by" someone's desk, you have to focus on communication in other ways. An asynchronous tool like Slack solves this naturally with channels. Since there is a log of all communication and decisions being made, it's easier to communicate, discuss, and collaborate.

That means no more email forwards and weird gaps in the conversation.

When a decision is made in a Slack channel, it not only drives the decision in a way that all teammates can see and chime in on. It also lets everyone read that communication when it makes sense for them as well.

You no longer have to worry about getting everyone into a meeting or having a face to face conversation with a product owner because as long as they're in the channel, they will see or read about the decisions that have been made. Decisions can and should also be pulled out of Slack and included in project management tools. This provides the historical context you can link to in the slack conversation. This allows everyone to catch up on the project on their schedule and when it's convenient for them.

Not sure how to begin?

Check out this article for getting started with Slack channels:

How to use Slack channels to organize your work life

Managing notifications and distractions

If you don't manage it correctly, Slack can be overwhelming. It can be very intrusive into your life with constant pinging and constant updates.

Don't be scared to turn notifications off.

I usually spend at least half of my day with "Do Not Disturb", on my computer. This allows me to check Slack on my schedule and since it's asynchronous communication, you check for updates when it makes sense for you.

Another strategy is to turn off notifications unless someone explicitly mentions you in Slack. This can be helpful if you're in a Slack channel that sees heavy use but you're not directly involved. Or if you just don't want notifications every time someone mentions something.

Remote whiteboarding tools and collaboration

Besides communication tools like Slack and Zoom, we use a plethora of other tools to make our experience working together optimal. I often hear that teams moving to work remotely have a hard time communicating when they don't have a whiteboard. There are some great tools to help solve this problem.

Sharing ideas visually

One big push back many folks have about working remotely is the lack of being able to have "whiteboard sessions" or collaborate with their peers in a visual manner. So-called "whiteboard sessions" are often used to quickly better understand problems, scope, or hard to visualize patterns. As a developer it can be really tough to communicate your thoughts in writing. We have found a few tools that really allow us to communicate visually virtually that have, on occasion, saved the day.

Whimsical

From a development standpoint the first tool that I reach for is Whimsical. Whimsical allows you to draw mind maps, wireframes, and flow charts quickly with your team. Whimsical allows you to think and communicate visually without too much friction. Whimsical gets used for architecture, code organization, process management, and quick and dirty UI flows.

Learn more about Whimsical

Miro

The other tool we reach for at Headway is Miro, Miro is team collaboration software that feels like more like we are collaborating on a whiteboard. It's great for brainstorming, planning, and user story mapping. It's easy to use, fast, and extremely collaborative. Often we'll leave Miro up during meetings just to share notes. Then we can organize those notes together after the meeting.

Learn more about Miro

Between Miro and Whimsical rarely am I unable to feel like I'm missing out on collaboration without a whiteboard. Using these tools is often more collaborative, no one is hogging a marker, you can't run out of whiteboard space, and there almost infinite ways to move work into different formats for different learning styles. Another benefit is there is no "translating" step. It's already in a digital format.

Remote pair programming tools

From an integrated development environment (IDE)

As developers, we use quite a few tools to make remote collaboration with one another an easy experience. The most popular tool we use at Headway for remote pairing is Tuple.

Tuple is a screen sharing software built for developers. It allows a seamless screen share and has lots of options for the way to interact with your pairs screen. Tuple also has excellent screen annotation tools. It's the best option for pairing when developers are working in an IDE.

Learn more about Tuple

Without an IDE

If you're working on a remote server or like the idea of working from a remote server and working outside of an IDE (like using Vim) we use wemux. Wemux is a tool built with tmux that allows pairing through a remote server. It is very customizable and easy to use once it's set up. Though, if you don't already use tmux and a modal editor like Vim this one is a tough sell.

Learn more about Wemux

Headway developers are encouraged to learn Vim and Tmux as we think they are valuable tools and we can hone our craft by sharpening out tools. When we each sharpen our tools, we own that process and empower ourselves to work smarter not harder.

Headway developers have collaborated on an incredible Vim setup. Thanks Jon Kinney! It is available via open-source below.

See our Vim and Tmux Setup

Git and pull requests (PR)

You probably already use version control of some sort. We like to leverage the tools we already have on hand. Git provides a great framework for documenting the "story" of your code and we make sure that our commit messages and branching schemes match the "story" of our software as we build. Over time this allows us to use Git to understand better how our software is built, what went on in specific pull requests, and how certain features were added.

I also like to use pull requests to communicate what kind of work I'm doing. I encourage those on my team to do the same. The intent of a pull request is not to present work that is "finished" and to be added to the code base after a quick code review. The intent is to communicate the code that you are writing to the other developers to ensure that everyone agrees on the structure, libraries, and other important decisions you have made in your code. You're already going to open the PR regardless. You might as well get feedback sooner than later.

Learn more about Git and pull requests

Other options

The final tool we often use for sharing terminals with other developers is Tmate. Tmate allows you to share your terminal and ssh into another developer's terminal.

At Headway, we reach for tmate when we need to do something quick and dirty or just need someone's help for a few moments. When we have serious pairing sessions, we'll join a Wemux and happily code with everyone. Both Wemux and tmate are easy to set up and provide a lot of customization. They're great for sharing development work.

Learn more about tmate

Leading and managing your team

While process and approach can be powerful, people are the true heroes that bring projects to completion. Helping every person on your team grow to become better communicators and team players is vital.

We all have a responsibility to lead each other, even if that's not in our title.

The human element of project management is not easy or simple, but if you make efforts, you will see improvement. Below are some of the tools we use to gain a better understanding of each person on our team and how we can all work better together.

Lead Honestly

Lead Honestly is an automated tool that helps our leadership team have candid conversations about certain topics based on the person's needs. Questions are sent out once a week for our 1-1 meetings that last about fifteen minutes. These help us uncover many issues before they become a big problem. They also help each leader get to know each team member better on a personal level because they are dedicating time to that.

Learn more about Lead Honestly

Tools to understand your team

We use a few different approaches to understanding each individual on our team and how we can work better together. From personality traits, key motivators, and how people take action. The friendly folks at Navigate the Journey help us manage these efforts. Below are the tools we use to do that.

Assessments to better understand your team

DiSC Profiles

Motivational Core: MCORE Assessment

Kolbe A Index Assessment

Improve your retrospectives

Taking the time to review how what went well and what didn't go well in a project helps you continuously improve your process and relationships within a team. We wrote an article all about it. If you're interested, check out the link below.

Level Up Your Development Team with Better Agile Retrospectives

Find what works best for you and your team

The key is to take the time to evaluate the tools and methods you have and to not be afraid to try new approaches. While these tools and techniques that have worked for us, they may not be the best fit for you and your team. Our tools change as we identify issues or needs with our team or when new technologies are available. Don't be afraid to try something new.

Start small to experiment

Rather than getting everyone on a new tool, try a small team first. Listen to your team and share experiences together. See what results you get. This lowers the risk in case you don't see a positive impact. It can be hard to get a whole team onboarded to new ideas or products, but that's where leadership comes in. Become an advocate for the tool and celebrate the positive results together.

Level Up Your Development Team with Better Agile Retrospectives

Andrew Stuntz — Mon, 30 Mar 2020 21:30:30 +0000

One of the best parts about creating great software is getting to collaborate with others. It's also one of the hardest things to get right. The best software developers are not the 10x developers who know how to build everything themselves. They are the team players who know how to be a force multiplier for all the other people involved with a project.

In Agile methodology, a retrospective is run at the end of each sprint. When run properly, with a willing team, a retrospective accomplishes the core mission of enhancing collaboration across a development team and increasing the overall efficacy of the development process.

Retrospectives allow a team to identify and discuss issues within a project and work together to solve those issues.

What is the goal of a retrospective?

Retrospectives (i.e. retros) are meetings that generally uncover three things:

What went well during the sprint?
What didn't go well?
What could be done better next time?

These seemingly simple questions have a huge impact on team morale and cohesion and help teams refactor their process by learning from past mistakes and growing together.

“Greatness is not a function of circumstance. Greatness, it turns out, is largely a matter of conscious choice, and discipline.”

Jim Collins: Good to Great

Chances are, a team is a mix of different skill levels, aptitudes for social interaction, and hopefully different backgrounds. It is said that diverse teams build better software, but how does a team learn to gel? How do people know the right feedback to give or when to give it?

What happens when:

A project or week doesn't go well?
Rifts begin to build in teams?
People get angry or frustrated and have unproductive disagreements?

It would seem like stopping everything to address those concerns would make sense - however, the feature requests and bug reports don't stop, and the team still needs to deliver effective software. If left unaddressed, those ragged edges will continue to fray and eventually pull teams apart. So what's the solution? While not a silver bullet, sprint retrospectives are a great place to start.

Make retrospective meetings more productive

Meetings can often have too much unhealthy agreement vs. healthy disagreement, with retros commonly falling into the former.

So what are the pieces that need to come together for an effective retro?

Set ground rules

Instead of jumping right to the formal retrospective questions above (which can often lead to blank looks or tacit agreement), start by laying the ground rules. This frames the conversation and sets up people to think about the conflict before it starts.

Here are some ground rules that are helpful to establish:

Be respectful

Creating software and building products is much more than just putting in time and money, and having excellent features come out. Everyone is on the same team - work together, respect one another, leave egos at the door, and enter each retro with a growth mindset.

What's said in a retro stays in the retro

Retros are the time and place to push people to be their best selves, be critical, and talk about how certain behaviors impacted the team. It's a safe space to ask for help and identify areas of improvement. It's also best practice to not keep audio/video recordings, and clarify that notes of the meeting will be shared between the meeting attendees only.

The goal is to work on the process

When developers write software, it's a reasonably personal endeavor - and sometimes they feel other people are blocking their work. But it's important to realize everyone is on the same team, and it's not the time or place to make things personal. Questions about code quality are not the point of a retro and should stay in respectful code reviews.

Stay on track

In general, retros should be around an hour. Software developers are well known for "solutionizing" and over-engineering. But the goal of a retro should be to suss out issues - not come up with solutions to every problem. It's easy to break down the first problem that is presented and spend the rest of the meeting coming up with a solution. Instead, note the issues and move on. Problems that require follow up will become apparent, and solutions for those issues should happen in a separate meeting.

Focus on unity

It should go without saying that projects are more effective when team members feel safe to share their experiences and have a desire to work on growing together. Retros are not a place for anger or decision making by seniority. All ideas should be on the table, and nothing should be shot down without healthy discussion. Effective retros will elevate the entire sprint process by helping the team to work with, and not against, each other.

"If you could get all the people in the organization rowing in the same direction, you could dominate any industry, in any market, against any competition, at any time."

Patrick Lencioni

Have a prepared facilitator

The facilitator should guide the meeting intentionally, not letting any one person or topic dominate the discussion in an unhealthy way. This process can often be difficult when team members are invested in their issue or point of view, resulting in lots of discussion on how to move forward. The goal here is to make sure everyone is heard and divert conversations that aren't immediately applicable to future actionable items.

The bottom line - if the facilitator senses unnecessary discussion, off-track topics, or that things are going too far, they need to get the meeting back on track.

Have actionable takeaways

It's not enough to write items down and never revisit them. Each action item should either be assigned to an individual or put in place as a new standard for the team. That way rather than only reminiscing on the tough parts of the last sprint, having clear action items and assigning them to the right people will leave everyone feeling empowered, excited, and with a sense of forward momentum. Write action items down during the retro and review them at the end to get buy-in and a sense of shared team accountability.

When retrospectives don't go well

That all sounds great...but in reality, it's not always that cut and dried. What are some common reasons retros don't go as planned?

Retros are an afterthought

This is the most common reason given from people who don't like retros. When they seem like an afterthought and little time is spent on them, of course, they aren't well received. But, just like many things in agile, the important part of sprinting is taking action to correct issues over time - not letting those issues continue sprint after sprint.

There are no effective outcomes to the retro

Retros provide a format for everyone to be heard on a development team. Sometimes being heard is enough, and retros can provide a safe space to vent. But some issues are more critical than others and require action to be taken - sometimes immediately. If those issues aren't taken seriously and no corrective measures are put in place, it can feel like a lot of wasted effort. Keeping good notes and writing down action items is a good first step to combat this issue.

There are zero or few issues brought up from the retro

There are always problems - no matter how many people tell you that everything is peachy, things can always get better. For teams that haven't seen a retro before, or have seen ineffective retros, there can often be a propensity to just ignore issues because "nothing changes".

Refresh your retros with new ideas

The solutions to these problems are not to stop doing retros. It's rare to hear, "the process is perfect, we should never change it" in any development project. So what are some ways to approach retros in new ways and unlock a better process?

Start with a light question

Developers are often stuck working in their own world. They often have to stretch their comfort zones to work well with others - but it can be hard to connect with everyone, and some people on the team may be less outspoken. One way to help set the tone is to ask an ice breaker question or a question focused on feeling. People open up more and are better able to give/receive criticism when they feel they are in a safe and trusted environment.

Some suggestions for kicking off the meeting:

Ask for a "feel color" (i.e., red if things are going terribly, green if things are going great)
Ask about weekend plans
Other ice breaker topics that can get the room talking

Change the facilitator

In the capital "A" Agile methodology, retros are supposed to be run by a scrum master. However, this choice can result in lower than ideal participation - especially if no action occurs. This meeting should not be hogged by a team lead or someone "up above" - this is to help developers increase efficiency. One way to encourage the team to be open and have a growth mindset is to have one of the developers to facilitate the meeting.

Ask for feedback before the retro

If there is a group of non-participants, it can be helpful to ask those people to write their opinions down before the retro. Then at the meeting, ask those people to share what they wrote down prior. This goes a long way to increasing participation from people who feel they can't share at the moment or need more time for preparation.

Retros at Headway

Retrospectives are crucial for us here at Headway. They not only help us hone our process and continuously improve each week as we work to bring new ideas to market - they also help improve relationships with clients and partners, and in turn, help us build better products.

Retros fit well with our Guiding Manifesto and are imperative to ensure that we grow together, rather than separately. While we still spend time individually improving ourselves and enhancing our craft, retros let us do that as a team - which improves our ability to deliver software together on a sprint by sprint basis.

Free Download - Project retrospective template

This is the retro document we use at Headway. We hope you'll give it a shot! If you find it useful, feel free to share it with your friends and colleagues.

Template for Retrospective Meetings

Thanks to Amy Marco for encouraging me to explore team building and for the structure of the awesome retro document that I continue to use to this day.

Building a SVG Line Chart in React

Kelsey Leftwich — Mon, 30 Mar 2020 15:54:20 +0000

This article was originally posted on the Headway blog. Visit us at headway.io to see how we're making waves. 🏄‍♀️

In this article, we're going to build a line chart using SVGs and React. There are thousands of chart packages available via NPM, but I decided to build one from scratch.
‍

Why build a line chart from scratch?

The effort to create this simple chart from scratch would be the about the same amount of effort as customizing a library chart.
You don't have to add another dependency to the project.
Gain a better understanding of how line charts function.

My suspicion that I could create a chart fairly easily myself was confirmed in seeing that my finished chart component is fewer than 200 lines of code.

Visual aids to stay organized

As I developed this component, I created a series of diagrams to record the various values and expressions needed to render the chart component. A handful of figures - chart width, chart height, and desired padding - are the basis for laying out axes, guides, points, and labels.

Having a visual aid helped me to keep them organized and ensure the formulas to lay out chart components are accurate. I used LucidChart but you can use any charting software or even a paper and pencil.‍
‍

Setting up the container padding and the X and Y chart axes

Let's start with the container and chart axes. The first diagram consists of a box representing the chart in a container with padding. I labeled the corners of both boxes with expressions of how to calculate the XY coordinates. The expression variables use the container's height, width, and padding as variables. The height and width are passed in as props to the component.

The padding is calculated by adding the font size of the SVG component and the number of digits for the maximum X value from the data and multiplying the product by two.

‍

padding = (font size + max(x) number of digits) * 2

‍

With these expressions, I can draw the chart's axes:

const Axis = (points) => (
  <polyline
    fill="none"
    stroke="#ccc"
    strokeWidth=".5"
    points={points}
  />
)

// Axis start point: (padding, height - padding)
// Axis end point: (width - padding, height - padding)
const XAxis = () => (
  <Axis
    points={`${padding},${height - padding} ${width - padding},${height -
      padding}`}
  />
);

// Axis start point: (padding, padding)
// Axis end point: (padding, height - padding)
const YAxis = () => (
  <Axis
    points={`${padding},${padding} ${padding},${height - padding}`}
  />
);

Plotting points and connecting them with lines

With the chart area set up, we'll want to start plotting points and connecting them with a line. I added a point to my diagram with expressions of how to calculate the XY coordinates for any element from the dataset. The expressions use the element's X and Y values and the container's height, width, and padding.

With these expressions we can map the data to coordinates for an SVG polyline:


const data = [
  { label: 'S', x: 0, y: 0 },
  { label: 'M', x: 1, y: 4 },
  { label: 'T', x: 2, y: 3 },
  { label: 'W', x: 3, y: 1 },
  { label: 'TH', x: 4, y: 4 },
  { label: 'F', x: 5, y: 5 },
  { label: 'S', x: 6, y: 4 }
];

/*
    data.map(e => e.x) returns an array of only the x values:
            [0, 1, 2, 3, 4, 5, 6]
    then we spread this array in the Math.max function so the 
        values in the array can be used as arguments for the function

    we repeat these steps for the y values in data
*/
const maximumXFromData = Math.max(...data.map(e => e.x));
const maximumYFromData = Math.max(...data.map(e => e.y));

const points = data.map(element => {
    /*
    map over each element in the data array and 
    calculate the x and y values for the SVG point
    */

    const x = (element.x / maximumXFromData) * chartWidth + padding;
    const y = chartHeight - (element.y / maximumYFromData) * chartHeight + padding;

    return `${x},${y}`;
}).join(' ');

‍

Making the chart easier to read with guides

To make our chart easier to read, we will add guides. I started by adding horizontal guides to my diagrams. To lay out a guide, it needs a calculated ratio of the index of the guide plus one to the number of desired guides:

‍

ratio = (index of guide + 1) / number of desired guides

‍

The ratio is then used in calculating the y coordinate of the horizontal line:

The x coordinate for the start of the horizontal guides is the padding value. The x coordinate for the end of the horizontal guides is the width of the canvas minus padding.


const HorizontalGuides = () => {
    const startX = padding;
    const endX = width - padding;

    /*
        Array(n) creates an array of n length and 
        fill(0) fills the created array with zeros
        so we can map over it
    */
    return new Array(numberOfHorizontalGuides).fill(0).map((_, index) => {
      const ratio = (index + 1) / numberOfHorizontalGuides;

      const yCoordinate = chartHeight - chartHeight * ratio + padding;

      return (
          <polyline
            fill="none"
            stroke={'#ccc'}
            strokeWidth=".5"
            points={`${startX},${yCoordinate} ${endX},${yCoordinate}`}
          />
      );
    });
  };

‍

I added vertical guides to my chart, using the same ratio calculation used in laying out the horizontal guides. In the vertical guides, the ratio is used to calculate the x coordinate for the guides:

‍

The y coordinate for the start of the vertical lines is equal to the padding. The y coordinate for the end of the guides is equal to the height minus padding.

‍

Note:

For the vertical guides, the number of guides is set to the number of data points minus one if the number of desired vertical guides is not passed in to the LineChart component as a prop.

‍


const VerticalGuides = () => {
    /* if numberOfVerticalGuides is null, use the length of the data
         to calculate the number of guides */
  const guideCount = numberOfVerticalGuides || data.length - 1;

  const startY = padding;
  const endY = height - padding;

  return new Array(guideCount).fill(0).map((_, index) => {
    const ratio = (index + 1) / guideCount;

    const xCoordinate = padding + ratio * (width - padding * 2);

    return (
      <>
        <polyline
          fill="none"
          stroke="#ccc"
          strokeWidth=".5"
          points={`${xCoordinate},${startY} ${xCoordinate},${endY}`}
        />
      </>
    );
  });
};

‍

Adding labels to the guides

To make our guides more useful we can add labels along the axes. I added x-axis labels to the diagram. The x coordinate for the data element's label is calculated by multiplying the ratio of the element's x value to the maximum x value from the dataset by the width of the chart and adding half of the padding value. The y value is calculated by subtracting the padding value from the height value and adding half of the font size value.

‍


const LabelsXAxis = () => {
    const y = height - padding + FONT_SIZE * 2;

    return data.map(element => {
      const x =
        (element.x / maximumXFromData) * chartWidth + padding - FONT_SIZE / 2;
      return (
        <text
          x={x}
          y={y}
          style={{ fill: '#ccc', fontSize: FONT_SIZE, fontFamily: 'Helvetica' }}
        >
          {element.label}
        </text>
      );
    });
  };

‍

Y-axis labels

Next I added y-axis labels to the diagram. There are as many labels as there are horizontal guides. The x coordinate is equal to the font size variable. To calculate the y coordinate, I calculated the ratio of the index of the label by the number of guides. I multiplied this ratio by the chart height and subtracted the resulting product from the chart height. I then added padding and the font size divided by 2.

‍


const LabelsYAxis = () => {
    const PARTS = numberOfHorizontalGuides;
    return new Array(PARTS + 1).fill(0).map((_, index) => {
      const x = FONT_SIZE;
      const ratio = index / numberOfHorizontalGuides;

      const yCoordinate =
        chartHeight - chartHeight * ratio + padding + FONT_SIZE / 2;
      return (
        <text
          x={x}
          y={yCoordinate}
          style={{ fill: '#ccc', fontSize: FONT_SIZE, fontFamily: 'Helvetica' }}
        >
          {parseFloat(maximumYFromData * (index / PARTS)).toFixed(precision)}
        </text>
      );
    });
  };

‍

Finished SVG line chart example

The result is our finished chart!

import React from "react";
import LineChart from "./components/LineChart";

const data = [
  { label: "S", x: 0, y: 0 },
  { label: "M", x: 1, y: 400 },
  { label: "T", x: 2, y: 300 },
  { label: "W", x: 3, y: 100 },
  { label: "TH", x: 4, y: 400 },
  { label: "F", x: 5, y: 500 },
  { label: "S", x: 6, y: 400 }
];

function App() {
  return (
    <div style={{ padding: 25, maxWidth: 700 }}>
      <LineChart
        data={data}
        horizontalGuides={5}
        precision={0}
        verticalGuides={6}
      />
    </div>
  );
}

export default App;

‍

Experimenting with properties

Try experimenting with the height, width, and guides properties. And in reviewing the source code, you'll see I've added a prop for setting the precision of the y-axis label.

‍

Change Example 01

‍

/* Modified height, vertical guides, and precision of y-axis labels*/

<LineChart
  height={200}
  data={data}
  horizontalGuides={5}
  precision={2}
  verticalGuides={1}
/>

‍

Change Example 02

/* Modified height, width, and guides props */

<LineChart
  height={350}
  width={600}
  data={data}
  horizontalGuides={1}
  precision={0}
  verticalGuides={1}
/>

‍

Adding Y-axis unit labels and titles

You might remember from math class that a chart needs unit labels on the y-axis and a title. Add these as sibling components or modify the chart component to accept these as props as well.


function App() {
  return (
    <div style={styles.chartComponentsContainer}>
      <div/>
      <ChartTitle text="Movements per Day of the Week"/>
      <Label text="Movements" rotate/>
      <div style={styles.chartWrapper}>
        <LineChart
            width={500 }
          height={300}
          data={data}
          horizontalGuides={5}
          precision={2}
          verticalGuides={1}
        />
      </div>
      <div/>
      <Label text="Days of the Week"/>
    </div>
  );
}

‍

Happy coding!

‍

Source code

You can find the source code for the project here.
‍

Resources to learn more about SVGs

Once you are familiar with the foundational components of SVG, you can pair that knowledge with CSS styles and animations and powerful tools like Figma to create engaging visualizations.

SVG: Scalable Vector Graphics | MDN

The MDN topic for SVG includes links to documentation, tutorials, and examples including mapping, interactions, animations, and games. It's a great resource to work through in order to learn SVG.

Styling And Animating SVGs With CSS

In her article for Smashing Magazine, Sara Soueidan covers in detail what SVGs are, editing and optimizing SVGs in graphics editors, styling SVGs, and animating them. The last section on making responsive SVGs is especially worth reading.

‍

Regain control of branches with git rebase --onto

Andrew Stuntz — Wed, 15 May 2019 12:00:00 +0000

This article originally appeared on Headway's blog

Rebasing branches with git is a process that all developers work through. It can be challenging at times to get all your commits exactly where you're hoping that they will end up. While git isn't perfect, git rebase --onto can help tame your branches when you have to work with non standard rebasing. git rebase --onto let's us be a little more choosy about where and which commits we want to more easily handle complicated rebases.

How a traditional rebase works

Traditional rebases (those without the --onto flag) are pretty easy to understand. Commits get applied to the head of the branch you originally created your working brach off of this works for the majority of cases but sometimes the head of your base branch is faulty, or your doing some testing and want to move your feature branch one commit at a time.

Most of the following examples are pretty contrived, but I think git rebase --onto is applicable to a number of situations. Testing large feature branches, or moving a feature branch from one base to another base. Reasons to use git rebase --onto include fixing mistakes, or moving a feature off of a feature branch and onto a base branch of some kind. git rebase --onto can be your friend when you need a scalpel for your git rebase.

To easily reproduce a bunch of commits in a repo and make it easy to work with, here is a quick bash script that will generate a ruby file and commit a bunch of times to make our "git world" more consistent.

  #!/bin/bash

  function create_basic_git_repo()
  {
    echo 'git rebase is great'
    mkdir gitexample
    cd gitexample
    git init
    mkdir lib
    touch lib/my_thing.rb
    echo "class MyThing; def my_method; 1 + 1 == 2; end; end" | tee lib/my_thing.rb
    git add lib/my_thing.rb
    git commit -m 'Commit 1'
    echo "class MyThing; def my_method; 1 + 2 == 3; end; end" | tee lib/my_thing.rb
    git add lib/my_thing.rb
    git commit -m 'Commit 2'
    echo "class MyThing; def my_method; 1 + 3 == 4; end; end" | tee lib/my_thing.rb
    git add lib/my_thing.rb
    git commit -m 'Commit 3'
    git checkout -B My_Feature_Branch
    echo "class MyThing; def my_method; 1 + 4 == 5; end; end" | tee lib/my_thing.rb
    git add lib/my_thing.rb
    git commit -m 'My Feature Commit 1'
    echo "class MyThing; def my_method; 1 + 5 == 6; end; end" | tee lib/my_thing.rb
    git add lib/my_thing.rb
    git commit -m 'My Feature Commit 2'
    git checkout master
    echo "class MyThing; def my_method; 1 + 6 == 7; end; end" | tee lib/my_thing.rb
    git add lib/my_thing.rb
    git commit -m 'Commit 4'
    echo "class MyThing; def my_method; 1 + 7 == 8; end; end" | tee lib/my_thing.rb
    git add lib/my_thing.rb
    git commit -m 'Commit 5'
  }

  create_basic_git_repo

In this repo you should see a lib directory as well as a file called my_thing.rb with some commits on. 5 commits on the master branch and 2 commits on a feature branch that are based off of the third commit of the master branch. The SHA's between your repo and my repo will be different, but at least the commit messages will be the same to easily follow what we are doing below.

Object Identifiers

As a quick aside, let's talk about object identifiers in git for a second.

An object identifier usually identifies a commit, we often call them SHA's but we can also be talking about a branch. When we refer to set a of work by the branch name we are just talking about the collection of commits that make up and we reference the head of that collection of commits by the name of the branch.

Any object identifier is a valid argument with a rebase. We can rebase on a branch name, a SHA, a tag, as long as it identifies a commit, it is a valid argument to rebase.

Git rebase —onto

There are two versions of git rebase --onto , the binary and ternary functions. Also written as git rebase --onto/2 and git rebase --onto/3.

Git rebase —onto/2

The two argument version of git rebase onto is used to move a set of commits from one one object identifier to any arbitrary object identifier.

In words I want to move my set of commits from one commit to any other arbitrary commit.

For the most part, this is helpful if you don't want to move your commits to the top of a branch or for some reason you can't have your feature branch at the top of master . But it can also be useful if you have a release branch and need to maintain your work across multiple branches.

I like to think about git rebase --onto/2 git rebase "where I want to go" from "where I was", with "where I want to go" being the object identifier of the place you want all your commits to go to and "where I was" to be the object identifier of where your branch is currently sitting off at.

For example in this case I did git rebase --onto 2b4c572 b45626d

I want my work to be on top of commit 4 with SHA 2b4c572 and it's currently on commit 3 with SHA b45626d. Not too bad or crazy complicated. For these cases I took the changes from My Feature Commit 1 and My Feature Commit 2 to make sure the commits applied to see the example.

Git rebase --onto/3

The three argument version of git rebase --onto is a little more powerful, but not as useful always. I tend to only use it when I have really messed something up or have a pretty nifty reason to use it. In fact, I am not certain I have ever used it to do something entirely useful in git repository. Either way, it could be useful at some point.

For this one, we want to move my set of commits from one object identifier to another object identifier, but I want to only select a certain amount of commits from my branch.

Note that we masterfully and easily cut out commit G from our feature branch. This makes it pretty easy to do this.

We want to git rebase --onto "where I want to go" from "where we were" up to "my chosen commit"

For example here we could do git rebase --onto c5d6535 42fa4e5 22d71a4

We are at commit 42fa4e5 and we want just commit 22d71a4 on top of commit c5d6536.

Pretty easy if you ask me. One thing to note is that git rebase --onto/3 leaves HEAD in a detached state and to save this state, you need to name the branch something.

All of these examples were generated using a quick bash script that generates the same commits each time. Though the commit SHA's (object identifiers) will be different (thanks Git!).

Feel free to check out the bash script and play around with git commit rebase --onto it can take some getting used to but its a powerful tool that has really helped me minimize some git pain in the past.

Have any questions? Let me know below.

Learn more about Git rebasing

Git Rebase Documentation

Git Rebase —onto Tutorial

Build a Simple Static Site on Amazon S3

Andrew Stuntz — Wed, 13 Feb 2019 12:00:00 +0000

This article originally appeared on Headway's blog

Today I am going to walk you step by step on how to build a simple static website using Amazon S3. Sometimes all you need is a little HTML and CSS for a successful website. In fact, it can often be faster to develop a website without an entire web framework.

What is a static site?

A static site is a website that is a collection of HTML and other assets that does not get served from a web framework. A static site is in no way non-interactive though.

The static part just refers to the way the HTML and other assets are served to browsers when a user navigates to your website. There is no web framework serving those assets to the browser dynamically, the site loads up and then uses JavaScript to interact with other web servers and API's.

Examples of cool web applications that are static:

Mint: Budget Tracker & Planner
Dropbox

What is the value of using a static site?

HTML and CSS are all you need to get started with a simple static site.

Static sites do not need to be served by a web server. You don't need the infrastructure that is otherwise required to host a web framework. Developing a website without an entire web framework can be more efficient.

You also benefit from a separation of concerns, your front end is just that, no templating languages or calling methods on your models in your view. You get to just deal with the frontend without worrying about the backend.

The steps for building your first static site:

Build a tiny bit of HTML
Upload the HTML to an AWS S3 Bucket
Make the Bucket accessible and public
Add some JS and CSS to make your "static" site shine!

Getting started with your HTML file

The easiest way to do it, is to create an HTML file. Traditionally this is called index.html but the naming doesn’t matter too much. You can point the web server to serve whatever HTML file you want.

<!DOCTYPE html>
<html>
  <body>
    Hello World!
  </body>
</html>

Now you have some basic HTML and you need to serve that somewhere. One of the easiest options is to simply upload the HTML file to an S3 bucket on AWS.

Create a new bucket on AWS

First, head to the S3 console on AWS. You need to add a new bucket.

For this example, I just created a public bucket named "testheadway." Don’t worry about the settings yet. Just click through to get the bucket created.

Edit the bucket for hosting abilities

Next you need to turn on the ability for the bucket to host a static website. Click on the bucket to edit it.

Once we’re in the edit view for the bucket, head to the "Properties" tab for the bucket.

Then click into the Static website hosting card.

Now select "Use this bucket to host a website" and add the name of your index document this is almost always going to be your index.html it should match the name of the document you created earlier.

Easy peasy if you ask me!

Now, once this is turned on you should see an endpoint for your S3 bucket. This is the URL used to access your newly created static website.

Edit the bucket permissions

You need to adjust a few more settings to have public access to this S3 bucket. The bucket permissions need to allow everyone to getObject's from your bucket. As basic policy could look like the below. Just make sure to update the "Resource" to be the name of your S3 bucket.

Note: This is not secure nor recommended for production ready static sites. Seek an AWS security expert for recommended bucket permissions.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::yourbucketname/*"
    }
  ]
}

Copy and paste the below in the Bucket Policy by heading to Permissions.

The next step is to click into the Bucket Policy.

Now, you need to save the getObject policy. AWS will warn you that you are giving public access to your objects in your bucket. This policy only allows people to access objects in your bucket, which is what you want since people are going to be accessing your index.html.

If you head to that URL now you can see that you get a giant 404.

This is expected, you haven’t uploaded your index.html file yet.

Upload the index.html

The next step is to upload your index.html.

At this point, if you head back to the bucket URL you should see your HTML rendered in the browser.

Congratulations, you’ve got a basic website being hosted from AWS!

Here are some ways you can extend the site easily with some CSS and JS.

In the same way that it was pretty easy to serve straight up HTML, it’s just as easy to add some CSS to your application.

Stick a new file into your directory called styles.css. Like other static site generators you can add some basic styling to your HTML just by referencing the CSS in your HTML.

Your HTML should now look like:

<!DOCTYPE html>
<html>
  <head>
    <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <div class='center'>
      <h1>
        Hello World!
      </h1>
    </div>
  </body>
</html>

Now you can add some styling to the styles.css style sheet like:

h1 {
  font-family: 'Roboto', sans-serif;
}
.center {
  width: 100%;
  display: flex;
  flex-direction: row;
  align-items: center;
  justify-content: center;
}

Now you just need to delete the index.html file from the S3 bucket and upload these two files and you should have a minimally styled website up and running.

It should look something like:

Using jQuery to add new elements

So far you have done all of this with no Javascript and no web server or application server. How can you interact with the world outside of your little app? Well, you need to add some JavaScript to make that happen. But, that is pretty easy too. Just update the HTML to pull in some JavaScript, you are going to use jQuery to quickly grab some weather and display it on your static site.

You only have three files. Pretty easy and simple, but very powerful.

<!DOCTYPE html>
<html>
  <head>
    <link href="[https://fonts.googleapis.com/css?family=Roboto](https://fonts.googleapis.com/css?family=Roboto)" rel="stylesheet">
    <link rel="stylesheet" href="styles.css">
    <script src="[http://code.jquery.com/jquery-latest.min.js](http://code.jquery.com/jquery-latest.min.js)" type="text/javascript"></script>
    <script src="weather.js" type="text/javascript"></script>
  </head>
  <body>
    <div class='center'>
      <h1>
        Hello World!
      </h1>
      <button id='weather_button' class='basic_button'>
        Get my Weather
      </button>
      <div class='error'>
      </div>

      <div class='weather'>
          <div class='city-name text'>
          </div>
          <div class='weather-main text'>
          </div>
          <div class='description text'>
          </div>
      </div>
    </div>
  </body>
</html>

Your slightly more complete CSS:

h1 {
  font-family: 'Roboto', sans-serif;
}

.center {
  width: 100%;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}

.text {
  margin-top: 30px;
  font-family: 'Roboto', sans-serif;
}

.basic_button {
  font-family: 'Roboto', sans-serif;
  font-size: 18;
  margin-top: 30px;
  width: 300px;
  height: 45px;
  border-radius: 4px;
  background-color: #44AAB5
}

Some JS to interact with a weather API and make your static site a little more interesting.

$(document).ready(function() {
  $("#weather_button").click(function(e) {
    console.log(e)
    e.preventDefault();
    $.ajax({
      type: "POST",
      data: 'json',
      url: 'https://api.openweathermap.org/data/2.5/weather?zip=98229,us&appid=useyourownopenweathermapkeyplease',
      success: function(result) {
        console.log(result)
        $( ".city-name" ).text(result.name);
        $(".weather-main").text(
          result.weather &&
          result.weather[0] &&
          result.weather[0].main
        )
        $(".description").text(
          result.weather &&
          result.weather[0] &&
          result.weather[0].description
        )
      },
      error: function(result) {
        console.log('error', result)
        $(".error").text(result.error)
      }
    });
  });
});

Checkout the final product here, it’s not so static after all 😉:

See the "testheadway" website

This same process stands with a single page application (SPA) with React. If you want to host your SPA on S3 all you would need to do is build your React app and then add all the static assets (HTML, JS, CSS files) to your S3 bucket.

If you built your SPA from a create-react-app application there is already a build command to build your app.

You need to run:

npm run build

This should build your static assets and compile them into the build directory for your application.

Instead of uploading a single HTML file, you'll upload the contents of the build directory to the S3 bucket.

my-react-directory/build

Now your React app will mount when it finds your index.html.

The advantages of building a static site vs a dynamic site

There are many ways to build web applications in todays day in age, and one of them is to host a static site and let it interact with your backend.

While there are certainly challenges to building websites in this manner there are plenty of positives as well, including separating concerns between the front end and the backend, more easily supporting multiple clients, and better supporting modern JavaScript SPA’s.

Overall this is a quick overview of how you can build a sample application completely from a static website that is easily and cheaply host on Amazon S3.

Let me know if you have any questions about static sites or if we can help you build a SPA, a static site, or help you deploy your static site to Amazon S3, we’re happy to help.

Recommended resources for building static sites

Deploying a create React app:

Facebook Github - Create React App: Deployment

Static site generators:
GatsbyJS
Hugo
Jekyll

Places to host static websites:
GitHub Pages
Netlify
AWS S3