DEV Community: Ben Fox

Next.js Setup | ESLint, Jest, React Testing Library, and Absolute Imports

Ben Fox — Thu, 10 Mar 2022 22:15:14 +0000

A comprehensive step-by-step guide to configuring Jest, React Testing Library, ESLint, and Absolute Path Aliases in a Next.js project.

Next.js is amazing when it comes to installing, learning the framework, and jumping into the code. Its superb documentation & zero-config philosophy make this possible, and not having to think about configuration is wonderful…right up to the point when you want to add some additional configuration.

The configuration I want to add is, technically speaking, useless to your final product. It won’t make it faster, or reduce your bundle size, or add amazing new features.

How’s that for a hook…🙄

But it’s important 🤩 Consider this step the first reminder to go slow to go fast (esp. check the second to last paragraph). If you need more convincing, remember when Facebook changed its motto to ‘move fast with stable infra’?

You don’t even have to use all of it right away. ESLint and path aliases for absolute imports, once set up, are a free productivity boost. Absolute imports mean no need to worry about how many levels of ../../ are needed to find the component you are trying to import. Linting means no need to worry that a missing ) or } will leave you bashing your head against the wall for 30 minutes wondering why your code doesn’t work.

Jest & React Testing Library, on the other hand, require some effort after setup. Testing your code is a good habit to have, and there are some very good resources out there to help you figure out what to test.

You may not start testing much right away — particularly if your UI & functional requirements are subject to frequent, drastic changes — but you should test what you can. If you’re not testing at all, you may want to consider evaluating why you’re putting it off. At least now, with this setup ready to go, you’re more likely to get into the habit.

The problem?

Sounds great right? You’ll have stable infrastructure to boost productivity, linting to enforce consistent coding standards, increasing readability and maintainability, and testing to make sure you don’t break stuff 🥳 but getting all of these set up and playing nicely with each other, with Next.js and with your IDE, can be a time consuming exercise in frustration. It’s also WAY less fun than writing code 😩

The solution?

This is it! Take the time to set it all up once, before writing any project specific code, to create a codebase that can be easily duplicated for any new projects.

Let’s look at what it takes.

What We’ll Cover

Assumptions
Final Repository
Next.js: Installing
ESLint: Install & Configure
Jest & React Testing Library: Install, Configure, Implement
Configuring Path Aliases/Absolute Imports

Assumptions

I’m going to assume you have familiarity running commands in a terminal, and I’m going to use npm commands. None of the commands are anything fancy, so you should be able to convert to yarn if needed.

I’m going to jump right in to adding configuration, and won’t dive in to too much detail on any one item — Next.js, React, Jest, React Testing Library, or ESLint —but I will try to give at least some high-level context for what’s happening at each step.

I’m not going to talk about IDE-specific integrations or setup. I’m using VSCode, and I’ll mention it in a few places. Other IDEs should have similar options, but likely require other specific setup steps. If you run into IDE specific issues let me know and I can see about adding additional notes.

A note before we start

Some of the configuration files we create (jest.config.js, .eslintrc) can be included within package.json rather than using separate files, if that feels cleaner to you. That will require additional wrapping syntax, which you can find at their respective links. The jsconfig.json & jest.setup.js files will have to be separate.

Final Repository

https://github.com/BenjaminWFox/nextjs-base

Next.js: Installing

To start, in your terminal of choice, cd into a folder where you want to install this project. A new subfolder will be created be after you run the setup:

npm init next-app

Give your project a name like "nextjs-base" (this will also be the folder name). Once the install completes, cd nextjs-base into your project folder.

Now, for better organization, create a new folder called src and then move the pages and styles folders into src. Your project should look like this:

.next/
node_modules/
public/
src/
 - pages/
  - api/
 - styles/
.eslint.json
.gitignore
next.config.js
package-lock.json
package.json
README.md

ESLint: Install & Configure

For configuration, let’s start with eslint — that’ll ensure that any future code we write is linted right away and we don’t need to go back and make edits. This will also include a plugin for specifically linting React, and another for linting import/export statements. You'll already have eslint and eslint-config-next - so let's add two more:

npm i -D eslint-plugin-react eslint-plugin-import

While that’s running, open up the .eslintrc.json file that is at the root of your site. Replace the contents with the configuration below.

Note that there are a ton of options for configuring ESLint.

You can just extend next and next/core-web-vitals if you want, leaving out the others. If you do, you can also omit the everything in the rules property. Personally, I like the extra structure and what's there feel to me like a good default baseline. A number of the react/ specific rules are disabled to prevent conflicts with the default next-app code style.

If you're working anyone else I'd highly recommend leaving the rules in place, it goes a long way towards keeping a codebase stylistically consistent:

{
  "extends": [
    "next",
    "next/core-web-vitals",
    "eslint:all",
    "plugin:react/all",
    "plugin:import/errors",
    "plugin:import/warnings"
  ],
  "env": {
    "browser": true,
    "es2020": true,
    "node": true,
    "jest": true
  },
  "parserOptions": {
    "sourceType": "module",
    "ecmaFeatures": {
      "jsx": true
    }
  },
  "rules": {
    "indent": ["error", 2],
    "quotes": ["error", "single"],
    "semi": ["error", "never"],
    "func-style": 0,
    "max-len": 0,
    "no-magic-numbers": 0,
    "max-lines-per-function": 0,
    "space-before-function-paren": ["error", {
      "anonymous": "never",
      "named": "never",
      "asyncArrow": "always"
    }],
    "function-call-argument-newline": 0,
    "padded-blocks": 0,
    "padding-line-between-statements": [
      "error",
      { "blankLine": "always", "prev": "*", "next": "return" },
      { "blankLine": "always", "prev": ["const", "let", "var"], "next": "*"},
      { "blankLine": "any",    "prev": ["const", "let", "var"], "next": ["const", "let", "var"]}
    ],
    "object-curly-spacing": ["error", "always"],
    "one-var": ["error", "never"],
    "quote-props": 0,
    "react/prop-types": 0,
    "react/jsx-indent": [2, 2],
    "react/jsx-indent-props": [2, 2],
    "react/jsx-filename-extension": 0,
    "react/react-in-jsx-scope": 0,
    "react/jsx-no-literals": 0,
    "react/jsx-one-expression-per-line": 0,
    "react/jsx-max-depth": 0,
    "react/jsx-newline": 0,
    "react/jsx-props-no-spreading": 0,
    "react/jsx-max-props-per-line": ["error", {"maximum": {"single": 3, "multi": 1}}]
  },
  "ignorePatterns": [
    "node_modules/",
    ".next/"
  ]
}

^ some breakdown of what this is doing:

extends sets up a set of base rules to use as a starting point. Using all is probably going to make your life harder…but I would recommend keeping it, and adding specific modifications to rules you don’t like. It will give you a good sense of the different ways people might format code. There are all kinds of base configs you could extend instead, from companies (airbnb, facebook) and projects (standard, prettier).
env tells ESLint what global variables & special syntax to expect. Since this is for Next.js, we’re adding the browser and node. The es2020 (which is ecmaVersion 11 (which basically means JavaScript version 11)) allows for using newer JavaScript syntax, and jest is for global variables used when writing tests.
parserOptions is specifically for allowing additional JavaScript language features. sourceType will prevent errors from import syntax, and ecmaFeatures allows for additional features outside the standard ecma syntax.
rules is where you can configure the linting behavior to your liking. Any that are prefixed with react/ are specific to the ESLint react plugin, similarly import/ would prefix any rules for the import plugin — we just don’t need to add any here. Otherwise they are standard ESLint rules.
ignorePatterns lets you define specific files, folders, or patterns to exclude from linting. Both the node_modules and .next folders are actually excluded be default, and added here only as examples.

