DEV Community: nathan amick

Writing Your Own React Hooks, the Return Value

nathan amick — Thu, 19 Dec 2019 11:35:11 +0000

JavaScript can only return one value from a function. However, destructuring in modern JavaScript makes this largely irrelevant.

We can return multiple values in arrays or objects from a function and instantly destructure them. And, as you know, a React hook is just a convention-following function.

const [one, two] = useNumbers()
const { a, b, c } = useAlphabet()

So why use one method over another?

Let's look at some different use cases and explore why we might want to return an array vs. an object.

First, it should be noted, that we don't have to return anything. The built in React.useEffect hook does just this, (returning undefined actually).

We can also just return a single value, such as a string or integer. An example of this might be a hook that subscribes to a WebSocket API and returns a continuously updating value representing the current number of users online:

function OnlineUsers() {
  const userCount = useOnlineUserCount()

  return (
    <Users count={userCount} />
  )
}

Returning an Array

A hook that has a very general use case benefits from exporting return values as an array. A great example of this is actually the built-in React.useState hook. Exporting an array makes it easy to customize the names of the state variables and their setters. Unique names enable us to use the hook repeatedly.

const [color, setColor] = useState('MintCream')
const [width, setWidth] = useState('100vw')

A slightly-contrived example of a custom hook that would benefit from returning an array might be CSS builder that also holds on to some state.

const [leftStyle, setLeftTheme] = useStyleBuilder('dank-kitty')
const [rightStyle, setRightTheme] = useStyleBuilder('no-drama-llama')

When to Return an Array

The number of values that need to be returned is low. Order is significant and remembering the order of a bunch of values takes extra brain cycles.
The hook is expected to be used more than once in the same component. Although we can rename properties when destructuring an object, the simpler syntax for custom-named values returned from an array makes more sense.

Returning an Object

A hook that has a more specialized use case and returns a larger number of values may benefit by returning an object.

Object destructuring doesn't rely on ordering and it is easier to ignore values that are not needed. An example might be a hook with 3 or 4 state values along with handler functions:

const { color, count, isValid, handleChangeColor, handleChangeCount } = useItemOptions()

When to Return an Object

The number of values that need to be returned is high. We don't have to remember the order or even use all the values when returning an object.
The hook is not expected to be used more than once in the same component. We can use the original property names when destructuring an object returned from a hook that will only be used once in a component.

Not destructuring

If a hook needs to return a larger number of values AND is expected to be used more than once, we don't have to destructure at all. This can occasionally be useful.

  const leftOptions = useItemOptions()
  const rightOptions = useItemOptions()

  return (
    <>
      <Column
        side="left"
        color={leftOptions.color}
        count={leftOptions.count}
        isValid={leftOptions.isValid}
        handleChangeColor={leftOptions.handleChangeColor}
        handleChangeCount={leftOptions.handleChangeCount}
      />
      <Column
        side="right"
        color={rightOptions.color}
        count={rightOptions.count}
        isValid={rightOptions.isValid}
        handleChangeColor={rightOptions.handleChangeColor}
        handleChangeCount={rightOptions.handleChangeCount}
      />
    </>
  )

Not Destructuring with Spread

If we are careful with the naming of the properties in the object that our hook returns, we can use the spread syntax to dump props directly into our components.

The above component could be rewritten using the spread syntax like this:

  const leftOptions = useItemOptions()
  const rightOptions = useItemOptions()

  return (
    <>
      <Column side="left" {...leftOptions} />
      <Column side="right" {...rightOptions} />
    </>
  )

(Apparently, Dev.to syntax highlighting for the spread operator in JSX is not yet supported, but this works.)

Conclusion

We can return multiple values in several different ways that make sense at different times. Hopefully, this will give you some ideas about how to make your hooks more readable and easier to understand.

We have a bunch of options in our toolbelt here. There is overlap and there are trade-offs, so play around and figure out what makes sense for your application. And have fun!

Writing Your Own React Hooks - a TDD Example

nathan amick — Mon, 09 Dec 2019 04:10:42 +0000

In my last post I discussed how writing your own hooks can encapsulate imperative code in useful and reusable objects, leaving your components simple and completely declarative.

In this post I explain the same concept with a simpler example and less code. And perhaps, more importantly, this will give us room to test-drive it and experience the benefits of TDD. Here we go...

Imagine we want to be able to try out various fonts right in the app we are building. It's hard to get a sense of what a font will look like until it's viewed in place, so easily cycling through a few fonts in context would be handy, like this:

Writing a Test

