• How can we track Santa?
• How can I create a map?
• What are we going to build?
• Step 0: Creating a new Next.js app from Next.js Leaflet Starter
• Step 1: Fetching Santa Data with SWR
• Step 2: Showing Santa's Stops on a Map with React Leaflet Markers
• Step 3: Adjusting Santa arrival and departure datetimes to current year
• Step 4: Updating Markers to custom icons
• Step 5: Showing where Santa's at and where he's been by comparing datetimes

How can we track Santa?

The people who brought you Google's Santa tracker in years past created an unofficial endpoint that gives you a list of destinations where Santa stops for presents.

While there's a chance they might all of a sudden kill it, it's been running strong since 2019. So there's a good chance it will stay up (I also backed up the data to a Gist 👀).

But with that data, we can add points on a map telling us the locations Santa will stop along with whether or not he's stopped there yet.

How can I create a map?

We'll use React Leaflet, which is a wrapper around the popular Leaflet mapping library.

The library allows us to build a map and add lots of different types of visuals like data, imagery, or it can even create custom maps of sci-fi worlds if you get advanced enough.

But we'll use this to build our map to track Santa on.

What are we going to build?

We're going to build a Santa Tracker application that gives us a map with all of the destinations. It will tell use if Santa has stopped there, if Santa's currently there, and if he's already left.

We'll do this in Next.js by using a Starter I created called Next.js Leaflet Starter. This will give us our basic map that we can use to get productive in React Leaflet.

Step 0: Creating a new Next.js app from Next.js Leaflet Starter

We’re going to start off with a new Next.js app using the Next.js Leaflet Starter. This will get us moving quickly with a basic map we can start to play with.

Inside of your terminal, run:

yarn create next-app -e https://github.com/colbyfayock/next-leaflet-starter my-santa-tracking-app
# or
npx create-next-app -e https://github.com/colbyfayock/next-leaflet-starter my-santa-tracking-app

Note: feel free to use a different value than my-santa-tracking-app as your project name!

Once installation has finished, you can navigate to that directory.

cd my-santa-tracking-app

Then you can start your local development server with:

yarn dev
# or
npm run dev

And once you visit it in your browser at http://localhost:3000, we should see our new application:

Next.js Leaflet Starter

If we take a second to browse around the project, we're primarily interested in the homepage managed inside src/pages/index.js for this tutorial. There, along with some basic UI, we have a map.

The map is built by wrapping the React Leaflet Map with a Next.js Dynamic Import. The tricky thing with Leaflet and React Leaflet is that it requires the browser's window object to work. So we use the Dynamic Import to only load it once it hits the client.

But in the homepage, we can see how we're currently utilizing our map, along with some introductory components, which will allow us to get started building our tracker app!

Step 1: Fetching Santa Data with SWR

In order to get our Santa data, we need to fetch it from our API.

While we could technically just use fetch and store it in state, let's use SWR which gives us a little bit cleaner of a way to manage that request.

In your terminal, first install SWR with:

yarn add swr
# or
npm install swr

Next, let's import it into our project.

At the top of src/pages/index.js add:

import useSWR from 'swr';

And to use our newly imported SWR hook, we have two parts, where first let's define our "fetch" function, which is essentially the abstracted request logic.

Above the Home page component add:

const fetcher = (url) => fetch(url).then((res) => res.json());

And then we can set up the request itself inside, at the top of our Home page component:

const { data } = useSWR(
  'https://firebasestorage.googleapis.com/v0/b/santa-tracker-firebase.appspot.com/o/route%2Fsanta_en.json?alt=media&2018b',
  fetcher
);

To quickly review what's happening, we're using the useSWR hook which will give us some data fetching features (caching, revalidation). But we need to tell SWR 2 things: how to fetch the data (fetcher) and where (our endpoint).

And with that, we should have our data, which we can now test by adding a console log. There, when we load our page and look in the console, we should see a bunch of destinations logged out:

Santa destinations

Follow along with the commit!

Step 2: Showing Santa's Stops on a Map with React Leaflet Markers

We have Santa's future stops! Now let's throw them on the map.

If we scroll down to our Map component, we should see that we're nesting two components:

• Tilelayer: this is the background, the actual map imagery
• Marker: the pin that's dropped on the map (and a Popup inside)

These are abstracted as React components, so like any other React component, we can map through our data adding a new Marker for every stop.

Let's replace the Marker component with:

{data?.destinations?.map(({ id, location, city, region }) => {
  return (
    <Marker key={id} position={[location.lat, location.lng]}>
      <Popup>{ city }, { region }</Popup>
    </Marker>
  )
})}

If we reload the page, we'll see...the same thing.

Still showing Washington, DC

But this is deceiving. Zoom out on the map and we'll see all of our pins:

Zoomed out showing pins

We can even click each of those pins, which we'll see the location of since we added it in a Popup.

World Cup 2022 winner with location popup!

Everything is working well so far, but we don't want people to have to zoom out every time, so let's fix that.

On the Map component, we can see a center prop and a zoom prop:

• Center: the default location to center the map on
• Zoom: the zoom left the map starts with

Let's make those more appropriate for our project:

<Map ... center={[0, 0]} zoom={1}>

This will set it in the center of the world with a zoom level of 1, which lets us see the entire world.

Map showing pins all over world

Now as one final thing, instead of only showing what the location name is, let's add when Santa will arrive.

Update the map statement for destinations with:

{data?.destinations?.map(({ id, arrival, departure, location, city, region }) => {
  const arrivalDate = new Date(arrival);
  const arrivalHours = arrivalDate.getHours()
  const arrivalMinutes = arrivalDate.getMinutes()
  const arrivalTime = `${arrivalHours}:${arrivalMinutes}`;

  const departureDate = new Date(departure);
  const departureHours = departureDate.getHours()
  const departureMinutes = departureDate.getMinutes()
  const departureTime = `${departureHours}:${departureMinutes}`;

  return (
    <Marker key={id} position={[location.lat, location.lng]}>
      <Popup>
        <strong>Location:</strong> { city }, { region }
        <br />
        <strong>Arrival:</strong> { arrivalDate.toDateString() } @ { arrivalTime }
        <br />
        <strong>Departure:</strong> { arrivalDate.toDateString() } @ { departureTime }
      </Popup>
    </Marker>
  )
})}

Here we're:

• Using the arrival and departure times to create new dates
• Getting specific values for both date and time
• Formatting the time
• Adding arrival and departure datetimes to Popup

And when we reload the page and click on a pin, we should see all of our information!

Ukraine's Santa destination

Follow along with the commit!

Step 3: Adjusting Santa arrival and departure datetimes to current year

Plot twist! The API we're using to load Santa's destinations is currently showing 2019 😱.

Santa's in the past!

Turns out that after 2019, Google stopped updating this API. But that's okay, the timings and locations remain the same, we just need to correct it to the current year, which we can do dynamically to also future proof this.

At the top of the Home page component and under the SWR request, let's first get the current date and time:

const currentDate = new Date(Date.now());
const currentYear = currentDate.getFullYear();

Next, we can create a new "corrected" set of destinations:

const destinations = data?.destinations.map((destination) => {
  const { arrival, departure } = destination;

  const arrivalDate = new Date(arrival);
  const departureDate = new Date(departure);

  arrivalDate.setFullYear(currentYear);
  departureDate.setFullYear(currentYear);

  return {
    ...destination,
    arrival: arrivalDate.getTime(),
    departure:  departureDate.getTime(),
  }
});

Here we're:

• Mapping through each destination, ultimately creating a new array of destinations
• Getting the arrival and departure dates into a new Date object
• Using our currentYear value to adjust our arrival and departure
• Returning all the destination data with the updated values

Finally as one last step, we need to update the code that's creating our Markers from data?.destinations?.map to:

{destinations?.map(({ id, arrival, departure, location, city, region }) => {

And if we open up our app.

Popups with correct date!

We should now see that all of our popups have the right date.

Follow along with the commit!

Step 4: Updating Markers to custom icons

Right now we're using the default graphics that come with React Leaflet for our Markers, but we can do better.

We can provide our own custom images that will replace the marker, including something fun like Christmas trees!

To help out, I created an image for this already, which you can grab here:

2x: https://github.com/colbyfayock/my-santa-tracking-app/blob/main/public/images/tree-marker-icon-2x.png

1x: https://github.com/colbyfayock/my-santa-tracking-app/blob/main/public/images/tree-marker-icon.png

Note: you can use whatever images you want, you'll just need to be sure to adjust the sizes and use the right filenames.

First, place your images inside of the public/images directory to make them available for us to use.

Then we're going to tell our Marker we want to use our custom icon.

To start, we need to make the Leaflet library available to use in our Map component:

<Map className={styles.homeMap} width="800" height="400" center={[0, 0]} zoom={1}>
  {({ TileLayer, Marker, Popup }, Leaflet) => (

Here we're adding the Leaflet variable as a second argument to our function prop.

Then we need to use it to create our icon using a Leaflet Icon instance.

Inside of our destinations map, update the Marker opening tag to:

<Marker
  key={id}
  position={[location.lat, location.lng]}
  icon={Leaflet.icon({
    iconUrl: '/images/tree-marker-icon.png',
    iconRetinaUrl: '/images/tree-marker-icon-2x.png',
    iconSize: [41, 41]
  })}
>

Here we're adding a new prop of icon to our Marker where we're creating a new Leaflet Icon along with the path to our Icons.

We additionally specify the size as we're providing square images as opposed to the rectangular images that are there by default.

And just like that, we now have Christmas tree markers!

Christmas tree marker icons!

But we can take this a step further and show where Santa is with a custom icon as well as where he's already been with another custom icon, which we'll do in the next step.

Follow along with the commit!

Step 5: Showing where Santa's at and where he's been by comparing datetimes

Previously, we set up our custom icons for all of Santa's stops.

We can take that further and use Santa's arrival and departure times to determine if he's currently at a location and if he was at a location, then show different icons.

This will include a couple of steps:

• Determining if Santa "is here" and "was here"
• Adding and showing different icons
• Faking the current time to test that it works

Starting off, let's figure out where Santa currently is.

For every destination, we have our arrival time and departure time, which we're already using in the Popup. We can compare those values to the current time to determine where he is.

Inside of the destinations map and right before the return statement (under the time variables) add:

const santaWasHere = currentDate.getTime() - departureDate.getTime() > 0;
const santaIsHere = currentDate.getTime() - arrivalDate.getTime() > 0 && !santaWasHere;

Here we're determining:

• If Santa was here – essentially if the current time is later than the departure time
• If Santa is here – essentially if the current time is later than the arrival time AND Santa hasn't left (the above is false)

Next, we need to dynamically set our icon URLs to use new icons in different time instances.

To do that, we need new images. Luckily, I'm providing them for you again!

Gift 2x: https://github.com/colbyfayock/my-santa-tracking-app/blob/main/public/images/gift-marker-icon-2x.png

Gift 1x: https://github.com/colbyfayock/my-santa-tracking-app/blob/main/public/images/gift-marker-icon.png

Santa 2x: https://github.com/colbyfayock/my-santa-tracking-app/blob/main/public/images/santa-marker-icon-2x.png

Santa 1x: https://github.com/colbyfayock/my-santa-tracking-app/blob/main/public/images/santa-marker-icon.png

Like before, we want to drop all four images into the public/images directory.

Note: again, you can use different images if you'd like, but be sure to pay attention to the size and filenames.

With our images, we can set up our dynamic image URL.

First, let's create a variable to store this information:

let iconUrl = '/images/tree-marker-icon.png';
let iconRetinaUrl = '/images/tree-marker-icon-2x.png';

And update our Marker icon prop to use these variables:

<Marker
  key={id}
  position={[location.lat, location.lng]}
  icon={Leaflet.icon({
    iconUrl,
    iconRetinaUrl,
    iconSize: [41, 41]
  })}
>

Putting it all together, we can check our time comparisons and set the URL based on that:

if ( santaIsHere ) {
  iconUrl = '/images/santa-marker-icon.png';
  iconRetinaUrl = '/images/santa-marker-icon-2x.png';
}

if ( santaWasHere ) {
  iconUrl = '/images/gift-marker-icon.png';
  iconRetinaUrl = '/images/gift-marker-icon-2x.png';
}

If we open the map, we'll notice we have an issue. It's not Christmas yet, so how do we know if this is going to work?

We can fake the time to check!

At the top of the Home component, let's comment out our currentDate and set it to a static value:

// const currentDate = new Date(Date.now());
const currentDate = new Date('2022-12-25T02:34:30.115Z');

If we look at our map:

So many gifts!

We should now see that because we set the time to Dec 25 at 2:34:30 UTC, which is Dec 24th around 9:34pm EST, we should see that Santa has started to give gifts in most of the world, but not quite yet on the east coast of the United States.

Now a tiny little issue, did you find Santa yet?

Santa!

There he is! Peeking around a tree from Buenos Aires.

This isn't ideal, as Santa is arguably the most important icon, right?

So we can fix this with a little CSS.

Similar to our icon URL, we're going to create a new variable to add a class dynamically to our icon.

First, the className variable:

let className = '';

if ( santaIsHere ) {
  className = `${className} ${styles.iconSantaIsHere}`;
}

And then we apply that to our icon prop:

<Marker
  key={id}
  position={[location.lat, location.lng]}
  icon={Leaflet.icon({
    iconUrl,
    iconRetinaUrl,
    iconSize: [41, 41],
    className
  })}
>

Then we can open up src/styles/Home.scss and add the following at the bottom:

.iconSantaIsHere {
  z-index: 9999!important;
}

And once we reload the page, we should now see Santa at the top of all of the icons:

Santa clear on the map

Before moving on...

Important: be sure to update your currentDate variable to:

const currentDate = new Date(Date.now());

We don't want to be disappointed when the tracker isn't... tracking.

Follow along with the commit!

What else can we do?

Hope you had fun and that this put you in the holiday spirit! Looking to take it to another level? Here are a few more things you can do.

Refresh the time to update Santa's location

When you first load the page, we get a currentDate value, but that won't update throughout the night.

If you want to keep this app up and actively see where Santa is traveling to, try moving the time to React state and set an interval that automatically updates it every so often, such as every 30 seconds.

Show Santa's location if he's not at a stop

The static time I used to test where Santa was at was 2:34:30, which wasn't a coincidence. If I had set it to 2:34:00, he wouldn't have been at a location, rather, he would have been traveling to one.

Using this information, we can determine where Santa is by:

• Finding the last destination Santa departed
• Finding the next destination where Santa will arrive
• Finding the middle of the two geographical locations (latitude and longitude)
• Adding a Marker to that location

One way is by using JS library Turf, which along with a lot of other tools, allows you to find the midpoint between two locations:

https://turfjs.org/docs/#midpoint

Customize and style the map

It's Christmas! We don't want a boring map and application.

We can use tools like Mapbox to change the map imagery and CSS to theme our app.

This tutorial is for using Mapbox with Gatsby but the concepts should generally be the same: https://www.youtube.com/watch?v=KcPJr1b_rv0.

Add Santa's path so you know where he's going next

We see a bunch of locations, but we don't know where Santa is going when.

React Leaflet allows us to add other "shapes" to the map, such as a Polyline, where we can pass in an array of points.

The only issue is after you try that, because our line crosses over the Antimeridian, we get big zig-zags on our map.

This one will be a challenge, but try using the library Leaflet Antimeridian to fix this issue:

https://github.com/briannaAndCo/Leaflet.Antimeridian

Tip: I implemented this in Gatsby a few years ago. Maybe try checking out what I did there, again, the concepts should be the same.

Share your tracker with me!

Send a Tweet with a link to your deployed Santa Tracker and tag me @colbyfayock.

• What are CSS Modules?
• What is Sass?
• What are we going to build?
• Step 0: Creating a new Next.js app
• Step 1: Installing Sass in a Next.js app
• Step 2: Importing Sass files into a Next.js app
• Step 3: Using Sass variables in a Next.js app
• Step 4: Using Sass mixins with global imports in Next.js

What are CSS Modules?

CSS Modules are essentially CSS files that, when imported into JavaScript projects, provide styles that are scoped to that particular part of the project by default.

When importing your module, the classes are represented by an object mapped with each class name, allowing you to apply that class right to your project.

For instance, if I had a CSS module for the title of my page:

.title {
  color: blueviolet;
}

And I import that into my React project:

import styles from './my-styles.css'

I can then apply that title right to an element as if it were a string:

<h1 className={styles.title}>My Title</h1>

By scoping styles, you no longer have to worry about breaking other parts of the application with cascading styles. It’s also easier to manage smaller chunks of code that pertain to a specific piece of the application.

What is Sass?

Sass is an extension of the CSS language that provides powerful features like variables, functions, and other operations that allow you to more easily build complex features into your project.

As an example, if I wanted to store my color above in a variable so I can easily change it later, I can add:

$color-primary: blueviolet;

.title {
  color: $color-primary;
}

If I wanted to change that color but only in one spot, I can use built-in color functions to change the shade:

$color-primary: blueviolet;

.title {
  color: $color-primary;
  border-bottom: solid 2px darken($color-primary, 10);
}

One additional benefit is the ability to nest styles. This allows for easier, more logical organization of your CSS.

For instance, if I wanted to change only a <strong> element nested in a title, I can add:

$color-primary: blueviolet;
$color-secondary: cyan;

.title {

  color: $color-primary;
  border-bottom: solid 2px darken($color-primary, 10);

  strong {
    color: $color-secondary;
  }

}

What are we going to build?

We're going to create a new React app using Next.js.

With our new app, we'll learn how to install and configure Sass so that we can take advantage its features inside of Next.js.

Once set up Sass, we'll walk through how to use Sass variables and mixins to recreate some of the default elements of the Next.js UI.

Want to skip the tutorial and dive into the code? Check out Next.js Sass Starter on GitHub: https://github.com/colbyfayock/next-sass-starter

Step 0: Creating a new Next.js app

To get started with a new Next.js app, we can use Create Next App.

In your terminal, navigate to where you want to create the new project and run:

yarn create next-app my-next-sass-app

Note: you can use npm instead of yarn for any examples with installation and package management.

Once the installation finishes, you can navigate into the directory, and start your development server:

yarn dev

Which should start your new Next.js project at http://localhost:3000!

New Next.js app

If this is your first time creating a new Next.js app, have a look around! It comes with a basic homepage as well as two CSS files:

• /styles/globals.css
• /styles/Home.module.css

Here we’ll be focusing on the home file. If you look inside pages/index.js, there, you’ll see that we’re importing the home file, making those styles available.

Next.js has CSS Modules built in by default. This means that when we import our home styles file, the CSS classes are added to the styles object, and we apply each of those class names to the React elements from that object, such as:

<h1 className={styles.title}>

That means that our styles are scoped to that single page.

To learn more about CSS Modules or the built-in support in Next.js, you can check out the following resources:

• https://github.com/css-modules/css-modules
• https://nextjs.org/docs/basic-features/built-in-css-support

Step 1: Installing Sass in a Next.js app

While Next.js comes with some good built-in CSS support, it doesn’t come with Sass completely built in.

Luckily, to get Sass up and running inside of our Next.js app, all we need to do is install the Sass package from npm, which will let Next.js include those files in its pipeline.

To install Sass, run the following inside of your project:

yarn add sass

And if we start back up our development server and reload the page, we’ll actually notice that nothing has happened yet, which is a good thing!

But next we’ll learn how to take advantage of our CSS superpowers.

Follow along with the commit!

Step 2: Importing Sass files into a Next.js app

Now that Sass is installed, we’re ready to use it.

In order you use any Sass-specific features though, we’ll need to use Sass files with either the .sass or .scss extension. For this walkthrough, we’re going to use the SCSS syntax and the .scss extension.

To get started, inside of pages/index.js, change the import of the styles object at the top of the page to:

import styles from '../styles/Home.module.scss'

And once the page reloads, as we probably expect, the page is actually broken.

Next.js failed to compile

To fix this, rename the file:

/styles/Home.module.css

to

/styles/Home.module.scss

The difference is we’re changing the file extension from .css to .scss.

Once the page reloads, we’ll see that our Next.js site is loading and is back ready for action!

New.js app loading

_Note: We’re not going to cover the global styles file here – you can do the same thing by renaming the global styles file and updating the import inside of /pages/_app.js_

Next, we’ll learn how to use Sass features for our Next.js app.

Follow along with the commit!

Step 3: Using Sass variables in a Next.js app

Now that we’re using Sass in our project, we can start using some of the basic features like variables.

To show how this works, we’re going to update the blue inside of our app to my favorite color, purple!

At the top of /styles/Home.module.css, add the following:

$color-primary: #0070f3;

The color #0070f3 is what Next.js uses by default in the app.

Next, update each location that uses that color in our home CSS file to our new variables, such as changing:

.title a {
  color: #0070f3;

to

.title a {
  color: $color-primary;

If we refresh the page, nothing should change.

Unchanged Next.js app

But now because we’re using a variable to define that color, we can easily change it.

At the top of the page, change the $color-primary variable to purple or whatever your favorite color is:

$color-primary: blueviolet;

And when the page reloads, we can see that our colors are now purple!

Next.js app with purple color

Variables are just the start to the superpowers Sass gives our CSS, but we can see that they allow us to easily manage our colors or other values throughout our application.

Follow along with the commit!

Step 4: Using Sass mixins with global imports in Next.js

One of the other many features of Sass is mixins. They give us the ability to create function-like definitions, allowing us to configure rules that we can repeat and use throughout our app.

In our example, we’re going to create a new mixin that allows us to create responsive styles using a media query throughout our app. While we can already do that with a media query alone, using a mixin allows us to use a single definition, keeping that consistent and allowing us to manage that responsive definition from one place.

Because this mixin is something we want to use throughout our entire application, we can also use another feature of Sass, which is the ability to import files.

To get started, create a new file under the /styles directory:

/styles/_mixins.scss

We’re using an underscore in front of our filename to denote that it’s a partial.

Next, inside of our /styles/Home.module.scss file, let’s import that new file:

@import "mixins";

Once the page reloads, we’ll notice nothing changed.

If we lookout the bottom of Home.module.scss, we’ll see that we’re using a media query to make the .grid class responsive. We’re going to use that as a basis for our mixin.

Inside of _mixins.scss, add the following:

@mixin desktop() {
  @media (max-width: 600px) {
    @content;
  }
}

Note: while we probably can come up with a better name for this mixin than desktop, we’ll use that as the basis of our example.

The @content means that any time we use our desktop mixin, it will include the nested content in that location.

To test this out, back in our Home.module.css file, let’s update our .grid snippet:

@include desktop() {
  .grid {
    width: 100%;
    flex-direction: column;
  }
}

If we open our app back up and shrink the browser window, we can see that we still have our responsive styles!

Responsive styles in Next.js

We can even take this a step further. Sass allows you to nest styles. For instance, instead of writing:

.footer {
  // Styles
}

.footer img {
  margin-left: 0.5rem;
}

We can include that img definition right inside of the original .footer definition:

.footer {

  // Styles

  img {
    margin-left: 0.5rem;
  }

}

That img definition will compile to .footer img, just the same as if it was written in standard CSS.

So with that in mind, we can use the same concept and move our desktop mixin into our original .grid class:

.grid {

  @include desktop() {
    width: 100%;
    flex-direction: column;
  }

}

And if you notice, because we’re inside of the .grid class already, we can remove that from inside of the mixin, as it will already be applied.

This allows for much easier organization of our responsive styles.

Finally, if we look back at our app, we’ll notice that still, nothing has changed, which means we’re successfully using our Sass mixin.

No change in our Next.js app

Follow along with the commit!

What else can we do with Sass and Next.js?

We’re only scratching the surface here with Sass. Because our CSS modules now have the power of Sass, we have a ton of capabilities that don’t come by default with CSS.

Color Functions

Sass has a ton of functions built in that allow us to manipulate colors, mixing and matching shades much more easily.

Two that I use often are darken and lighten, that allow you to take a color and change the shade.

Learn more about all of the available color functions in Sass.

Custom Functions

While mixins seem like functions, we can define true functions in Sass that allow us to perform complex operations and produce values based on an input.

Learn more about custom functions in Sass.

Other Value Types

While most of the time with CSS we’re using strings or numbers, we saw that a simple extension of that is the ability to use variables.

In addition to variables, Sass gives us more value types like Maps, which function sort of like an object, and Lists, which are kind of like arrays.

Learn more about the value types in Sass.

More

There are a ton of features available in Sass and lots of articles that cover the most used features. Take some time to explore the documentation and find what’s out there!

• What is VS Code?
• VS Code Extensions
• Sublime Text Keymap and Settings Importer
• Import Cost
• indent-rainbow
• Rainbow Brackets
• Settings Sync
• Profile Switcher
• Better Comments
• Duplicate Action

What is VS Code?

A quick note in case you’re not familiar. VS Code, which is short for Visual Studio Code, is a popular text or code editor that’s maintained by the Microsoft team.

It’s grown a tremendous share of the developer market over the last year or two making it the go-to editor for web developers.

Coupled with the fact that Microsoft is investing a lot of time into it and independent developers are building a ton of extensions, you can’t go wrong with giving it a shot.

VS Code Extensions

Part of what makes VS Code great is it’s extensibility. It allows developers to creatively take the editor to another level by implementing features Microsoft may not want to support or even building a whole note-taking experience on top of it with Foam.

While there are thousands of extensions available in the VS Code Marketplace, these are the 7 that are critical to my workflow as an active developer.

Sublime Text Keymap and Settings Importer

Before moving to VS Code, I was a Sublime Text 3 user. It’s still a great text editor, but when moving to VS Code, a lot of the shortcuts and key mappings weren’t the same.

Sublime Text Keymap and Settings Importer let me first import my settings from Sublime text, but it also set up the default key mappings. This made shortcuts that were available in Sublime immediately available in VS Code.

Sublime Text key mappings in VS Code

This includes two of my favorites like multi-select (selecting something then pressing CMD+D / Ctrl+D) and duplicating a line (adding a cursor on a line and pressing CMD+Shift+D / Ctrl+Shift+D).

Sublime Text Keymap and Settings Importer (marketplace.visualstudio.com)

Import Cost

Modern day developers have to constantly deal with dependencies coming from various sources. As we pull in a bunch of different code to build our project, that additional code comes at a cost.

Showing import size in VS Code

Import Cost calculates an estimate of the size of an import allowing us to see how much additional weight we would be adding to our project size with that added dependency.

This helps us recognize the size of our dependencies, preventing accidental overload of huge libraries that could impact performance and hurt our customer’s user experience.

Import Cost (marketplace.visualstudio.com)

indent-rainbow

Style is an important factor in making our code readable. Part of that style is how we indent our code, so we understand nesting of different code blocks.

The issue is sometimes that nesting can grow pretty large and it can be difficult to try to find which opening tag belongs to which closing tag.

Rainbow-colored indent spacing in VS Code

indent-rainbow adds colors to the indent spaces, allowing us to easily line up and see which tags belong to each other.

indent-rainbow (marketplace.visualstudio.com)

Rainbow Brackets

Similar to indenting, complex code, particularly when using math, can create easily confusing lines of code when you have multiple uses of parenthesis within the same statement.

For instance, if we want to apply some simple math:

const value = (((1+1)*2)+1)*2;

And while that’s a simple example, that can easily get out of hand and hard to track.

Rainbow-colored brackets in VS Code

Rainbow Brackets highlights the parenthesis in different colors allowing us to get a better idea which opening bracket belongs to which closing bracket of our equation.

Rainbow Brackets (marketplace.visualstudio.com)

Settings Sync

If you typically work between two laptops or two different environments, you might have to manually maintain keeping your text editor the same, if you’re particular about your setup (like I am).

Configuration for Settings Sync in VS Code

Settings Sync allows you to save your VS Code settings in a GitHub Gist. This lets you sync those settings across different VS Code installations

Settings Sync (marketplace.visualstudio.com)

Note: if you want to learn more, I wrote a tutorial that walks you through setting this up step-by-step!

Profile Switcher

As a content creator, I need to make sure that when I’m showing my screen to others, that I’m using accessible colors and font sizes that allow people to easily see what I'm demo'ing.

The issue is those settings aren’t what I like to use day-to-day when I’m heads down coding.

Switching profiles in VS Code

Profile Switcher allows you to set up multiple VS Code profiles each with their own configuration allowing you to easily switch between different setups.

Profile Switcher (marketplace.visualstudio.com)

Better Comments

While they might not seem important when you’re writing code, comments are critical to helping others understand that code. They also typically help you understand it when you look at it a year down the road.

Those comments are helpful, but they can be hard to read, as they’re typically all one gray color that doesn’t necessarily stand out.

Keyword highlighting of comment blocks in VS Code

That’s where Better Comments comes in, which adds a kind of syntax highlighting to the comments, adding color to keywords and statements that helps the readability of your code comments.

Better Comments (marketplace.visualstudio.com)

Duplicate Action

This last one seems like a small thing, but for some reason, VS Code doesn’t come with the ability to right click a file and duplicate it by default.

When I’m heads down in code, I’ll typically duplicate a file, like an existing template, which allows me to only change the content. This makes creating a new page more productive.

Duplicate file or directory option in VS Code

Duplicate Action simply adds the Duplicate File or Folder option to the context menu when you right click a file or folder.

Duplicate Action (marketplace.visualstudio.com)

What’s your favorite extension?

There are a ton of extensions out there that do amazing things – what’s your favorite? Let me know by sharing with me on Twitter!

There are a ton of testing tools available to us, but not all of them test what someone actually experiences. How can we use Applitools to visually test our project and make sure it’s actually working right?

• What is Visual Regression Testing?
• What is Cypress?
• What is Applitools?
• What are we going to build?
• Step 0: Creating a new React application with Next.js
• Step 1: Installing and configuring Cypress in a Next.js app
• Step 2: Creating your first Cypress test in a Next.js app
• Step 3: Installing and configuring Applitools Eyes
• Step 4: Visual regression testing with Applitools Eyes

You can also check out my live stream from my Twitch channel where I walked through the entire process of setting up a new app and testing it with Cypress and Applitools.

And full disclosure, I recently accepted a job as a Developer Advocate with Applitools. But you can do this tutorial using its free tier, with no credit card required.

What is Visual Regression Testing?

Similar to most tests, Visual Regression Testing is a type of test that will run periodically and at various stages of a project’s lifecycle like on pull request or production deployment to make sure everything in the app is functioning properly.

What Visual Regression Testing does differently, though, is it directly compares visual snapshots of your project. It detects any changes in content, layout, or any other detail you’d like either by statically visiting a page or interacting with it to preview the result of that interaction.

What is Cypress?

Cypress is a JavaScript-based testing framework that we’ll use to run our test suite. It runs tests in the browser, allowing us to directly check the state of our project where people will actually use it.

The great thing about Cypress is it also provides the ability to interact with the page. For instance, if we want to test that someone using our app is able to log in, we can enter credentials and submit the login form, then check that the authentication process properly worked.

What is Applitools?

Applitools is a visual testing tool and automation platform that lets us visually compare our app at different points in time, giving us the ability to check if something changed or isn’t functioning properly.

While Applitools has a few different features we can take advantage of, we’re going to focus on using the Eyes API, which we’ll use to capture our snapshot and send it up to the Applitools dashboard.

What are we going to build?

While we can really run Cypress and Applitools on a variety of project types, we’re going to use Next.js to quickly spin up a new React application. This will allow us to focus on the testing tools rather than the app itself.

Once we have our app set up, we’ll install Cypress and Applitools so we can use them to run our visual regression testing.

Note: you’ll need to have an Applitools account in order to set up visual regression testing. You can sign up for a free account at applitools.com.

Step 0: Creating a new React application with Next.js

To get started, we’re going to use Create Next App to create a new Next.js app.

Once you’re in the directory that you want to create your new project in, inside of your terminal run:

npx create-next-app my-testing-app

Note: you can change the project name from my-testing-app to whatever you would like.

This will clone the default Next.js example from GitHub, install the dependencies, and immediately allow us to get productive with our testing tools.

Once it’s finished, navigate into your new project:

cd my-testing-app

Start your development server:

npm run dev

And now your site should be available at http://localhost:3000!

New Next.js App

Step 1: Installing and configuring Cypress in a Next.js app

Now that we have our app set up, we want to install Cypress so that we can use it to run our tests.

Back inside of our terminal, we can install Cypress with:

npm install cypress --save-dev

Here, we’re including the —save-dev flag, as we don’t need Cypress to run in the production version of our application, so we install it as a dev dependency.

Once that’s complete, we need a way to run Cypress from the command line. While we can navigate to Cypress itself, we can instead add a new script command, which will make it easier to run Cypress.

Inside of package.json, under scripts, add the following:

"cy:open": "cypress open"

Now, inside our terminal, we can run that script to open Cypress:

npm run cy:open

If this is the first time you’re running Cypress, it might take an extra second and install Cypress in your project.

Opening Cypress for the first time

Once finished, Cypress will open a new dialogue panel that will serve as your dashboard for running tests for your project.

You’ll also notice that Cypress lets you know they also added a new directory to your project at cypress. This includes example files that let you see how Cypress works and immediately get started.

To try this out, on the right side of the Cypress panel, click Run 19 integration specs.

Cypress will then open up a new browser and run through all of the example tests.

Next, we’ll add some of our own tests.

Follow along with the commit!

Step 2: Creating your first Cypress test in a Next.js app

Now that we can successfully run our tests, let’s try adding our own.

We don’t need really any of the tests that Cypress included in the examples, so let’s remove the entire integration/examples directory.

Then, create a new file under integration called home.spec.js and inside add the following:

/// <reference types="cypress" />

context('Home', () => {
  beforeEach(() => {
    cy.visit('http://localhost:3000');
  });

  it('should find the title of the homepage', () => {
    cy.get('h1').contains('Welcome');
  });
});

In the code above, we’re:

• First adding Cypress as a reference type, which allows Cypress to find the file and know that it should use it to run a test
• Creating a new context for our test and defining it as Home
• Telling Cypress that before each test, we want it to visit our homepage
• Defining a test that grabs the h1 and checks that it contains “Welcome”

If we now look back at Cypress, we’ll see that we only have that one Integration Test. If we click it and try to run the test, we’ll see that we actually get an error, as we never started up our development server, meaning it’s not available.

To fix this, we’re going to use a tool called start-server-and-test.

This package will do what the name implies, it will:

• Start our server based on the command we provide
• Run the tests that we provide
• Stop the server once complete

To add it, inside of our terminal let’s run:

npm install start-server-and-test --save-dev

Then, inside of our package.json file, we’re going to add another new command to the scripts object:

"test": "start-server-and-test dev 3000 cy:open"

Here, we’re telling start-server-and-test that we want to run the dev command to start our server, that it will be available at port 3000, and that we want to run the cy:open command after to run our tests.

And if we go back to our terminal and run:

npm run test

We’ll see that Cypress opens up like before. But if we now run our test, we can see that it successfully opens up our Next.js app and it sees the word “Welcome” inside of our h1!

Successfully running a test in Cypress

Follow along with the commit.

Step 3: Installing and configuring Applitools Eyes

With Cypress successfully running our tests, we can now hook into our tests and use Applitools to run visual regression testing on our project.

Before we dive in, make sure you have a free account set up over at Applitools, which we’ll need in order to set up an API key.

To get started, we’re going to need to install the Eyes library to our project.

In our terminal, we can run:

npm install @applitools/eyes-cypress --save-dev

Which will install the Cypress-specific SDK for Applitools Eyes.

Once that’s finished installing, we can run the Eyes setup script.

npx eyes-setup

This will go through the project and add the necessary configurations to Cypress to make Eyes work properly.

Finally, we’ll need to make our Applitools API key available whenever we run our tests.

To start, we need to find our API key in our Applitools account.

Inside the Applitools dashboard, select My API Key under the account dropdown.

Finding the Applitools API key

It will open a dialogue where you can select and copy your API key.

Copying the Applitools API key

You’ll want to save this API key for later when we run our tests.

Next, we’ll want to be able to set our API key. We can do this a few ways:

• Export the environment variable in our shell before running the tests
• Prepend the API key to the test command
• Add the API key to the applitools.config.js file
• Create an environment variable using dotenv and the cypres-dotenv package

For this demo, we’re going to run our test by prepending the API key to our command. This will allow us to quickly test this out.

To do this, any time we run a command like npm run test, we’re going to include our API key in front of it like:

APPLITOOLS_API_KEY="abcd1234" npm run test

Note: remember to replace the API key with your unique ID.

And now, we should be ready to add our first test.

Follow along with the commit!

Step 4: Visual regression testing with Applitools Eyes

We have Cypress and Applitools both configured and ready to go, meaning we can now add Applitools Eyes to visually test our app!

Our app doesn’t have a lot of functionality yet., so we can start off with a basic check that makes sure our homepage looks the way it’s supposed to each time our tests run.

To start, inside of our cypres/integrations/home.spec.js file, let’s add the following right below our existing it statement:

it('should verify the homepage looks as expected', () => {
  cy.eyesOpen({
    appName: 'My App',
    testName: 'Homepage Check',
  });

  cy.eyesCheckWindow({
    tag: 'App Window',
    target: 'window',
    fully: true
  });

  cy.eyesClose();
});

Here’s what we’re doing here:

• First, we’re “opening the eyes” of Applitools, which will prepare the Eyes functionality to check our app
• Next, we’re running a check on the window of our application, essentially capturing a screenshot of our app and sending it to Applitools
• Finally, we “close the eyes” of Applitools, letting Eyes know that we’re running our checks

Now, if we run our test command and start our test:

APPLITOOLS_API_KEY="abcd1234" npm run test

We can see that Cypress runs our new test case which doesn’t appear that it’s doing anything inside of our browser, but shows a passing indicator.

Successfully ran an Applitools Eyes check in Cypress

Now, if we go back to our Applitools dashboard:

First snapshot in Applitools

We can see that we have a new “run” titled Homepage Check (which we specified in the code) which shows that it passed with a snapshot of our app.

Now, having this screenshot alone isn’t what makes this powerful. From now on, any time we run this test, Applitools will compare our app against this original snapshot and let us know if anything changed.

To test this out, we’re going to change the color of title of our page. This might seem like a simple change, but style changes can be more challenging for tools like Cypress alone to detect an issue, which is where Applitools Eyes will shine with its snapshot comparison.

Inside of styles/Home.module.css file, let’s add the following to the .title class:

color: #ddd;

Next.js app with light gray title

While we may not have intentionally made a change like this in practice, this could have happened if we were changing styles that cascade to our title. This makes our title hard to read, but that makes this perfect for a test case.

Now, let’s run our tests again:

APPLITOOLS_API_KEY="abcd1234" npm run test

But this time, we can see that our test fails!

Cypress throwing an error with the Applitools Eyes check

Our Applitools test fails because it states that “Eyes-Cypress detected diffs or errors during execution of visual tests”.

If we look inside of our Applitools dashboard:

Change detected in text of app title in Applitools Eyes

We can see that we now have an “Unresolved” run where Applitools shows us the differences on the page, which in our case, is the "Welcome to" part of our title.

This is super useful when working on projects where it can be challenging to test every single page or type of page in an app. We can make sure that if anything changes or breaks, it will immediately get flagged in Applitools.

From here, if we’re happy with color change, we can accept the new version of our app.

Accept or reject changes in Applitools Eyes

Otherwise we can reject it and let our team know that it needs to be fixed.

Follow along with the commit!

What’s next?

Between Cypress and Applitools, we have a lot of things we can do to make sure that our app is behaving the way we want it to.

Most of the time when we’re building an app, we’re building that app so people can interact with it.

Using Cypress, we can click on different parts of the page, changing the state of the page, then run a check with Applitools Eyes to make sure it’s functioning the way we expect it to.

We can also have Cypress run on different browsers to make sure our app is working properly everywhere someone is trying to use it!

• What is GraphQL?
• What is Apollo GraphQL?
• Fetching data in Next.js
• What are we going to build?
• Step 0: Creating a new Next.js app
• Step 1: Adding Apollo GraphQL to a Next.js app
• Step 2: Adding data to a Next.js page with getStaticProps
• Step 3: Fetch data with a GraphQL query in Next.js using Apollo Client
• Step 4: Adding SpaceX launch data to the page

What is GraphQL?

GraphQL is a query language and runtime that provides a different way of interacting with an API than what you would expect with a traditional REST API.

When fetching data, instead of making a GET request to a URL to grab that data, GraphQL endpoints take a “query”. That query consists of what data you want to grab, whether it’s an entire dataset or a limited portion of it.

If your data looks something like this:

Movie {
  "title": "Sunshine",
  "releaseYear": "2007",
  "actors": [...],
  "writers": [...]
}

And you only want to grab the title and the year it was released, you could send in a query like this:

Movie {
  title
  releaseYear
}

Grabbing only the data you need.

The cool thing is, you can also provide complex relationships between the data. With a single query, you could additionally request that data from different parts of the database that would traditionally take multiple requests with a REST API.

What is Apollo GraphQL?

Apollo GraphQL at its core is a GraphQL implementation that helps people bring together their data as a graph.

Apollo also provides and maintains a GraphQL client, which is what we’re going to use, that allows people to programmatically interact with a GraphQL API.

Using Apollo’s GraphQL client, we’ll be able to make requests to a GraphQL API similar to what we would expect with a REST-based request client.

Fetching data in Next.js

When fetching data with Next.js, you have a few options for how you want to fetch that data.

First, you could go the client side route and make the request once the page loads. The issue with this is that you’re then putting the burden on the client to take the time to make those requests.

The Next.js APIs like getStaticProps and getServerSideProps allow you to collect data at different parts of the lifecycle, giving us the opportunity to make a completely static app or one that’s server-side rendered. That will serve the data already rendered to the page straight to the browser.

By using one of those methods, we can request data along with our pages and inject that data as props right into our app.

What are we going to build?

We’re going to create a Next.js app that shows the latest launches from SpaceX.

SpaceX launches demo

We’ll use the API maintained by SpaceX Land to make a GraphQL query that grabs the last 10 flights. Using getStaticProps, we’ll make that request at build time, meaning our page will be rendered statically with our data.

Step 0: Creating a new Next.js app

Using Create Next App, we can quickly spin up a new Next.js app that we can use to immediately start diving into the code.

Inside your terminal, run the command:

npx create-next-app my-spacex-launches

Note: you don’t have to use my-spacex-app, feel free to replace that with whatever name you want to give the project.

After running that script, Next.js will set up a new project and install the dependencies.

Once finished, you can start up your development server:

cd my-spacex-launches
npm run dev

This will start a new server at http://localhost:3000 where you can now visit your new app!

New Next.js app

Step 1: Adding Apollo GraphQL to a Next.js app

To get started with making a GraphQL query, we’ll need a GraphQL client. We’ll use the Apollo GraphQL Client to make our queries to the SpaceX GraphQL server.

Back inside of the terminal, run the following command to install our new dependencies:

npm install @apollo/client graphql

This will add the Apollo Client as well as GraphQL, which we’ll need to to form the GraphQL query.

And once installation completes, we’ll be ready to get started Using Apollo Client.

Follow along with the commit!

Step 2: Adding data to a Next.js page with getStaticProps

Before we fetch any data with Apollo, we’re going to set up our page to be able to request data then pass that data as a prop to our page at build time.

Let’s define a new function at the bottom of the page below our Home component called getStaticProps:

export async function getStaticProps() {
  // Code will go here
}

When Next.js builds our app, it knows to look for this function. So when we export it, we’re letting Next.js know we want to run code in that function.

Inside our getStaticProps function, we’re going to be ultimately returning our props to the page. To test this out, let’s add the following to our function:

export async function getStaticProps() {
  return {
    props: {
      launches: []
    }
  }
}

Here, we’re passing a new prop of launches and setting it to an empty array.

Now, back inside of our Home component, let’s add a new destructured argument that will serve as our prop along with a console.log statement to test our new prop:

export default function Home({ launches }) {
  console.log('launches', launches);

If we reload the page, we can see that we’re now logging out our new prop launches which includes an empty array just like we defined.

Logging launches prop

The great thing about this is that given that the getStaticProps function we’re creating is asynchronous, we can make any request we’d like (including a GraphQL query) and return it as props to our page, which is what we’ll do next.

Follow along with the commit!

Step 3: Fetch data with a GraphQL query in Next.js using Apollo Client

Now that our application is prepared to add props to the page and we have Apollo installed, we can finally make a request to grab our SpaceX data.

Here, we’re going to use the Apollo Client, which will allow us to interface with the SpaceX GraphQL server. We’ll make our request to the API using the Next.js getStaticProps method, allowing us to dynamically create props for our page when it builds.

First, let’s import our Apollo dependencies into the project. At the top of the page add:

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

This is going to include the Apollo Client itself, InMemoryCache which allows Apollo to optimize by reading from cache, and gql which we’ll use to form our GraphQL query.

Next, to use the Apollo Client, we need to set up a new instance of it.

Inside the top of the getStaticProps function, add:

const client = new ApolloClient({
  uri: 'https://api.spacex.land/graphql/',
  cache: new InMemoryCache()
});

This creates a new Apollo Client instance using the SpaceX API endpoint that we’ll use to query against.

With our client, we can finally make a query. Add the following code below the client:

const { data } = await client.query({
  query: gql`
    query GetLaunches {
      launchesPast(limit: 10) {
        id
        mission_name
        launch_date_local
        launch_site {
          site_name_long
        }
        links {
          article_link
          video_link
          mission_patch
        }
        rocket {
          rocket_name
        }
      }
    }
  `
});

This does a few things:

• Creates a new GraphQL query inside of the gql tag
• Creates a new query request using client.query
• It uses await to make sure it finishes the request before continuing
• And finally destructures data from the results, which is where the information we need is stored

Inside of the GraphQL query, we’re telling the SpaceX API that we want to get launchesPast, which are the previous launches from SpaceX, and we want to get the last 10 of them (limit). Inside that, we define the data we’d like to query.

If we take a second to add a new console log statement after that, we can see what data looks like.

Once you refresh the page though, you’ll notice that you’re not seeing anything inside of the browser’s console.

getStaticProps runs during the build process, meaning, it runs in node. Because of that, we can look inside of our terminal and we can see our logs there:

Logging data to the terminal

After seeing that, we know that inside of the data object, we have a property called launchesPast, which includes an array of launch details.

Now, we can update our return statement to use launchesPast:

return {
  props: {
    launches: data.launchesPast
  }
}

And if we add our console.log statement back to the top of the page to see what our launches prop looks like, we can see our launch data is now available as a prop to our page:

Logging props to web console

Follow along with the commit!

Step 4: Adding SpaceX launch data to the page

Now for the exciting part!

We have our launch data that we were able to use Apollo Client to request from the SpaceX GraphQL server. We made that request in getStaticProps so that we could make our data available as the launches prop that contains our launch data.

Digging into the page, we’re going to take advantage of what already exists. For instance, we can start by updating the h1 tag and the paragraph below it to something that describes our page a little bit better.

Updated page title

Next, we can use the already existing link cards to include all of our launch information.

To do this, let’s first add a map statement inside of the page’s grid, where the component we return is one of the cards, with launch details filled in:

<div className={styles.grid}>
  {launches.map(launch => {
    return (
      <a key={launch.id} href={launch.links.video_link} className={styles.card}>
        <h3>{ launch.mission_name }</h3>
        <p><strong>Launch Date:</strong> { new Date(launch.launch_date_local).toLocaleDateString("en-US") }</p>
      </a>
    );
  })}

We can also get rid of the rest of the default Next.js cards including Documentation and Learn.

Page with SpaceX launches

Our page now includes the last 10 launches from SpaceX along with the date of the launch!

We can even click any of those cards, and because we linked to the video link, we can now see the launch video.

Follow along with the commit!

What’s next?

From here, we can include any additional data from inside of our launches array on our page. The API even includes mission patch images, which we can use to show nice graphics for each launch.

You can even add additional data to the GraphQL query. Each launch has a lot of information available including the launch crew and more details about the rocket.

https://api.spacex.land/graphql/

While that can include building an HTML file by hand, how can we leverage static generation to build apps with modern tools?

• What is Static Generation?
• What happens during Static Generation?
• How does Next.js use Static Generation?
• Statically generating an app with Next.js

What is Static Generation?

Static Generation describes the process of compiling and rendering a website or app at build time. The output is a bunch of static files, including the HTML file itself and assets like JavaScript and CSS.

If you haven’t heard of Static Generation but that concept sounds familiar, you might have heard of it by its longer name Static Site Generation or its acronym SSG.

What happens during Static Generation?

JavaScript-based web apps as we traditionally know them work by running libraries like React or scripts at run time in the browser.

When the browser receives the page, it’s usually simple HTML without a lot of content. This then loads the scripts to pull the content into the page, a process also known as hydration.

With Static Generation, tools like Next.js try to render that page mostly like it would in the browser but at compile time. This gives us the ability to serve the entire content on first load. The scripts still hydrate the page during this process, but ideally with fewer changes or no changes at all.

How does Next.js use Static Generation?

Out of the box, Next.js will attempt to statically generate any pages that it can. It does this by detecting how an app is fetching its data.

Next.js provides a few different APIs to fetch data including getStaticProps and getServerSideProps, which, depending on how they’re used, determines how Next.js will build your app.

If you only use getStaticProps to fetch data, Next.js will fetch that data at build time, leaving you with a completely static page.

If you use getServerSideProps, Next.js will know that the app requires a server to render those pages.

Alongside a deployment solution like Vercel that will automatically handle configuring a server, Next.js will load any of the data when someone requests the page from the server.

While it doesn’t do it by default, Next.js also provides the ability to export the app into static files into a separate directory after the app has been built.

First, you would run the next build command to build the app, then you would run next export which, by default, makes the app available as static files in the out directory.

How to statically generate an app with Next.js

To get an idea of how this works, we can quickly create a new Next.js app.

The only requirements for this is that you have Node installed with npm and the ability to use a terminal to run commands.

How to create a Next.js app

Getting started is as simple as running a single line in the terminal.

Open up the directory you’d like to create your project in and run:

npx create-next-app my-static-nextjs-app

After the installation is complete, you can navigate to your new project directory:

cd my-static-nextjs-app

Once there, start your development server:

npm run dev

And once the server is ready, you can open up http://localhost:3000 in your browser where you can now see your new Next.js app!

New Next.js app

How to build a Next.js app

Now that we have our application available, let’s try to build it.

In the same directory, run the command:

npm run build

If you look at the output inside of the terminal, we see a few important things happen.

First, Next.js lets us know that it’s running through its build process, including optimizing the app for performance, compiling the app, and collecting data.

Building with Next.js

Next, we see that Next.js shows us a breakdown of how it’s built each page.

The default Next.js starting template includes a few static pages and an example API route.

Using the legend at the bottom, we can see that all of the pages and assets were statically generated with one route tagged as requiring a server, which would be our API route.

Next.js generating pages

Note: For the purposes of this walkthrough, we can ignore the API route, but Next.js along with Vercel provides the ability to build lambda functions as part of the Next.js API.

How to build a static Next.js app

With our Next.js build output, we know that we just built some static pages, but we might have trouble finding them. If we look at the folders and files in our project, it’s not immediately clear where those files are.

When Next.js builds an app, by default, it only outputs that app inside the .next directory. This includes configuration files that tools like Vercel can use and understand to deploy the app.

Technically, that directory includes our entire app, but this isn’t something we can easily deploy to static hosting.

Next.js also provides the ability to export an app. This will take the app that we built and produce a set of static files which we can then use to deploy our app.

Inside of the package.json file, update the build script to include next export:

"build": "next build && next export",

Once updated, run the build command again in the project directory:

npm run build

And now we can see that not only did we build the app like we did in our last step, Next.js lets us know that we’re also exporting the app that we built into static files.

Exporting static Next.js app

If we look inside of our project folder, we should now see a new directory called out.

If we look inside of that folder, we can now see our entire app statically compiled including the index.html file as well as all of the CSS and JS needed to use the app!

Where can we go from here?

We learned that we can use Next.js and the concept of Static Generation to statically compile an app.

Tools like Next.js can do this by compiling our code, similar to what we might see in a browser, so that by the time our app hits the browser, it’s all ready to go.

With a simple command, we can also build and compile our app, as well as export it into static files. We can deploy those static files to any static storage service like Vercel or AWS S3. This provides us with an easy way to craft dynamic web apps that are fast and cheap.

Learn more about how Next.js leverages its different APIs to provide both static and dynamic experiences by visiting the Next.js docs.

How can we use GitHub Actions to automate and continuously deploy our app to S3?

• What are GitHub Actions?
• What is Continuous Deployment?
• What are we going to build?
• Step 0: Setting up a new Next.js project on GitHub
• Step 1: Manually creating and deploying a Next.js project to a new S3 Bucket
• Step 2: Creating a new GitHub Action workflow to automatically build a Next.js project
• Step 3: Configuring a GitHub Action to deploy a static website to S3

What are GitHub Actions?

GitHub Actions is a free service from GitHub that allows us to automate code tasks.

I previously wrote about how we can use them to automate tasks like running tests on our code and sending notifications to Slack.

They provide a flexible way to automatically run code based on our existing workflows. This provides a lot of possibilities like even deploying our website!

What is AWS S3?

S3 (Simple Storage Service) is an object storage service from AWS. It allows you to store files in the cloud easily making them available around the world.

It also allows you to use these files as a website. Because we can upload an HTML file as an object, we can also configure S3 to access that file as an HTTP request. This means that we can host an entire website right in S3.

What is Continuous Deployment?

Continuous Deployment, often referred to by its acronym CD, is the practice of maintaining code in a releasable state and deploying that code automatically or in short cycles.

Particularly in our use case, we’re going to configure our project so that any time a new update is pushed or merged to the primary Git branch, our website will deploy.

What are we going to build?

We’re first going to bootstrap a simple Next.js app using the default Next.js starting template and configure it to compile to static files.

If you don’t want to create a Next.js project, you can follow along with even a simple HTML file and not run any of the build commands. But Next.js is a modern way to build dynamic web apps, so we’ll start there.

With our website files ready to go, we’ll create and configure an S3 bucket in AWS where we’ll host our website.

Finally, we’ll create a new GitHub Action workflow that will automatically update the website files in S3 any time a new change occurs on our primary branch (main).

Step 0: Setting up a new Next.js project on GitHub

We’re going to get started with the default template with Next.js.

After navigating to the directory you want to create your project in, run:

yarn create next-app my-static-website
# or
npx create-next-app my-static-website

Note: Feel free to replace my-static-website with the name of your choice. We’ll use that for the rest of this tutorial.

If you navigate to that directory and run the development command, you should be able to successfully start up your development server.

cd my-static-website
yarn dev
# or
npm run dev

New Next.js App

Next, let’s configure our project to statically compile.

Inside the package.json file, update the build script to:

"build": "next build && next export",

What this will do is tell Next to take the website and export it to static files, which we’ll use to host the site.

We can test this out by running the command:

yarn build
# or
npm run build

And once finished, we can look inside of the out directory and see all of the files of our new website.

Static output from Next.js

Finally, we want to host this on GitHub.

Inside of your GitHub account, create a new repository. This will then provide instructions on how you can add an existing project to that repo.

And once you push our your project to GitHub, we should be ready to set up our new website project!

New repo in GitHub

Follow along with the commits:

• Adding the initial Next.js project via Create Next App
• Configuring Next.js to export the project

Step 1: Manually creating and deploying a Next.js project to a new S3 Bucket

To get started with our new S3 Bucket, first log in to your AWS account and navigate to the S3 service.

No buckets in S3

We’ll want to create a new bucket, using the name of our choice, which will be used for the S3 endpoint where our website is hosted. We’ll also want to configure our S3 bucket to be able to host a website.

Note: this tutorial will not walk you through how to host a website on S3, but you can check out my other tutorial that will walk you through hosting a website on S3 step-by-step.

Static website hosting in AWS S3

Once we have our S3 bucket configure as a website, we can go back to our Next.js project folder, run our build command, and then upload all of our files from the out directory into our new S3 bucket.

S3 Bucket with Static App

And once those files are uploaded and we’ve configured our S3 bucket for website hosting, we should now be able to see our project live on the web!

AWS S3 hosted Next.js app

Step 2: Creating a new GitHub Action workflow to automatically build a Next.js project

To get started, we’re going to need to create a new workflow.

If you’re familiar with GitHub Actions, you could create one manually, but we’ll quickly walk through how to do this in the UI.

Navigate to the Actions tab of your GitHub repository and click on "set up a workflow yourself."

New GitHub Action Workflow

GitHub provides a starting template that we can use for our workflow, though we’ll want to make some changes.

Let’s do the following:

• Optional: rename the file to deploy.yml
• Optional: rename the workflow to CD (as it’s a bit different from CI)
• Optional: remove all of the comments to make it a bit easier to read
• Remove the pull_request definition in the on property
• Remove all steps except for uses: actions/checkout@v2

So at this point we should be left with:

name: CD

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

This code alone will trigger a process that spins up a new instance of Ubuntu and simply checks out the code from GitHub any time there’s a new change pushed to the main branch.

Next, once we have our code checked out, we want to build it. This will allow us to take that output and sync it to S3.

This step will differ slightly depending on if you are using yarn or npm for your project.

If you’re using yarn, under the steps definition, add the following:

- uses: actions/setup-node@v1
  with:
    node-version: 12
- run: npm install -g yarn
- run: yarn install --frozen-lockfile
- run: yarn build

If you’re using npm, add the following:

- uses: actions/setup-node@v1
  with:
    node-version: 12
- run: npm ci
- run: npm run build

Between both of these sets of steps, what we’re doing is:

• Setting up node: this is so that we can use npm and node to install and run our scripts
• Install Yarn (Yarn Only): if we’re using yarn, we install it as a global dependency so that we can use it
• Install Dependencies: we install our dependencies and we use a specific command that makes sure we use the lock file available to avoid any unexpected package upgrades
• Build: finally, we run our build command which will compile our Next.js project into the out directory!

And now we can commit that file right to our main branch which will kick off a new run of our workflow that we can see in our Actions tab.

New workflow in GitHub Actions

To see that it works, we can navigate into that run, select our workflow, and see that all of our steps ran including building our project!

Successful build logs for a GitHub Action workflow

Follow along with the commit!

Step 3: Configuring a GitHub Action to deploy a static website to S3

Now that we’re building our project automatically, we want to automatically update our website in S3.

To do that, we’re going to use the GitHub Action aws-actions/configure-aws-credentials and the AWS CLI.

The GitHub Action that we’re using will take in our AWS credentials and configuration and make it available to use throughout the lifecycle of the workflow.

As of now, the Ubuntu instance that GitHub Actions provides allows us to use the AWS CLI as it comes included. So we’ll be able to use the CLI commands right in our workflow.

Alternatively, we could use the S3 Sync action. But by using the AWS CLI, we gain more flexibility to customize our setup, we can use it for additional CLI commands, and it’s also generally nice to get familiar with the AWS CLI.

So to get started, let’s add the following snippet as additional steps in our workflow:

- uses: aws-actions/configure-aws-credentials@v1
  with:
    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    aws-region: us-east-1

What the above will do is use the AWS credentials configuration action to set up our AWS Access Key, Secret Key, and region based on our settings.

The AWS Region can be customized to whatever region you typically use with your AWS account. I’m in the northeast United States, So I’ll keep us-east-1.

The Access Key and Secret Key are credentials that you’ll need to generate with your AWS account. The way our code is set up is that we’ll store those values inside of GitHub Secrets, which will prevent those keys from being leaked. When the action runs, Github changes those values to stars (***) so people can't access those keys.

So to set up those secrets, we first want to generate Access Keys in AWS.

Navigate to the AWS console. Under the user menu, select My Security Credentials, and then select Create access key.

Creating an Access Key in AWS

This will provide you with two values: the Access key ID and the Secret access key. Save these values, as you won’t be able to access the Secret key ID again.

Finding Secret and Access Key in AWS

Note: remember to NOT include the Access Key and Secret Key inside of your code. This could lead to someone compromising your AWS credentials.

Next, inside of the GitHub repo, navigate to Settings, Secrets, then select New secret.

Here we’ll want to add our AWS keys using the following secrets:

• AWS_ACCESS_KEY_ID: your AWS Access key ID
• AWS_SECRET_ACCESS_KEY: your AWS Secret key

And once saved you should have your two new secrets.

Creating Secrets in GitHub

Now that we have our credentials configured, we should be ready to run the command to sync our project to S3.

Inside of the GitHub Action, add the following step:

- run: aws s3 sync ./out s3://[bucket-name]

Note: be sure to replace [bucket-name] with the name of your S3 Bucket.

This command will trigger a sync with our specified S3 bucket, using the contents of the out directory, which is where our project builds to.

And now, if we commit our changes, we can see that our action is automatically triggered once committed to the main branch, where we build our project and sync it to S3!

Successful AWS S3 sync in GitHub Action workflow

Note: Make sure that before setting up this action you’ve configured the S3 bucket to host a website (including unblocking permissions on S3 bucket) – otherwise this action may fail.

At this point, our project probably looks the same, as we didn’t make any changes to the code.

Next.js app on AWS S3

But if you make a code change, such as changing the title of the homepage inside of pages/index.js and commit that change:

<h1 className={styles.title}>
  Colby's <a href="https://nextjs.org">Next.js!</a> Site
</h1>

We can see that our change triggers the workflow to kick off:

New GitHub Action workflow from code change

And once our workflow finishes, we can see that our content is now automatically updated on our website:

AWS S3 hosted app with updated code changes

Follow along with the commits:

• Adding AWS configuration and S3 sync command
• Title update to test workflow

What else can we do?

Setting up CloudFront

The goal of this post wasn’t to go through the entire process of configuring a website for AWS, but if you’re serving a website on S3, you might want to also include CloudFront in front of it.

You can check out my other guide here which walks you through setting up CloudFront as well as a step-by-step guide through creating the site in S3.

Invaliding CloudFront cache

If your S3 website is behind CloudFront, chances are, you’ll want to make sure CloudFront isn’t caching the new changes.

With the AWS CLI, we can also trigger a cache invalidation with CloudFront to make sure it’s grabbing the latest changes.

Check out the docs here to learn more.

Pull request deployments

If you’re constantly working on website changes in a pull request, sometimes it can be easier to see the changes live.

You can set up a new workflow that only runs on pull requests, where the workflow can dynamically create a new bucket based on the branch or environment and add a comment to the pull request with that URL.

You might be able to find a GitHub Action that exists to manage the comments on the pull request for you or you can check out the GitHub Actions docs.

How can we take advantage of the power of Chakra UI to build great web apps?

• What is Chakra UI?
• What makes Chakra UI so great?
• What are we going to build?
• Step 0: Creating a new React project with Next.js
• Step 1: Installing and configuring Chakra UI in Next.js
• Step 2: Adding Chakra UI components to a React app
• Step 3: Making responsive components with Chakra UI
• Step 4: Customizing the default Chakra UI theme

What is Chakra UI?

Chakra UI is a component library for React that makes it easy to build the UI of an app or website.

Their goal is to provide a simple, modular, and accessible set of components to get up and running quickly.

What makes Chakra UI so great?

To start, by default Chakra strives to make each component accessible. It’s a critical part of application development that’s often overlooked, and the Chakra maintainers have gone out of their way to ensure the components follow the WAI-ARIA guidelines.

Chakra also includes a simple API allowing developers to get productive. It allows people and teams to make inclusive apps without having to worry about building a bunch of components themselves.

For styling and customization, Chakra uses Emotion under the hood to provide developers the ability to style their components right inside of their JavaScript with style props. It comes with a default theme, but allows the ability to easily override it with custom settings.

What are we going to build?

To get a good idea of how Chakra works, we’re going to essentially rebuild the default Next.js template with Chakra UI components.

This will help us understand a few important concepts, such as how to use Chakra UI with Next.js, how to add custom styles with props, and how to customize the Chakra UI theme.

The concepts here can apply pretty much to any React app, though the examples will be slightly specific to Next.js.

Step 0: Creating a new React project with Next.js

To get started, we need a React app. We’re going to use Next.js as our framework which will give us the ability to easily spin up a new app.

Once inside the directory you want to create your project in, run:

yarn create next-app my-chakra-app
# or
npx create-next-app my-chakra-app

Note: feel free to change my-chakra-app to whatever you want to name the project directory.

And once that’s finished, you can navigate into that directory and start the project with:

yarn dev
# or
npm run dev

That should spin up your development server at http://localhost:3000 and we should be ready to go!

Default Next.js template

Follow along with the commit!

Step 1: Installing and configuring Chakra UI in Next.js

Next, let’s install Chakra UI.

Inside of your project directory, run:

yarn add @chakra-ui/core @emotion/core @emotion/styled emotion-theming
# or 
npm install @chakra-ui/core @emotion/core @emotion/styled emotion-theming

This will install Chakra UI and its dependencies, which includes Emotion, as it relies on it for the styling.

To get Chakra working inside of our app, we need to configure a Provider at the root of our application. This will allow all of Chakra’s components to talk to each other and use the configuration to maintain consistent styles.

Inside pages/_app.js, first let’s import our Provider at the top:

import { ThemeProvider, theme } from '@chakra-ui/core';

Next, replace the return statement inside of the component with:

function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider theme={theme}>
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

As you’ll notice, we’re also passing a theme variable to our provider. We’re importing the Chakra UI default theme straight from Chakra and passing it in to our ThemeProvider so all of our components can get the default styles and configurations.

Finally, we want to add a component called CSSReset right as a direct child of our ThemeProvider.

First, add CSSReset as an import:

import { ThemeProvider, theme, CSSReset } from '@chakra-ui/core';

Then add the component right inside ThemeProvider:

<ThemeProvider theme={theme}>
  <CSSReset />
  <Component {...pageProps} />
</ThemeProvider>

And now if we reload the page, we can see that things are looking a little bit different!

Next.js with Chakra UI CSS Reset

The browser comes with a lot of default styles and by default, Chakra UI doesn’t override them. This includes styles like borders on a button element.

While we don’t necessarily need the CSS Reset here, we could override those things manually. This provides us with a foundation where we’ll know that Chakra UI is working as it’s intended to and we can start adding our components.

Follow along with the commit!

Step 2: Adding Chakra UI components to a React app

Now for the fun part. We’re going to use Chakra UI components to try to rebuild the Next.js default template. It’s not going to look 100% exactly like it, but it will carry the spirit and we can customize it as we’d like.

Building the Title and Description

Starting from the top, let’s update our title and description.

At the top of the page, we need to import our Heading component:

import { Heading, Link } from "@chakra-ui/core";

Then let’s replace the <h1> with:

<Heading as="h1" size="2xl" mb="2">
  Welcome to Next.js!
</Heading>

Here, we’re using the Heading component which we then set “as” an h1. We can use any HTML heading element tag name, but since we’re replacing an h1, we want to use that.

We’re also setting a size attribute, which allows us to control how big out heading is, as well as mb, which stands for margin-bottom, allowing us to add some space below.

And we can already see our page is looking more like the default template.

Chakra UI Heading component

We also want to add back our link.

Add Link to our import statement at the top and then inside of our <Heading> component, replace the Next.js text with:

<Link color="teal.500" href="https://nextjs.org">Next.js!</Link>

Chakra’s Link component creates a link as expected, but then allows us to use the style props to customize it. Here, we’re using the color variable teal.500 that Chakra provides to change our link to Chakra’s colors.

And we can see that we have our Next.js link!

Chakra UI Heading with Link component

The last piece of the header is the description. For that, we want to use the Text component.

Add Text and Code to the import statement and replace the description with:

<Text fontSize="xl" mt="2">
  Get started by editing <Code>pages/index.js</Code>
</Text>

We’re using the Text component to recreate a <p> tag and the Code component to create our <code> tag. Similar to our Heading component, we’re adding a fontSize to make the font bigger and mt which stands for margin-top to add some space above it.

And now we have our header!

Chakra UI Text component with Code

Replacing info cards with Chakra UI components

For each of our cards, we can use the same concepts as we did with the header to recreate each of our boxes.

To start, add an import for the Flex component and replace the tag <div className={styles.grid}> with:

<Flex flexWrap="wrap" alignItems="center" justifyContent="center" maxW="800px" mt="10">
  ...
</Flex>

Make sure to leave all of the cards inside of the Flex component. The Flex component will recreate our grid by adding Flexbox along with the same properties that were on the grid before.

At this point, it should exactly the same as it did before.

Next, add Box to the import statement and then replace the first card with:

<Box as="a" href="https://nextjs.org/docs" p="6" m="4" borderWidth="1px" rounded="lg" flexBasis="45%">
  <Heading as="h3" size="lg" mb="2">Documentation &rarr;</Heading>
  <Text fontSize="lg">Find in-depth information about Next.js features and API.</Text>
</Box>

Similar to our Heading component, we’re setting our Box component “as” an <a> tag allowing it to serve as a link. We then configure our style props to replicate our cards.

Inside of that, we use the Heading and Text component to recreate the actual content of the cards.

And after only changing the first card, we can now see the changes:

Chakra UI Box component

Now, we can go back and replace the other three cards with the same components to finish recreating our grid.

For fun, we can add a 5th card that links to Chakra UI:

<Box as="a" href="https://chakra-ui.com/" p="6" m="4" borderWidth="1px" rounded="lg" flexBasis="45%">
  <Heading as="h3" size="lg" mb="2">Chakra UI &rarr;</Heading>
  <Text fontSize="lg">Build accessible React apps & websites with speed.</Text>
</Box>

And with all of our changes, we can now see our recreated Next.js starting template!

Chakra UI recreating Next.js grid

Follow along with the commit!

Step 3: Making responsive components with Chakra UI

Part of what the default Next.js grid was able to provide was the ability for the cards to expand to full width once the size of the browser becomes small enough. This is particularly relevant at 600px, which typically means someone’s on a mobile device.

If we look at our page on a mobile device, we can see that our cards aren’t filling up the entire width.

Chakra UI default without responsive

Chakra allows us to set responsive styles with its baked in sizing, allowing us to easily recreate our responsive grid cards.

To do this, instead of passing in a single value to our style props, we can pass in an array.

For instance, on each of our Box components, let’s update the flexBasis prop to:

flexBasis={['auto', '45%']}

Here, according to Chakra’s default responsive breakpoints , we’re saying that by default, we want our flexBasis to be set as auto. But for anything 480px and larger, again which is Chakra’s default first breakpoint, we set it to 45%.

Chakra considers its responsive styling to be mobile first, which is why you see the 480px act as a minimum size, not a maximum size.

And with that change, we can now see that on a large device, we still have our grid.

Chakra UI components on large device

But now on mobile, our cards take up the entire width!

Chakra UI components on small device

Using the array pattern works for all of the breakpoints, so if you wanted more control over your styles, Chakra lets you do that.

Follow along with the commit!

Step 4: Customizing the default Chakra UI theme

While Chakra provides a pretty great default theme, we also have the ability to customize it to our liking to match our brand or personal taste.

For instance, while the teal that we used for our Heading link is great and uses Chakra’s styles, what if I wanted to customize all links to use the purple that I use on my website?

To start, Chakra comes with a default purple, so we can update our link to use that purple:

Welcome to <Link color="purple.500" href="https://nextjs.org">Next.js!</Link>

And we see our change.

Making Next.js header link purple with color style prop

That looks great, but let’s update it to the exact purple I use.

Inside of pages/_app.js, we’re going to create a new object at the top of the page, where we spread the default theme creating a new theme object. We’ll also replace the theme prop with our new object:

const customTheme = {
  ...theme
}

function MyApp({ Component, pageProps }) {
  return (
    <ThemeProvider theme={customTheme}>

If we save and reload the page, it will look exactly the same.

Next, we want to update the colors, so in our custom theme object, let’s add the colors property, where we can then set our custom purple:

const customTheme = {
  ...theme,
  colors: {
    ...theme.colors,
    purple: '#692ba8'
  }
}

Note: you’ll see here that we’re also spreading theme.colors. If we don’t, we’ll be replacing the colors object with only the purple value, meaning we won’t have any other colors.

But if we reload the page, our link isn’t purple anymore!

Next.js link with no color

Chakra typically uses ranges of colors which allows us to use different shades of each of the colors. In our Link component, we’re specifying purple.500 which we didn’t set to exist.

So to fix that, we can use a tool like Smart Swatch to get all of our color values that we need and set those in our custom theme object:

const customTheme = {
  ...theme,
  colors: {
    ...theme.colors,
    purple: {
      50: '#f5e9ff',
      100: '#dac1f3',
      200: '#c098e7',
      300: '#a571dc',
      400: '#8c48d0',
      500: '#722fb7',
      600: '#59238f',
      700: '#3f1968',
      800: '#260f40',
      900: '#10031a',
    }
  }
}

Tip: Smart Swatch actually lets you copy those values as a JavaScript object, making it easier to paste into our theme!

And now if we reload the page, we can see our purple!

Next.js with custom purple

While we used a range value here, we can also specify color variables without a range.

Say I wanted to leave the default Chakra purple “as is” but provide a way for me to reference my purple.

To do that, I could remove those purple values and add a new custom variable:

const customTheme = {
  ...theme,
  colors: {
    ...theme.colors,
    spacejelly: '#692ba8'
  }
}

Then update my Link to use that color:

Welcome to <Link color="spacejelly" href="https://nextjs.org">Next.js!</Link>

And we can see that we’re now using our purple without overriding the original:

Next.js with custom color variable

We can apply this to most parts of the styles of Chakra, including Typography and setting custom Breakpoints. It’s another way to make our project custom to our own while still taking advantage of the power of Chakra!

Follow along with the commit!

What else can you do with Chakra UI?

While we went through some simpler examples, it really opens the door to more complex style changes and controls that Chakra provides with its component APIs.

There are also a whole lot of awesome components that you can use to transform your website or application and make development fast and easy!

They even provide recipes that have some examples of how you can combine the components resulting in powerful functionality. This includes a responsive header and even adding animations with Framer Motion.

But not everyone on the team will remember to run those commands every time they commit. How can we use Husky to add Git hooks to run them for us?

• What are Git Hooks?
• What is Husky?
• What are we going to build?
• Step 0: Setting up a new project
• Step 1: Installing Husky to a project
• Step 2: Configuring Husky to run Git hooks
• Step 3: Using Husky to format code with Prettier

What are Git Hooks?

Git hooks are scripts that you can set up to run at certain events in the Git lifecycle. These events include different stages of a commit, like before a commit (pre-commit) and after a commit (post-commit).

These are useful in that they allow developers to run custom code tasks or even enforce standards by automating other scripts to run those tasks.

What is Husky?

Husky is a tool that allows us to easily wrangle Git hooks and run the scripts we want at those stages.

It works by including an object right within our package.json file that configures Husky to run the scripts we specify. After that, Husky handles managing at which point in the Git lifecycle our scripts will run.

What are we going to build?

We’re going to set up a simple project that we can use to test out Git hooks.

While you should be able to follow along with any project that you’re working with, I’m going to use Next.js as the starting point for this project, simply for the fact that we can run a single command to get a project started.

One consideration about following along with this project, though, is that we’ll use Prettier as an example of what you can do with Git hooks.

Prettier is a tool that will automatically format our code for us, which if you’re not expecting that to happen, can cause a lot of stress. Following along with me using the Next.js project will allow you to test this out without making any unintentional changes.

As for testing the Git hooks, we’ll start by adding a simple command line statement to see Husky work. But we’ll also test out adding Prettier, which will automatically format our code for us.

Finally, at the time of writing this, Husky released an v5 Alpha version of their Git hook solution. Given it’s still just an Alpha version, we’re going to move forward with v4, which allows us to easily install Husky with npm.

Step 0: How to set up a new project

As I mentioned, you can really follow the same steps here with any project that’s managed with a package.json file.

Next.js is absolutely overkill for this walkthrough, but the goal is to minimize the steps for getting set up to actually work with Husky.

To get started with Next.js, navigate to the directory you want to start your project in and run the following:

yarn create next-app my-husky-project
# or
npx create-next-app my-husky-project

Note: feel free to replace my-husky-project to whatever you’d like to name your directory.

This will create a new folder, create a new Next.js project, and install all the dependencies.

Once it’s done, navigate to that new folder, and we should be ready to go!

Follow along with the commit.

Step 1: How to install Husky to a project

To install Husky, we can use yarn or npm.

yarn add husky
# or
npm install husky

Note: if installing Husky at this point installs v5, that means v5 has been officially released. Please see the updated Husky documentation or you can install the latest v4 version by specifying husky@4.3.0 (or whatever the latest version is) when installing.

Once the package is finished installing, we should be ready to go with Husky.

Follow along with the commit.

Step 2: How to configure Husky to run Git hooks

Next, we’re going to set up Husky so we can use it for our Git hooks.

Inside of our package.json file, create a new property called husky with an empty object.

"husky": {},

You can add this really wherever you want in the package.json file, but I’m going to add it right below the scripts property so I can more easily manage them together.

Inside of that, we want to add another property called hooks that also specifies an empty object:

"husky": {
  "hooks": {}
},

This is where we’re going to add our Git hooks. Husky supports pretty much all Git hooks defined by Git, so we can be as flexible we would like within our Git event flow.

To test this out, I created a new branch where I literally added every Git hook from that page including a script that simply writes to the terminal [Husky] event name.

Note: don’t feel like you need to do this unless you’re curious. The goal is to be able to show you with my example how it works.

“husky”: {
  “hooks”: {
    “applypatch-msg”: “echo \”[Husky] applypatch-msg\””,
    “pre-applypatch”: “echo \”[Husky] pre-applypatch\””,
    “post-applypatch”: “echo \”[Husky] post-applypatch\””,
    “pre-commit”: “echo \”[Husky] pre-commit\””,

What this will do is tell Husky that at every single stage where we’re permitted to hook into Git, tell us!

When I commit that change, we can immediately see that Husky fires off some of our scripts.

These are all of the events that Git allows us to hook into that happen during the commit process.

And similarly, if I push those changes out to Github, I can see that the push process runs the pre-push hook!

You may never use most of the hooks that Husky and Git provide (we only saw a few between those two commands).

But it’s awesome to be able to see how powerful this can be, whether it’s running code that formats our code, prevents secret access keys from being committed, or really anything else that can help automate important tasks to your workflow.

We can now see that we can configure Husky by specifying the configuration and the hooks right in our package.json.

Follow along with the commit.

Note: If you want to check out my branch that includes every Git hook to test with, you can find it on Github.

Step 3: How to use Husky to format code with Prettier

Finally, for a real-world use case, we’re going to test out using Prettier to automatically format our code.

Prettier is an opinionated code formatting tool that allows you to easily clean up your code to make it look like a single person wrote it.

Why are tools like Prettier important? When working through code, especially with a team, it’s important to maintain consistency so everyone knows what to expect. It will help prevent arguing over a semi-colon in a code review, but it will also help catch syntax errors and prevent bugs.

Warning: running Prettier will automatically format all of your code. While we’re going to test this out before committing the changes, once you apply this as a Git Hook, it will automate this process.

To get started with Prettier, let’s install it with our package manager:

yarn add prettier -D
# or
npm install prettier --save-dev

Note: we’re installing Prettier as a devDependency as our application doesn’t need this to run.

Next, we can add a new script in our package.json that will make it easier to run Prettier to test this out.

Inside the scripts property, add:

"lint": "prettier --check ."

For this first test, we’re going to run it as a “check” which will allow us to see which files would change.

Run the following:

yarn lint
# or 
npm run lint

And once we do, we can see that Prettier is telling us that would change the files listed.

At this point, our code will remain unchanged. But if we want to run Prettier for real to make those changes, we can first add an additional script:

"format": "prettier --write ."

And if we run that script, it will update all of those files to format the code to Prettier’s specification.

Warning: just another note, running Prettier to write the changes will make changes in your files. These are all code-style changes that shouldn’t impact how the code runs, but how the code looks. Before running format, you should save any changes by committing with Git so that you can easily revert the changes if you’re not happy with them.

You can now run the script with:

yarn format

And we can see that Prettier updated our files!

Now the part that’s relevant to this walkthrough: we can add this as a Git hook. This way, when someone tries to commit code, Prettier is run before the code is saved. This means that we’ll always keep code consistent with Prettier’s formatting style.

Inside our Husky hooks configuration, let’s add:

"husky": {
  "hooks": {
    "pre-commit": "prettier --write . && git add -A ."
  }
},

If you notice in our pre-commit hook, we’re also adding git add -A ..

When Husky runs, it simply runs the script provided. When running our Prettier command, we’re only formatting the code, but we never save those changes as part of the process. So we use git add to store all of those changes and include them in the commit.

To test this out, I reverted the changes to all of the files that were formatted before. If you’re following along with the same project, you can run:

git checkout pages

Which will reset all of the changes in pages to the last commit.

Now, let’s try to add all of our files with Git and commit the changes.

And once we run our commit command, we can see that the Husky pre-commit hook kicks in already and formats our code!

Follow along with the commit.

What can I do next?

Use lint-staged to only run formatting on changed files

We’re using Prettier right in our pre-commit hook and specifying . which means it’s going to run on all files every time.

We can use a tool called lint-staged, which allows us to still run our Git hooks with Husky, but it will only run on files that are staged.

For instance, if we wanted to do this with Husky and Prettier, our configuration might look like:

"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
},
"lint-staged": {
  "*": "prettier --write"
},

As part of how lint-staged runs, it will attach the changed files to the end of our Prettier statement automatically for us.

You’ll also notice we didn't include git add. lint-staged will also add any changes to Git for us automatically.

Set up a Prettier config to customize formatting rules

Prettier is very opinionated. There are some things I personally don’t prefer and you might feel the same.

Luckily, Prettier allows you to set up a configuration file that can override some of those files to make your code just the way you and your team want it.

Tell Prettier to ignore files with .prettierignore

You also probably don’t want Prettier running on “all the things” (maybe you do).

Prettier allows you to set up a .prettierignore file right inside of the root of the project next to package.json, similar to .gitignore, that allows you to tell Prettier what files it should not run on.

How can we add that interaction when building a React app with React Beautiful DnD?

• What is Drag and Drop?
• What is React Beautiful DnD?
• What are we going to build?
• Step 0: Creating a new React.js app
• Step 1: Installing React Beautiful DnD
• Step 2: Making a list draggable and droppable with React Beautiful DnD
• Step 3: Saving list order after reordering items with React Beautiful DnD

What is Drag and Drop?

Drag and drop is pretty much what it sounds like — it’s an interaction allowing someone to click and drag an item, then drop it somewhere else, often having a side effect within the app.

Moving items on a board

This effect is pretty common in applications like to-do lists or project management dashboard, where you need to prioritize and create an order for how things should be done.

While drag and drop can have some advanced use cases, we’ll stick to basic list functionality for our walkthrough.

What is React Beautiful DnD?

React Beautiful DnD is an accessible drag and drop library from Atlassian. If you don’t know of Atlassian, they’re the team behind Jira. If you’re not familiar with Jira, it’s probably the biggest Agile tool on the internet right now.

The team’s goals were to provide drag and drop capabilities with accessibility in mind, in addition to keeping it night and performant with a powerful API.

What are we going to build?

We’re going to start off with a simple list and add the ability to drag and drop.

In this walkthrough, we won’t spend time building the list itself. The list that we’ll be using uses a standard unordered list (<ul>) and list items (<li>) to create a list with a little bit of CSS to make it look like cards.

We’ll be focusing on adding the ability to drag and drop to rearrange the list using React Beautiful DnD.

Step 0: Creating a new React.js app

To get started, we want a simple app that includes a list of items. This can be an existing project or a brand new project using your favorite framework like Create React App.

I started with a new app using Create React app and I added a simple list of Final Space characters.

Final Space characters list

If you want to start from the same place, you can clone my demo repository at that branch and start right along with me.

This command will clone the specific branch to get started:

git clone --single-branch --branch part-0-starting-point git@github.com:colbyfayock/my-final-space-characters.git

Otherwise, you can clone the repository as normal and check out the branch part-0-starting-point.

If you want to follow along with just the code, I first created an array of objects:

const finalSpaceCharacters = [
  {
    id: 'gary',
    name: 'Gary Goodspeed',
    thumb: '/images/gary.png'
  },
  ...

And then I loop through them to create my list:

<ul className="characters">
  {finalSpaceCharacters.map(({id, name, thumb}) => {
    return (
      <li key={id}>
        <div className="characters-thumb">
          <img src={thumb} alt={`${name} Thumb`} />
        </div>
        <p>
          { name }
        </p>
      </li>
    );
  })}
</ul>

Follow along with the commit!

Step 1: Installing React Beautiful DnD

First step is to install the library via npm.

Inside of your project, run the following:

yarn add react-beautiful-dnd
# or
npm install react-beautiful-dnd --save

This will add the library to our project and we’ll be ready to use it in our app.

Step 2: Making a list draggable and droppable with React Beautiful DnD

With our library installed, we can give our list the ability to drag and drop.

Adding Drag and Drop context to our app

At the top of the file, import DragDropContext from the library with:

import { DragDropContext } from 'react-beautiful-dnd';

DragDropContext is going to give our app the ability to use the library. It works similarly to React’s Context API, where the library can now have access to the component tree.

Note: If you plan on adding drag and drop to more than one list, you need to make sure that your DragDropContext wraps all of those items, like at the root of your application. You can not nest DragDropContext.

We’ll want to wrap our list with DragDropContext:

<DragDropContext>
  <ul className="characters">
  ...
</DragDropContext>

At this point, nothing will have changed with the app and it should still load as it did before.

Making our list a Droppable area

Next, we want to create a Droppable area, meaning, this will allow us to provide a specific area where our items can be moved around inside.

First, add Droppable to our import at the top of the file:

import { DragDropContext, Droppable } from 'react-beautiful-dnd';

For our purpose, we want our entire unordered list (<ul>) to be our drop zone, so we’ll again want to wrap it with this component:

<DragDropContext>
  <Droppable droppableId="characters">
    {(provided) => (
      <ul className="characters">
        ...
      </ul>
    )}
  </Droppable>
</DragDropContext>

You’ll notice we wrapped it a bit differently this time though. First, we set a droppableId on our <Droppable> component. This allows the library to keep track of this specific instance between interactions.

We’re also creating a function immediately inside of that component that passes in the provided argument.

Note: This function can pass in two arguments including a snapshot argument, but we won’t be using it in this example.

The provided argument include information and references to code that the library needs to work properly.

To use it, on our list element, let’s add:

<ul className="characters" {...provided.droppableProps} ref={provided.innerRef}>

This is going to create a reference (provided.innerRef) for the library to access the list element’s HTML element. It also applies props to the element (provided.droppableProps) that allows the library to keep track of movements and positioning.

Again, at this point, there won’t be any noticeable functionality.

Making our items Draggable

Now for the fun part!

The final piece of making our list elements draggable and droppable is wrapping each list item with a component similar to what we just did with the entire list.

We’ll be using the Draggable component, which again, similar to the Droppable component, will include a function where we’ll pass through props to our list item components.

First, we need to import Draggable along with the rest of the components.

import { DragDropContext, Droppable, Draggable } from 'react-beautiful-dnd';

Next, inside of our loop, let’s wrap the returning list item with the <Draggable /> component and it’s top level function.

{finalSpaceCharacters.map(({id, name, thumb}) => {
  return (
    <Draggable>
      {(provided) => (
        <li key={id}>
          ...
        </li>
      )}
    </Draggable>

Because we now have a new top level component in our loop, let’s move the key prop from the list element to Draggable:

{finalSpaceCharacters.map(({id, name, thumb}) => {
  return (
    <Draggable key={id}>
      {(provided) => (
        <li>

We also need to set two addition props on <Draggable>, a draggableId and an index.

We’ll want to add index as an argument into our map function and then include those props on our component:

{finalSpaceCharacters.map(({id, name, thumb}, index) => {
  return (
    <Draggable key={id} draggableId={id} index={index}>

Finally, we need to set some props on the list element itself.

On our list element, add this ref and spread additional props from the provided argument:

<Draggable key={id} draggableId={id} index={index}>
  {(provided) => (
    <li ref={provided.innerRef} {...provided.draggableProps} {...provided.dragHandleProps}>

Now, if we refresh our page, and hover over our list items, we can now drag them around!

Dragging items on a list

However, you’ll notice that when you start moving an item around, the bottom of the page appears to be a little messed up. There’s some overflow issues with our list items and our footer.

You’ll also notice that in the developer console, React Beautiful DnD is giving us a warning message that we’re missing something called a placeholder.

Console warning - placeholder could not be found

Adding a placeholder from React Beautiful DnD

Part of React Beautiful DnD’s requirements is that we additionally include a placeholder item.

This is something that they provide out of the box, but this is used to fill up the space that the item we’re dragging previously took.

To add that, we want to include provided.placeholder at the bottom of our Droppable top level list component, in our case at the bottom of the <ul>:

<Droppable droppableId="characters">
  {(provided) => (
    <ul className="characters" {...provided.droppableProps} ref={provided.innerRef}>
      ...
      {provided.placeholder}
    </ul>
  )}
</Droppable>

And if we start dragging things around in our browser, we can see that our page flow doesn’t have issues and the content stays where it should!

Dragging items with fixed spacing

The last issue though, is when you move something around, it doesn’t stay, so how can we save the order of our items?

Follow along with the commit!

Step 3: Saving list order after reordering items with React Beautiful DnD

When we move our items, they stay where they land for a split second. But after React Beautiful DnD finishes doing its work, our component tree will rerender.

When the components rerender, our items go back to the same place that they were before, because we never saved that outside of DnD’s memory.

To resolve this, DragDropContext takes in an onDragEnd prop that will allow us to fire a function after dragging has complete. That function passes in arguments that includes the new order of our items so that we can update our state for the next render cycle.

Saving our list items in state

First, let’s store our items in state so that we’ll have something to update between cycles.

At the top of the file, add useState to the React import:

import React, { useState } from 'react';

Then, we’re going to create our state using our default list of items.

Add the following to the top of our App component:

const [characters, updateCharacters] = useState(finalSpaceCharacters);

Because we’ll be updating our new characters state to provide our list items and their order, we’ll now want to replace the array we’re mapping through to our new state:

<ul className="characters" {...provided.droppableProps} ref={provided.innerRef}>
  {characters(({id, name, thumb}, index) => {

And if we save and refresh our page, nothing should change!

Updating state when dragging items

Now that we have our state, we can update that state any time our list items are dragged.

The DragDropContext component that we added to our page takes in a prop onDragEnd. Like it sounds, that will fire a function whenever someone stops dragging an item in the list.

Let’s add a function handleOnDragEnd as our prop:

<DragDropContext onDragEnd={handleOnDragEnd}>

Next, we need that function to actually exist.

We can define a function under our state:

function handleOnDragEnd(result) {
}

Our function takes an argument called result.

If we add console.log(result) to the function and move an item in our list, we can see that it includes details about what should be the updated state after our move action.

Dragged item result

Particularly, we want to use the index value in both the destination and source properties, which tell us the index of the item being moved and what the new index of that item should be in the array of items.

So using that, let’s add the following to our function:

const items = Array.from(characters);
const [reorderedItem] = items.splice(result.source.index, 1);
items.splice(result.destination.index, 0, reorderedItem);

updateCharacters(items);

Here’s what we’re doing:

• We create a new copy of our characters array
• We use the source.index value to find our item from our new array and remove it using the splice method
• That result is destructured, so we end up with a new object of reorderedItem that is our dragged item
• We then use our destination.inddex to add that item back into the array, but at it’s new location, again using splice
• Finally, we update our characters state using the updateCharacters function

And now after saving our function, we can move our characters around, and they save their location!

Drag item with saved state

Preventing errors from dragging out of bounds

One issue with our implementation, is if someone doesn’t drag the item exactly within our defined containers, we get an error.

Error when dragging out of container

The issue is that when we drag it outside of the defined container, we don’t have a destination.

To avoid this, we can simply add a statement above the code that moves our item around that checks if the destination exists, and if it doesn’t, exits out of the function:

function handleOnDragEnd(result) {
  if (!result.destination) return;

And if we reload the page and try to drag our item out again, our item snaps back to the original location without an error!

Snap back when dragged out of container

Follow along with the commit!

What else can we do with React Beautiful DnD?

Custom styles when dragging and dropping

When moving items, DnD will provide a snapshot of the given state. With this information, we can apply custom styles so that when we’re moving our items, we can show an active state for the list, the item we’re moving, or both!

https://react-beautiful-dnd.netlify.app/?path=/story/single-vertical-list--basic

Dragging between different lists

If you’ve used Trello before or a tool like it, you should be familiar with the concept of different columns that you can drag cards between so that you can prioritize and organize your tasks and ideas.

This library allows you to do the same thing, providing the ability to drag and drop items from one draggable area to another.

https://react-beautiful-dnd.netlify.app/?path=/story/multiple-vertical-lists--stress-test

How can we add icons using SVG to our React apps to improve our visual communication?

• What is SVG?
• What makes SVG great for the web?
• Part 0: Creating a React app
• Part 1: Adding SVG icons with react-icons
• Part 2: Manually adding SVG files to a React component

What is SVG?

SVG stands for Scalable Vector Graphics. It’s a file format based on a markup language similar to XML that allows developers and designers to create vector-based images using path definitions.

What makes SVG great for the web?

SVG was born for the web. It’s an open standard that was created by W3C to provide a better way to add images to the web. If you open an SVG file on your computer, you might be surprised to find that it’s all code!

This plays a part in the small file size. Typically when using SVG, you can take advantage of its smaller size compared to larger image files that might be required to deliver the same high resolution.

Additionally, since we’re defining SVG as paths, they can scale as large or as small as we want. This makes them extra flexible for web usage, especially when making experiences responsive.

What are we going to create?

We’re first going to walk through using a package called react-icons that will allow us to easily import icons from popular icon sets like Font Awesome right into our app.

We’ll also take a look at how we can manually add SVG files right into our app by copying the code of an SVG file right into a new component.

Part 0: Creating a React app

For this walkthrough, you can use any React framework you’d like whether that’s Create React App or Next.js. You can even use an existing project.

Because we don’t need anything special to add our icons, I’m going to use create-react-app.

To get started with create-react-app, you can create a new project using the following command in your terminal:

yarn create react-app [project-name]
# or
npx create-react-app [project-name]

Note: replace [project-name] with the name you want to use for your project. I’m going to use my-svg-icons.

Once you have your new app or your existing app, we should be ready to go!

New Create React App

Part 1: Adding SVG icons with react-icons

Adding react-icons to your project

To get started with react-icons, we want to install it in our project.

Inside of your project, run the following command:

yarn add react-icons
# or
npm install react-icons --save

Once it’s completed, we should be ready to use it in our project.

Selecting icons for a project

One of the cool things about react-icons is the extensive library they make available within the single package.

Not only do we have Font Awesome immediately available, we have GitHub’s Octicons, Heroicons, Material Design Icons, and a whole bunch more.

react-icons Heroicons

When choosing icons, you pretty much have the ability to use any icon you want at any time. That said, I would recommend trying to keep a consistent look and feel with your icons.

If you primarily use Font Awesome for your website, it might look a bit strange and inconsistent if you were to start adding Flat Color Icons to the mix. You ultimately want to provide an experience that people will be able to easily identify the patterns that you create.

Using react-icons in your project

Once you’ve found the icons you want to use, we can now add them to our project.

react-icons’s website makes it easy for us to look up the name of the icon we want to use to import to our project.

If we wanted to use the Font Awesome rocket icon, we can navigate to Font Awesome in the sidebar, search the page for “rocket” (CMD+F or CTRL+F), and then click the icon which will copy its name to your clipboard.

Font Awesome rocket icon

We could also search for “rocket” in the search form at the top left of the page, which shows us the result “rocket” throughout all icon sets.

Rocket icons in react-icons

Inside of our project, we can now import that icon. Similar to the instructions at the top of the react-icons page, we want to import that specific icon from the react-icons/fa, which refers to the Font Awesome module of react-icons.

Add the following to the top of the file you want to import the icon in. If using a new create-react-app project, you can add it to the top of src/App.js.

import { FaRocket } from 'react-icons/fa';

To test this out, let’s replace the React logo with our icon.

Remove the <img component and instead add:

<FaRocket />

And if we reload the page, we can see our rocket!

Rocket icon in React app

Our rocket isn’t spinning like the React logo though, so let’s fix that.

Add the class .App-logo to the FaRocket component:

<FaRocket className="App-logo" />

And the rocket should now be spinning!

Spinning rocket icon in React app

But it’s also a little small. If we look inside of src/App.css, we’re setting the height of .App-logo to 40vmin. While that’s working, for our icon to fill the space, we need to also provide a width for it to fill.

Add the following to the .App-logo class to add a width:

width: 40vmin;

And while it’s probably a little too big now, we’re at a more appropriate size and we have our icon!

Increased size of spinning rocket icon in React app

Follow along with the commit.

Part 2: Manually adding SVG files to a React component

Sometimes you don’t want to add a new library just to get an icon. Sometimes it’s a custom icon that’s not available in a public library.

Luckily with React, we can create a new SVG component pretty easily that allows us to add our custom SVG icons anywhere we want.

First, let’s find an icon.

While all Heroicons are available inside react-icons, let’s use it as an example since it’s easy to find and copy some SVG code.

Go to heroicons.com and search for an icon that you’d like to use for this example. I’m going to use “globe”.

After finding the icon you want, hover over that icon, where you’ll see options to copy that icon as SVG or JSX, and copy it as JSX.

Copy as JSX in Heroicons

With that icon copied, create a new file under src called Globe.js.

Inside of that file, we’re going to create a new component called Globe and paste in our SVG within that component.

import React from 'react';

const Globe = () => {
  return (
    <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3.055 11H5a2 2 0 012 2v1a2 2 0 002 2 2 2 0 012 2v2.945M8 3.935V5.5A2.5 2.5 0 0010.5 8h.5a2 2 0 012 2 2 2 0 104 0 2 2 0 012-2h1.064M15 20.488V18a2 2 0 012-2h3.064M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
    </svg>
  )
}

export default Globe;

Note: when copying normal SVG to a React component, it might not work "as is". Sometimes SVG files include CSS classes or element attributes that aren't valid with JSX.

If you run into errors, try fixing the attributes and looking at the web console to see the warnings and errors React throws. Because we copied as JSX, we were able to make it work right away.

Now, go back to src/App.js and import our new component:

import Globe from './Globe';

Then we can replace our rocket icon with our new component:

<Globe />

And if we open up our browser, we can see our globe!

Large globe icon in REact app

Though, it’s a little big.

We want to apply our .App-logo class to our Globe component, so we need to update that component to take a className prop.

Back at src/Globe.js, add a className prop argument:

const Globe = ({ className }) => {

Then, add a new prop with that className to the <svg component:

<svg className={className}

Now, we can update our Globe component in src/App.js to include that class:

<Globe className="App-logo" />

And if we reload the page, we can see our logo is back at the right size and it’s spinning again!

Spinning, normal size globe icon in React app

Follow along with the commit.

Why don’t we include it as an img file?

While we can include it as an image file just like React does in the default create-react-app code, we get a few benefits from adding our SVG files “inline”.

For one, when adding SVG inline, we can access the different paths with CSS properties. This gives us more flexibility for customizing it dynamically.

It’s also going to provide fewer HTTP requests. The browser will know how to load that SVG, so we don’t need to bother the browser to request that file to include in the page.

That said, it’s still a valid option for adding an SVG file to the page.

How can we leverage the web framework Next.js and hosting platform Vercel to build and deploy performant and reliable web apps?

Note: This is a preview of my Jamstack Handbook, a guide to everything you need to know about the Jamstack. It has 3 tutorials, including this one. Get your copy and learn how to build fast, dynamic apps with JavaScript and the static web.

• What will we build?
• Step 1: Getting started with a Next.JS React app
• Step 2: Setting up the project with Git
• Step 3: Deploying Next.js with Vercel
• What did we just deploy?
• Understanding modern CI / CD with Git
• Make a change and watch it automatically deploy
• What did we learn?

Next.js is a web framework that’s built and maintained by Vercel. Next.js makes it easy to spin up a new React application and provides a ton of features out of the box like server side rendering (SSR) and static site generation (SSG).

What will we build?

Our project itself will be relatively simple. We’re going to use the default Next.js Starter as a way to easily bootstrap the project, learn how to configure Next.js to statically compile, and then deploy that project with our customizations to Vercel.

A Starter is a template that allows developers to recreate that template from the command line. When installing the starter, the framework will set up the project and install all dependencies.

Step 1: Getting started with a Next.JS React app

To get started, we first want to navigate to the directory we want to create our project in.

We’ll use a Starter to create our project. To do this, we have two options for a package manager to use: yarn or npm. You can choose whichever you feel more comfortable with for the remainder of the walkthrough.

yarn create next-app
# or
npx create-next-app

Creating a new Next.js app

When running this command, Next.js will first ask you for a project name. Here we can use any name we want to identify the project. I’m going to use my-nextjs-app.

Naming a Next.js project

Once installation is finished, we’re now ready to get started with Next.js.

Navigate in your terminal to the new directory where your project is located and run:

yarn dev
# or
npm run dev

This will start your development server, which will make your new site available at http://localhost:3000.

Starting Next.js development server

If you open up your http://localhost:3000 address, you should now see the Next.js default project!

New Next.js app

Step 2: Setting up the project with Git

You'll want to set this next step up on your own. Create a new repository with your favorite Git provider that’s supported by Vercel.

At the time of writing this, Vercel supports GitHub, Gitlab, and Bitbucket.

If you’re choosing a provider for the first time, GitHub is a solid option and is easy to get started.

You’ll then want to add your project to that new repository and push the project up to Git.

Need help? Check out “Adding an existing project to GitHub using the command line” https://docs.github.com/en/github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line

For the rest of this walkthrough, I’ll be referencing GitHub, but the instructions should be the same for any supported provider.

Next.js app on GitHub

Step 3: Deploying Next.js with Vercel

Once your project is set up with GitHub, navigate to vercel.com and log in.

If you don’t already have a Vercel account, you should create one now. I would recommend creating an account with your GitHub account as it will help you import your project.

Inside the Vercel dashboard, click Import Project.

Import project to Vercel

Next, under Import Git Repository, click Continue.

Import Git repository to Vercel

Vercel will now ask for the repository URL. This will be the homepage for the repository you just created for your project.

Add Git repo URL to Vercel

After you click Continue, Vercel has already detected that your project uses Next.js. This means that we don’t need to set up and custom configurations, and we can hit Deploy!

Deploy Next.js project to Vercel

At this point, Vercel will get to work and start to build the new project and deploy it to their infrastructure.

Once it’s finished, it will congratulate you and give you a link to visit your site.

Vercel project successfully deployed

Click Visit and you’ll be directed to your project live on the internet:

Next.js app live

What did we just deploy?

We just created a new React app with Next.js and deployed it to Vercel.

We’ll walk through each specific step:

• Create Next App: We first created a new Next.js project on our computer. This provided us with a new React application complete with dependencies and code to get started with a basic website.
• Add Project to Git: We added our new Next.js project to a Git repository online that’s supported by Vercel. This allows us to easily interface with the project with other services like Vercel.
• Connect Git to Vercel: We imported our project from Git into Vercel. This allowed Vercel to interact with our code.
• Build & Deploy with Vercel: Vercel downloaded our code, was able to recognize it was a Next.js project, built our project, and deployed the compiled output to its infrastructure and made it available on the web.

If you were waiting for more steps to get your project out to the world, there are none! The entry point for publishing a new React project is now lower than it’s ever been and Next.js and Vercel are helping you get there.

Understanding modern CI / CD with Git

Another benefit of modern infrastructure providers like Vercel, is that when utilizing GitHub as a service connection, Vercel can watch for changes on our main branch.

Once Vercel recognizes that a change was made, it will download the latest code and re-run the same process as we did the first time (aside from any caching and optimization).

This means that any time we have new changes to our production branch, they’ll automatically be deployed.

Make a change and watch it automatically deploy

To test out the automatic deployments, let’s make a change to our project.

Inside our project, let’s make a change to some of the page content inside of pages/index.js. I’m going to change the title to “Colby’s Next.js Project”.

<h1 className={styles.title}>
  Colby's Next.js App
</h1>

Next.js app with change

Next, commit this change to your main Git branch and push it up to GitHub.

If you wait a few seconds and navigate back to vercel.com, find your project and click on the Deployments tab.

Vercel deployment when change detected

You’ll see that your project is now running or might have already finished if you weren’t quick enough. Now if you open your website link again, you’ll see the changes deployed!

Deployed changed Next.js app to Vercel

What did we learn?

Next.js is a web framework that allows us to quickly and easily spin up a new React application.

This, along with other similar frameworks, can be useful to get immediately productive instead of spending time building the project framework ourselves.

Vercel is a hosting and deployment platform that allows us to integrate with our favorite supported Git provider. Once connected, Vercel will download our project, build our project, and deploy the output to the internet.

Modern infrastructure tools like Vercel will watch for changes on our Git repository and will build and deploy our project so that we’re always seeing the latest version.

Learn more about the Jamstack!

You can learn more about the Jamstack, including 2 more in depth tutorials, with my Jamstack Handbook.

Order at jamstackhandbook.com

How can Iconset help take away the pain and get us more productive?

• What is SVG?
• What is Iconset?
• What are we going to learn?
• Part 1: Getting started with Iconset
• Part 2: Adding icons to Iconset
• Part 3: Using Iconset with design software like Figma
• Part 4: Using Iconset in development like with React
• Part 5: Syncing Iconset across multiple computers with Dropbox

What is SVG?

SVG is a nearly 20 year old image file format. And while it’s been around for a while, it has only recently been gaining momentum in the development community.

SVG is great for a number of reasons. First of all, it’s a vector format, meaning it scales as big or small as you want.

But it’s also flexible in that you can use SVG right in your development project with a typically small file size and infinite scale. You can even animate it!

But trying to collect and organize a bunch of files can be challenging. What do you name them? Do you have a computer that can easily preview them? What about search?

What is Iconset?

Iconset is a free cross-platform tool that allows you to collect and manage all of your SVG files in one place.

Iconset library

Love to quickly move between Font Awesome and heroicons but don’t want to keep switching libraries? You can use Iconset to make a quick search and drag it right into your project.

If you’re planning on using it for a React project, you can even copy the file as JSX and dump it right into your project!

Iconset "Copy As"

What are we going to learn?

We’re going to walk through a few different scenarios that'll show us how Iconset is useful.

We’re also going to walk through how you can easily manage Iconset between different computers or environments so you can have the same great library anywhere you work.

Part 1: Getting started with Iconset

To get started, you’ll need to first install Iconset locally. It should be a similar installation process as any other application.

Iconset with no icons

Once it’s ready and available locally, you should be able to open it up and see a UI with No Icons, which is expected, as it doesn’t come with any icons out of the box.

Part 2: Adding icons to Iconset

Adding icons to Iconset is as easy as dragging in, but you have a few options during the process.

To get started, let’s download the free icon set heroicons.

Download at: https://heroicons.com/.

On the heroicons website, you should see a big Download all button, which will download a zip file including all of the files.

Downloading heroicons

If you navigate to the optimized folder, you’ll see that there are two different versions: solid and outline.

Now to get these into Iconset, select each folder individually and drag it right into Iconset.

Dragging heroicons into Iconset

Once there, you have a few options.

• Set: Since this is our first set, you’ll automatically be creating a new one. If you had existing sets, you could import into those sets.
• Set Name: Here we can name the set something that we’ll remember. For this, I recommend naming it “heroicons - Outline”.
• Import Options: these are optional settings, but I typically select the optimize and clean option to make sure any icons are immediately ready to get working with.

Iconset with heroicons set

And once you click Import, it will do it’s thing, and you’ll now have your first set of icons in Iconset!

You can go ahead and do the same thing with the solid directory so then we’ll now have our two sets ready to go.

Iconset with Outling and Solid sets of heroicons

At this point, you can use Iconset to search through your icons and see all of your files currently available in your collection.

Part 3: Using Iconset with design software like Figma

The great thing about Iconset is how easy it is to use it with design software like Figma.

If I wanted to add an envelope icon to my website so people could contact me, I could search for the mail icon, and simply drag it onto my canvas:

Dragging mail icon into Figma

I can then treat it like any other vector design element and immediately use it in my project.

SVG Mail icon in Figma

Part 4: Using Iconset in development like with React

Another cool thing is how easy it is to use in a project like React.

Out of the box, you get a few different ways you can copy the file and use it in development like copying it as JSX.

Next.js Sass Starter

If I feel like my Next.js Sass Starter could use some icons on the page, I can right-click any icon I want and under Copy As select JSX I can paste it right into my project!

Copying icon from Iconset as JSX

And while it will need some styling once you drop it in just like any other image or icon, it’s immediately ready to go.

Using icon JSX in Next.js React app

Part 5: Syncing Iconset across multiple computers with Dropbox

With Iconset, you have the ability to switch between different libraries. But importantly, you can also set the location of your library.

When Iconset creates your library, it stores everything as files and a database on your computer.

Iconset library folder

And inside the Iconset UI, we can both Move and Switch the location we use.

Iconset library settings

If this is your first time setting up Iconset, you can start by clicking Move and then selecting the location you want to sync it to.

Moving Iconset library location

And once you click Move, it will move it to that directory, like a folder on Dropbox, and sync to the cloud like any other folder and file.

Syncing Iconset library with Dropbox

Alternatively, if you already have a shared Iconset library or if you’re setting this up on a new computer, you can use the Switch option, and select that option right from Dropbox.

Switching Iconset location

And once you hit Switch, you’ll now load up your shared library and be ready to get productive.

Iconset with full library

What else can you do?

Publish and share icon sets

Another cool feature is that you can export sets and share them. If you’ve spent a lot of time on a collection and want to share it with others, export it, publish it, and share it with the community!

More organization

Iconset also supports features like Folders and Favorites. This makes it even easier to group and collect the icons however it makes sense to you to keep you productive.

It also supports tagging, making it even easier to search.

But accepting form submissions usually requires an additional service or complex server-side code. How can we take advantage of Netlify to easily create new forms?

• What is Netlify?
• What are we going to build?
• How much does this cost?
• Part 1: Creating a contact form with HTML
• Part 2: Adding a custom Netlify form to a Next.js React app

What is Netlify?

Netlify is a web platform that lets you easily deploy new web projects with easy to configure workflows. This includes deploying a static website, lambda functions, and like we’ll talk about here, custom forms.

Their form service works as part of the build and deployment pipeline. When we include a form with a specific attribute to our page, Netlify will recognize that form and configure it to work.

What are we going to build?

We’re going to build a contact form that will allow people to send you a note through your website.

The form itself will be pretty simple. Like a standard contact form, we'll ask for someone's name, email address, and a message.

We’re going to build this out using plain HTML to demonstrate how it works and then build it with Next.js for creating a form in a React app.

How much does this cost?

Netlify forms are free to get started. This free tier is limited to 100 form submissions per website per month, so if you stay under that, it will always be free.

That said, if you exceed 100 form submission on any particular site, the first tier is going to be $19+ at the time of writing this. You can check out the latest pricing plans on Netlify’s website.

Part 1: Creating a contact form with HTML

To get started, we’re going to create a basic form with pure HTML. It’s a quick win to demonstrate how this works.

Step 1: Creating an HTML form

For our form, we can really use whatever we want. Contact forms can be as simple as an email address and a message field or it include a variety of options to help a business answer specific questions.

We’re going to start with something simple. We’ll create a form that asks for someone’s name, email address, and a message.

To get started, create a new HTML file in the root of your project. This HTML file should include the basic structure of an HTML document. Inside of the body, let’s add our new form:

<form name="contact" method="POST" data-netlify="true">
    <p>
      <label for="name">Name</label>
      <input type="text" id="name" name="name" />
    </p>
    <p>
      <label for="email">Email</label>
      <input type="text" id="email" name="email" />
    </p>
    <p>
      <label for="message">Message</label>
      <textarea id="message" name="message"></textarea>
    </p>
    <p>
      <button type="submit">Send</button>
    </p>
  </form>

In the snippet above, we’re:

• Creating a new form
• The form has a name attribute, a method, and a data-netlify attribute set to true
• Creating 3 form fields with labels, each identified with a name attribute
• Creating a button to submit the form

The thing we want to take most notice of is the data-netlify attribute and the form name. When Netlify reads the site, it will see those fields and use those to turn your form into an actively working form.

I’m also going to add a little bit of CSS to make the labels look a little more consistent. You can optionally add this to the <head> of the document:

<style>
  body {
    font-family: sans-serif;
  }
  label {
    display: block;
    margin-bottom: .2em;
  }
</style>

And at this point, we should have a basic form!

Basic HTML form

You’ll now want to put this form on GitHub or your favorite Netlify-supported Git provider and we’ll be ready for the next step.

Follow along with the commit!

Step 2: Configuring a new form with Netlify

Once our form is pushed to our Git provider, we can now sync it up with Netlify.

First create an account or use an existing account with Netlify and click the New site from Git button.

Here, select whichever Git provider you used. I'm using GitHub in my example.

Connecting a Git provider in Netlify

Once selecting your Git provider, it will ask you to authorize access so that Netlify can find your Git repository.

After you successfully connect your account, you should now see a list of the repositories you provided access to. Find the repository you added your form to and select it.

Connecting a Git repository to Netlify

If you’re following along with me, our form is pure HTML, meaning, there should be no build steps or no special directory it gets published to. But feel free to tweak these settings if you did something different.

Configuring the build steps in Netlify

Now, click Deploy site which will open up a new page in Netlify and in no time your site will be successfully deployed.

Finally, click the URL at the top of the Netlify project dashboard that ends in netlify.app. Once it's loaded, you’ll see your form!

Step 3: Viewing form submissions

Now that we have our form, we ultimately want to see responses.

To get started, add some information to your form and click submit.

Testing HTML form

Once you submit, you’ll notice you get taken to a Netlify page that says the form was successfully submitted.

You can now go back to your Netlify project dashboard and scroll down a little bit where you can now see a box with Recent form submissions as well as your new submission.

Netlify Form submission

Part 2: Adding a custom Netlify form to a Next.js React app

If the form is going to live by itself and not be part of a bigger site, there are a lot of advantages to leaving your form as pure HTML. But often, we want our contact form to be part of our website or app.

Here we’ll walk through adding a form to a Next.js app.

Note: our demo of using Next.js is a statically rendered app. If you’re loading your form client side, meaning the underlying HTML doesn’t include the form, check out the notes at the bottom of this page for more information on solutions.

Step 0: Creating a Next.js app

To start off, we need an app. We’re going to use Next.js since we can pretty easily spin up a new app from scratch.

To do this, you can navigate to where you want to create the app and run:

yarn create next-app [project-name]
# or
npx create-next-app [project-name]

I’m going to name my project my-nextjs-netlify-form.

Once Next.js finishes installing dependencies, it’ll give you instructions to navigate to your project directory and start your development server.

And after you run yarn dev or npm run dev, you should be ready to go with your Next.js app:

New Next.js app

Follow along with the commit!

Step 1: Adding an HTML form to a Next.js app

Our Step 1 is going to look very similar to Part 1.

Inside of pages/index.js, we want to find our grid wrapper and we’ll use that to add our form.

Find <div className={styles.grid}> and replace the entire block with the following:

<div className={styles.grid}>
  <div className={styles.card}>
    <form name="contact" method="POST" data-netlify="true">
      <p>
        <label htmlFor="name">Name</label>
        <input type="text" id="name" name="name" />
      </p>
      <p>
        <label htmlFor="email">Email</label>
        <input type="text" id="email" name="email" />
      </p>
      <p>
        <label htmlFor="message">Message</label>
        <textarea id="message" name="message"></textarea>
      </p>
      <p>
        <button type="submit">Send</button>
      </p>
    </form>
  </div>
</div>

Here’s what we’re doing:

• We’re taking advantage of the existing grid from Next.js
• We’re also taking advantage of the existing card that we’ll include our form in
• Inside of the card, we’re pasting in the exact same HTML form as Part 1

If we reload the page, we can now see our form inside of a card, like this:

Adding a form to a Next.js app

Now before we move on, we want to do 2 things.

First, because we’re creating this form in a JavaScript app, Netlify recommends that we add a hidden input with our form name.

Inside of our form, add the following input at the top of the form element:

<input type="hidden" name="form-name" value="contact" />

Make sure the value of that input is the same as your form’s name.

Second, because the card that we’re reusing is intended for a list of links, Next.js includes some hover effects. This makes the form confusing to use, so let’s remove those

Remove the following from styles/Home.module.css:

.card:hover,
.card:focus,
.card:active {
  color: #0070f3;
  border-color: #0070f3;
}

For an extra bonus step, I’m going to update my page title to “Contact Me” and remove the description. Feel free to make this whatever you want.

Updating the form title

And once you’re ready, similar to before, add this as a new repository to GitHub or your favorite Git provider.

Follow along with the commit!

Step 2: Setting up and deploying your Next.js app to Netlify

Deploying our app to Netlify will look pretty similar, but before we get there, we need to set up our Next.js app to be able to export on build.

In our Next.js app, inside of the package.json file, we want to update the build script to:

"build": "next build && next export",

Now when you run the build script, it will compile the app to static HTML, CSS, and JS inside of the out directory. This will let us deploy it to Netlify. You can even try it locally on your machine if you want.

With that change, commit that and push it out to your Git provider.

Next, deploying the app will mostly look similar to Part 1. The only difference is because we have a Next.js app, we need to add our build steps.

To get started, we’ll want to connect our Git provider just like in Part 1.

Once we get to the Deploy Settings page, we want to configure our Build command and our Publish directory.

Our Build command will be yarn build or npm run build depending on what package manager you used and the Publish directory will be out.

Deploy settings for a static Next.js app

After that, click Deploy site, and it will kick off just like before.

Once it’s finished deploying, we’ll now be ready to open the app.

Successfully deployed Next.js app on Netlify

And once we open up our app we can test our form by filling it out and hitting submit.

Similar to before, we’ll land on a Netlify success page. But if we go back and look inside of our Netlify dashboard, we’ll now see our submission!

Succesful Next.js form submission on Netlify

Follow along with the commit!

Bonus: Keep people on your website with a success message

Another cool feature with Netlify forms is that it allows you to set up your form to keep people on your website by configuring the form right on the page.

You have a lot of options here, whether it’s redirecting someone to a new page or configuring messaging on the page they submitted from.

For this demo, we’re going to set up a URL parameter that we can detect to show a success message if we see that parameter.

To do this, on your HTML form, add the following attribute:

action="/?success=true"

This will tell Netlify we want to stay on the homepage (since we only have one page) but apply the URL parameter so we can detect it in our app.

Next, we can use the useState and useEffect hooks to see this parameter and update the page.

At the top of the file, let’s import these hooks:

import { useState, useEffect } from 'react';

Inside of our Home component at the top, let’s add our state:

const [success, setSuccess] = useState(false);

And to detect the URL parameter, we can use the useEffect hook:

useEffect(() => {
  if ( window.location.search.includes('success=true') ) {
    setSuccess(true);
  }
}, []);

Note: this is a simple way of achieving this result for the demo. If you have a more complicated app, you might want to name the parameter something more logical and properly parse the URL parameters for the value.

What this is doing, is when the component renders, it will fire this useEffect hook, checking the parameters in the URL, and looking for success=true. If it finds it, it will update our success state variable to true!

Next, under our page title (<h1>), let’s add the following snippet:

{success && (
  <p style={{ color: 'green'}}>
    Successfully submitted form!
  </p>
)}

Here we’re looking to see if success is true, and if it its, we include a line of text that says the form was successfully submitted.

While you can’t submit your form locally, you can test this out by visiting your app running locally with the ?success=true URL parameter like:

http://localhost:3000/?success=true

Testing success message locally

Finally, you can push these changes out to your Git provider and Netlify will automatically rebuild your site.

And once it’s finished, you can submit your form like before and see the success message.

Successful form redirect on Netlify

And see that our form is still submitting!

Successful form submission on Netlify

Follow along with the commit!

Netlify forms and client-side code

One thing to take note of with Netlify’s solution is this only works this “simply” for static HTML pages.

If your page uses JavaScript to manage the content of that page, such as not adding a form until after the page loads, you’ll need to check out Netlify’s documentation on how you can make this work with an additional form attribute.

Netlify also gives an example on how you can submit your form dynamically with JavaScript so you can create a custom experience in your app.

What else can you do?

Setting up advanced workflows with other tools

Netlify lets you integrate with other tools to allow you to wrangle your form submissions. Notably, Netlify works with Zapier, meaning you can accept incoming submissions and do whatever you want with them.

https://docs.netlify.com/forms/notifications/

Preventing spam with reCAPTCHA

Spam is also a real thing. You don’t want your inbox flooded with spam, so you can take advantage of Netlify’s built-in Honeypot field or they walk you through how to add reCAPTCHA 2.

https://docs.netlify.com/forms/spam-filters/

How can we use Starters to become super productive when starting a new project with our favorite tools?

• What is Next.js?
• What is a Starter?
• What are we going to build?
• Adding Sass to a Next.js Starter
• Setting up Next.js Starter documentation for easy setup
• Some other things to consider

What is Next.js?

Next.js is an application framework from Vercel that allows you to very quickly bootstrap a new React application.

Some basic features include creating pages and data fetching, and they allow you to generate a static site or use server side rendering to dynamically load your app.

On top of that, you can take advantage of its advanced features like Routing or creating an API right next to your UI.

What is a Starter?

Starters are basically a git repository in the form of a template that allows you to easily create a preconfigured app.

There’s nothing necessarily special about a Starter. At it’s core, it’s a Next.js app that’s already been set up a specific way and typically generalized so that anyone can use it.

For example, if you tend to build lots of apps the same way each time, you might have to repeat those same configuration steps every time you create a new app.

Instead, you can create a Starter from where you'll start your projects – and it'll eliminate the need to repeat those first steps each time.

What are we going to build?

We’re going to build a basic Next.js Starter that will let you or anyone else quickly and easily create a new project with that Starter as a starting point.

While we won’t go too heavy into features, as the goal here is to learn about Starters, we’ll test this out by adding Sass to Next.js so someone can easily get started with CSS superpowers.

You can check out the Starter on GitHub: github.com/colbyfayock/next-sass-starter.

Creating a new Next.js Starter

To get started with creating a Starter, we need to start with a Next.js app.

We can do this by running the following command in whatever directory you want to create this in:

yarn create next-app
# or
npx create-next-app

Once you run that, Next.js will ask you for a project name. While you can use whatever you like, Next.js Starters typically have a name pattern of next-[name]-starter.

So because we’re creating a Sass Starter, I might call it next-sass-starter.

New Next.js app in the terminal

Once Next.js has installed all of our dependencies, you’ll be ready to navigate to that folder and run the command to start your development server.

yarn dev
# or
npm run dev

And once the development server starts up, we should be ready to go!

New Next.js app in the browser

At this point, we pretty much have a basic Starter. As mentioned before, there really isn’t much that’s actually special with a Next.js Starter. So if we pushed this up to Github, we could immediately start using it “as is”.

You can test this out by running the following:

yarn create next-app [project-name] -e [GitHub URL]
# or
npx create-next-app [project-name] -e [GitHub URL]

After running that, you should be set up with a new directory that has a project created from your Starter with all of the dependencies installed.

But we want to do more than that. Our goal is to add features that help get an app started with more than the default, so let’s add Sass.

Follow along with the commit!

Adding Sass to a Next.js Starter

Note: For our example, we’re going to create a Sass starter as the name above might have implied. Feel free to add any features you want at this point, whether it includes Sass or not.

Remember – the goal here will be to provide something that we’ll be able to use when creating a new project with this Starter.

Next, we want to actually add Sass to our project. To get started, we want to install sass as a dependency:

yarn add sass
# or
npm install sass

Next, because Next.js already looks for .scss as a file extension, we can simply update out two CSS files under the styles directory to .scss.

So change the following files:

styles/globals.css => styles/globals.scss
styles/Home.module.css => styles/Home.module.scss

Next, we need to set up our import statements to recognize our new file extensions.

In pages/_app.js, update the styles import at the top to:

import '../styles/globals.scss'

And in pages/index.js, update the styles import to:

import styles from '../styles/Home.module.scss'

At this point, you can start your development server and we should still see the default Next.js page.

Next.js app should look the same

To see our Sass in action, we can update some of our classes to use nested styles instead of individual selectors.

Update all of the .footer selectors inside of styles/Home.module.scss to the following:

.footer {

  width: 100%;
  height: 100px;
  border-top: 1px solid #eaeaea;
  display: flex;
  justify-content: center;
  align-items: center;

  img {
    margin-left: 0.5rem;
  }

  a {
    display: flex;
    justify-content: center;
    align-items: center;
  }

}

You can use the same nesting structure to update .title and .card.

We can also add the following to the top of our styles/Home.module.css file:

$color-primary: #0070f3;

And update all instances of the color in that file from #0070f3 to $color-primary:

.title {
  ...
  a {
    color: $color-primary;

If you reload the page, nothing will change. But update that variable to your favorite color like:

$color-primary: blueviolet;

And now all of the colors change.

Updated colors in the Next.js app

Finally, since we now have a Sass starter, let’s update the title of the page. Replace “Welcome to Next.js!” In pages/index.js to:

<h1 className={styles.title}>
  <a href="https://nextjs.org">Next.js</a> Sass Starter
</h1>

And now we have a Sass starting point!

Updated title in the Next.js app

Similar to before, you can test this out by creating a new project with your starter once all of the changes are on GitHub.

yarn create next-app [project-name] -e [GitHub URL]
# or
npx create-next-app [project-name] -e [GitHub URL]

Follow along with the commit!

Setting up Next.js Starter documentation for easy setup

Arguably one of the most important things about a Starter is documentation.

It might not be as important if you’re only using this yourself. But if you want other people to use it, you want them to know how to use it or else they’ll get stuck and become frustrated.

The most important part is getting the Starter set up. Setting up your Starter in a GitHub repo is a great first step. But if someone wants to use that Starter, they would have to clone or download that repo and then remove the git history.

Instead, you can add the command we used above in your README.me file to give people instructions on how to quickly get started, such as:

## Getting Started

Run the following command to create a new project with this Starter:

yarn create next-app [project-name] -e https://github.com...

or

npx create-next-app [project-name] -e https://github.com...

This will prevent people who might not understand how to do some of those things manually from getting stuck.

It’s also important to add any documentation of configuration options you’ve added.

If you’re adding some variables that allow you to change some site-wide features, make sure to add notes about those.

You ultimately want people to understand how to use the features you added to make their lives easier. If they don’t understand it, they may just rip that code out and do it manually.

Ultimately, creating and publishing a Starter is about making people’s lives easier. Whether it’s you coming back to your Starter a few months later or a swarm of new people looking to get productive, you’re giving them a better developer experience by adding good documentation.

Some other things to consider

Generalizing features and adding configuration for a Next.js Starter

Adding features is a great way to make a Starter more likely to be used. If I used a Starter to create a new blog, I would love if that Starter included my name as an author and maybe even an About Me page.

But what I wouldn’t want is to have to replace someone else’s name 100 times throughout the code to update my own project. Not to mention, seeing that name on the Starter might make me feel more like it’s their blog rather than a template I can use for my project.

Consider starting off by using a generalized name throughout the project. Instead of using Colby Fayock’s Blog throughout the Starter, make it My Blog, which will make it feel less personal to the creator for the person using the Starter.

Also add some configuration options. It’s much easier to be able to update a single variable that would make my project include Colby Fayock instead of My Blog than it is to search all files to make that change manually.

Choose carefully where to be opinionated

When using a tool like Sass, there is more than one way to use that tool. If you set up an incredibly specific and opinionated project structure, you’re alienating people using your Starter.

It'll either force them to rework the entire project or make them want to delete a bunch of code which might make them avoid wanting to use it in the future.

You can create opinionated Starters, but choose wisely where you inject those opinions. This will make your work usable by a larger group of people who want to be productive.

If you want to create something very opinionated, consider naming it something different and using the tool as part of the name. For example, I could create an opinionated Sass Starter called Colby’s Sassy Next.js Starter.

Did you create a new Starter?

Share with me on Twitter!