DEV Community: Justin

4 Patterns for Responsive Props in React

Justin — Thu, 15 Oct 2020 18:35:35 +0000

Responsive CSS
Responsive Props
Responsive Prop Patterns
- Conditional Rendering
- Breakpoint Props
- Object of Props
- Array of Props
A Note About SSR
Summary
Responsive Prop Libraries

Responsive CSS

Many solutions exist for writing responsive CSS in React.

CSS-in-JS (Emotion and styled-components are two popular options)
Tailwind CSS
CSS Modules

If you feel like you need to use one, I recommend choosing something which supports reusable media queries. You don't want to be hard-coding breakpoint values all throughout your code (it's tedious to write, error prone, and difficult to change).

But you might not need to write any responsive CSS.

Responsive Props

Responsive CSS in React has a glaring weakness: it doesn't allow you to responsively change the values of props. Instead of writing CSS wrapped in media queries, responsive props is a method where you specify the value of the prop for predefined breakpoints and logic exists somewhere that chooses the value associated with the active breakpoint.

Why would you want to do that? Let's say you have different button sizes: large, medium, small. You probably don't want all buttons to change size responsively the same way. You might want one button to be small in mobile layouts while another is medium. So instead of responsive CSS, what you really want is responsive props.

We'll introduce some patterns below which primarily differ in two ways:

How the different prop values are specified
Where the logic exists for choosing the correct value

The code samples shown in this blog post are copied from a sample app that has working examples of all the patterns.

Responsive Prop Patterns

The foundation of responsive props in react is knowing whether a given media query (aka breakpoint) is active. Let's write a custom hook for that called useMediaQuery().

import { useEffect, useState } from "react";

/**
 * Custom hook that tells you whether a given media query is active.
 *
 * Inspired by https://usehooks.com/useMedia/
 * https://gist.github.com/gragland/ed8cac563f5df71d78f4a1fefa8c5633
 */
export default function useMediaQuery(query) {
  const [matches, setMatches] = useState(false);
  useEffect(
    () => {
      const mediaQuery = window.matchMedia(query);
      setMatches(mediaQuery.matches);
      const handler = (event) => setMatches(event.matches);
      mediaQuery.addEventListener("change", handler);
      return () => mediaQuery.removeEventListener("change", handler);
    },
    [] // Empty array ensures effect is only run on mount and unmount
  );
  return matches;
}

It can be used like this:

const isActive = useMediaQuery('(max-width: 640px)');

But remember we don't want to be littering our code with breakpoint values so let's create another hook which returns booleans for all of our defined breakpoints. We'll call it useBreakpoints().

import useMediaQuery from "./useMediaQuery";

/**
 * Get a set of boolean representing which breakpoint is active
 * and which breakpoints are inactive.
 *
 * Inspired by: https://github.com/contra/react-responsive/issues/162#issuecomment-592082035
 */
export default function useBreakpoints() {
  const breakpoints = {
    isXs: useMediaQuery("(max-width: 640px)"),
    isSm: useMediaQuery("(min-width: 641px) and (max-width: 768px)"),
    isMd: useMediaQuery("(min-width: 769px) and (max-width: 1024px)"),
    isLg: useMediaQuery("(min-width: 1025px)"),
    active: "xs"
  };
  if (breakpoints.isXs) breakpoints.active = "xs";
  if (breakpoints.isSm) breakpoints.active = "sm";
  if (breakpoints.isMd) breakpoints.active = "md";
  if (breakpoints.isLg) breakpoints.active = "lg";
  return breakpoints;
}

It's used like this:

const {isXs, isSm, isMd, isLg, active} = useBreakpoints();

Those hooks can power all of the responsive prop patterns discussed below.

Conditional Rendering

Conditional rendering is the pattern of specifying content that gets rendered at the different breakpoints. We can accomplish that in two different ways.

Conditional Rendering with a Hook

We can use the useBreakpoints() hook from above to do conditional rendering like this:

const {isXs, isSm} = useBreakpoints();
return isXs || isSm ? <Button size="small" /> : <Button />;

Conditional Rendering with a Component

We could also write a component which will do something similar for us. Let's call it <Breakpoint>.

import useBreakpoints from "./useBreakpoints";

export default function Breakpoint({ at, children }) {
  if (!at) {
    console.error("<Breakpoint>: must specify a breakpoint for the `at` prop.");
  }
  const { active } = useBreakpoints();
  return active === at ? children : null;
}

Then we can use it like this:

return (<>
  <Breakpoint at="xs">
    <Button size="small">Button</Button>
  </Breakpoint>
  <Breakpoint at="sm">
    <Button size="small">Button</Button>
  </Breakpoint>
  <Breakpoint at="md">
    <Button>Button</Button>
  </Breakpoint>
  <Breakpoint at="lg">
    <Button size="large">Button</Button>
  </Breakpoint>
</>);

In its naive form, the component version of this pattern can be quite verbose. fresnel is a library which uses this pattern and provides additional props such as greaterThan and between which can decrease the amount of code you need to write.

Notice that with conditional rendering, we're not changing the value of props so much as changing what gets rendered. There are situations where that's exactly what we need, such as choosing whether to render the mobile or desktop menu.

return isXs || isXm ? <Mobile /> : <Desktop />;

As shown with the button example above, the conditional rendering pattern doesn't fit as well when we just want to make small tweaks such as changing the size or position of components. For those situations, we have other patterns that just modify props.

Breakpoint Props

Maybe we could have one prop for each breakpoint. So instead of just size we have sizeXs, sizeSm and so on. It would be used like this:

<Button sizeXs="small" sizeSm="small" sizeMd="medium" sizeLg="large">Button</Button>

In terms of usage, that's quite a bit less verbose than the example for conditional rendering. What about the implementation?

In the naive form, the implementation of this is very verbose.

import styles from "../Button.module.css";
import useBreakpoints from "../useBreakpoints";

const defaultSize = "";
const defaultColor = "#eee";

export default function ButtonNaive({
  sizeXs,
  sizeSm,
  sizeMd,
  sizeLg,
  colorXs,
  colorSm,
  colorMd,
  colorLg,
  children
}) {
  const { isXs, isSm, isMd, isLg } = useBreakpoints();
  let activeSize = defaultSize;
  let activeColor = defaultColor;
  if (isXs) {
    activeSize = sizeXs;
    activeColor = colorXs;
  } else if (isSm) {
    activeSize = sizeSm;
    activeColor = colorSm;
  } else if (isMd) {
    activeSize = sizeMd;
    activeColor = colorMd;
  } else if (isLg) {
    activeSize = sizeLg;
    activeColor = colorLg;
  }
  const buttonClasses = [styles.base];
  if (styles[activeSize]) {
    buttonClasses.push(styles[activeSize]);
  }
  return (
    <button
      className={buttonClasses.join(" ")}
      style={{ backgroundColor: activeColor }}
    >
      {children}
    </button>
  );
}

We can do much better with a dynamic lookup for the props.

import styles from "../Button.module.css";
import useBreakpoints from "../useBreakpoints";

const defaultSize = "";
const defaultColor = "#eee";

export default function DynamicButton({ children, ...props }) {
  const { active } = useBreakpoints();
  // The active breakpoint comes out lowercase but for the props
  // the first letter of the breakpoint needs to be capitalized.
  const activeCapitalized = active[0].toUpperCase() + active[1];
  // Now we dynamically lookup the value of each responsive prop
  // according to the active breakpoint.
  const activeSize = props[`size${activeCapitalized}`] || defaultSize;
  const activeColor = props[`color${activeCapitalized}`] || defaultColor;
  const buttonClasses = [styles.base];
  if (styles[activeSize]) {
    buttonClasses.push(styles[activeSize]);
  }
  return (
    <button
      className={buttonClasses.join(" ")}
      style={{ backgroundColor: activeColor }}
    >
      {children}
    </button>
  );
}