Let's pretend this wasn't a (somewhat) contrived example but an actual feature in our app. We start off by writing a test using the React Testing Library.

// src/Title.spec.js

import Title from './Title'

test('Cycles through a list of fonts when clicked', () => {
  const text = 'Clickable Fonts'
  const { getByText } = render(<Title>{text}</Title>)

  const fontBefore = window.getComputedStyle(getByText(text)).fontFamily

  fireEvent.click(getByText(text))

  const fontAfter = window.getComputedStyle(getByText(text)).fontFamily

  expect(fontBefore).not.toEqual(fontAfter)
})

There are some problems with this test, not the least of which is that testing CSS is not a great idea, but we don't yet know how our component is going to work, except from the user perspective. And changing the style when it is clicked is the feature, so this will get us going.

As expected, our test is failing. (Red, green, refactor, right?)

Making the Test Pass

To make the test pass, we create a Title component, add some Google Fonts, a bit of style via Styled-Components, a useState hook to keep track of which font is currently being displayed and an onClick handler to change the font. We end up with this:

// src/Title.js

function Title({ children }) {
  const [fontIndex, setFontIndex] = React.useState(0)

  const handleChangeFont = () =>
    setFontIndex(fontIndex >= fontList.length - 1 ? 0 : fontIndex + 1)

  const fontList = [
    'Indie Flower',
    'Sacramento',
    'Mansalva',
    'Emilys Candy',
    'Merienda One',
    'Pompiere',
  ]

  const fontFamily = fontList[fontIndex]

  const StyledTitle = styled.h1`
    font-size: 3rem;
    cursor: pointer;
    user-select: none;
    font-family: ${fontFamily};
  `

  return <StyledTitle onClick={handleChangeFont}>{children}</StyledTitle>
}

That makes our test pass, yay.

And the component works as seen in this CodeSandbox demo.

We Can Make this Better

We have some problems with this. We'd like our component to be more declarative. It's currently showing all the nitty-gritty details about how the font gets changed when a user clicks on it.

There is also the problem that something just doesn't feel right about testing the CSS in the component. But let's solve the first problem first since that is easy enough.

We'll just push all the logic into our own custom hook.

Our new hook looks like this:

// src/useClickableFonts.js

const useClickableFonts = fontList => {
  const [fontIndex, setFontIndex] = React.useState(0)

  const handleChangeFont = () =>
    setFontIndex(fontIndex >= fontList.length - 1 ? 0 : fontIndex + 1)

  const fontFamily = fontList[fontIndex]

  return { fontFamily, handleChangeFont }
}

Our component looks like this:

// src/Title.js

function Title({ children }) {
  const { fontFamily, handleChangeFont } = useClickableFonts([
    'Indie Flower',
    'Sacramento',
    'Mansalva',
    'Emilys Candy',
    'Merienda One',
    'Pompiere',
  ])

  const StyledTitle = styled.h1`
    font-size: 3rem;
    cursor: pointer;
    user-select: none;
    font-family: ${fontFamily};
  `

  return <StyledTitle onClick={handleChangeFont}>{children}</StyledTitle>
}

Notice we left the declaration of the fonts in the component, passing them into the hook. This is important because it is part of what we want components to do, declare all of their possible states. We just don't want them to know how they get into those states.

The Styled-Components API is also completely declarative and is part of the implementation of the component. It stays.

Our tests still pass so we know we haven't broken anything. Refactoring is fun with the security of tests.

And our component still works: (CodeSandbox demo).

Adding the Font Name to the Footer

As we are clicking endlessly on it, we realize it would be nice to know which font is currently being displayed. However, we want that info far away from the Title component, so that it doesn't interfere with the UX design testing we are doing. Let's display it subtle-like in the footer for now.

But how do we get that font information out of the Title component and on to the page in a different location?

The answer, of course, is to lift state up. Luckily, pushing logic and state into our own hook has made this task as simple as moving the useClickableFonts line up and passing down the props.

// src/App.js

function App() {
  const { fontFamily, handleChangeFont } = useClickableFonts([
    'Indie Flower',
    'Sacramento',
    'Mansalva',
    'Emilys Candy',
    'Merienda One',
    'Pompiere',
  ])

  return (
    <>
      <Title fontFamily={fontFamily} handleChangeFont={handleChangeFont}>
        Clickable Fonts
      </Title>
      <Footer>{fontFamily}</Footer>
    </>
  )
}

Great, we moved the hook up to the closest common ancestor (in this simple example it is App) and we passed the props into the Title component and displayed the name of the font in the Footer.

The Title component becomes a pure, deterministic component:

// src/Title.js

function Title({ fontFamily, handleChangeFont, children }) {
  const StyledTitle = styled.h1`
    font-size: 3rem;
    cursor: pointer;
    user-select: none;
    font-family: ${fontFamily};
  `

  return <StyledTitle onClick={handleChangeFont}>{children}</StyledTitle>
}

Now we can see the name of the font down at the footer. Go ahead, click it:

However, our test is now broken. (See the CodeSandbox demo with the broken test.)

Fixing the test

This gives us some insight into why we had that gnawing feeling something was wrong with our test. When we update the component to take props instead of using the useClickableFont hook directly, that requires us to update the test as well. However, it was slightly unexpected because we didn't change or refactor any of the logic.

Our test was brittle because we were testing the wrong thing. We need to test that the imperative gears of changing the font work, not the (now) simple and declarative React component. The nuts and bolts of React and Styled-Components are already well tested. We can just use them with confidence if we are not adding our own logic.

This doesn't mean we should be testing implementation details. When writing our own hooks, we are adding to the API that our React component will use. We need to test that new API, but from the outside.

What we really want to be testing is our useClickableFont hook. We can do that with the react-hooks-testing-library

Our new test looks like this:

// src/useClickableFonts.spec.js

import useClickableFonts from './useClickableFonts'

test('Cycles through a list of fonts', () => {
  const { result } = renderHook(() =>
    useClickableFonts(['Indie Flower', 'Sacramento', 'Mansalva']),
  )

  expect(result.current.fontFamily).toBe('Indie Flower')

  act(() => result.current.handleChangeFont())

  expect(result.current.fontFamily).toBe('Sacramento')

  act(() => result.current.handleChangeFont())

  expect(result.current.fontFamily).toBe('Mansalva')

  act(() => result.current.handleChangeFont())

  expect(result.current.fontFamily).toBe('Indie Flower')
})

Notice we are testing it from the outside, just like the user would use it. The test should resemble the way the hook is used. In this case the user is a React component. We can have confidence in this new test because the test uses it just like a component would.

We test that the hook returns the first, second and third font in order, each time the handler is called. We also test that it loops around to the first one again.

Here is the final component on CodeSandbox:

Conclusion

It's not always easy to know the right design or the correct abstraction at first. That's why the refactor part of the red, green, refactor cycle is so important and ignoring this step is often the cause of code deterioration and growing technical debt.

Often, separating the tasks of making the code work and making the code right creates freedom. Freedom to get started, and then freedom to discover a better implementation.

We test-drove a new component, discovering an initial implementation. Extracting the logic into a hook made our code easier to change. Changing it helped us discover a better way to test it.

We ended up with clean, declarative components and the hook gives us a convenient interface to test and reuse imperative code.

Why You Should be Writing Your Own React Hooks

nathan amick — Sat, 30 Nov 2019 05:20:11 +0000

tl;dr

Custom React hooks can provide a great place to draw a boundary between imperative and declarative code.

In this example, we'll look at extracting essential complexity into composable, encapsulated, reusable objects while keeping your components clean and declarative.

Composability

Trick question: what is the one place you can use React hooks outside of a Component? The answer, of course, is in other hooks.

As you likely know, when you write your own hooks you are writing plain old Javascript functions that follow the convention of React Hooks. They don't have a specific signature; there is nothing special about them and you can use them however you need to.

As you build an app, adding features and making it more useful, components tend to take on more complexity. Experience helps you prevent avoidable complexity, but this only goes so far. A certain amount of complexity is necessary.

It's a great feeling to take some messy but necessary logic scattered around a component and wrap it up in a hook with a clear API and single purpose.

Let's look at a simple stopwatch component. Here is the implementation in codesandbox to play with.

And this is the code.

function App() {
  return (
    <div className="App">
      <Stopwatch />
    </div>
  )
}