So…that’s a lot! But it will let us lint the Next.js project we have now with the --fix flag enabled to automatically format our code (next step!).

Add & Run the Lint Script

Now add one new script to your package.json file under the start script:

    "start": "next start",
    "lint": "next lint",
    "lint.fix": "next lint --fix"

^ Don’t forget the , (comma) at the end of the "lint" line! If you've integrated your IDE with ESLint you’ll already have seen a bunch of errors if you open src/pages/index.js. The src/pages/api/hello.js should be error-free!

If you npm run lint now, you can also see all the errors in the console. I've tweaked the eslint config over time, so the exact set of errors may be slightly different.

…now do npm run lint.fix and you’ll see a number of formatting changes to align the code with the linter rules, and no more errors!

Two Final Notes on Linting

Regarding IDE integration if you go that route — it’s super convenient to set it up to lint & fix whenever you save the file.
Assuming you use this base template in new projects, if you find yourself making updates to the .estlintrc file to accommodate your style preferences, remember to copy those back to the base project!

Jest & Testing Library: Install, Configure, Implement

Install Dependencies

Next up let’s add testing capabilities. Start with the install:

npm i -D jest @types/jest @testing-library/react @testing-library/jest-dom

^ jest for running the tests & @types/jest to help with IDE auto-complete when writing tests. @testing-library/react to render components in the testing environment & test them in a way that tries to mimic how users interact with them. @testing-library/jest-dom for additional DOM-related assertions.

Create Config Files

Create two new files at the project root for Jest: jest.config.js & jest.setup.js. Add this content to the jest.config.js file:

// Jest.config.js
const nextJest = require('next/jest')

const createJestConfig = nextJest({
  // Provide the path to your Next.js app to load next.config.js and .env files in your test environment
  dir: './'
})

// Jest.config.js
const customConfig = {
  // Automatically clear mock calls and instances between every test
  'clearMocks': true,
  // The directory where Jest should output its coverage files
  'coverageDirectory': '.coverage',
  // A list of paths to modules that run some code to configure or set up the testing framework before each test
  'setupFilesAfterEnv': ['./jest.setup.js'],
  // By default jest will use a node environment, so DOM elements (like document) will be undefined without this
  'testEnvironment': 'jsdom'
}

module.exports = createJestConfig(customConfig)

^ There are a huge number of configuration options for Jest. This is a very small subset. clearMocks can prevent headaches with unintended persistence of mock data between tests. coverageDirectory is for generating test coverage, running jest with the --coverage flag. The most important piece here is setupFilesAfterEnv, which will run before each test file. Add this to the jest.setup.js file:

// Jest.setup.js
import '@testing-library/jest-dom'

^ This enables access to the additional assertions provided by the@testing-library/jest-dom package.

Write a Test File

Create a file src/page-tests/index.test.js and add some test code:

import { render, screen } from '@testing-library/react'
import Home from '../pages/index'

// `describe` is not required, but it helps the tests read nicely
describe('The Home Page Component', () => {
  // Each test for the component will get an `it` block
  it('should have exactly 1 `main` section', () => {
    // The getByRole will error if there are less or more than 1 element found
    render(<Home />)
    const main = screen.getByRole('main')

    expect(main).toBeInTheDocument()
  })
})

Add a Test Script

The last change for Jest is to the package.json file; Update it to add a test script under the lint script you added earlier:

"lint.fix": "eslint --fix --ext .js ./",
"test": "jest"

Then in the project root in the terminal you can npm run test — and should see it passing!

Configuring Path Aliases/Absolute Imports

I have seen some debate that leads me to believe path aliases are a love-it or hate-it addition to a codebase. I personally hate having to remember which particular file I’m working in and how many levels it is to import some other component or method…so I love aliasing my import paths. The difference is:

// (Default) Relative imports 😈: 
import { Awesome } from '../../components/awesome
import { Method } from '../../../classes/method

// (Aliased) Absolute imports 😇:
import { Awesome } from '@/components/awesome
import { Method } from '@/classes/method

^ Note that the syntax I’m using, @/folder/path, is arbitrary — the @ may look fancy but it is only there to make it obvious that this isn’t an npm package or a relative import — you could name the alias paths however you like!

The challenge setting these up is that once you start using them in your application and in your tests, all the different systems in your code that have to resolve imports (<-- good explanation of resolving modules — ignore the TypeScript parts 😅) need to understand these aliases. For us, that means adding configuration for Next.js, Jest, ESLint, and VSCode 😰 … so a lot of updates to the configuration we’ve done thus far but don’t worry —it’s not too drastic.

Create a Test Component

In order to verify the aliased paths are working we need something to import. Typically you would alias the top-level folders to reference the import path from there, but the only two top-level folders we have currently aren’t really something we need to alias; Anything in pages/ probably shouldn’t be imported anywhere else, and anything in public/ can already be referenced by absolute path in src or href attributes.

Instead, let’s create a new section in the code specifically for components. This will be two new folders and a file: src/components/callout/callout.js. Add this to the callout.js file:

import PropTypes from 'prop-types'

export default function Callout({ children }) {
  return <p><strong style={{ color: 'red' }}>!</strong> {children} <strong style={{ color: 'red' }}>!</strong></p>
}

Callout.propTypes = {
  children: PropTypes.node.isRequired
}

Try The Component

If you import that component in src/pages/index.js via a relative import, you can confirm it’s working:

import Callout from '../components/callout/callout'
import Head from 'next/head'

Then wrap the component around the “Welcome…” message in the h1 tag:

<h1 className={styles.title}>
  <Callout>Welcome to <a href="https://nextjs.org">Next.js!</a></Callout>
</h1>

Then npm run dev and see: ❗️️ Welcome to Next.js! ❗️

Now change src/pages/index.js to use the aliased absolute import:

import Callout from '@/components/callout/callout'

…and you should see an error, yay! Let’s fix that!

Next.js & VSCode