That's a little better but there's still more logic than we'd like to have in our components, so let's move some of it into a hook.

const defaultSize = "";
const defaultColor = "#eee";

function useResponsiveProp(props, propName, defaultValue) {
  const { active } = useBreakpoints();
  const activeCapitalized = active[0].toUpperCase() + active[1];
  return props[`${propName}${activeCapitalized}`] || defaultValue;
}

export default function DynamicButton({ children, ...props }) {
  const activeSize = useResponsiveProp(props, 'size', defaultSize);
  const activeColor = useResponsiveProp(props, 'color', defaultColor);
  const buttonClasses = [styles.base];
  if (styles[activeSize]) {
    buttonClasses.push(styles[activeSize]);
  }
  return (
    <button
      className={buttonClasses.join(" ")}
      style={{ backgroundColor: activeColor }}
    >
      {children}
    </button>
  );
}

If you still think that's too much logic for dumb presentation components then you could also create an HOC.

export default MakeResponsive(Button, ["size", "color"]);

function MakeResponsive(WrappedComponent, responsiveProps = []) {
  function MakeResponsiveWrapper(props) {
    const { active } = useBreakpoints();
    const activeCapitalized = active[0].toUpperCase() + active[1];
    const modifiedProps = { ...props };
    // Process the responsive props to extract responsive values
    for (const prop of responsiveProps) {
      const breakpointProp = `${prop}${activeCapitalized}`;
      if (props[breakpointProp]) {
        modifiedProps[prop] = props[breakpointProp];
      }
    }
    return <WrappedComponent {...modifiedProps} />;
  }
  MakeResponsiveWrapper.displayName = `MakeResponsive(${
    WrappedComponent.displayName || WrappedComponent.name
  })`;
  return MakeResponsiveWrapper;
}

That lets our components be dumb again, but now we have an HOC 😬.

Object of Props

The same code which inspired the useMediaQuery() hook also introduced me to a new pattern: specifying values for each breakpoint and letting a hook choose those values.

useBreakpointValues()

We can use the useBreakpoints() hook to create another hook called useBreakpointValues() which accepts a map of breakpoints and values and returns the value for the breakpoint that is currently active.

function useBreakpointValues(breakpointValues) {
  const { active } = useBreakpoints();
  return breakpointValues[active];
}

We could use that inside our components to make any prop accept responsive values.

const defaultColors = {
  xs: "#eee",
  sm: "#eee",
  md: "#eee",
  lg: "#eee"
};

export default function Button({ size, color = defaultColors, children }) {
  const appliedSize = useBreakpointValues(size);
  const appliedColor = useBreakpointValues(color);
  const buttonClasses = [styles.base];
  if (styles[appliedSize]) {
    buttonClasses.push(styles[appliedSize]);
  }
  return (
    <button
      className={buttonClasses.join(" ")}
      style={{ backgroundColor: appliedColor }}
    >
      {children}
    </button>
  );
}

But that makes our component more complicated. I recommend keeping the component simple and using the hook outside of the component.

const currentSize = useBreakpointValues({
  xs: 'small',
  sm: 'small',
  md: 'medium',
  lg: 'large'
});
return <Button size={currentSize}>Button</Button>;

Using this pattern, our components can remain dumb presentation components by moving the breakpoint logic into a custom hook that we use outside of the components.

Component

We could also build a component version of useBreakpointValues() which uses render props to create a responsive prop pattern I learned from instructure-ui.

import useBreakpointValues from "./useBreakpointValues";

export default function Responsive({ props, children, render }) {
  const appliedProps = useBreakpointValues(props);
  if (!(children || render)) {
    console.error("<Responsive> must be given a render prop or children prop.");
  }
  const renderFn = children || render;
  return renderFn(appliedProps);
}

We would use it like this:

return (
  <Responsive props={{
    xs: 'small',
    sm: 'small',
    md: 'medium',
    lg: 'large'
  }}>
    {(size) => <Button size={size}>Button</Button>}
  </Responsive>
);

Why would you want to do that instead of the hook? Perhaps just personal preference. And when you have responsive props for multiple components, it could help avoid the need for coming up with unique names. You can see this in the following contrived example using different button sizes for three buttons. Using the <Responsive> component is a little more verbose, and the render props pattern is pretty awkward to type, but maybe you just really dislike coming up with creative variable names.

const size1 = useBreakpointValues({...});
const size2 = useBreakpointValues({...});
const size3 = useBreakpointValues({...});
return (
  <div>
    <Button size={size1}>Button 1</Button>
    <Button size={size2}>Button 2</Button>
    <Button size={size3}>Button 3</Button>
  </div>
);

// Here's the same setup using <Responsive>
return (
  <div>
    <Responsive props={{...}}>
      {(size) => <Button size={size}>Button 1</Button>}
    </Responsive>
    <Responsive props={{...}}>
      {(size) => <Button size={size}>Button 2</Button>}
    </Responsive>
    <Responsive props={{...}}>
      {(size) => <Button size={size}>Button 3</Button>}
    </Responsive>
  </div>
);

HOC for Responsive Props

Maybe neither of those are quite what you're looking for because you really like HOCs. We can do that too.

Usage:

<ButtonHOC size={{ xs: "small", sm: "small", md: "medium", lg: "large" }}>
  Button
</ButtonHOC>

Implementation:

function MakeResponsive(WrappedComponent, responsiveProps = []) {
  function MakeResponsiveWrapper(props) {
    const { active } = useBreakpoints();
    const modifiedProps = { ...props };
    // Process the responsive props to extract responsive values
    for (const prop of responsiveProps) {
      if (props[prop]) {
        modifiedProps[prop] = props[prop][active];
      }
    }
    return <WrappedComponent {...modifiedProps} />;
  }
  MakeResponsiveWrapper.displayName = `MakeResponsive(${
    WrappedComponent.displayName || WrappedComponent.name
  })`;
  return MakeResponsiveWrapper;
}

const ButtonHOC = MakeResponsive(Button, ['size','color']);

Again, our component stays dumb while the HOC makes it smarter.

TIP: If you dislike having to specify a value for each breakpoint, even when each breakpoint doesn't have a distinct value, then you could add some logic to useBreakpointValues() so that if a breakpoint value isn't specified it just uses the value for the breakpoint below it. Then you would only have to specify when the value changes. Example: {xs: 'small', md: 'large'}.

Array of Props

If you like how the object props pattern moves the logic outside of the component but dislike having to specify the breakpoints each time by name, then you may like this variation where props are specified via an array.

const size = useBreakpointValues([ "small", "small", "medium", "large" ]);
return <Button size={size}>Button</Button>;

// Or...

<Button size={[ "small", "small", "medium", "large" ]}>
  Button
</Button>

The downside of this pattern is that it's not explicit; e.g. it's not immediately clear which value is associated with which breakpoint.

A Note About SSR