function Stopwatch() {
  const [isCounting, setIsCounting] = React.useState(false)
  const [runningTime, setRunningTime] = React.useState(0)

  const intervalId = React.useRef()

  const startCounting = () =>
    (intervalId.current = setInterval(intervalCallback(), 0))

  const stopCounting = () => clearInterval(intervalId.current)

  const intervalCallback = () => {
    const startTime = new Date().getTime()

    return () => setRunningTime(runningTime + new Date().getTime() - startTime)
  }

  React.useEffect(() => stopCounting, [])

  const handleStartStop = () => {
    isCounting ? stopCounting() : startCounting()
    setIsCounting(!isCounting)
  }

  const handleReset = () => {
    stopCounting()
    setIsCounting(false)
    setRunningTime(0)
  }

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

Quick explanation of the component

Let's walk through the code really quick so we are all on the same page.

We start off with a couple of useState hooks to keep track of if and how long the timer has been running.

const [isCounting, setIsCounting] = React.useState(false)
const [runningTime, setRunningTime] = React.useState(0)

Next we have a couple of functions that start and stop the timer by setting and clearing an interval. We store the interval ID as a Ref because we need a bit of state, but we don't care about it triggering a rerender.

We are not using setInterval to do any timing, we just need it to repeatedly call a function without blocking.

  const intervalId = React.useRef()

  const startCounting = () =>
    (intervalId.current = setInterval(intervalCallback(), 0))

  const stopCounting = () => clearInterval(intervalId.current)

The time counting logic is in a callback which gets returned by this function and passed to setInterval. It closes over startTime at the moment the stopwatch is started.

 const intervalCallback = () => {
    const startTime = new Date().getTime()

    return () => setRunningTime(runningTime + new Date().getTime() - startTime)
  }

We need to use useEffect here to return a clean-up function to prevent memory leaks when the component is unmounted.

  React.useEffect(() => stopCounting, [])

And finally we define a couple of handlers for our start/stop and reset buttons.

  const handleStartStop = () => {
    isCounting ? stopCounting() : startCounting()
    setIsCounting(!isCounting)
  }

  const handleReset = () => {
    stopCounting()
    setIsCounting(false)
    setRunningTime(0)
  }

Pretty straightforward, but the component is handling multiple concerns.
This code knows too much. It knows how to start and stop counting time and how it should be laid out on the page. We know we should refactor it, but let's think about why.

There are two main reasons we might want to extract this logic out, so we can add unrelated features, and so we can add similar components that use this same feature.

The first reason is that when we need to add more features, we don't want the component to grow out of control and be difficult to reason about. We want to encapsulate this timer logic so that new, unrelated logic doesn't get mixed in with this logic. This is adhering to the single responsibility principle.

The second reason is for simple reuse without repeating ourselves.

As a side note, if the code in question didn't contain any hooks, we could just extract it into a normal function.

As it is, we'll need to extract it into our own hook.

Let's do that.

const useClock = () => {
  const [isCounting, setIsCounting] = React.useState(false)
  const [runningTime, setRunningTime] = React.useState(0)

  const intervalId = React.useRef()

  const startCounting = () =>
    (intervalId.current = setInterval(intervalCallback(), 0))

  const stopCounting = () => clearInterval(intervalId.current)

  const intervalCallback = () => {
    const startTime = new Date().getTime()

    return () => setRunningTime(runningTime + new Date().getTime() - startTime)
  }

  React.useEffect(() => stopCounting, [])

  const handleStartStop = () => {
    isCounting ? stopCounting() : startCounting()
    setIsCounting(!isCounting)
  }

  const handleReset = () => {
    stopCounting()
    setIsCounting(false)
    setRunningTime(0)
  }

  return { runningTime, handleStartStop, handleReset }
}

Notice we are returning the running time of the clock and our handlers in an object which we immediately destructure in our component like this.

function Stopwatch() {
  const { runningTime, handleStartStop, handleReset } = useClock()

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

So far so good. It works (codesandbox demo), and the immediate benefit is that our component becomes completely declarative, which is the way React components should be. One way to think about this is that the component describes it's final state, that is, all of it's possible states, at the same time. It's declarative because it simply declares how it is, but not the steps it takes to get it into those states.

Adding a Timer

Let's say we don't just need a stopwatch that counts up. We also need a timer that counts down.

We'll need 95% of the Stopwatch logic in the timer, and that should be easy since we just extracted it.

Our first inclination might be to pass it a flag and add the conditional logic where it is needed. Here is the relevant parts of what that might look like.

const useClock = ({ variant }) => {
  // <snip>

  const intervalCallback = () => {
    const startTime = new Date().getTime()

    if (variant === 'Stopwatch') {
      return () =>
        setRunningTime(runningTime + new Date().getTime() - startTime)
    } else if (variant === 'Timer') {
      return () =>
        setRunningTime(runningTime - new Date().getTime() + startTime)
    }
  }

  // <snip>
}

function Stopwatch() {
  const { runningTime, handleStartStop, handleReset } = useClock({
    variant: 'Stopwatch',
  })

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

function Timer() {
  const { runningTime, handleStartStop, handleReset } = useClock({
    variant: 'Timer',
  })

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

OK, this works (codesandbox demo), but we can see that it is already getting harder to read. If we had several more of these "features" its going to get out of control.

A better way might be to extract out the unique part, give it a name (not always easy) and pass it into our hook, like this.

const useClock = ({ counter }) => {
  // <snip>

  const intervalCallback = () => {
    const startTime = new Date().getTime()

    return () => setRunningTime(counter(startTime, runningTime))
  }

  // <snip>
}

function Stopwatch() {
  const { runningTime, handleStartStop, handleReset } = useClock({
    counter: (startTime, runningTime) =>
      runningTime + new Date().getTime() - startTime,
  })

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

function Timer() {
  const { runningTime, handleStartStop, handleReset } = useClock({
    counter: (startTime, runningTime) =>
      runningTime - new Date().getTime() + startTime,
  })

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

Awesome, it works (codesandbox demo), and our useClock hook stays nice and clean. It may arguably be more readable than the original since we have named one of its squishy parts.

However, the changes we have introduced to our Stopwatch and Timer components have made them less declarative. This new imperative code is instructing as to how it works, not declaring what it does.

To fix this, we can just push that code out into into a couple more hooks. This demonstrates the beauty of the React hook api; they are composable.

const useStopwatch = () =>
  useClock({
    counter: (startTime, runningTime) =>
      runningTime + new Date().getTime() - startTime,
  })

function Stopwatch() {
  const { runningTime, handleStartStop, handleReset } = useStopwatch()

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

const useTimer = () =>
  useClock({
    counter: (startTime, runningTime) =>
      runningTime - new Date().getTime() + startTime,
  })

function Timer() {
  const { runningTime, handleStartStop, handleReset } = useTimer()

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

Much better (codesandbox demo), our components are back to being fully declarative, and our imperative code is nicely encapsulated.

To demonstrate why this is a good thing, lets see how easy it is to add more features without mucking up our code.

Adding a start time

We don't want our timer to count down from zero, so let's add an initial time.

function App() {
  return (
    <div className="App">
      <Stopwatch />
      <Timer initialTime={5 * 1000} />
    </div>
  )
}

const useClock = ({ counter, initialTime = 0 }) => {
  const [isCounting, setIsCounting] = React.useState(false)
  const [runningTime, setRunningTime] = React.useState(initialTime)

  // <snip>

  const handleReset = () => {
    stopCounting()
    setIsCounting(false)
    setRunningTime(initialTime)
  }

  return { runningTime, handleStartStop, handleReset }
}

const useTimer = initialTime =>
  useClock({
    counter: (startTime, runningTime) =>
      runningTime - new Date().getTime() + startTime,
    initialTime,
  })

function Timer({ initialTime }) {
  const { runningTime, handleStartStop, handleReset } = useTimer(initialTime)

  return (
    <>
      <h1>{runningTime}ms</h1>
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

Not too bad (codesandbox). We just added a prop and passed it on to our useClock hook.

Adding Timer Notification

Now we want our Timer component to notify us when the time is up. Ding, Ding!

We'll add a useState hook to the useClock hook to keep track of when our timer runs out.

Additionally, inside a useEffect hook, we need to check if the time is up, stop counting and set isDone to true.

We also switch it back to false in our reset handler.

const useClock = ({ counter, initialTime = 0 }) => {
  // <snip>
  const [isDone, setIsDone] = React.useState(false)

  // <snip>

  React.useEffect(() => {
    if (runningTime <= 0) {
      stopCounting()
      setIsDone(true)
    }
  }, [runningTime])

  // <snip>

  const handleReset = () => {
    // <snip>
    setIsDone(false)
  }

  return { runningTime, handleStartStop, handleReset, isDone }
}

function Timer({ initialTime }) {
  const { runningTime, handleStartStop, handleReset, isDone } = useTimer(initialTime)

  return (
    <>
      {!isDone && <h1>{runningTime}ms</h1>}
      {isDone && <h1>Time's Up!</h1>}
      <div>
        <button onClick={handleStartStop}>Start/Stop</button>
        <button onClick={handleReset}>Reset</button>
      </div>
    </>
  )
}

That works (codesandbox demo). Notice we didn't need to touch useTimer because we just pass the isDone flag through in the same object.

In the end we have nicely declarative components that are now very easy add styling to.

Our hooks turned out pretty clean too because we didn't add conditional logic but instead we injected the logic that makes them unique.

After moving things into their own modules, and adding some style oriented components with Material-UI our Stopwatch and Timer look like this.

function Stopwatch() {
  const { runningTime, ...other } = useStopwatch()

  return (
    <Clock>
      <TimeDisplay time={runningTime} />
      <Buttons {...other} />
    </Clock>
  )
}

function Timer({ initialTime }) {
  const { runningTime, isDone, ...other } = useTimer(initialTime)

  return (
    <Clock>
      {!isDone && <TimeDisplay time={runningTime} />}
      {isDone && <TimeContainer>Time's Up!</TimeContainer>}
      <Buttons {...other} />
    </Clock>
  )
}

And here is the end result.

Conclusion

Custom React hooks are easy and fun! And they are a great way to hide away imperative code in reusable, composable functions while keeping your components simple and able to cleanly declare what you want your application to look like. Yay.

A New Look at Strong Opinions (Weakly Held)

nathan amick — Tue, 26 Nov 2019 19:09:53 +0000

Strong opinions (weakly held), we hear this desired attribute a lot, in mantras and job descriptions from companies looking for talented engineers who will add to and not detract from the unique and valuable culture they already have.

Attributed to Paul Safo, who was originally talking about individual thought, today it has been applied across the entire tech industry and used to describe a soft skill nurtured in teams. They want passion... and something else.

Great teams are built from people with passion; this much is clear. And we do have passion, we're programmers who love our craft. This is what we would be doing even if we weren't getting paid.

But effective teams also require people who are flexible and able to be won over to a different, possibly opposing viewpoint. People who are not so attached to what they believe that they are unable to hear or accept evidence that clashes with their understanding.

Apart from the slogans and catchphrases, how is this applied in our daily work building stuff together? What does this actually look like in ~~reality~~ the perfect world?

The Vision

In a conference room scattered with colorful, geeky toys and half wiped-down whiteboards, a spirited group of developers, armed with coffee and Macbooks, discuss how to approach the next sprint. This is a greenfield project and endless choices must be made.

Two engineers are passing the conversational ball back and forth. The pros and cons of.. well, let's say crucial matters of the project. Definitely not bikeshedding!

The passion of a well-articulated, and well-reasoned (strong) viewpoint is contagious and can be unifying, and we see that here. It builds consensus in the herd of cats we call engineers. It is fun to listen to and generates excitement and energy, bringing life to an otherwise slightly routine Monday.

And it does this all the way up until the point that someone with an already formed, but opposing, viewpoint speaks up.

Their argument is also logical and eloquent. They also speak with passion, and it becomes clear that there can be only one true way.

Suddenly, the newly budding consensus is gone and the excitement teters on the edge of tension.

At this point one of several things can happen, and only one of them is the best outcome for the team.

(You have probably experienced or can guess some of the others but let’s look at the happy path, the one that doesn’t cause a downward spiral of argument, defensiveness and hurt feelings.)

As our two engineers each hear a counter argument to the strong view they espouse, they feel an unpleasant emotional jab inside, almost as if they are being attacked. (They’re not, but they feel that way.) Indeed, each speaker is actually expressing their own passionate, but personal opinion.

Luckily, these engineers both have the emotional intelligence to step back from the conversation and listen, really listen to the other side of the argument.

They consciously and pro-actively try to see the other points of view, setting aside their own experience, if momentarily. They are aware, at least intellectually, that their strong feelings about it the issue are subjective.

They pause inside, not rushing to respond. But they also do not immediately roll over. They consider this alien point of view, ask clarifying questions, and try to shine a light on different aspects of the subject.

In the tension between obstinacy and apathy, there lies not a tired middle-of-the-road but a unique superpower.

They are aware of their own, almost self-deceptive tendency to try to veil their instinctive defensiveness in placating, but passive-aggressive comments. They combat this by thinking carefully and deliberately about each word they speak.

Each person knows how little time there is before emotions start to run away - just minutes really. Tension builds. Each has a good case to be made, but so does the other.

Then, seemingly out of the blue, and yet, it is as if they had planned it out ahead of time, a miracle occurs.

One of our two engineer-turned-exhorters decides to let themselves be convinced.

In graceful acquiescence, they share back some of the good points and reasonable logic the other side has made.

"Yep, that's good. Let's do it your way," they say.

Lively fun-time debate is over and a consensus must be reached.

All is well, and the team is happy with their choice.

How It's Done

That's all very nice, but how did they respond so quickly, and decide almost telepathically, who should be the one to back down?

They didn't, it is a natural outcome of two people who have the humility to practice creative self doubt. It just looks like magic.

One did not convince the other. The other chose to be convinced.

Both engineers know from experience and sometimes instinct how far a friendly but lively micro-debate can go before it goes too far. There is a peak in the conversation, and they dare not go over. As they get closer and closer to that moment, each weighs their own commitment to their opinion, and more importantly, they consciously begin to allow themselves to be convinced.

They both know, and have a shared understanding that they are both willing to be convinced, and willing to do so before that invisible timer goes off.

Letting Yourself be Convinced

Of course there are endless ways to let yourself be convinced. Most of them fall into the life-hack category and that is a conversation for another day. But maybe you gain a moment of curiosity.

What if I tried it the other way, what would that be like?

I’ve never done it this way. This will be interesting.

Maybe you notice at least one good point being made by the other party. Latch on to that. Allow it to transform your mind. Renew and reset your thoughts. Let it temporarily outweigh the seven other good points you have.

Oh, I hadn't thought of that, makes sense.

Other times, if there are seconds before the clock runs out, before feelings are hurt, you make an intellectual choice to set aside your ego and do what is best for the group. This is the humility part, the fake it till you make it part.

`I’m just going to let this go.`

`In the grand scheme of things, it really isn’t going to make that big of a difference.`

`I can do this.`

For some of us, strong opinions are easy. Holding them weakly, well that takes some work. Sometimes it’s really hard and can feel like a bitter pill to swallow.

But most of the time, it feels great to learn from others. Humble, yet bold.

Conclusion

We need speak out about the things that we love, the things that get us excited, the things that drive us. This is life to our team.

And we need to be aware of emotions, and have the maturity to be able to set aside our own long enough to engage in the ideas of others.

Valuable things are worth working hard for, and this is a skill worth having.

The Missing Guide to Twitter OAuth User Authorization

nathan amick — Thu, 07 Nov 2019 16:21:40 +0000

There are a number of prebuilt solutions to do authentication using Twitter as an identity provider (Sign-in with Twitter). This is OAuth user authentication. But if your application needs to do tasks like post a tweet on behalf of a user, you need to use Twitter OAuth user authorization to allow your users to authorize your app.

In this guide, I'll explain how to do Twitter authorization as simply as possible.

In a recent app I built, I needed to enable the users to authorize the app to use Twitter on their behalf. I found Twitter documentation to be confusing and inaccurate to say the least.

After spending way too much time pouring over the API documentation, I got the feeling that Twitter is intentionally trying to make it difficult for developers to use. I doubt this is actually true, but a quick search shows Twitter has been struggling with developer relations for nearly 10 years.

Check out this section from the developer docs.

Rather than standardizing on terminology and updating their documentation, they put in a clarification section that includes what appears to be a copy-paste typo.

In any case, I didn't find much help elsewhere on the web either, so in this article I'll share how to do Twitter authorization in a simple and clear way.

An overview of the steps needed to get an authorization token

Your app requests a key from Twitter and tells Twitter where you want the user redirected to after authorization.
Your app uses this key to construct a twitter.com URL and redirects the user to it.
The user authorizes your app on the Twitter website and is then redirected back to your app.
Your app collects verifier information from this redirect.
Your app uses all this information to request the actual authorization token from Twitter.

Your app can now use this token with the Twitter API to make posts and other "user context" tasks on behalf of your users.

A closer look at each of these five steps

Your app first requests an oath_token and oauth_token_secret from Twitter. Your app does this by making a POST request to Twitter's oauth/request_token endpoint. While doing this, your app also provides Twitter with a callback URL pointing back to your app.
Your app temporarily stores both the oauth_token and oauth_token_secret and then uses the oauth_token to construct a twitter.com url that looks like this:
https://api.twitter.com/oauth/authorize?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0
Your app redirects the user to this twitter.com url and the user is given the opportunity to authorize your app. As soon as the user authorizes your app, Twitter redirects the user back to your app using the callback URL you provided in step 1.
Your app's callback URL expects two pieces of information from Twitter in the form of url encoded parameters, oauth_token and oauth_verifier. The oauth_token is the same token your app received in step 1 and can be used to look up the previously stored oauth_token_secret.
Your app now has oauth_token, oauth_token_secret, and oauth_verifier. It uses these three pieces of information to make another POST request to Twitter. This time it uses the oauth/access_token endpoint. The response to this request contains the final oauth_token and oauth_token_secret.

This final oauth_token and oauth_token_secret are stored securely associated with the user. Your app can now use the Twitter API on behalf of the user.

Note: It is important to understand that there are two each of oauth_token and oauth_token_secret. The first is temporary and is requested in step 1 and used in step 2 and step 5. The second is requested in step 5 and is the final token needed to use the Twitter API.

Twitter libraries

Let's look at how this can be implemented. We'll be using Node on the server and a library that will take care of some of the HTTP work for us.

There are quite a few dead Twitter libraries out there. Twitter itself currently links to unmaintained libraries like this:
twitter-node-client

The node-twitter library is not linked from Twitter but is maintained and works for most of the Twitter API. However, it does not work to request keys from Twitter on behalf of your users. It prepends an API version string to the request path, which isn't wanted for the OAuth URLs. Additionally, despite the documentation, Twitter's auth/request_token endpoint doesn't return JSON, it returns url-encoded form data. Node-twitter assumes response bodies are always JSON and it crashes with a parse error.

So we'll go slightly less specialized and use the excellent request HTTP client. Actually, we'll use the request-promise-native version of the same thing.

The same five steps explained in code

This should be viewed as pseudo-code in that it is just the important bits pulled out of async functions. It represents only the happy path with all error checking, refactoring and testing removed.

Step One

The first (and every) request you'll make to Twitter requires your app's "Consumer API keys." You can get these from the "Keys and tokens" tab in your app page of the Twitter developer dashboard. Provide the url-encoded callback URL that will receive oauth_token and oauth_verifier in step four. This URL needs to be whitelisted in the "App details" tab of the Twitter dashboard.

const request = require('request-promise-native')
const encodeUrl = require('encodeurl')

const options = {
  headers: { Accept: '*/*', Connection: 'close', 'User-Agent': 'node-twitter/1' },
  oauth: {
    consumer_key: process.env.TWITTER_CONSUMER_KEY,
    consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
    callback: encodeUrl('https://your-app.com/twitter-callback'),
  },
  url: `https://api.twitter.com/oauth/request_token`,
}

const result = await request.post(options)

Step Two

Parsing the result will give us oauth_token and oauth_token_secret. Store these in your database associated with the user for later retrieval after the user has authorized your app.

const responseData = queryString.parse(result)

console.log(responseData)
//=> { oauth_token: 'NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0', oauth_token_secret: 'veNRnAWe6inFuo8o2u8SLLZLjolYDmDP7SzL0YfYI' }

const tmpOauthToken = responseData.oauth_token
const tmpOauthTokenSecret = responseData.oauth_token_secret

Step Three

Create a twitter.com URL and redirect the user to it. They are given
the opportunity to authorize your app. As soon as your app is authorized, Twitter redirects the user back to your app using the callback URL you provided in step one.

const redirectUrl =
  `https://api.twitter.com/oauth/authorize?oauth_token=${tmpOauthToken}`

Step Four

Your app's callback URL expects two pieces of information from Twitter in the form of url encoded parameters, oauth_token and oauth_verifier. The oauth_token is the same token your app received in step 1 and can be used to look up the previously stored oauth_token_secret. The URL will look something like this: https://your-app.com/twitter-callback?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY

const queryString = require('query-string')

console.log(location.search)
//=> 'oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY'

const tokens = queryString.parse(location.search)

const tmpOauthToken = tokens.oauth_token
const oauthVerifier = tokens.oauth_verifier

Fetch the tmpOauthTokenSecret value that you received in step one and stored in the database in step two. Use the tmpOauthToken value from above to do this.

Step Five

Your app now has oauth_token, oauth_token_secret, and oauth_verifier. Use these three pieces of information to make another POST request to Twitter. This time it uses the oauth/access_token endpoint. The response to this request contains the final oauth_token and oauth_token_secret. Store this final oauth_token and oauth_token_secret in the database securely associated with the user.

const options = {
  headers: { Accept: '*/*', Connection: 'close', 'User-Agent': 'node-twitter/1' },
  oauth: {
    consumer_key: process.env.TWITTER_CONSUMER_KEY,
    consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
    token: tmpOauthToken,
    token_secret: tmpOauthTokenSecret,
    verifier: oauthVerifier,
  },
  url: `https://api.twitter.com/oauth/access_token`,
}

const result = await request.post(options)

const responseData = queryString.parse(result)

// Final token to be stored with the user
const userOauthToken = responseData.oauth_token
const userOauthTokenSecret = responseData.oauth_token_secret

Using the results

Your app can now use the Twitter API on behalf of the user. This can be done with a Node Twitter client like this:

const Twitter = require('twitter')

const client = new Twitter({
  consumer_key: process.env.TWITTER_CONSUMER_KEY,
  consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
  access_token_key: userOauthToken,
  access_token_secret: userOauthTokenSecret
})

const result = await client.post('statuses/update', {
  status: 'All your Twitter are belong to us! (you did give us permission)'
})