Now that we have a component to test and we can see it’s not working, let’s start the configuration updates. Create a file in the project root named jsconfig.json. This will let us nab two birds with one stone since both VSCode and Next.js use this format for aliases. Add this to the file you just created:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/components/*": ["src/components/*"]
    }
  }
}

^ This won’t trigger a HRM refresh, so you’ll have to stop the dev server and npm run dev again, but after that — your component should be up and running again!

In the IDE, if you’ve integrated ESLint, you’ll probably see an error still about how it is “Unable to resolve path to module,” so let’s update ESLint next.

Update ESLint

The configuration for ESLint will be added to .eslintrc, but first we need to install another package:

npm i -D eslint-import-resolver-alias

^ this package adds the functionality for ESLint to handle the resolution of aliased paths, which it can’t do by default. Update the .eslintrc file by adding the following at the bottom, after the ignorePatterns property:

"ignorePatterns": ["node_modules/", ".next/"],
"settings": {
  "import/resolver": {
    "alias": [
        ["@/components", "./src/components"],
        ["@/classes", "./src/classes"]
    ]
  }
}

^ I’ve added an additional entry for a hypothetical /classes directory to show the syntax for multiple aliases. The need for each entry to be its own array was not intuitive for me.

If you npm run lint now, there shouldn’t be any module import errors (you may have some spacing/minor issues from copy-pasting, so maybe npm run lint.fix), and the IDE error should have disappeared!

Update Jest

Finally we need to update Jest. In the file src/pages/index.test.js add an import for our Callout component:

import Callout from '@/components/callout/callout'
import Home from './index'
import { render } from '@testing-library/react'
...

… then try npm run test. You should see an error about the module:

Cannot find module ‘@/components/callout/callout’ from ‘src/pages/index.test.js’

The addition to fix this will go into jest.config.js, a property called moduleNameMapper which uses RegEx syntax, so is a bit more complicated:

const customConfig = {
  // Automatically clear mock calls and instances between every test
  'clearMocks': true,
  // The directory where Jest should output its coverage files
  'coverageDirectory': '.coverage',
  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
  moduleNameMapper: {
    '^@/components(.*)$': '<rootDir>/src/components$1'
  },
  // A list of paths to modules that run some code to configure or set up the testing framework before each test
  'setupFilesAfterEnv': ['./jest.setup.js'],
  // By default jest will use a node environment, so DOM elements (like document) will be undefined without this
  'testEnvironment': 'jsdom'
}

^ The regex is using a capturing group to take everything that comes after @/components and resolve it instead from the /components specified on the right. Check it out on regex101.com for a more complete breakdown of what’s going on.

…now try npm run test, error should be gone!

Since we only added it for testing, you can remove the import Callout ... line we added to src/pages/index.test.js.

Important to remember

When you add new aliases in the future, you’ll need to add them to three files:

jsconfig.json
.eslintrc
jest.config.js

Complete!

Whew, that was a lot 😰 Fantastic job getting through it all, and you now have a robust Next.js base project you can use to build from in the future!

Questions? Comments?

Find me on twitter — @BenjaminWFox

How to Think in Next.js

Ben Fox — Tue, 15 Jun 2021 12:04:07 +0000

Let me tell you a story about a client.

This client was demanding. They wanted all the things, and they wanted them now.

Servers know this kind of client all too well. When the client comes in, asking for everything and the kitchen sink, a server just has to sigh.

"A lot of that is just going to go to waste, you know," says the server, softly.

Their comments go unheeded.

Does this client sound familiar?

This client is your Single Page Application (SPA).

There's a new client in town, though, and it only asks for what it needs.

This client is Next.js.

It also happens to be the server 🤔

Clients and Servers and Node Oh My

Starting with Next.js after working on SPAs can be challenging (at least it was for me) with the whole server thing going on, not to mention the node.js runtime 😱

It can feel like a steep learning curve, especially if you haven't worked much with Node.js, but at the end of the day remember that the client is still React! A majority of getting comfortable with Next.js, I've found, is understanding three things:

Client vs server contexts
Page types
API Routes

Next.js is powerful, and a lot of fun to build with once you get a handle on how it works 🏗 It combines some of the best features of traditional and single page web applications into a hybrid application.

If you want a refresher check out the high-level differences between the three application types!

⚠️ Expect that things will take longer, at least at first. If you're not learning at your own pace and have to make time estimates, remember to pad those so that you have the time needed to do things correctly the 'Next' way, and not just revert to SPA patterns on top of Next.

⚠️ Inevitably there will be places where adding functionality is just more complex when rendering occurs in both a server and a browser context like Redux or CSS-In-JS.

Review: SPA vs Next.js

In a SPA

Your code executes in the browser only

The entire site code bundle is downloaded upfront
You should not include sensitive information (API keys, passwords, etc...)
Subsequent pages are all built from bundle code
You have access to Web APIs and the DOM

In Next.js

Your code executes on the server first and in the browser second

On the server:

Pages are pre-built and/or pre-rendered (more on that later)
During API Routes & Data Fetching you can include sensitive information
You do not have access to Web APIs & the DOM on the server
You do have access to a whole new set of APIs in Node.js

In the Browser:

The browser only gets the code it needs for the requested page
None of the sensitive data from the server is available
Subsequent pages make new requests to the server
You have access to Web APIs and the DOM

This also means implementing functionality which may have had a common approach for SPAs, like Authentication, now has multiple approaches to choose from depending on a variety of factors related to how you design your application.

Execution Context

The considerations I want to focus on all revolve around the fact that there is now a server you have to deal with. At the risk of sounding obvious, I think it's hard to overstate how important this is.

The biggest gotcha?

Adding a server adds an execution context

Consider that you've essentially doubled the complexity of your application!

The context in which your code executes can be either the server or the client (browser). There may be code you write that can only execute in one or the other of these. Common examples are:

The browser globals window & document are undefined on the server
The Node.js File system (fs) module is undefined in the browser

Right off the bat do yourself a favor and create two utility functions to wrap code that should run in only one context:

export const isClient = () => typeof window !== 'undefined'
export const isServer = () => !isClient()

⚠️ Those methods aren't always necessary. The useEffect (and useLayoutEffect) React hooks will only run in the browser. The API Routes and Data Fetching methods will only run on the server.

⚠️ Don't leave unused imports; Node.js modules that are imported and unused will throw errors. The reference won't be removed before the code goes to the client and the browser will choke on the Node.js code.

Your Application is Starbucks

Before we go further, let's go back to our metaphor from the beginning.

Our client (a customer) walks into a Starbucks. Our server (a barista) will be ready to help with whatever the client wants.

Starbucks knows certain things about what the customer might want. Since there are things they can make ahead, they have a nice selection of canned beverages (like the DOUBLESHOT) that the customer can just grab and go!

The server has to do almost no work, huzzah 🥳

But Starbucks also knows that the customer might be picky (I'm looking at YOU Edward) so they're ready to make something crazy (the TikTok Special) on the fly.

The server has to do a lot of work, dang 😰

Finally, there might be some things the server can't provide. In this case the client will sneak into the bathroom with their hip flask (don't try this at home, always drink responsibly) and add their own whisky to the coffee.

The server will do some work, and so does the client 🍻

Can you guess who Starbucks is in the scenario above? It's Next.js 😆

The three scenarios above encompass the choices you have when building pages in Next.

Pages

Before building any pages it pays to step back and think about:

where does your content come from?
how often does your content change?
how much of a page depends on certain content?

Answers to these questions will impact whether you want to implement the page via Static Site Generation (SSG), Server Side Rendering (SSR), or some combination of those mixed with client side rendering (CSR).

SSG

The Grab-and-Go: The fastest choice, Static Site Generation means little to no processing on the server & best for SEO & Core Web Vitals. The server only has to return pre-built, static content.

"Statically generated pages are still reactive: Next.js will hydrate your application client-side to give it full interactivity." - Next.js Documentation

Use this option with content that doesn't change frequently (or ever). Blogs, marketing sites, policy documents, and FAQs all fall more or less in this category.

This can get cumbersome on sites with many (thousands or more) pages, but can be mitigated to some degree with incremental static regeneration.

SSR

The TikTok Special: Server Side Rendering means rather than serving pre-built pages, the server builds the page when it is requested. The browser still gets static content, but data fetching & processing likely means longer time to largest contentful paint.

It's an excellent option for pages that depend on particular input data and where it isn't possible (or feasible) to statically generate all page combinations for given inputs.

Input data might be something like user details, purchase/order history, weather, time, or traffic.

CSR

The Hip Flask: Client Side Rendering can be added in addition to either of the strategies above. It can serve as a strategy to defer loading some page content so that most content can be ready faster via SSG or SSR.

The deferred content might be frequently updating/real-time data like a stock chart or chatbar, or content with a particularly long load time.

⚠️ Be mindful that if some content is not readily available there may be impact to SEO and issues with cumulative layout shift.

⚠️ Remember that page code may be executed on both the server and client! If you have any sensitive information in environment variables or other stores be careful that it doesn't get sent to the client accidentally.

API Routes

Let's extend our metaphor above even further! Consider an espresso maker, a beautiful and complex machine that you definitely do not want your customers, err I mean clients, touching.

To shield the clients from the complexity of the espresso maker, the client makes a request of the server. The server goes off and deals with all the complicated bits, and after a while the order is ready. Then the server gives a response, "Edward, I have your Venti Caramel Crunch Frappuccino!"

Until the response arrives, the client is free to doomscroll TikTok looking for cat videos and a new crazy coffee drink.

Your API Routes in Next.js mirror that interaction. They won't get you coffee, but if you build them right they can get you cat memes.

⚠️ Remember this is in the server context. You can use sensitive keys, secrets, passwords, and connection strings if required. You could interact with the filesystem, say, to pull in markdown documents for creating content. You could add an ORM like Prisma to interact with a database.

⚠️ Server-only context extends beyond API Routes. It also includes the Data Fetching methods getServerSideProps, getStaticProps, and getStaticPaths. These methods are more specialized and I won't be going into more detail on them here, but the documentation linked in the pages section for each of the three types are great resources.

For reference, an API Route looks something like:

export default function handler(req, res) {
  // Do lots of processing...call apis...access database...

  res.status(200).json({ name: 'Next.js' })
}

Simple right? 😬

The Request

You're probably familiar with fetching data from APIs from the SPA architecture. Now you're on the API side of that transaction.

The request, or req object, will have all kinds of information about the request that the client has made. This includes headers, referrers, browser information.

In API Routes there is also extra data added by Next which includes objects for cookies, query, and body if that information is present.

If you're doing CRUD operations pay especially close attention to the method the client is using, since you'll want to respond differently to different methods!

The Response

The response, or res sends information back to the client. It's important to always send back a response or the browser request will never finish, drifting endlessly in the wind.

Similar to the req object, the res object in API Routes has some extra helper methods added by Next, which make building the response easier than default Node.js http.ServerResponse functionality. It tripped me up when I saw these helpers used in tutorials but couldn't find them referenced in the Node.js documentation.

And with the response sent you're all wrapped up and ready to get on with building something new and exciting!

Questions? Comments?

Follow me on Twitter @BenjaminWFox for more tech and leadership content, and reach out with any thoughts or questions!

How Does a Website Get its Data, and Why Does it Matter?

Ben Fox — Tue, 15 Jun 2021 03:40:08 +0000

Servers to No Servers to Serverless

In the beginning, there were servers.

The servers roamed the wild, waiting for clients and their connections, and when a server received a connection it would pounce. The servers liked the connections and held on to them, guarding them closely.

Thus the traditional web app was born.

But the clients grew tired of the servers, which were needy and somehow both clingy and flakey.

"Give us back our connections!" cried the clients, "On our terms!"

"We will just stop by to grab all the things when we need them," the clients went on, "that's really all we need."

Thus the single page application was born.

But the clients grew lonely. They had no one to tell their secrets to, and no one to help rearrange the furniture.

"Maybe we could work out a friends with benefits kind of thing?" mused the clients.

The servers were into it.

Thus Next.js was born.

Say What Now?

Ok, if the epic story of creation didn't do it, let's try again with pictures.

I've been building on the web for what feels like a long time, and I haven't reviewed the basics of how a site works in recent memory. I've been working with Next.js a lot over the last year, and I thought I'd write some notes to refresh my memory on how my sites used to work, and how they work now.

The story of each application had three main players, the:

Screen (or other interface) to drive input on the client
Client (the browser) to interact with the server to get data
Server to send data to the client

The client sends a request to the server for some stuff. The server sends that stuff back to the client. The client does things to it, and bam it's available to show on the screen.

Exactly what happens at each of those steps differs a little depending on whether you're talking about a traditional, single page, or hybrid/serverless (like Next.js) application.

Let's dive in to a high level overview of what those differences are. In all cases, the first two steps and the final step are the same:

The screen triggers a page request
The client sends a page request to the server
??
??
Profit! The screen displays the page

So let's look specifically at steps 3 and 4 for each application!

Traditional Server App

Server grabs or builds the requested page
Client receives ready-to-display page

This process will repeat itself every time. New page requested, new request fulfilled. In a traditional app servers are also often stateful, so could remember details about a specific connection in between requests, and use that stored information for each connection to build pages on subsequent requests.

Page loads can be slow and unoptimized, and the UI refreshes for all transitions. AJAX offered some additional flexibility but it was clunky to implement and rarely felt like a first-class citizen.

Single Page App

Server grabs a bundle of stuff (like JavaScript and CSS)
Client receives & processes the bundle to build pages

Right up front the client has grabbed everything it needs, for better or worse. No more requests to the server need to be made for pages, which will all be built from the bundle that the browser now controls. Other requests might be made for data, either from the same server or other APIs.

Bundles can grow quite large, increasing load times and degrading user experience. Bundle splitting was one solution to that problem, but it could get complex and was often poorly implemented, if at all.

Next.js or Hybrid App

Server grabs or builds the requested page
Client receives a page that may requires some processing

First a note on serverless, which only means that the servers are run and maintained by a 3rd party. The term is commonly used in tandem with hybrid apps, but it's just a reference to how they're deployed. One way or another, there are still servers involved.

The hybrid app is like the traditional app where new pages are requested from the server, but there is a lot more flexibility, hence the "hybrid" designation. Fetching new data has first-class support. The types of pages available on the server have explicitly defined options and can be entirely ready-to-serve or generated at request-time.

Like the single page app, a page in hybrid applications like Next.js can also still have large portions that need to be processed on the client.

This flexibility comes with increased complexity, and unlike the traditional app, this server is not stateful. It knows nothing about a connection except what is provided in the incoming request.

At the End

None of these approaches are inherently better or worse than the others, and don't let anyone tell you otherwise. All have pros and cons. One may work better for a particular use case than another, but that will depend on project-specific requirements, so you'll have to do your homework once you determine what those are.

And you should definitely determine your requirements up front! 😉

The first time I lobbied to build a site with Next.js I ended up stripping it out a month later 🤦‍♂️ it became clear that there was actually only a single page with different sections of the page that changed at certain times, so back to the single page app I went!

Questions? Comments?

Follow me on Twitter @BenjaminWFox for more tech and leadership content, and reach out with any thoughts or questions!

Atomic Design for Developers: Better Component Composition and Organization

Ben Fox — Sun, 09 May 2021 03:11:44 +0000

A practical guide to developing component based sites and apps around the Atomic Design methodology.

Organizing your application (or app/site, I'll use these interchangeably) can seem easy. A folder for components, one for assets, another for utility methods. Maybe even a separate folder for pages! Don't be fooled, it is almost never that easy...

"It's alright. This place just needs a one-hour bureaucratizing."

— Hermes Conrad

Hermes Conrad would agree that what your app needs is a good, one-hour bureaucratizing. Hooray for rules and regulations! I'm not normally for bureaucracy but as your app starts to grow you should have a way to organize things that provides more granular organization, separation and, importantly, is based on explicit rules and guidelines rather than guesswork or instinct.

My Goal

I'll provide a little background, but there is a lot of content out there about Atomic Design generally, both from designers and developers. My main goal is three-fold:

Enumerate the rules I've found that work for me and my team when determining how to categorize a component.
Provide code showing implementation for each of the five categories.
Show usage of these components in the context of a "real" site.

Please note: You are free to disagree with any/all of the rules I present. You may find that they do not cover every edge case. I'd love to hear any thoughts and opinions. My hope is that you come away with an idea of how to implement this methodology in a way that works for you.

Backstory
Atomic Design
Why this Article
Why NOT this Article
Sample Code
Atoms
- Examples of Atoms
- Rules of Atoms
Molecules
- Examples of Molecules
- A Nebulous Molecule
- Rules of Molecules
Organisms
- Examples of Organisms
- Rules of Organisms
Templates
- Examples of Templates
- Template Variations
- Tiered Templates
- Rules of Templates
Pages
- Examples of Pages
- Rules of Pages
- A Note on Routes
Conclusion
- One Rule to Rule Them All

Backstory

A few years back I was searching for a better way to organize components in web apps. The designers I was working with at the time were adopting a design system that followed Atomic Design principles and it seems like that would translate well into the front-end development space since ultimately our work was to implement the components created by the design team.

Having a common language to use for categorizing components seemed like a no-brainer, although for a variety of reasons unrelated to Atomic Design this didn't end up being the case between our designers and engineers.

It did work out pretty well for the engineering team internally though so, good news, you don't need to have buy-in and adoption from designers to start using these principles for development!

Atomic Design

Atomic Design is a methodology for creating design systems created by Brad Frost. You can read his full post for a comprehensive overview.

For the purposes of this article it's important to know that Atomic Design breaks design systems (and the components that make up an application) into a hierarchy with five levels.

It begins at the smallest component level (atoms) and combining those to create larger components (molecules) which themselves get combined into still larger components (organisms) which are then displayed in logical groups (templates) that make up the app (pages).

Atoms -> Molecules -> Organisms -> Templates -> Pages

In this article I'm going to talk about applying Atomic Design principles to front-end development. I'll be using React for specific examples, but the definitions and principles should apply to any component or composition based UI applications.

Why this Article

The biggest challenge I faced with my team after deciding to use Atomic Design principles as the basis for our component organization and hierarchy was figuring out what components went into which buckets. There were some other writeups I found that had bits and pieces of details, but I never found anything that gave both a prescriptive example of how each level might be delineated and examples of implementation and usage.

When you're building reusable components there are a lot of considerations, including decisions like how a component is structured, what data it needs, where that data lives, if (and where) state is needed, and so on. Since you've (hopefully) already made most, or all, of those decisions before starting the build the component, you can use them as a set of heuristics to store your component where it makes the most sense.

heuristic - a practical method [for decision making] that is not guaranteed to be optimal, perfect, or rational, but is nevertheless sufficient for reaching an immediate, short-term goal.

— wikipedia

I say heuristics intentionally, since you're certain to find edge cases or gray areas in any methodology. The goal is to make sure those are few and far between, so you're left with a system of organization providing maximum reusability, flexibility, and composability.

Atomic design is not a linear process, but rather a mental model to help us think of our user interfaces as both a cohesive whole and a collection of parts at the same time.

— Brad Frost

Why NOT this Article

In my experience this approach is best suited to applications that are (or expect to be) large, frequently updated, and/or frequently extended.

It helps to have a well-planned design and information hierarchy, but it's not strictly necessary. Even with relatively simple mockups or wireframes you can start to develop a sense of what parts of the UI build upon one another.

I would not use this approach if I were working on libraries or applications that were relatively limited in scope, complexity, or life expectancy.

Sample Code

Throughout this article I'll be sharing and referring to code that I've developed in the form of a relatively simple list/todo app. There's no interactive functionality. It's designed to show visually & structurally how components build on one another other using Atomic Design. On the site, you can take a look at the /settings page to toggle outlines for various levels of components.

Website: https://atomic-design-example.benjaminwfox.com/
Repository: https://github.com/BenjaminWFox/example-app-atomic-design

Atoms

The atom is the most basic component, as generic as can be.

Examples of Atoms

Icons, buttons, links, and labels are good examples of atoms. They don't do much on their own, and many other components on a site will typically depend on using these in one way or another. They can be used virtually anywhere throughout a site, so they have a lot of flexibility. Let's look at a very basic example, the Button:

export default function Button({label, onClick}) {
  return <button role="button" onClick={onClick}>{label}</button>
}

This is about as basic as it gets. Not even any styles needed here. While that may not be the case for most sites, styles would not add much complexity and wouldn't change anything about the "Atomness" of the Button. Another example, a BlockLink:

import Link from 'next/link'

export default function BlockLink({href, children}) {
  return <div className="underline"><Link href={href}>{children}</Link></div>
}

For whatever reason, the demo site I built has a frequent need for block-display links! In this case importing a framework primitive is fine. It's smaller than an Atom. You can call it a neurotron if you want, that's a cool-sounding made-up word 😎 ⚛️. The Link is just an abstraction of the a tag with framework-specific functionality. It doesn't do anything from a style or markup perspective.

Visual example of Atoms: BlockLink, Button, and Icon components.

Rules of Atoms

Should not compose other components/only uses native elements or framework-specific components similar to native elements
Can have its own markup & styles
Can maintain its own internal state
Should not be tightly coupled to specific UI or Logic areas
Should not access application (or higher level) state directly
Should not have any non-ui/layout related side effects
Should not implement any application-specific business logic

Molecules

The molecule composes atoms to create a more complex component, with its own markup and styling added to the mix. Aside from that, the rules I use for molecules are virtually identical to those of atoms.

Examples of Molecules

Molecules, being made up of Atoms, tend to be a little more specific in usage, but (and this is of course also design dependant) they should also still be reusable in areas throughout the site. Below is an example atom ImageWithOverlay that overlays some text onto an image. It doesn't have much in the way of specific styling besides positioning the text.

Below that is a molecule BannerImage that composes ImageWithOverlay to create a banner designed specifically to be added at the start of content, flush with the top & side margins of its parent element.

// /atoms/image-with-overlay.js
import styles from './image-with-overlay.module.css'
import Image from 'next/image'

export default function ImageWithOverlay({ title, subtitle, src, layout = 'fill' }) {
  return (
    <>
      <div className={styles.caption}>
        {title ? <h1>{title}</h1> : null}
        {subtitle ? <p>{subtitle}</p> : null}
      </div>
      <Image
        src={src}
        layout={layout}
        objectFit="cover"
        objectPosition="center center"
      />
    </>
  )
}

// /molecules/banner-image.js
import Image from 'next/image'
import styles from './banner-image.module.css'
import ImageWithOverlay from '../atoms/image-with-overlay'

export default function BannerImage({ src, title, subtitle, height }) {
  return (
    <div
      style={{height}}
      className={[styles.banner, 'flush-width', 'flush-top'].join(' ')}>
      <ImageWithOverlay title={title} subtitle={subtitle} src={src}/>
    </div>
  )
}

Compare the BannerImage here (stretched to the top & side margins) against the ImageWithOverlay in the previous screenshot:

A Nebulous Molecule

There are a few components in the example project that, on first glance, don't fit neatly into the molecule definition. The SidebarLinkList, HeaderLinkList, and HeaderIconList fall into this category. They are all about the same, and render a collection of children in a single div:

import styles from './header-link-list.module.css'

export default function HeaderLinkList({children}) {
  return <div className={styles.headerLinkList}>{children}</div>
}

The reason I've labeled these as molecules is that while they don't explicitly compose any atoms, they all depend implicitly on a specific atom being passed as children. In the case here of the HeaderLinkList, all the children should be BlockLink components. If the example app were more robust, I might create a custom PropType entry to throw an error if any of the children were not BlockLink.

Rules of Molecules

A component made up of one or more Atoms
Can have its own markup & styles
Can maintain its own internal state
Should not be tightly coupled to specific UI or Logic areas
Should not access application (or higher level) state directly
Should not have any non-ui/layout related side effects
Should not implement any application-specific business logic

Organisms

Organisms are where the business logic of your application starts to come out. They might correspond to a specific feature or section of the app. They may also be generally applicable but tightly coupled with the application logic. Data fetching and reading/writing to application state should primarily happen here (or alternatively at the Page level).

Examples of Organisms

One of the more basic organisms in the sample app is the SidebarNavigation. At two molecules and one atom, it has not grown terribly complex, but it is specialized enough - designed to live in the sidebar and further composes a molecule - that it is no longer a molecule itself.

Constructing organisms might be a good time to re-evaluate your other components. Do they really belong where you've categorized them? If they are categorized in the correct place, have you named them appropriately?

Literally as I am writing this, I noticed that in the SidebarNavigation component I had named IconHeading as SidebarTitle, and VerticalListLayout as SidebarLinkList 😱

That's sub-optimal!

Why? There isn't anything explicitly sidebar-related about those two components!

It just happened that the sidebar was the only place they had been implemented. While I feel I was correct in making them molecules (even that may be debatable for the VerticalListLayout, but meh...heuristics), if they were actually only usable within the context of the sidebar adding them as organisms may have been more appropriate.

After re-naming those two components to ensure they're more generalized, my SidebarNavigation component looks like:

import SidebarLinkList from '../molecules/sidebar-link-list'
import BlockLink from '../atoms/block-link'
import SidebarTitle from '../molecules/sidebar-title'

export default function SidebarNavigation({ title, subtitle, sidenav, selected, children }) {
  return (<>
    <IconHeading title={title} subtitle={subtitle} />
    <VerticalListLayout>
      {sidenav.map(entry => {
        const label = selected === entry.name ? `> ${entry.name}` : entry.name

        return <BlockLink key={entry.href} href={entry.href}>{label}</BlockLink>
      })}
    </VerticalListLayout>
    {children}
  </>)
}

The SidebarNavigation component is used in other more specific components like the ListSidebar. In this example it doesn't do a whole lot, but it would eventually require business logic for handling things like the button.

import SidebarNavigation from '../../components/organisms/sidebar-navigation'
import Button from '../atoms/button'

export default function ListSidebar({category, name, description, sidenav}) {
  const handleClick = () => {
    alert('Add List Functionality not implemented!')
  }

  return (
    <SidebarNavigation selected={category} title={name} subtitle={description} sidenav={sidenav}>
      <Button onClick={handleClick} label="Add List" />
    </SidebarNavigation>
  )
}

Rules of Organisms

A complex component made up of multiple atoms and/or molecules and/or other organisms
Can have its own markup & styles
Can fetch application-specific data
Can implement application-specific business logic
Can be connected to application (or higher level) state
Can be tightly coupled with a specific area (UI and/or Logic) of the app
Can be organized into sub-folders by logical categorization (feature, page, etc...)

Templates

Templates are a way to ensure that the Pages of your app are consistent. They handle creating the layout, and make it easy to know where specific areas of content or functionality need to go. There are a number of ways to create templates. The way I'm going to show is very explicit, and I like it because it helps force high-level separation of application logic (into pages and organisms) and application layout (in templates).

Examples of Templates

In React this is not a pattern I've seen very often, although I have seen at least a couple articles where it was discussed. That may be because people more often talk about lower-level (atom/molecule/organism) or higher-level (page) components 🤷‍♂️

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

export default function TemplateSidebarContent({ header, sidebar, content }) {
  return (
    <>
      <header className={styles.header}>
        {header}
      </header>
      <section className={styles.content}>
        <aside className={styles.sidebar}>
          {sidebar}
        </aside>
        <main className={styles.main}>
          {content}
        </main>
      </section>
    </>
  )
}

The component really doesn't do much right?! The css import does most of the heavy lifting, but even then it's not much - primarily setting flex properties, widths, and heights. It's not until this component is composed into Pages that the good times start rolling 🥳 as each of those props (header/sidebar/content) will be an individual component that we can count on to be placed on screen exactly as intended. 🤓

A template, highlighting the Header, Sidebar, and Content

Template Variations

It can be tempting to start adding additional props to templates to support 'variations' like a border, a background color, or other minor stylistic differences. Is this something I've done? 👀 Yes. Is this something you should do? No. Is it the end of the world if you do? Also no.

Just consider that the more thought that has to go into using the template component, the less useful it becomes. The beauty is in its simplicity and not having to worry about high-level details of how the site is laid out on the page.

Tiered Templates

It's worth noting that templates don't have to be implemented only at the page level. Suppose you're using a template to lay out the highest-level elements of the site (header, sidebar, content area) as you'll see in the next section, you may find that you also want templates to lay out content within the content area!

Templates are an excellent choice anywhere a consistent layout is reused with different content.

Rules of Templates

A component that facilitates the layout of multiple organisms
Can have its own markup & styles.
Can accept & pass props as required.
Should not access application (or higher level) state
Should not have any non-ui/layout related side effects
Should not implement any application-specific business logic

Pages

Pages are the final piece of the puzzle, and each one will implement a specific Template. Pages are distinctly separate from Routing, and while I'm not covering Routing in this article it should at least be said that in the same way each Page implements a Template, each Route should implement a Page.

Because I'm using React with Next.js, which has page-based routing, I've made a specific delineation in my project structure. All Atomic Design Pages live under /src/components/pages, and all Routes live under /src/pages. Excluding the special _app.js, there is a 1:1 ratio of component pages to route pages.

Examples of Pages

import TemplateSidebarContent from '../templates/template-sidebar-content'
import UserHeader from '../../components/organisms/user-header'
import CategoryDetails from '../../components/organisms/category-details'
import CategorySidebar from '../../components/organisms/category-sidebar'

export default function Category({name, description, category, categories, sidenav}) {
  return <TemplateSidebarContent
    header={<UserHeader />}
    sidebar={<CategorySidebar category={category} name={name} description={description} sidenav={sidenav} />}
    content={<CategoryDetails category={category} />}
  />
}

For each page I'll pick both the template and the components to fill the template. These could be fairly general-use like the UserHeader, which is used on all pages. They can also be specific use like the CategoryDetails organism. As mentioned in the Templates section, CategoryDetails could implement another template if needed! Heck, either of the other components could implement another template as well if the content were complex enough!

Rules of Pages

A component that implements a particular template
Can fetch application-specific data
Can implement application-specific business logic
Can be connected to application (or higher level) state
Should not have its own markup & styles

A Note on Routes

You may find, depending on your particular framework, that Routes do more of the heavy lifting than pages. In Next.js this will probably be the case, since it is in the Routes where you have to work with the special getStaticProps and getServerSideProps.

That's not a problem, but I would pick just one, Pages or Routes, to put this logic. Whichever of those you don't pick should be a more basic implementation.

In the sample app, I've put the data fetching and other logic into the Route to simplify the Page implementation.

Conclusion

Hopefully this has given you some concrete examples of developing with Atomic Design and a new way to think about structuring your applications.

I want to reiterate the quote from Brad Frost that this is primarily "a mental model to help us think of our user interfaces as both a cohesive whole and a collection of parts at the same time." As you continue developing component based applications, always consider how you structure those components to be as generic, flexible, and reusable as possible.

One Rule to Rule Them All

To that end I have one more rule that probably deserves its own post, but has caused me enough headache over the years that it bears mentioning here. If you forget everything else, remember this!

Assign margins to a component via its parent, never to the component itself.

Why not? Consider that each component you create should be a self contained unit that functions predictably within its own bounds. Margins break this pattern by creating space outside of the element itself, and can lead to unpredictability or variable behavior due to margin collapsing.

Consider the above div with margin, padding, and a border. The border of the element is essentially where the component should end. If the margin is applied to the div component itself, reusing the component in other contexts may have unintended layout and display consequences.

If the div needs a margin, the better approach is to specifically target it in the parent component.

Margins create extra space around an element. In contrast, padding creates extra space within an element.

— MDN Web Docs, emphasis added

An example from the sample app is the VerticalListLayout component. It renders a collection of children that are intended to be BlockLinks.

export default function VerticalListLayout({children}) {
  return <div className={[styles.verticalListLayout, 'molecule'].join(' ')}>{children}</div>
}

It is also intended that every BlockLink has a certain layout within the parent component, including specific margins. If I had created this component in a vacuum, I might have applied the margin to each BlockLink, since that's how it needs to appear in the list, but that would cause problems reusing the BlockLink in other contexts. To prevent this the margin is assigned from the VerticalListLayout itself, applied to any first-level children.

.verticalListLayout > * {
  margin: 0 var(--spacing-md) var(--spacing-lg);
}

Questions? Comments?

Hope you found this informative, maybe even helpful! Let me know on Twitter: @BenjaminWFox.

How to Configure Azure AD B2C Authentication with Next.js

Ben Fox — Tue, 25 Aug 2020 17:04:24 +0000

Configuring authentication with Azure B2C in Next.js is not a particularly straight forward process. We'll look at how to facilitate this using the NextAuth.js library.

Authentication with Azure B2C and Next.js

Authentication with Next.js is, at least for me, a bit of a nebulous problem, especially if development requirements are not 100% solidified. Since you have access to both the client and server(less) environments, you could handle authentication purely in the client, on the server, or with a mix of both.

Add in the task of configuring authentication with Azure B2C and complications are compounded. Azure AD B2C is many things but straight-forward is not one of them at least as far as I have found.

Please note that Azure AD B2C is not the same thing as Azure AD. Azure AD B2C (also referred to here as Azure B2C) is an identity & access management solution specifically for customer facing applications.

Enter NextAuth.js

NextAuth.js is a framework that aims to make authentication with Next.js a (relatively) simple and painless process. After setting initial configuration values the heavy lifting is done for you via dynamic routes in Next.js. From there, you have the flexibility of setting & checking sessions on both the client and server.

NextAuth + Azure B2C

Setting up Azure B2C for authentication with NextAuth, though, is still a bit of a process. It requires some initial setup & configuration in the Azure Portal, as well as a custom configuration in NextAuth.

My goal with this article is to detail all of the necessary steps to create a minimal authentication setup in Next.js using Azure B2C and NextAuth.js, and specifically to share the NextAuth configuration file I'm using. I'm not going to dive deep into the workings Azure B2C, Next.js, or NextAuth.

Required Steps

Example Repository
Set up Azure B2C
Create a Next.js App
Test the NextAuth Signin
Add Signout Functionality

Example Repository

If you want to go straight to the implementation, take a look at the repository for the full code, as well as two different PRs showing the initial diff to create basic working authentication, as well as the diff to add signout functionality.

Set up Azure B2C

Create a Subscription and Azure AD B2C Tenant

This is probably the most complex part of the process. Since you're here, I'd assume that you already have access to an Azure subscription. Possibly even an Azure AD B2C Tenant...

BUT if one or the other of those are not the case you will have to start here, which will walk you through the process of creating a Subscription (as a prerequisite) if you don't have one, then through the process of creating hte Azure AD B2C Tenant.

Pay special attention to the Initial domain name you create, which you will use in a later step for NextAuth configuration.

Create an App Registration

Next up is another walkthrough from Microsoft detailing how to create an App Registration. This app registration, which lives within your Azure B2C Tenant, will be the authority that authenticates users and issues tokens.

Pay special attention to the Client ID & Client Secret you create, which you will use in a later step for NextAuth configuration.

Add Additional Redirect URIs

Go back to the Authentication section in the App Registration and add two additional Redirect URIs which will be used by NextAuth:

http://localhost:3000/api/auth/callback/azureb2c
http://localhost:3000/auth/signout

Also make sure you checked the two checkboxes under 'Implicit grant'

Create a User Flow

Ok...one more walkthrough from Microsoft on creating the User Flow. User Flows are the managed interfaces that users will use for signup, signin, profile editing, and password resets.

Note that you may want to add additional properties to be either collected or returned from the user flow!

The basic pre-generated user flows are enough to get started, but as needs evolve the user flows can be fully customized to provide any functionality desired during the registration/authentication process.

Create a Next.js App

That should be all the setup & configuration needed on the Azure B2C side, so let's get a Next.js environment set up. I named mine nextjs-azureb2c-nextauth when I ran the following commands:

npx create-next-app
cd nextjs-azureb2c-nextauth
npm install next-auth

Add NextAuth Config & Files

There are four files we need to create or modify in order to get this working which are the .env, next.config.js, _app.js and [...nextauth].js files. Then we'll update the index.js file to prove that it's working.

.env

To set this up, copy and rename (or just rename) the .env.example file in the root of the project to .env. You'll need to update this with four values from Azure B2C:

AUTH_CLIENT_ID - The App Registration client id.
AUTH_CLIENT_SECRET - The App Registration client secret. If you didn't save the value when you created it the first time, just create a new one.
AUTH_TENANT_NAME - The 'Initial domain name' from when you initially set up Azure B2C.
AUTH_TENANT_GUID - The GUID of the B2C Tenant, it can be found in the "Directory + subscription" blade in the Azure top nav bar, this icon:
USER_FLOW - The name of your signup/signin user flow, probably starting with B2C_1_

next.config.js

Next.js needs this file to read your .env values and provide them to the application. Create the file in the root of your project. It should look like:

// next.config.js
require('dotenv').config()

module.exports = {
  env: {
    NEXTAUTH_URL: process.env.NEXTAUTH_URL,
    AUTH_CLIENT_ID: process.env.AUTH_CLIENT_ID,
    AUTH_CLIENT_SECRET: process.env.AUTH_CLIENT_SECRET,
    AUTH_TENANT_NAME: process.env.AUTH_TENANT_NAME,
    AUTH_TENANT_GUID: process.env.AUTH_TENANT_GUID,
    JWT_SECRET: process.env.JWT_SECRET,
    USER_FLOW: process.env.USER_FLOW,
  }
}

I'm not sure the require('dotenv').config() is even required, but it isn't breaking anything at the moment.

_app.js

We have to wrap pages/_app.js in the NextAuth Provider component in order to have access to the session, and to provide NextAuth with the NEXTAUTH_URL, which is required. Update the file to look like:

// pages/_app.js
import '../styles/globals.css'
import { Provider as AuthProvider } from 'next-auth/client'

function MyApp({ Component, pageProps }) {
  const { session } = pageProps

  return (
    <AuthProvider options={{ site: process.env.NEXTAUTH_URL }} session={session}>
      <Component {...pageProps} />)
    </AuthProvider>
  )
}

export default MyApp

[...nextauth.js]

Finally we need to add our NextAuth configuration for Azure AD B2C to the dynamic route file. This lives in pages/api/auth/[...nextauth].js. For this basic example, you shouldn't need to make any changes to the options below - all of the Azure AD B2C tenant-specific customizations are pulled from .env variables.

// pages/api/auth/[...nextauth].js
import NextAuth from 'next-auth'

const tenantName = process.env.AUTH_TENANT_NAME
const tenantGuid = process.env.AUTH_TENANT_GUID
const userFlow = process.env.USER_FLOW

const options = {
  session: {
    jwt: true,
  },
  secret: process.env.JWT_SECRET,
  pages: {
    signOut: '/auth/signout',
  },
  providers: [
    {
      id: 'azureb2c',
      name: 'Azure B2C',
      type: 'oauth',
      version: '2.0',
      debug: true,
      scope: 'offline_access openid',
      params: {
        grant_type: 'authorization_code',
      },
      accessTokenUrl: `https://${tenantName}.b2clogin.com/${tenantName}.onmicrosoft.com/${userFlow}/oauth2/v2.0/token`,
      // requestTokenUrl: `https://login.microsoftonline.com/${process.env.AUTH_TENANT_GUID}/oauth2/v2.0/token`,
      authorizationUrl: `https://${tenantName}.b2clogin.com/${tenantName}.onmicrosoft.com/${userFlow}/oauth2/v2.0/authorize?response_type=code+id_token&response_mode=form_post`,
      profileUrl: 'https://graph.microsoft.com/oidc/userinfo',
      profile: (profile) => {
        console.log('THE PROFILE', profile)

        return {
          id: profile.oid,
          fName: profile.given_name,
          lName: profile.surname,
          email: profile.emails.length ? profile.emails[0] : null,
        }
      },
      clientId: process.env.AUTH_CLIENT_ID,
      clientSecret: process.env.AUTH_CLIENT_SECRET,
      idToken: true,
      state: false,
    },
  ],
}

export default (req, res) => NextAuth(req, res, options)

Some Notes

The providers.id string must match what you've used in your callback (Redirect URI) in Azure B2C, which for us was http://localhost:3000/api/auth/callback/azureb2c.

The profile property is used to map values returned from the authorization flow to the users token. Auzre AD B2C does some weird stuff, like returning an array of email addresses, so if you want any of these available make sure to understand the values that are coming back in the profile obejct and map them accordingly to the return properties.

The state property is false. I had some issues when NextAuth release v3 and this was enabled, but it doesn't sound like disabling it should be a problem.

See more details on all the options for using a custom provider here.

Test the NextAuth Signin

You should now (assuming you're running the project) be able to navigate to http://localhost:3000/api/auth/signin/azureb2c and run through the login flow! In order to actually test that it's working though, you can add a little code to your pages/index.js file to check for the session - the useSession hook!

// pages/index.js
// ...
import styles from '../styles/Home.module.css'
import { useSession } from 'next-auth/client'

export default function Home() {
  const [session, loading] = useSession()

  return ( //...

Then, anywhere else in the file you can add some conditional logic to show messaging based on whether or not there is a user session:

// pages/index.js
// ...
{session ?
  <>
    <div className={styles.grid}>
    You are signed in!
    </div>
  </>
  : 
  <div>
    You are not signed in! <a style={{color: 'blue'}} href="/api/auth/signin">You must sign in to access documentation!</a>
  </div>
}
// ...

Add Signout Functionality

NextAuth exposes a SignOut function that we can leverage, but this will only clear the local session. If the user signs out via this method, then signs in again via Azure AD B2C, they will not be prompted to re-enter their credentials since a session in B2C still exists.

That may not be a problem for you 🤷‍♂️ but if it is you can call the Azure B2C signout url, then redirect the user to the NextAuth signout url. The B2C sign-out URL looks like:

https://${process.env.AUTH_TENANT_NAME}.b2clogin.com/${process.env.AUTH_TENANT_NAME}.onmicrosoft.com/${process.env.USER_FLOW}/oauth2/v2.0/logout?post_logout_redirect_uri=${process.env.NEXTAUTH_URL}/auth/signout

Wherever you want the user to be able to log out, you can include that in a link. If you don't need the full B2C signout, you can also call the NextAuth API signout route instead:

// Addition to `index.js`
// Can also `useSession` to show only if signed in!
// ...
<div>
  <p>You are signed in! You can also sign out if you like.</p>
  <ul>
    <li>
      <a style={{color: 'blue'}} href="/api/auth/signout/azureb2c">Sign Out (API)</a>
    </li>
    <li>
      <a style={{color: 'blue'}} href={`https://${process.env.AUTH_TENANT_NAME}.b2clogin.com/${process.env.AUTH_TENANT_NAME}.onmicrosoft.com/${process.env.USER_FLOW}/oauth2/v2.0/logout?post_logout_redirect_uri=${process.env.NEXTAUTH_URL}/auth/signout`}>Sign Out (FULL)</a>
    </li>
  </ul>
</div>
// ...

If you notice on the end of the url, we've specified the post_logout_redirect_uri set to ${process.env.NEXTAUTH_URL}/auth/signout - so we also need to make another route to facilitate this. The signOut method only works on the client, so this can not be an API route, and it should not run on the server. Create the file at pages/auth/signout.js

// pages/auth/signout.js
import { signOut } from 'next-auth/client'

export default function Signout() {
  if (typeof window !== 'undefined') {
    signOut({ callbackUrl: process.env.NEXTAUTH_URL })
  }

  return null
}

And Is That It?

In theory you're all set...but given some of the idiosyncrasies I've experienced with Azure (and sometimes Next.js) maybe not? Hopefully this at least helps you in the right direction if you were also struggling with this integration. My experience so far with Azure AD B2C has not been particularly pleasant, but given that it's significantly cheaper than a lot of the alternatives out there I'll be sticking with it for the forseeable future.

Issues? Questions? Comments?

Find me on Twitter — @BenjaminWFox

DEV Community: Ben Fox

Next.js Setup | ESLint, Jest, React Testing Library, and Absolute Imports

A comprehensive step-by-step guide to configuring Jest, React Testing Library, ESLint, and Absolute Path Aliases in a Next.js project.

The problem?

The solution?

What We’ll Cover

Assumptions

A note before we start

Final Repository

Next.js: Installing

ESLint: Install & Configure

Add & Run the Lint Script

Two Final Notes on Linting

Jest & Testing Library: Install, Configure, Implement

Install Dependencies

Create Config Files

Write a Test File

Add a Test Script

Configuring Path Aliases/Absolute Imports

Create a Test Component

Try The Component

Next.js & VSCode

Update ESLint

Update Jest

Important to remember

Complete!

Questions? Comments?

How to Think in Next.js

Clients and Servers and Node Oh My

Review: SPA vs Next.js

Execution Context

Your Application is Starbucks

Pages

API Routes

Further Reading

Questions? Comments?

How Does a Website Get its Data, and Why Does it Matter?

Servers to No Servers to Serverless

Say What Now?

Traditional Server App

Single Page App

Next.js or Hybrid App

At the End

Further Reading

Questions? Comments?

Atomic Design for Developers: Better Component Composition and Organization

A practical guide to developing component based sites and apps around the Atomic Design methodology.

My Goal

Contents

Backstory

Atomic Design

Why this Article

Why NOT this Article

Sample Code

Atoms

Examples of Atoms

Rules of Atoms

Molecules

Examples of Molecules

A Nebulous Molecule

Rules of Molecules

Organisms

Examples of Organisms

Rules of Organisms

Templates

Examples of Templates

Template Variations

Tiered Templates

Rules of Templates

Pages

Examples of Pages

Rules of Pages

A Note on Routes

Conclusion

One Rule to Rule Them All

Questions? Comments?

How to Configure Azure AD B2C Authentication with Next.js

Authentication with Azure B2C and Next.js

Enter NextAuth.js

NextAuth + Azure B2C