There is no screen on the server so no breakpoints will be active. The best way to handle this situation is to choose a breakpoint that is active by default. Make this choice carefully because it could impact SEO (particularly for search engines that don't execute JavaScript).

Summary

A few patterns exist for responsive props in React. While choosing which patterns to use, consider these characteristics.

		How props are specified	Where the logic exists for choosing the active value
Conditional Rendering		Separately in each instance	Outside the component
Breakpoint Props	Naive	One prop for each breakpoint	Inside the component
	Dynamic	One prop for each breakpoint	Inside the component
	Dynamic Hook	One prop for each breakpoint	Inside a hook
	HOC	One prop for each breakpoint	Inside an HOC
Object of Props	Hook	An object	In the component or in a hook
	Render-prop Component	An object	In the render-prop component
	HOC	An object	In the HOC
Array of Props	Hook	An array	In the component or in a hook
	Render-prop Component	An array	In the render-prop component
	HOC	An array	In the HOC

My preference is to use the Object Props pattern with the useBreakpointValue() hook and <Responsive> component because I like the explicit nature of the props object and I like having the logic for choosing the active breakpoint value outside of my components.

What do you think? Which pattern do you like? Are there responsive prop patterns I didn't include? If you're not using responsive props, do you feel like you should? Let me know in the comments. Thanks for reading!

Responsive Prop Libraries

Conditional Rendering

fresnel
react-responsive
react-media was an early player in this game. Unfortunately the library hasn't been updated for hooks.

Blue/Green Node.js Deploys with NGINX

Justin — Thu, 10 Sep 2020 23:10:59 +0000

I recently faced a situation where I needed to deploy Node.js apps to my own servers¹. When I started this endeavor, I tried to find helpful material so that I didn't have to figure it all out myself, but all I could find was "use NGINX" and "probably use pm2." Those were helpful recommendations, but it still left a lot of details for me to figure out. In this post, I'll discuss the issues I faced and the solutions I chose so that maybe it helps someone else in the future who is facing similar problems.

We'll cover the following topics:

Verifying Host Keys
Remotely Executing a Deploy Script on the VMs
Managing the Node.js Processes with PM2
Blue/Green Deploys with NGINX
Parallel Deploys
Reusable Private GitHub Action
Scrubbing Secrets in GitHub Action Logs

Requirements

Zero-downtime deploys. I could easily justify to management that it's too complicated and we must have a maintenance window, but zero-downtime deploys are expected these days, especially for front-end apps. For my own sake (my pride and my conscience), I wanted to make this happen.
Automatically deploy whenever the master branch is updated. I don't know how common this is but I've been doing this for years with Heroku and I can't imagine any other way of developing. Manually triggering deploys feels archaic.
Deploy to existing machines. The deploy targets would be a set of production VMs that are currently in use. I did not have the option of using new VMs and swapping out the old ones.

Implementation

We already used GitHub Actions to run tests against all PRs so I figured we'd also use them to trigger deploys when the master branch is updated.

Conceptually, I imagined the process would look something like this:

A push to master triggers a deploy
Connect to all deploy targets (servers) and run a script that installs and runs the new code
Divert traffic from the old code to the new code
Cleanup the old code

It took me 3-4 days to get from that high-level outline to the final implementation. I'll explain where I ended up and why I made certain choices.

Verifying Host Keys

One of the first issues I ran into was verifying the host keys. When you first ssh into a machine, a prompt asks you whether you trust the remote server's key. But I was running this in a script so I needed to avoid that prompt. You can disable it, but that's considered dangerous because of potential man-in-the-middle attacks. An alternative is to use ssh-keyscan to automatically add the remote keys to your trusted list.

ssh-keyscan "$IP" >> ~/.ssh/known_hosts

But I don't see how that's any more secure. Either way, you're blindly trusting the IP. What are the alternatives? Perhaps you could manually run ssh-keyscan once for each host and then store the result in a config that then get's added to known_hosts.

Remotely Executing a Deploy Script on the VMs

I had a list of IPs that were deploy targets and an SSH key. Somehow I needed to run a set of commands on the VMs that would actually perform the deploy. The set of commands started small so I began by using appleboy/ssh-action.

      - name: SSH Commands
        uses: appleboy/ssh-action@v0.1.3
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        with:
          host: ${{ secrets.DEPLOY_IP }}
          username: ${{ secrets.DEPLOY_USERNAME }}
          key: ${{ secrets.SSH_KEY }}
          script_stop: true
          envs: GH_TOKEN
          script: |
            cd /srv/bg
            git clone --depth 1 "https://${GH_TOKEN}@github.com/Org/Repo.git"
            cd bg-web
            npm i
            npm run build
            npm run start

But my short list of commands quickly grew and I soon desired to maintain a bash script that would be remotely executed. So I switched to something like this:

      - name: Deploy
        run: | 
          KEY_FILE=$(mktemp)
          echo "${{ secrets.SSH_KEY }}" > "$KEY_FILE"
          ssh -i $KEY_FILE ubuntu@${{ secrets.DEPLOY_IP }} -- < deploy.sh

That worked well. I particularly enjoyed having syntax highlighting while working on the deploy script. But eventually I wanted more, such as logging output of the deploy script to a temporary log file and passing env vars to the script. I decided to just copy the deploy script onto the VM before executing. I already had an SSH key available which made this easy with scp:

# Transfer the deploy script onto the VM so that we can execute it later.
# If we have previously deployed to the VM, an older version of the script will be there and be overwritten with the latest version.
scp -i $KEY_FILE /scripts/deploy.sh ubuntu@$IP:~/

# Execute the deploy script and save the logs to a temp file.
ssh -i $KEY_FILE ubuntu@$IP "tmpfile=$(mktemp /tmp/deploy.XXXX); echo \"Deploy log for $IP saved in \$tmpfile\"; GH_TOKEN=$GH_TOKEN IP=$IP REPO=$REPO bash deploy.sh > \$tmpfile 2>&1"

That's what I ended up. The only thing I don't like about it is the list of environment variables (the list is actually a lot longer in the version I'm using). If you know of a better way, please let me know.

Managing the Node.js Processes with PM2

Node.js is single-threaded which means you need to run multiple instances of the same process in order to use all available CPU cores. Typically this is done with the Cluster API. I've used it before and I didn't want to use it again. You have to setup a master file that spawns processes and manages their lifecycle, handles errors, respawns processes that die, etc. Instead of handling all that myself, I chose to use pm2. Now clustering an app is as simple as:

pm2 start -i max --name $PROCESS_NAME $START_COMMAND

Later, when I need to cleanup the old code, I can use pm2 list to find any processes which don't match the new $PROCESS_NAME and kill them with pm2 delete. More on that in the next section.

Blue/Green Deploys

A blue/green deployment is one way to achieve zero-downtime deployments by spinning up a new server then routing traffic to it before retiring the old server. However, I didn't have the affordance of using a new server so I had to accomplish the same thing on an existing server.

Traffic would come in on port 80 or 443. Binding to those ports requires root privileges. But you don't want your web app to have root privileges. So you can either use iptables to redirect port 80 to your app, or you can use NGINX. We chose NGINX because it offers much more in the way of HTTP configuration which we anticipate needing in the future (SSL certificates, headers, etc.).

We start off with a conf file in /etc/nginx/site-enabled that looks like this:

server {
  listen 80;
  server_name domain.com;
  location / {
    proxy_pass http://localhost:3000;
  }
}

Later, when we deploy a new script, port 3000 is already used so we need to use a different port. We could constantly swap back and forth between port 3000 and 3001, but keeping track of which port is currently being requires state and feels fragile. So I opted with randomly generating a port each time, then checking that it's not currently being used.

# Picks a random number between 3000 and 3999.
function random-number {
  floor=3000
  range=3999
  number=0
  while [ "$number" -le $floor ]
  do
    number=$RANDOM
    let "number %= $range"
  done
  echo $number
}

# Pick a random port between 3000 and 3999 that isn't currently being used.
PORT=$(random-number)
while [[ $(lsof -i -P -n | grep :$PORT) ]]
do
  PORT=$(random-number)
done

echo "Ready to deploy on port $PORT"

I also used the port number in the directory where I installed the code (to make sure there weren't any conflicts with previous installations) and to identify the processes with registering them with pm2.

Now we update the NGINX conf:

sudo cat << EOF | sudo tee /etc/nginx/sites-enabled/site.conf > /dev/null
server {
  listen 80;
  server_name domain.com;
  location / {
    proxy_pass http://localhost:$PORT;
  }
}
EOF

Though the configuration file has changed, NGINX isn't yet aware of it. We can tell it to reload the file by sending the reload signal:

sudo nginx -s reload

The NGINX docs say that this is supposed to happen gracefully:

It starts new worker processes, and sends messages to old worker processes requesting them to shut down gracefully. Old worker processes close listen sockets and continue to service old clients. After all clients are serviced, old worker processes are shut down.

That's wonderful. It takes care of gracefully transferring traffic so that we don't have to. However, it doesn't emit a signal when the transfer is done. So how do we know when we can retire and cleanup the old code?

One way is by watching traffic to your processes. But that sounds complicated to me. There are multiple processes. How do I know when traffic is done going to all of them? If you have any ideas here I'd love to hear. But I went with a different solution.

I realized that NGINX had a fixed number of worker processes (which appears to be tied to the number of CPU cores). But the paragraph I quoted above about reloading says it starts new workers in parallel to the old, so during the reload you have 2x the number of workers. Therefore I figured I could count the number of worker processes before the reload and then wait until the number of workers returned to normal. It worked.

function nginx-workers {
  echo $(ps -ef | grep "nginx: worker process" | grep -v grep | wc -l)
}

# Reload (instead of restart) should keep traffic going and gracefully transfer
# between the old server and the new server.
# http://nginx.org/en/docs/beginners_guide.html#control
echo "Reloading nginx..."
numWorkerProcesses=$(nginx-workers)
sudo nginx -s reload

# Wait for the old nginx workers to be retired before we kill the old server.
while [ $(nginx-workers) -ne $numWorkerProcesses ]
do
  sleep 1;
done;

# Ready to retire the old code

It's not 100% zero-downtime. I did load testing to confirm that there's about a second of down time. I don't know whether that's because I'm still killing the old processes too early or if it's because NGINX is refusing connections. I tried adding more sleep after the loop to make sure all connections had drained and terminated but it didn't help at all. I also noticed that the errors (during the load test) were about not being able to establish a connection (as opposed to the connection being terminated early) which leads me to believe it's due to NGINX reloads not being 100% graceful. But it's all good enough for now.

Now we're ready to cleanup the old code:

# Delete old processes from PM2. We're assuming that traffic has ceased to the
# old server at this point.
# These commands get the list of existing processes, pair it down to a unique
# list of processes, and then delete all but the new one.
pm2 list | grep -o -P "$PROCESS_NAME-\d+" | uniq | while IFS=$'\n' read process; do
  if [[ $process != $PROCESS_NAME-*$PORT ]];
  then
    pm2 delete $process
  fi
done

# Delete old files from the server. The only directory that needs to remain
# is the new directory for the new server. So we loop through a list of all
# directories in the deploy location (currently /srv/bg) and delete all
# except for the new one.
echo "Deleting old directories..."
for olddir in $(ls -d /srv/bg/*); do
  if [[ $olddir != /srv/bg/$PORT ]];
  then
    echo "Deleting $olddir"
    rm -rf $olddir
  else
    echo "Saving $olddir"
  fi
done;

Parallel Deploys

I first got the blue/green deploy working on one machine. I figured it'd be easy to change so that it works on multiple machines by looping over a list of IP addresses. It probably would've been easy if I had done the deploys serially, but I wanted to do the deploys in parallel to reduce the time spent on the deploy. I was hoping I could just background the ssh command ssh &. But I got some error message about how that was wrong. Searching the internet revealed a host of alternatives that didn't work or that didn't easily provide a child process ID (more later on why we need that). I finally ended up just creating another bash script that had the scp and ssh commands. Then I could easily background the execution of that bash script.

# Turn the list of IPs into an array
IPS=( $DEPLOY_IPS )
for IP in "${IPS[@]}"; do
  echo "Preparing to connect to $IP"
  # Here's that list of env vars again
  KEY_FILE=$KEY_FILE GH_TOKEN=$GH_TOKEN IP=$IP REPO=$GITHUB_REPOSITORY bash /scripts/connect.sh &
done

So I ended up with this trio of scripts:

deploy-manager.sh -> connect.sh -> deploy.sh

But how do I know when the deploys are done and how will I know if one of them fails? I found a nice solution on the Unix & Linux StackExchange website. You just collect the child process IDs, then wait on all of them to make sure their exit codes are 0.

What do you do if the deploy fails on one machine but succeeds on another? I haven't addressed that problem yet. Any ideas?

Reusable Private GitHub Action

After I got this all working in one repo with multiple deploy targets, I decided to move it into a private GitHub Action so that it could be shared across multiple Node.js apps. I expected this to be easy because I already had all the working code. But as always, I was wrong.

First, GitHub doesn't officially support private actions, but you can get around it with a handy solution.

GitHub offers two implementation choices for custom actions: Node.js or Docker. I have written Node.js actions before and I didn't enjoy the experience as much as I had hoped. It requires you to commit bundled code to your repo because it doesn't install dependencies for you. You can probably get away without using deps if you work hard at it, but it's even more inconvenient to not use @actions/core. It also feels wrong to write a node script that just executes a bash script. So I decided to create a Docker action.

I assumed that all I needed was vanilla dockerfile that would execute the deploy-manager.sh script. But I quickly ran into problems. My scripts were developed to execute on the GitHub workflow runners. I specified ubuntu-latest and assumed it was a pretty vanilla install. But it turns out they install tons of software and unfortunately do not have it available a docker container. Luckily, all I needed to install was openssh-server. Here's my final Dockerfile:

FROM ubuntu:18.04

RUN apt update && apt install -y openssh-server

COPY scripts/*.sh /scripts/

ENTRYPOINT ["/scripts/deploy-manager.sh"]

I ran into another problem. Host key verification started failing when I switched to the Docker action. It's because Docker GitHub Actions are run as root while I developed the scripts running as the user ubuntu. Users have their own known_hosts file located at ~/.ssh/known_hosts. But for root I needed to modify the global file located at /etc/ssh/ssh_known_hosts.

I was pleased to learn Docker, but I might reevaluate the decision to use it. Is it better to build a container every time an action runs or to commit bundled code to your action repo? 😬

Scrubbing Secrets in GitHub Action Logs

If you want have custom environment variables in GitHub Workflows, your only option is to use Secrets. One of my secrets stores the list of IPs for the deploy targets. But it's not really something I need to keep private and is often useful in debug logs.

GitHub scrubs action logs to automatically redact secrets. Since my IPs were in a list and I was only printing one, I figured it wouldn't be redacted. But it was! They must be doing partial matching on the secrets (I wonder what length of characters they use). To get around this, I used an $UNSECRET_IP variable that was $IP with all the dots replaced with dashes. Sure enough, it wasn't redacted.

UNSECRET_IP=$(echo $IP | tr . -)

Conclusion

That's a lot of work, and it doesn't even handle partial deploy failures, roll-backs, or log management. I imagine I'll spend quite a bit of time maintaining this creation. It's cemented by belief in the value of PaaS providers. I'd much rather pay someone to do this for me and to do it much better than I can.

I prefer using PaaS providers like Heroku, Netlify, and Vercel so that I don't have to do everything discussed here 😂. ↩

Automatically Create a Release When The package.json Version Changes

Justin — Thu, 20 Aug 2020 17:44:29 +0000

My Workflow

Automatic GitHub Release: Automatically generate a release when the package.json version changes.

It's currently being used to manage releases of itself. I created it to help manage releases of some private packages I'm working on.

Submission Category:

Maintainer Must-Haves

Yaml File or Link to Code

justincy / github-action-npm-release

Automatically generate a release when the package.json version changes

Automatic GitHub Release

Automatically generate a release when the package.json version changes. The release name and tag will match the new version. If no releases yet exist, this action will create the first release.

The release notes will contain a change log generated from git history in the following format:

- f0d91bd Making progress
- 275e3e2 Initial commit

Assumptions

This action makes a few assumptions:

actions/checkout@v2 with fetch-depth: 0 is used before this action runs. That allows this action to have all the information it needs to generate the change log from the git history.
You are only releasing from one branch
It is only used during push

Usage Example

name: Release
on
  push:
    branches:
      - master

jobs:
  build:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - name: Release
        uses

…

View on GitHub

Additional Resources / Info

What I learned:

Debugging is rough. act makes it easier but it's not a perfect solution.
The first gotcha I ran into was that steps need an ID in order to reference their output. For some reason can't reference steps by their name.
Actions can't depend on other actions. My original plan was to create a few small actions and stitch them together into a larger composite action but it's not possible.
Use @actions/core, even if you think your script will be small. It makes input, output, errors, etc much easier. Chances are your script will become quite a bit more complex when you start handling errors.
You must bundle all code that your actions needs, including dependencies. The best solution is to use @vercel/ncc.

Locale specific domains in Next.js with next-i18next

Justin — Tue, 18 Aug 2020 17:12:42 +0000

Google recommends three different ways for creating locale-specific URLs:

Country-specific domains: example.de
Subdomains: de.example.com
Subdirectories: examples.com/de/

In this post, I'll show how to use country-specific domains and subdomains for language detection in Next.js with next-i18next.

A full working example of what will be shown is available here: https://github.com/justincy/nextjs-domain-locales

By default, next-i18next uses the Accept-Language header (sent by the browser) to determine which language to show initially. This choice is stored in a cookie so that if the user requests a different language, that new preference is persisted.

But when using locale-specific domains and subdomains, we don't care about the Accept-Language header. We just need to know what domain is being used so that we can lookup the associated locale. Thankfully, next-i18next allows for custom language detectors. So let's create one.

First, we need a list of the domains we want to use as well as their associated locales. You can use any domain names you want as long as they get routed to your server and you configure them in the locale map.

const domainLocaleMap = {
  'localhost': 'en',
  'nexttest.com': 'en',
  'nexttest.es': 'es',
  'nexttest.de': 'de',
  'it.nexttest.international': 'it',
  'ua.nexttest.international': 'ua',
};

You'll need to modify your hosts file to get those domains working locally.

Now we need to write the code that uses the domainLocaleMap. For this we'll be writing a custom i18next-http-middleware language detector. We don't need to cache the language (because it's always determined by the URL) so we just need to specify name and lookup. The code will run both in the browser and on the server so we handle both cases.

const domainDetector = {
  // We use the name to refer to it later when we want to tell i18next when to use it.
  name: 'domain',
  lookup(req, res, options) {
    // You need to either set the value of DEFAULT_LOCALE before this or hard-code the value here.
    let locale = DEFAULT_LOCALE;
    // In the browser, get the hostname from window.location.
    if (typeof window !== 'undefined' ) {
      locale = domainLocaleMap[window.location.hostname];
    } 
    // On the server, get the hostname from the request headers.
    // We use the host header which is available on IncomingMessage.
    // https://nodejs.org/api/http.html#http_class_http_incomingmessage
    // But the host header may include the port so first we take that off, if it exists.
    else {
      const hostname = req.headers.host?.split(':')[0];
      locale = domainLocaleMap[hostname];
    }
    return locale;
  }
};

Now all that's left is to register the custom detector.

// https://github.com/isaachinman/next-i18next#options
module.exports = new NextI18Next({
  defaultLanguage: DEFAULT_LOCALE,
  otherLanguages: supportedLangs,
  localePath: path.resolve('./public/static/locales'),
  // Register our custom language detector
  customDetectors: [domainDetector],
  // Tell i18next to _only_ use our custom language detector.
  // https://github.com/i18next/i18next-http-middleware#detector-options
  detection: {
    order: ['domain']
  }
});

That's it! A full working example with Next.js is available here: https://github.com/justincy/nextjs-domain-locales

Hat tip to @lucasfeliciano for providing most of the details about how this can be done.

Using mapbox-gl in React

Justin — Wed, 22 Jul 2020 19:01:39 +0000

Mapbox has a great tutorial for getting started with mapbox-gl in React. We want to take it even further by creating a reusable hook component. Our maps won't always look the same: different container sizes, different controls, and different data.

Requirements:

Centralized location for instantiating the map. We don't want to duplicate the map setup and connection between React and mapbox-gl.
Flexibility in map options.
Access to the map instance so that we can add data and event handlers.
Control over the size of the map container.

import React, { useRef, useState, useEffect } from 'react';
import mapboxgl from 'mapbox-gl';

// Be sure to replace this with your own token
mapboxgl.accessToken = 'MY_ACCESS_TOKEN';

export default function Map({
  center,
  zoom = 17,
  width = '100%',
  height = '300px',
  onInit,
}) {
  const ref = useRef(null);
  const [map, setMap] = useState(null);
  useEffect(() => {
    // Don't create the map until the ref is connected to the container div.
    // Also don't create the map if it's already been created.
    if (ref.current && !map) {
      const map = new mapboxgl.Map({
        container: ref.current,
        style: 'mapbox://styles/mapbox/streets-v11',
        center,
        zoom,
      });
      setMap(map);
      onInit(map);
    }
  }, [ref, center, zoom, map, onInit]);
  return <div ref={ref} style={{ width, height }} />;
}

That's great, but it still only allows us to change the width and height of the map container. That's probably all you need, but if you want more control then you have two options.

1. Add a className prop to the component.

Adding a className prop allows you to specify a custom style for the map container. You could also accept a styles prop if you prefer inline styles, but I prefer className.

import React, { useRef, useState, useEffect } from 'react';
import mapboxgl from 'mapbox-gl';

// Be sure to replace this with your own token
mapboxgl.accessToken = 'MY_ACCESS_TOKEN';

export default function Map({
  center,
  zoom = 17,
  className,
  onInit,
}) {
  const ref = useRef(null);
  const [map, setMap] = useState(null);
  useEffect(() => {
    // Don't create the map until the ref is connected to the container div.
    // Also don't create the map if it's already been created.
    if (ref.current && !map) {
      const map = new mapboxgl.Map({
        container: ref.current,
        style: 'mapbox://styles/mapbox/streets-v11',
        center,
        zoom,
      });
      setMap(map);
      onInit(map);
    }
  }, [ref, center, zoom, map, onInit]);
  return <div ref={ref} classname={className} />;
}

2. Turn this into a custom hook

Using a custom hook means you've centralized instantiation of the map but have full control over the container it's attached to.

/**
 * useMap.js
 */
import mapboxgl from 'mapbox-gl';
import React, { useRef, useEffect, useState } from 'react';

// Be sure to replace this with your own token
mapboxgl.accessToken = 'MY_ACCESS_TOKEN';

export default function useMapbox({
  center,
  zoom = 17,
  onInit
}) {
  const ref = useRef(null);
  const [map, setMap] = useState(null);
  useEffect(() => {
    if (ref.current && !map) {
      const map = new mapboxgl.Map({
        container: ref.current,
        style: 'mapbox://styles/mapbox/streets-v11',
        center,
        zoom,
      });
      setMap(map);
      onInit(map);
    }
  }, [ref, center, zoom, map]);
  return { ref };
}

Then we use the hook in a component:

import useMap from './useMap';

function FancyMap() {
  const onInitHandler = map => {
    // Add data and events here
  }
  const { ref } = useMap({ center, zoom, onInit: onInitHandler });
  return <div ref={ref} style={{ width: '100%', height: '300px' }} />;
}

publicRuntimeConfig undefined when using Storybook with Next.js

Justin — Wed, 06 May 2020 21:26:48 +0000

publicRuntimeConfig is setup for us automatically in a Next app, but that doesn't happen when our code gets bundled into Storybook so we need to do it ourselves.

Developers have previously seen this issue in jest tests, so we'll borrow our solution from them by manually setting the config ourselves. We'll add the following code to .storybook/preview.js (create the file if it doesn't already exist):

// Allow us to use `publicRuntimeConfig` in stories
import { setConfig } from 'next/config';
import { publicRuntimeConfig } from './next.config';
setConfig({ publicRuntimeConfig });

That works fine if your next.config file is simple, but if you do any imports (such as for setting up Next Bundle Analyzer) then you might run into new errors in Storybook caused by it trying to bundle this imports. In that case, you can the runtime config to a separate file and importing just the runtime config into the storybook setup:

// runtimeConfig.js
module.exports {
  // Add your config here
};

// next.config.js
const runtimeConfig = require('./runtimeConfig');
module.exports = {
  publicRuntimeConfig: runtimeConfig
};

// storybook/preview.js
import { setConfig } from 'next/config';
import publicRuntimeConfig from '../src/config';
setConfig({ publicRuntimeConfig });

Detecting a User's Authenticated State Client-Side in Next.js using an HttpOnly Cookie and Static Optimization

Justin — Fri, 01 May 2020 22:09:24 +0000

In a previous post, I discussed how to detect a user's authenticated state when using SSR. In this post I propose a similar architecture that works with static optimization. The architecture described here also works with SSR, which makes it much more appealing than one which only works with SSR and doesn't work at all with static optimization.

First, let's review some key points which will inform the requirements of our architecture:

The client doesn't validate authentication; the server does validation. The client just needs to know whether or not the user is authenticated. In other words, just a boolean: true or false.
The traditional methods for clients to detect authenticated state is through either a) global data populated during render by the server or b) detecting the presence of a session cookie.
Statically optimized pages are rendered on the server during the build, but not at runtime. Therefore, we can't have the server populate global data on the page for detecting authenticated state.
We want to avoid having our session cookies stolen by 3rd party scripts, so we'll store the session token or ID in an HttpOnly cookie. Unfortunately, that also prevents our client-side JS from reading it.

Therefore, we need something else.

HttpOnly cookies are sent to the server, so we need a server endpoint that tells us whether the user is authenticated. It could be an endpoint for retrieving the user profile: if the profile is returned, the user is authenticated; if we get a 401, the user isn't authenticated. Or it could just be an endpoint built specifically for this (e.g. /checkAuth) which returns a 200 or 401.

As before, we will use the Context API to store our authenticated state. It will be initialized when the page loads by making a request to our API, as we just discussed. But until that request returns, the authenticated state is unknown. You might be able to assume false, but if you choose to render or redirect pages based on the authenticated state, then it's best not to make that assumption. So our context will also contain an isLoading boolean which we can use to show a loading indicator until the authentication response is returned and we know what to do.

import React from 'react';

const AuthContext = React.createContext({
  isAuthenticated: false,
  isLoading: true,
  setAuthenticated: () => {}
});

export const AuthProvider = ({ children }) => {
  const [isAuthenticated, setAuthenticated] = React.useState(false);
  const [isLoading, setLoading] = React.useState(true);
  React.useEffect(() => {
    const initializeAuth = async () => {
      const response = await fetch('/api/checkAuth');
      setAuthenticated(response.status === 200);
      setLoading(false);
    };
    initializeAuth();
  }, []);
  return (
    <AuthContext.Provider
      value={{
        isAuthenticated,
        isLoading,
        setAuthenticated
      }}
    >
      {children}
    </AuthContext.Provider>
  );
};

export function useAuth() {
  const context = React.useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}

export function useIsAuthenticated() {
  const context = useAuth();
  return context.isAuthenticated;
}

Now our end goal is to have two HOCs, withAuth and withoutAuth that will render or redirect pages based on the authenticated state. The majority of their code is shared so we'll create a withAuthRedirect HOC that they'll use.

import { useRouter } from 'next/router';
import { useAuth } from '../providers/Auth';

function DefaultLoadingFallback() {
  return <p>Loading...</p>;
}

/**
 * Support client-side conditional redirecting based on the user's
 * authenticated state.
 *
 * @param WrappedComponent The component that this functionality
 * will be added to.
 * @param LoadingComponent The component that will be rendered while
 * the auth state is loading.
 * @param expectedAuth Whether the user should be authenticated for
 * the component to be rendered.
 * @param location The location to redirect to.
 */
export default function withAuthRedirect({
  WrappedComponent,
  LoadingComponent = DefaultLoadingFallback,
  expectedAuth,
  location
}) {
  const WithAuthRedirectWrapper = props => {
    const router = useRouter();
    const { isLoading, isAuthenticated } = useAuth();
    if (isLoading) {
      return <LoadingComponent />;
    }
    if (typeof window !== 'undefined' && expectedAuth !== isAuthenticated) {
      router.push(location);
      return <></>;
    }
    return <WrappedComponent {...props} />;
  };
  return WithAuthRedirectWrapper;
}

Now we're ready to create the other two HOCs.

import withAuthRedirect from './withAuthRedirect';

/**
 * Require the user to be authenticated in order to render the component.
 * If the user isn't authenticated, forward to the given URL.
 */
export default function withAuth(WrappedComponent, location = '/login') {
  return withAuthRedirect({
    WrappedComponent,
    location,
    expectedAuth: true
  });
}

import withAuthRedirect from './withAuthRedirect';

/**
 * Require the user to be unauthenticated in order to render the component.
 * If the user is authenticated, forward to the given URL.
 */
export default function withoutAuth(WrappedComponent, location = '/profile') {
  return withAuthRedirect({
    WrappedComponent,
    location,
    expectedAuth: false
  });
}

Those two HOCs may be used like this:

export default withAuth(function ProfilePage() { ... });

We've accomplished our goal of an architecture which allows us to detect authentication client-side using an HttpOnly cookie and static optimization.

There is an example app using this pattern. It's also available in TypeScript.

Client-Side and Server-Side Redirects in Next.js

Justin — Tue, 28 Apr 2020 15:18:54 +0000

This guide was written back when only getInitialProps existed and only applies to that method. This does not apply to getServerSideProps, and it doesn't work with getServerSideProps because you can't use both getInitialProps and getServerSideProps on the same page.

Sometimes when rendering, you might want to perform a redirect. For example, you might have an HOC that only renders the component when the user is authenticated and otherwise redirects to the login page. Next.js supports both client-side and server-side rendering (SSR) and unfortunately the method for redirecting is very different in both contexts.

Client-Side

Client-side, imperative navigation is done via next/router.

import Router from 'next/router'

Router.push('/new/url')

There's also a useRouter() hook that can be used in components.

import { useRouter } from 'next/router'

function RedirectPage() {
   const router = useRouter()
   // Make sure we're in the browser
   if (typeof window !== 'undefined') {
     router.push('/new/url')
   }
}

export default RedirectPage

Server-Side

Router uses window.history underneath which means you can't change URLs on the server. Instead, we must get access to the response object and respond with an HTTP redirect status code.

The response object is available via the context object that get's passed to getInitialProps().

import { useRouter } from 'next/router'

function RedirectPage({ ctx }) {
  const router = useRouter()
  // Make sure we're in the browser
  if (typeof window !== 'undefined') {
    router.push('/new/url');
    return; 
  }
}

RedirectPage.getInitialProps = ctx => {
  // We check for ctx.res to make sure we're on the server.
  if (ctx.res) {
    ctx.res.writeHead(302, { Location: '/new/url' });
    ctx.res.end();
  }
  return { };
}

export default RedirectPage

Do Both in an HOC

That's messy logic for a page component, and if we plan on doing redirects in more than one place then it'd be best to abstract that into an HOC component.

import { useRouter } from 'next/router';

function isBrowser() {
  return typeof window !== 'undefined';
}

/**
 * Support conditional redirecting, both server-side and client-side.
 *
 * Client-side, we can use next/router. But that doesn't exist on the server.
 * So on the server we must do an HTTP redirect. This component handles
 * the logic to detect whether on the server and client and redirect
 * appropriately.
 *
 * @param WrappedComponent The component that this functionality
 * will be added to.
 * @param clientCondition A function that returns a boolean representing
 * whether to perform the redirect. It will always be called, even on
 * the server. This is necessary so that it can have hooks in it (since
 * can't be inside conditionals and must always be called).
 * @param serverCondition A function that returns a boolean representing
 * whether to perform the redirect. It is only called on the server. It
 * accepts a Next page context as a parameter so that the request can
 * be examined and the response can be changed.
 * @param location The location to redirect to.
 */
export default function withConditionalRedirect({
  WrappedComponent,
  clientCondition,
  serverCondition,
  location
}) {
  const WithConditionalRedirectWrapper = props => {
    const router = useRouter();
    const redirectCondition = clientCondition();
    if (isBrowser() && redirectCondition) {
      router.push(location);
      return <></>;
    }
    return <WrappedComponent {...props} />;
  };

  WithConditionalRedirectWrapper.getInitialProps = async (ctx) => {
    if (!isBrowser() && ctx.res) {
      if (serverCondition(ctx)) {
        ctx.res.writeHead(302, { Location: location });
        ctx.res.end();
      }
    }

    const componentProps =
      WrappedComponent.getInitialProps &&
      (await WrappedComponent.getInitialProps(ctx));

    return { ...componentProps };
  };

  return WithConditionalRedirectWrapper;
}

We added some logic to add a condition on the redirect, and now it's getting a little ugly, but that HOC lets us make other conditional redirecting HOCs that are much more simple. Let's say we want to create a withAuth() HOC that redirects the user to the login page if they aren't already logged in.

// This is a hook that returns a simple boolean: true if the user is
// signed in, false otherwise.
import { useIsAuthenticated } from 'src/providers/Auth';
import withConditionalRedirect from '../withConditionalRedirect';

/**
 * Require the user to be authenticated in order to render the component.
 * If the user isn't authenticated, forward to the signin page.
 */
export default function withAuth(WrappedComponent) {
  return withConditionalRedirect({
    WrappedComponent,
    location: '/signin',
    clientCondition: function withAuthClientCondition() {
      return !useIsAuthenticated();
    },
    serverCondition: function withAuthServerCondition(ctx) {
      // This isn't a good way to check for cookie values.
      // See the blog post linked below for something better.
      // We kept it simple here.
      return !ctx.req.headers.cookie.includes('session');
    }
  });
}

For more details on handling authentication in SSR with Next.js, read Detecting Authentication Client-Side in Next.js with an HttpOnly Cookie When Using SSR.

Why do we keep clientCondition and serverCondition separate? They are run in very different contexts: clientCondition is run during the component rendering and can use hooks while serverCondition is run in getInitialProps(), has access to ctx (and thereby req and res), and can't use hooks because it's not part of the component render.

You might wonder why we don't just return ctx from getInitialProps(). I tried it. It doesn't work because req and res are circular structures and can't be serialized into JSON to send down to the client for hydrating. See Circular structure in "getInitialProps" result.

Detecting Authentication Client-Side in Next.js with an HttpOnly Cookie When Using SSR

Justin — Mon, 27 Apr 2020 20:12:01 +0000

The architecture explained here only supports SSR. If you need to support Static Optimization then read my follow up post.

The best security practice is to store a session identifier or token in an HttpOnly cookie. HttpOnly cookies are not available to JavaScript, they are only sent to the server. This prevents 3rd party scripts from hijacking the session. However, this also prevents your own JavaScript from accessing the token. That's generally okay for apps that server-render all pages, but how do we deal with this in Next.js with pages that are rendered in the client?

First, let's acknowledge that the client doesn't validate sessions, only the server does. Clients typically just look to see if a session cookie is set and assume it's valid. In other words, clients treat the cookie as a boolean to answer the question: is the user logged in?

Why does the client need to know whether the user is logged in? It's an optimization. Let's imagine how a client-rendered app would behave where the client didn't know whether the user was authenticated. When first visiting the site, you'd see the home page with a login button in the header. If the user logs in, the login code could know to send the user to a logged-in home page. What if the user hit the back button? The app would render the login page again. This isn't ideal. Why allow the user to login again? We're wasting the user's time.

A few days later, this same user clicks a bookmark to load their logged-in home page. The page renders the full shell and a loading spinner to fetch data we need to populate the latest activity. Oops! The server responds with a 401. The user isn't authenticated. Now the user is sent to the login page. We just wasted a few seconds of their time, a little of their bandwidth, and some of our server resources (one hit doesn't make much of a difference but this adds up quickly over time).

These simple examples reveal that allowing the client to know whether the user is authenticated is just an optimization that aids primarily in routing and rendering. We want to avoid rendering pages and fetching data that the user can't see. We also want to prevent authenticated users from participating in registration, login, and reset-password flows.

One way to achieve this in Next.js is with page-level HOCs. It would be nice to have two HOCs: withAuth() that only renders the page if the user is authenticated and withoutAuth() that only renders the page if the user is not authenticated. It'd be nice to specify where the user should be sent if the required auth condition isn't met, so the first parameter will be the page component and the second parameter will be a URL.

The auth HOCs need access to the authenticated state. This could be done through a hook: useIsAuthenticated(). That hook will need to pull the value from some global state store. That will be accomplished through the Context API.

import React from 'react';

const AuthContext = React.createContext({
  isAuthenticated: false,
  setAuthenticated: () => {}
});

/**
 * The initial value of `isAuthenticated` comes from the `authenticated`
 * prop which gets set by _app. We store that value in state and ignore
 * the prop from then on. The value can be changed by calling the
 * `setAuthenticated()` method in the context.
 */
export const AuthProvider = ({
  children,
  authenticated
}) => {
  const [isAuthenticated, setAuthenticated] = React.useState(authenticated);
  return (
    <AuthContext.Provider
      value={{
        isAuthenticated,
        setAuthenticated
      }}
    >
      {children}
    </AuthContext.Provider>
  );
};

export function useAuth() {
  const context = React.useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}

export function useIsAuthenticated() {
  const context = useAuth();
  return context.isAuthenticated;
}

The AuthProvider accepts an authenticated prop which represents the initial authenticated value. The initial value will be calculated and passed in to the AuthProvider in a custom App.

Note that we also included two hooks which make it easy for the rest of our application to be informed about the current authenticated state: useAuth() and useIsAuthenticated(). But before they can be used, we must add AuthProvider to our application.

import React from 'react';
import App from 'next/app';
import { AuthProvider } from '../providers/Auth';
// Be sure to install this package for parsing cookies
import cookie from 'cookie';

class MyApp extends App {
  render() {
    const { Component, pageProps, authenticated } = this.props;
    return (
      <AuthProvider authenticated={authenticated}>
        <Component {...pageProps} />
      </AuthProvider>
    );
  }
}

MyApp.getInitialProps = async (appContext) => {
  let authenticated = false;
  const request = appContext.ctx.req;
  if (request) {
    request.cookies = cookie.parse(request.headers.cookie || '');
    authenticated = !!request.cookies.session;
  }

  // Call the page's `getInitialProps` and fill `appProps.pageProps`
  const appProps = await App.getInitialProps(appContext);

  return { ...appProps, authenticated };
};

export default MyApp;

Now that the auth state is being initialized, stored in context, and retrieved through the auth hooks, we are ready to create the withAuth() and withoutAuth() HOCs. Their API and general logic is almost all the same. The only difference is one checks for true and one checks for false. So first we'll build an HOC that they'll share. Let's call it withConditionalRedirect().

import { useRouter } from 'next/router';

function isBrowser() {
  return typeof window !== 'undefined';
}

/**
 * Support conditional redirecting, both server-side and client-side.
 *
 * Client-side, we can use next/router. But that doesn't exist on the server.
 * So on the server we must do an HTTP redirect. This component handles
 * the logic to detect whether on the server and client and redirect
 * appropriately.
 *
 * @param WrappedComponent The component that this functionality
 * will be added to.
 * @param clientCondition A function that returns a boolean representing
 * whether to perform the redirect. It will always be called, even on
 * the server. This is necessary so that it can have hooks in it (since
 * can't be inside conditionals and must always be called).
 * @param serverCondition A function that returns a boolean representing
 * whether to perform the redirect. It is only called on the server. It
 * accepts a Next page context as a parameter so that the request can
 * be examined and the response can be changed.
 * @param location The location to redirect to.
 */
export default function withConditionalRedirect({
  WrappedComponent,
  clientCondition,
  serverCondition,
  location
}) {
  const WithConditionalRedirectWrapper = props => {
    const router = useRouter();
    const redirectCondition = clientCondition();
    if (isBrowser() && redirectCondition) {
      router.push(location);
      return <></>;
    }
    return <WrappedComponent {...props} />;
  };

  WithConditionalRedirectWrapper.getInitialProps = async (ctx) => {
    if (!isBrowser() && ctx.res) {
      if (serverCondition(ctx)) {
        ctx.res.writeHead(302, { Location: location });
        ctx.res.end();
      }
    }

    const componentProps =
      WrappedComponent.getInitialProps &&
      (await WrappedComponent.getInitialProps(ctx));

    return { ...componentProps };
  };

  return WithConditionalRedirectWrapper;
}

Wow, that was unexpectedly complicated. We have to account for redirects both on the client and on the server (which unfortunately are performed very differently). Good thing we put this all in one place instead of duplicating the code in two HOCs.

For more details on redirects in Next.js, read Client-Side and Server-Side Redirects in Next.js.

Now let's see what our final auth HOCs will look like.

import { useIsAuthenticated } from '../providers/Auth';
import withConditionalRedirect from './withConditionalRedirect';

/**
 * Require the user to be authenticated in order to render the component.
 * If the user isn't authenticated, forward to the given URL.
 */
export default function withAuth(WrappedComponent, location='/signin') {
  return withConditionalRedirect({
    WrappedComponent,
    location,
    clientCondition: function withAuthClientCondition() {
      return !useIsAuthenticated();
    },
    serverCondition: function withAuthServerCondition(ctx) {
      return !ctx.req?.cookies.session;
    }
  });
}

import { useIsAuthenticated } from '../providers/Auth';
import withConditionalRedirect from './withConditionalRedirect';

/**
 * Require the user to be unauthenticated in order to render the component.
 * If the user is authenticated, forward to the given URL.
 */
export default function withoutAuth(WrappedComponent, location='/home') {
  return withConditionalRedirect({
    WrappedComponent,
    location,
    clientCondition: function withoutAuthClientCondition() {
      return useIsAuthenticated();
    },
    serverCondition: function withoutAuthServerCondition(ctx) {
      return !!ctx.req?.cookies.session;
    }
  });
}

You can see this architecture implemented in an example app. It's also available in TypeScript.

The architecture explained here only supports SSR. If you need to support Static Optimization then read my follow up post.

Using next-i18next in Storybook

Justin — Wed, 01 Apr 2020 14:46:00 +0000

next-i18next is built to work server-side as well as client-side. Storybook doesn't support server-side rendering so there's nowhere to add the next-i18next middleware. The good news is that means we don't have to support server-side rendering and can just use the underlying react-i18next and i18next-instance.

Adding a Storybook Decorator

We're going to add a decorator which will allow us wrap all stories in the <I18nextProvider>.

The decorator will be added to .storybook/preview.js so you need to create one if you haven't already.

import { I18nextProvider } from 'react-i18next';
import i18n from './i18n';

addDecorator(storyFn => (
  <I18nextProvider i18n={i18n}>{storyFn()}</I18nextProvider>
));

Configuring i18next

We can't use the same i18n config that we use in next-i18next. We need to use a react-i18next instance. I recommend creating the file at .storybook/i18n.js since it's just for Storybook config. The setup can be as simple as this:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

i18n.use(initReactI18next).init({
  fallbackLng: 'en',
  debug: true
});

export default i18n;

Configuring Static Paths in Storybook

The last step is to tell Storybook that it should serve the locales dir as a static path. We achieve this with the -s CLI flag.

{
  "scripts": {
    "start-storybook": "start-storybook -s ./public"
  }
}

Using React.forwardRef() and an HOC on the same component

Justin — Thu, 13 Feb 2020 19:07:20 +0000

Focus management in React currently has one solution: refs. If you want a function component to accept a ref, you should use React.forwardRef(). For a basic Input component, it would look like this:

import React from "react";

const Input = React.forwardRef(function Input({name, type, id, disabled, ...props}, ref) {
  return (
    <input
      {...props}
      name={name}
      id={id}
      disabled={disabled}
      type={type}
      ref={ref} />
  );
});

export default Input;

That's great. But what if we wanted to wrap it in an HOC? Maybe we have an HOC, shared between different form controls, for handling status messages. Let's call is withStatusMessages(). Normally, we would do something like this:

export default withStatusMessages(Input);

Everything will compile, but our ref stops working and we'll see an error in the console about function components not accepting refs.

What happened?

Remember, the component passed to React.forwardRef() needs to accept two parameters, with the second one being the ref. But our HOC doesn't know that, it just accepts and passes on props. We could update our HOC to pass on refs, but we might want it to be used with components that don't accept refs. So what can we do?

We've already decided that we can't apply the HOC after React.forwardRef() which means we have to apply the HOC before React.forwardRef(). We can't just have withStatusMessages(React.forwardRef()) because then our HOC will still drop the ref and not pass it on. What we need is a way to have the ref from React.forwardRef() passed on to the component via props (instead of as a second argument). Here's what I've come up with:

const Input = withStatusMessages(function Input({
  name,
  type,
  id,
  disabled,
  inputRef,
  ...props
}) {
  return (
    <input
      {...props}
      name={name}
      id={id}
      disabled={disabled}
      type={type}
      ref={inputRef}
    />
  );
});

export default React.forwardRef((props, ref) => {
  return <Input {...props} inputRef={ref} />;
});

We pass in the ref as the inputRef prop and then attach it to the input as normal. Now we get to use both React.forwardRef() and an HOC on the same component.

Note that we have to rename the prop, we can't just keep ref. In other words, we can't do this:

export default React.forwardRef((props, ref) => {
  return <Input {...props} ref={ref} />;
});

If you do, you'll get the error about function components not accepting refs because ref is handled specially by React (I don't know why, it sure would be nice if it just worked).

I created a working example of using this technique. And if you use TypeScript, the types are not straightforward so I've got you covered with the same example in TypeScript.

Do you know of a better way to handle this situation? I'd love to hear it.

DEV Community: Justin

4 Patterns for Responsive Props in React

Table of Contents

Responsive CSS

Responsive Props

Responsive Prop Patterns

Conditional Rendering

Conditional Rendering with a Hook

Conditional Rendering with a Component

Breakpoint Props

Object of Props

useBreakpointValues()

Component

HOC for Responsive Props

Array of Props

A Note About SSR

Summary

Responsive Prop Libraries

Conditional Rendering

Breakpoint Props

Object of Props

Array of props

Blue/Green Node.js Deploys with NGINX

Requirements

Implementation

Verifying Host Keys

Remotely Executing a Deploy Script on the VMs

Managing the Node.js Processes with PM2

Blue/Green Deploys

Parallel Deploys

Reusable Private GitHub Action

Scrubbing Secrets in GitHub Action Logs

Conclusion

Automatically Create a Release When The package.json Version Changes

My Workflow

Submission Category:

Yaml File or Link to Code

justincy / github-action-npm-release

Automatically generate a release when the package.json version changes

Automatic GitHub Release

Assumptions

Usage Example

Additional Resources / Info

Locale specific domains in Next.js with next-i18next

Using mapbox-gl in React

1. Add a className prop to the component.

2. Turn this into a custom hook

publicRuntimeConfig undefined when using Storybook with Next.js

Detecting a User's Authenticated State Client-Side in Next.js using an HttpOnly Cookie and Static Optimization

Client-Side and Server-Side Redirects in Next.js

Client-Side

Server-Side

Do Both in an HOC

Detecting Authentication Client-Side in Next.js with an HttpOnly Cookie When Using SSR

Using next-i18next in Storybook

Adding a Storybook Decorator

Configuring i18next

Configuring Static Paths in Storybook

Using React.forwardRef() and an HOC on the same component