
At Echobind, we all have up to 8 hours per week of self-directed investment time, where we stop working on client projects and we can build and learn the things that help us improve our craft. One week I decided to see what kind of simple game I could build with the full-stack Jamstack in one day; I came up with Emoji Battle, a game where all you have to do is click emoji. Here's how I built version 1.

The Emoji Battle GitHub repo is [here](https://github.com/mcavaliere/emoji-battle). This article covers how I built [version 0.1](https://github.com/mcavaliere/emoji-battle/tree/v0.1.0).

## Technologies used

* [Next.js](https://nextjs.org/)
* [Prisma ORM](https://www.prisma.io/)
* [SWR](https://swr.vercel.app/)
* [Chakra-UI](https://chakra-ui.com/)
* [NextAuth.js](https://next-auth.js.org/)

## Barely a game

In one day, I didn't expect to build the next Animal Crossing. But I wanted to see what I could come up with that would achieve the following:

* It would qualify as a "game" by being fully interactive. Anyone could log in and play it.
* It had to be self-teaching; you wouldn't need instructions to play.
* It had to use the full-stack Jamstack tools that I typically use; Next.js, Prisma, Chakra-UI, and the other libs in my current stack.

In order to get this done I knew I had to:

* Make sure it wasn't elaborate. I could spend hours thinking of game mechanics; I didn't have that kind of time.
* Build the simplest features.
* Build the simplest UI.
* NOT build all of the things.

## Decisions, decisions, decisions

So I limited myself to less than an hour thinking on it. The idea of using Emoji as the main UI element of the game was a practical decision: emojis are fun, universal, versatile, and textual. You don't need any UI to use them. That decision saved tons of time by itself.

The next time-saving idea I had was to make the game mechanics simple for v1. It would be easy to go down a rabbit hole thinking of different ways for players to compete, so I settled on the simplest of UIs: all you have to do is click. I found a react library for showing a list of emoji, and when you click on one it would register a vote for that emoji. The emoji with the most votes shows at the top of the leaderboard and becomes bigger and bigger.

## Authentication

I knew from the start I wanted users to log in to play. But I also wanted it frictionless; it should be easy for me to set up and easy for users to log in.

[NextAuth.js](https://next-auth.js.org/) is my default authentication solution for Next.js, so I dropped it in with the [Prisma adapter](https://next-auth.js.org/adapters/prisma). And since the Github API keys are among the easiest to set up (and most people I would show this game to are developers), I set up my API key and one-click GitHub login was working in no time.

Note that at the time I developed Emoji Battle v1, I used NextAuth v3. I've since upgraded to v4 since it came out of beta. If you start using NextAuth, I recommend starting with the latest version (v4 as of this writing).

## Page Layout

To limit how long I should spend on layout, I decided that this version would be desktop-only. Most people I demoed it to (at meetups or lunch-and-learns) would be using desktop browsers anyway.

I wanted a header up top with the name of the game, and below it, from left to right, the EmojiPicker, the Leaderboard, and the UserList. This was achieved easily with a Chakra-UI [`HStack`](https://chakra-ui.com/docs/layout/stack#stack-items-horizontally) (horizontal stack):


```js
//
// pages/index.tsx
//
const Home: NextPage = () => {
  // ...

  return (
    <Container maxW='100%' p={10}>
      <Heading mb={5} textAlign='center'>
        Emoji 🤪 ⚔️ 😀 Battle
      </Heading>
      <HStack spacing={20} alignItems='flex-start'>
        <EmojiPicker />
        <Leaderboard />
        <UserList />
      </HStack>
    </Container>
  )
}

export default Home;
```

Pretty clean right? Chakra-UI is 🔥. Later I would add some customization which displays the user's name if they're logged in, using the NextAuth.js `useSession` hook.


## Planning & building the React components

The interface was going to do a few things:

* List a bunch of emoji that players could click to vote
* Show a leaderboard of the emoji that were voted on (sorted by the most votes)
* Show a list of players

So I ended up with a few components:

* EmojiPicker: a list of emoji that players can click on
* Leaderboard: a list of emoji that were voted on sorted descending by vote count
* UserList: a list of the names of logged-in players

In React, you want to reduce renders as much as possible to preserve performance. To this end, I made each component in charge of fetching the data it needs to render as opposed to fetching at the page level so that a fetch would only cause the component to potentially re-render instead of the entire page.

For data fetching, I'd use Vercel's [SWR](https://swr.vercel.app/) library which is simple to use and handles keeping the data fresh automatically. This wouldn't give us real-time updates to the UI, but we could make it update components quickly *enough* that it was almost real-time, and made it feel like almost a real game. (In later versions, we'd make it true real-time with [Ably Realtime](https://ably.com/). For now, data polling with SWR would be good enough.)


### The EmojiPicker component

The first version of the picker code looks like this:

```js
// ... imports and types ...

export const EmojiPicker: FC<EmojiPickerProps> = ({ afterSelect }) => {
  const [emojiSet, setEmojiSet] = useState<EmojiSet>('apple');

  const handleEmojiSelect = async (emoji: any) => {
    await fetch('/api/emoji/create', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Accept: 'application/json',
      },
      body: JSON.stringify({ emoji }),
    });

    if (afterSelect) {
      afterSelect(emoji);
    }
  };

  return (
    <Container textAlign='center'>
      <Heading size='md' mb={5}>
        Pick an emoji!
      </Heading>
      <HStack justifyContent='center' mb={5}>
        <Button onClick={() => setEmojiSet('apple')}>Apple</Button>
        <Button onClick={() => setEmojiSet('google')}>Google</Button>
        <Button onClick={() => setEmojiSet('twitter')}>Twitter</Button>
        <Button onClick={() => setEmojiSet('facebook')}>Facebook</Button>
      </HStack>
      <Picker set={emojiSet} onSelect={handleEmojiSelect} />
    </Container>
  );
};
```

Breaking this down:

* The `<Picker>` from the `emoji-mart` package is what displays the emoji. We give it a `handleEmojiSelect` handler which makes a POST request to a Next.js API route we talk about later in the article. This API route will record a single vote for the clicked emoji and current user.
* `handleEmojiSelect` will call an optional `afterSelect` function if it's passed in via a prop. This is useful for letting us update other parts of the app after a vote is cast if we need to.
* Since `emoji-mart`'s `Picker` component lets us select from four emoji sets, we include a `Button` for each set. We track the currently selected set with a `useState` hook and set the current set when any button is clicked.


### The UserList component
The `Leaderboard` and `UserList` are going to both follow a common pattern: they fetch data and render it. Easy peasy.

Here's the `UserList` component:

```js
// ... imports and types ...

export const UserList: FC = () => {
  const { data: usersData, error: usersError } = useSWR(
    `/api/users/list`,
    fetcher,
    { refreshInterval: 200 }
  );

  if (usersError) return <div>failed to load</div>;
  if (!usersData?.users) return <div>loading...</div>;

  const { users } = usersData;

  return (
    <Container textAlign='center'>
      <Heading size='md' mb={5}>
        Who&#39;s battling?
      </Heading>
      <VStack>
        {users.map(({ id, name }) => (
          <Text key={id}>{name}</Text>
        ))}
      </VStack>
    </Container>
  );
};
```

**Breakdown:**

* `useSWR` lets the `SWR` library do all of the work here for us. It fetches the data from the API and keeps it fresh. We tell it to refresh at a 200ms interval so that there's very little delay between a user joining and the list updating.
* Our error state and loading state are no-frills. Keep it simple!
* The rest is up to Chakra-UI. We use a [`VStack`](https://chakra-ui.com/docs/layout/stack#import) to display a vertical list of users' names.

### The Leaderboard component

The `Leaderboard` follows the same fetch-and-render pattern as the `UserList` component, but has one tiny feature that is one of the minimal game elements of this version of the project: it uses some styling to make an emoji bigger based on the number of votes it has.

Here's the `Leaderboard` :

```js
// ... imports and types ...

export const Leaderboard: FC = () => {
  const { data: emojiData, error: listError } = useSWR(
    `/api/emoji/list`,
    fetcher,
    { refreshInterval: 200 }
  );

  if (listError) return <div>failed to load</div>;
  if (!emojiData?.emojis) return <div>loading...</div>;

  const { emojis } = emojiData;

  return (
    <Container textAlign='center'>
      <Heading size='md' mb={5}>
        Leaderboard
      </Heading>
      <VStack>
        {emojis.map((e) => (
          <Container key='e.native'>
            <span style={{ fontSize: 15 + e._count.votes * 5 }}>
              {e.native}
            </span>

            <Text fontSize='xs'>{e._count.votes} votes</Text>
          </Container>
        ))}
      </VStack>
    </Container>
  );
};

```

**Breakdown:**

* The same fetching as above in the `UserList`.
* The same error and loading states.
* The `emojis` array will return from the API with a vote count. So when rendering it, we take a base `fontSize` of 15px and add 5px for every vote. The 5x multiplier makes it obvious that an emoji grows when someone votes on it. (When I did it with a 1px increase, the growing was barely visible.)


## Planning the data model

Since I wanted to require logins to the game, there would certainly be a User table. This part was easy since I knew I was using NextAuth.js and Prisma, and NextAuth's Prisma adapter has a template for this already (along with tables for Accounts,  Sessions, and VerificationTokens)

The only remaining data I had to track for v1 was the votes on each emoji. So I added a Vote model and an Emoji model to my `schema.prisma`.

```js
model Emoji {
  id         Int    @id @default(autoincrement())
  name       String
  externalId String @map(name: "external_id")
  native     String
  unified    String @unique
  colons     String
  votes      Vote[]
}

model Vote {
  id        Int      @id @default(autoincrement())
  userId    Int
  emojiId   Int      @map(name: "emoji_id")
  createdAt DateTime @default(now())
  updatedAt DateTime @default(now())
  User      User     @relation(fields: [userId], references: [id])
  Emoji     Emoji    @relation(fields: [emojiId], references: [id])
}
```

Note the relationships: a `Vote` *belongs to* a `User` and an `Emoji`. An `Emoji` *has many* `Vote`s.


## Planning & building the API calls

There were only a few things the app needed to do with data:

* Let a user click an emoji to vote for it.
* Pull up the voted-on emoji sorted by most votes.
* Show a list of people currently playing.

This meant we only needed 3 Next.js API routes:

* `POST /emoji/create` (`/api/pages/emoji/create.ts`) - for voting. Yes, this will be renamed!
* `GET /emoji/list` (`/api/pages/emoji/list.ts`) - for getting the list of voted-on emoji.
* `GET /users/list` (`/api/pages/users/list.ts`) - for getting the list of players.

Note that Next.js doesn't have much API structure built-in. When I scaffold projects like this fast, I typically use a loose RESTful API structure to keep things simple. The benefit is that you don't have to overthink things and can move quickly. Then if and when the app grows, you can reassess whether you want to set up a GraphQL API, or a true REST API, or use an API framework like Nest.js, and so on.

All API routes would follow a similar pattern:

```js
import type { NextApiRequest, NextApiResponse } from 'next';
import { User } from '@prisma/client';
// Import a single prisma instance so we don't open unnecessary database connections.
import prisma from '../../../lib/prismaClientInstance';

// Define what the data looks like. The payload for /pages/api/users/list.ts is below as an example.
type Data = {
  users?: User[];
  error?: unknown;
};

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  try {
    const users = // ... Prisma.js database calls go here!

    res.status(200).json({ users });
  } catch (error) {
    // I typically just add a log, until the project is ready for connecting to an error handling service like Sentry.
    console.log(`error`, error);
    res.status(500).json({ error });
  }
}

```

Prisma does all the work of getting or creating data. Notable is that the voting endpoint  `/emoji/create` does a bit more work:

```js
// ...
  // Make sure it's a POST request.
  if (req.method !== 'POST') {
    return res.status(405).end();
  }

  // Ensure we're logged in to vote. Otherwise return a 401 unauthorized.
  const session = await getSession({ req });
  if (!session) {
    return res.status(401);
  }

  // ...


  // Insert the emoji into the database, if it's not already there.
  const emoji = await prisma.emoji.upsert({
    create: {
      externalId: id,
      name,
      native,
      colons,
      unified,
    },
    update: {},
    where: {
      unified,
    },
  });

  const vote = await prisma.vote.create({
    data: {
      Emoji: {
        connect: {
          id: emoji.id,
        },
      },
      User: {
        connect: {
          // @ts-ignore
          id: user.id,
        },
      },
    },
  });

  // ...

```

You can see that here we do an `upsert` into the `Emoji` table. This table is initially empty. The emoji are all stored in the [emoji-mart library](https://github.com/missive/emoji-mart). But to associate them with `Vote`s, we need to store them the first time anyone votes on them.

And yes, I cheated with the `@ts-ignore`. MVP, baby! In retrospect I could have used the TypeScript [non-null assertion operator (!)](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator).

---

The initial version of Emoji Battle was just enough for me to demo at the Prisma Meetup and have all the viewers log in and start clicking around. It was *barely* fun and interactive, and looked sorta messy, but was a great example of what I could throw together with this stack in a very short period.

Even more so, it was an excellent foundation to build on. Since then I've added realtime interaction, some animation, better layout, and am in the process of creating more game mechanics.

I'm planning more articles on this in the future. In the meantime check out these links:

* [Emoji Battle on GitHub](https://github.com/mcavaliere/emoji-battle)
* [v0.1 source](https://github.com/mcavaliere/emoji-battle/releases/tag/v0.1.0) (for this article) on GitHub
* The [Prisma Online Meetup](https://www.youtube.com/watch?v=II3a0WyIhXs&ab_channel=Prisma) where I demoed Emoji Battle for the Prisma Meetup and discussed the stack.



Building a Jamstack Game in a Day


While building the photo gallery app I cover in [Cut Into The Jamstack](/), I needed a UI that would allow users to type or paste emails and have them validated on the client side, very much like the email chip input field in Gmail. I didn't find an existing plug-and-play one, aside from this codepen which used class components and custom styling, so I decided to build a new one with React functional components and Chakra-UI. As it turns out this was pretty easy. Here's the breakdown.

If you want to jump to the code, here's the [Codesandbox for my version of the email chip input](https://codesandbox.io/s/chakra-ui-email-chip-input-47yh1?file=/src/components/EmailChipInput.js).

## Creating and styling presentational components

Visually, the UI has 2 main parts:

* A list of email "chips": highlighted emails that have been input already, with buttons to allow removal; and
* The email form field input.

I decided to make these "dumb" or "presentational" React components; they simply accept props and render UI, without any state or logic inside them. This way the UI stays pretty separate from those other pieces (and we follow the separation of concerns principle well).

### The Chip & ChipList components

Luckily, Chakra-UI already had a component that looked exactly like I wanted the Chip UI to look: the [`Tag`](https://chakra-ui.com/docs/layout/wrap) component. It even has a variant with a close button, so here's what the chip component came out looking like:

```js
/**
 * Represents an email added to the list. Highlighted with a close button for removal.
 */
export const Chip = ({ email, onCloseClick }) => (
  <Tag key={email} borderRadius="full" variant="solid" colorScheme="green">
    <TagLabel>{email}</TagLabel>
    <TagCloseButton
      onClick={() => {
        // TBD
      }}
    />
  </Tag>
);
```

To contain the chips, Chakra-UI has a lot of container components like `Flex` and `Stack`. In this case I want the chips to wrap to the next line if there are too many, so I used the [`Wrap`](https://chakra-ui.com/docs/layout/wrap) component:

```js
/**
 * A horizontal stack of chips. Like a Pringles can on its side.
 */
export const ChipList = ({ emails = [], onCloseClick }) => (
  <Wrap spacing={1} mb={3}>
    {emails.map((email) => (
      <Chip email={email} key={email} onCloseClick={onCloseClick} />
    ))}
  </Wrap>
);
```

### The ChipEmailInput component

And the input field just gets wrapped in a `Box`:

```js
/**
 * Form field wrapper.
 */
export const ChipEmailInput = ({ ...rest }) => (
  <Box>
    <Input type="email" {...rest} />
  </Box>
);
```

## Stateless utility functions

That's the presentation; now let's make our code do stuff.

Our `EmailChipInput` component will take one prop for an initial list of emails, in case we want to prepopulate the list.

```js
export const EmailChipInput = ({ initialEmails = [] }) => {
  // ...
}
```

We'll need a few utility functions. The first one, `isValidEmail()` can live outside the component since it doesn't have any state dependencies.

```js
const EMAIL_REGEXP = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
const isValidEmail = (email) => EMAIL_REGEXP.test(email);
```

The above regexp is one I grabbed from online, since email validation is so common. PSA: if you aren't comfortable with regular expressions, please start learning them now 😀 They'll change your life.

The other utility functions will be dependent on what's in our component state. So let's define the state we need.

## Adding state

The only two pieces of UI state we care about are:

* The current text in the input field; and
* The current list of emails.

So we'll have two `useState` calls for these:

```js
  const [inputValue, setInputValue] = useState("");
  const [emails, setEmails] = useState(initialEmails);
```

### Stateful utility functions

Now we can define our state-dependent utility functions:

```js
  // Checks whether we've added this email already.
  const emailChipExists = (email) => emails.includes(email);

  // Add an email to the list, if it's valid and isn't already there.
  const addEmails = (emailsToAdd) => {
    const validatedEmails = emailsToAdd
      .map((e) => e.trim())
      .filter((email) => isValidEmail(email) && !emailChipExists(email));

    const newEmails = [...emails, ...validatedEmails];

    setEmails(newEmails);
    setInputValue("");
  };

  // Remove an email from the list.
  const removeEmail = (email) => {
    const index = emails.findIndex((e) => e === email);
    if (index !== -1) {
      const newEmails = [...emails];
      newEmails.splice(index, 1);
      setEmails(newEmails);
    }
  };
```

That covers adding and removing the emails from the list, and tangentially clearing the input field when an email is added. If we wanted to get really picky about separation of concerns here we could have the `setInputValue("")` call in a `useEffect` since it's a side effect; for now this is fine IMO.


## Event handlers

There are a few events we care about for the input field:

* As the user is typing, we want to save the current form field value in state.
* If they press Enter, Tab or a comma, we want to validate what's in the email field and add it to the list.
* If they paste text in the field, we want to split it by commas, and validate and add each email they've pasted.


To achieve this we'll add event handlers for `onChange`, `onKeyDown`, and `onPaste` respectively. These will use the state and utility functions we've already defined.

```js
  // Save input field contents in state when changed.
  const handleChange = (e) => {
    setInputValue(e.target.value);
  };

  // Validate and add the email if we press tab, enter or comma.
  const handleKeyDown = (e) => {
    if (["Enter", "Tab", ","].includes(e.key)) {
      e.preventDefault();

      addEmails([inputValue]);
    }
  };

  // Split and add emails when pasting.
  const handlePaste = (e) => {
    e.preventDefault();

    const pastedData = e.clipboardData.getData("text");
    const pastedEmails = pastedData.split(",");
    addEmails(pastedEmails);
  };
```


## Handling email removal

We do need one last bit of functionality; when the user clicks the close button on a chip, we want to remove that email from the list. This requires a few more steps, because the handler for this will use the state functions (defined in the `EmailChipInput` component) but the actual click will be two levels down inside the `Chip` component.

There are at least two ways to pass a function to a component that is nested several levels down:

* Using the React Context API
* Using prop drilling

I opted to use prop drilling since the context API would be overkill in this case. So we've defined an `onCloseClick` prop on both the `Chip` component and `ChipList`. So if you notice in the `ChipList` we pass on the `onCloseClick` prop to the `Chip` component which is all the prop drilling we need:

```js
export const ChipList = ({ emails = [], onCloseClick }) => (
  <Wrap spacing={1} mb={3}>
    {emails.map((email) => (
      <Chip email={email} key={email} onCloseClick={onCloseClick} />
    ))}
  </Wrap>
);
```

The rest is just defining the handler at the top level:

```js
  const handleCloseClick = (email) => {
    removeEmail(email);
  };
```

## Rendering

The return value of `EmailChipInput` is straightforward. It renders the `ChipList` and the `ChipEmailInput` inside a React fragment, passing in the state and handlers we've defined.

```js
  return (
    <>
      <ChipList emails={emails} onCloseClick={handleCloseClick} />

      <ChipEmailInput
        placeholder="enter emails"
        onPaste={handlePaste}
        onKeyDown={handleKeyDown}
        onChange={handleChange}
        value={inputValue}
      />
    </>
  );
```

Boom, we've got a nice email chip. Full runnable code sandbox is [here](https://codesandbox.io/s/chakra-ui-email-chip-input-47yh1?file=/src/components/EmailChipInput.js).

---














Building an Email Chip Input Field with Chakra-UI


In my previous article I covered a wide array of Next.js basics with examples. Let's tie up that batch of basics with some remaining core essentials.

## The Next.js Link component

Next.js's routing system is great for a number of reasons—not only is it easy to use, but it makes it easy to keep your site's navigation **fast.** Using the Next.js `<Link>` component is how you make this happen.

Under the hood, `<Link>` uses prefetching to load the page you're linking to before you actually navigate to it, which makes it load faster when you do click the link. In addition it knows how to redirect the page and change the URL in the browser without loading more than it needs to.

The result is super-snappy links. Click around this site and you'll see this in effect.

Usage is simple. All you have to remember is to default to using `<Link>` and forget about using a standard `<a>` tags.

```js
//
// pages/page1.js
//
import Link from 'next/link';

export const Page1 = () => (
  <>
    <Link href="/page2">to Page 2</a></Link>
  </>
);

//
// pages/page2.js
//
import Link from 'next/link';

export const Page2 = () => (
  <>
    <Link href="/page1">to Page 1</a></Link>
  </>
);

```

The `<Link>` component has [a bunch of useful options](https://nextjs.org/docs/api-reference/next/link), but the most important think about the component is that you use it exclusively for navigation. Don't put an `<a href="...">` inside a Next.js site or you'll be sacrificing speed.


## The Next.js Image component

Like the `<Link>` component, the Next.js `<Image>` component packs a lot of magic under the hood that makes life easier.

Images are one of the big culprits of slow page loads. The `<Image>` component automatically handles some key things we used to do manually to speed up pages with images on them:

* Lazy loading images to prevent them from blocking the page load
* Using `srcset` to specify different image resolutions for different browser breakpoints
* Caching the image to make subsequent loads fast

So obviously, use the `<Image>` tag whenever you need to load an image, barring any specific exceptions.

Usage is pretty easy. A few things to keep in mind:

* Most of the time you need to specify `width` and `height`. The exception is when the image is static (i.e., it's saved inside the same repo as your app) and when `layout="fill"`.
* You need to specify the `layout` attribute, which tells the image how to stretch relative to its container. This trips me up often, so in addition to [the official docs](https://nextjs.org/docs/api-reference/next/image#layout), [here's a Stackblitz that I find helpful](https://stackblitz.com/edit/nextjs-9m8an5?file=pages%2Findex.js) for seeing the different layouts in action.

## Styling things

By default, Next.js lets you write CSS write inside your JavaScript, and reference it in your React components.

### Importing and using CSS files

CSS files can be imported in Next.js globally for the whole app, using a custom `<App>` component (more on these later in this article) like so:


```css
/*
 * styles/global.css
 */
body {
  background: #f4ebd9;
  color: #0c0910;
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
  font-size: 16px;
}
```

```js
//
// pages/_app.js
//
import '../styles/global.css'


export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}
```

For pages and components, you can use CSS modules; they're files with the .module.css extension that have all of their styles in classes. Next.js can import these as JavaScript objects that you can directly pass to the `className` attribute.

This allows for modular css without having to install any dependencies, which is convenient for getting a project started quickly.

```css
/*
 * styles/MyPage.module.css
 */

.left {
  background: #a393bf;
  float: left;
  height: 300px;
  width: 50%;
}

.right {
  background: #a4303f;
  float: right;
  height: 300px;
  width: 50%;
}
```

```js
import styles from "../styles/MyPage.module.css";

export default function MyPage() {
  return (
    <>
      <div className={styles.left}>Left div</div>
      <div className={styles.right}>Right div</div>
    </>
  );
}
```

### Other ways to style a Next.js app

You don't have to depend on plain ol' CSS to style your Next.js apps if you don't want to, naturally.

[Next.js supports Sass](https://nextjs.org/docs/basic-features/built-in-css-support#sass-support), for example, using either .scss or .sass syntax.

You can also use popular UI libraries like [TailwindCSS](https://tailwindcss.com/docs/guides/nextjs) or [Chakra-UI](https://chakra-ui.com/guides/with-nextjs), the latter of which is my current favorite and I use in [the book](/).


## Global style and behavior with a custom App component

When you need to add components (or context, or styles, etc) that affect all pages in the site, you can define a custom Next.js `<App>` component. Create `pages/_app.js` (or `pages/_app.tsx` for TypeScript projects) with a default export like so:

```js
//
// pages/_app.js
//
export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}
```

The boilerplate code just takes a component and props, and renders them out. Pretty straightforward.

If you want to add a UI library or global stylesheet, this is the place to do it. For example, setting ui Chakra-UI in Next.js looks like this:

```js
import { ChakraProvider } from '@chakra-ui/react'

export default function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  )
}

```

The global `_app.js` is a great place for any global [React Context API](https://reactjs.org/docs/context.html) providers you want in the app. Setups like the below are fairly common:

```js
import { UILibraryProvider } from '@some/ui-library'
import { AuthProvider } from '@some/authentication-library'
import { StateProvider } from '@some/state-library'

export default function MyApp({ Component, pageProps }) {
  return (
    <UILibraryProvider>
      <StateProvider>
        <AuthProvider>
          <Component {...pageProps} />
        </AuthProvider>
      </StateProvider>
    </UILibraryProvider>
  )
}
```

You can also use react hooks like `useEffect` in `_app.js` if you want to run them on every page. Do this sparingly, naturally, since you don't want to run lots of side effects everywhere if you don't need to. Here's an example of how we connect Google Analytics to Next.js using `useEffect` inside `_app.js` (extracted from [the Next.js examples repo](https://github.com/vercel/next.js/tree/canary/examples/with-google-analytics)):

```js
import { ReactElement, ReactNode, useEffect } from 'react';
import { useRouter } from 'next/router';
// This is a wrapper around some basic Google Analytics functions.
import * as analytics from 'lib/analytics';

export default function MyApp({ Component, pageProps }) {
  const router = useRouter();

  useEffect(() => {
    // The handler functions registers a single pageview with Google Analytics.
    const handleRouteChange = (url: URL) => {
      analytics.pageview(url);
    };
    // When the page mounts, add a listener for route changes.
    router.events.on('routeChangeComplete', handleRouteChange);

    // When the page unmounts, remove the listener.
    return () => {
      router.events.off('routeChangeComplete', handleRouteChange);
    };
    // Run this every time router.events changes.
  }, [router.events]);

  return (
    <Component {...pageProps} />
  )
}

```





---

The above should fill in some of the gaps from [Part 1 of this series on Next.js basics](/articles/next-js-fundamentals). At this point you should be able to create pages and routes in Next.js, style them, render images, load and render static content, and keep load times and navigation very fast.


Next.js Fundamentals Part 2


I've chosen Next.js as my framework of choice for building full-stack these days for a number of reasons. Namely:

* It handles common things like routing, server-side rendering, and static-site generation for free.
* It's fast as hell by every metric; load time, navigation, Core Web Vitals and more.
* It's great for SEO (partially because of its speed).
* It's very well supported and keeps improving.
* It's an absolute joy to work with.

So here's part one of a crash course in the core fundamentals of Next.js to get you started working with it.

## App generation with create-next-app

Generating a fresh Next.js app is easy.

```bash
# With yarn
yarn create next-app my-app
# With npx
npx create-next-app my-app
```

This will generate a runnable app with a simple landing page, the dev environment, configuration, and a local Git repository.

The default language is JavaScript, which will affect the generated files and configuration. Using TypeScript is easy as well though, just add the `--typescript` flag.

```bash
yarn create next-app --typescript my-app
# or
npx create-next-app --typescript my-app
```

## Next.js directory structure

Here's a quick overview of some of the more relevant files and directories that `create-next-app` generates:


```text
my-app
├── styles                # Put CSS styles in here to use CSS-in-JS.
├── next.config.js        # Used when you want to configure Next.js's behavior.
├── pages                 # Each JS/TS file in here becomes a page on the site.
│   └── api               # Each JS/TS file in here becomes an API endpoint.
├── tsconfig.json         # The generated TypeScript configuration.
├── .eslintrc.json        # The generated ESLint configuration.
├── README.md             # The generated README.
└── public                # Files added here become static assets (images, fonts, etc).
```


## Creating pages

Filesystem-based routing in Next.js makes it incredibly easy to add a new page to your web app. Just create a `mypage.js` or `mypage.ts` file in the `pages` directory and it will create a page on the site at `/mypage`. All you need to do is export a default function that renders the content.

```js
//
// pages/mypage.js
//
// Add any React code you want!
//
export default function MyArticle() {
  return <h1>Hello World</h1>;
}
```

Folders under `/pages` becomes parts of the URL path as well:


```js
//
// pages/articles/my-article.js
//
// Visiting /articles/my-article will render this page.
//
export default function MyArticle() {
  return <h1>This is my article.</h1>;
}
```


### Creating a dynamic route

Often you'll want to have a page that takes parameters like an ID, article slug, or so on. We can define a dynamic route segment in the url by naming the file or folder with brackets (`[]`) around a variable name. For instance, to handle urls of the form  `/articles/my-article-name`, we could add a `[slug].js` file to the `/articles` directory and grab the slug from the URL as a variable using the Next.js router.

```js
//
// pages/articles/[slug].js
//
// This could just as easily be pages/articles/[slug]/index.js
//
import { useRouter } from 'next/router';

export default function ArticlePage() {
  const router = useRouter();

  return (
    <h1>
      This is the article for {router.query.slug}
    </h1>
  );
}
```

Of course, you'll want to do something with the variable passed in like fetch the content from an API:

```js
//
// pages/articles/[slug].js
//
// This could just as easily be pages/articles/[slug]/index.js
//
import { useEffect, useState } from 'react';
import { useRouter } from 'next/router';

export default function ArticlePage() {
  const router = useRouter();
  const [article, setArticle] = useState(null);

  useEffect(() => {
    async function loadArticle() {
      const data = await fetch(`http://my-api.com/articles/${router.query.slug}`)
      const json = await data.json();
      setArticle(json);
    }

    loadArticle();
  }, [])

  return (
    {article && <h1>{article.title}</h1>}

    {article && {article.body}}
  );
}
```

Note that in the example above, you're fetching the data each time a user visits the page, which isn't optimal for SEO or page load time. Route variables can also be used to fetch data at build time (i.e., when you're deploying your site), so that the pages load statically and much faster. We do this using Next.js's **static site generation** feature.

## Creating API routes

Creating a server-side endpoint to do backend-y things with is as simple as creating a page. Under the hood, a Next.js API route is just an [Express.js](https://expressjs.com/) route function that takes request and response objects and returns status codes and content.

To create a Next.js API route, create a file in the `pages/api` directory. An extremely basic page just returns a function which returns some data. The following API endpoint would be available by making a GET request to `http://localhost:3000/api/articles`:

```js
//
// pages/api/articles/index.js
//
export default function handler(req, res) {
  const articles = [
    {id: 1, name: "Next.js Fundamentals", slug: "next-js-fundamentals"},
    {id: 2  , name: "Modern React Component Structure", slug: "modern-react-component-structure"},
    // ...
  ]

  // Send back an HTTP 200 code (success), and a JSON object.
  res.status(200).json(articles);
}

```

### Processing API route parameters

The `req.params` object will have dynamic route variables in it:

```js
//
// pages/api/articles/[id].js
//
import fetch from 'node-fetch';

export default function handler(req, res) {
  const articleId = req.params.id;

  const article = await fetch(`https://jsonplaceholder.typicode.com/posts/${articleId}`)
  const json = await article.json();

  res.status(200).json(json);
}

```

### Enforcing request method

Since API routes can respond to any request method by default (`GET`, `POST`, etc), you'll want to explicitly ensure each route only responds to the verb you want it to:

```js
//
// pages/api/articles/create.js
//
import fetch from 'node-fetch';

export default function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({
      error: 'Method not allowed'
    });
  }

  // Otherwise, do something with the request body.
  const { title, slug, body } = req.body;

  const article = await fetch(`https://jsonplaceholder.typicode.com/posts//${articleId}`, {
    method: 'POST',
    body: {
      title, slug, body
    }
  })

  res.status(200).json(json);
}

```

### Returning success/failure

Typically in real-world scenarios you'll want to return different status codes based on success or failure. Expanding on the above example:

```js
//
// pages/api/articles/create.js
//
import fetch from 'node-fetch';

export default function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({
      error: 'Method not allowed'
    });
  }

  try {
    // Otherwise, do something with the request body.
    const { title, slug, body } = req.body;

    const article = await fetch(`https://jsonplaceholder.typicode.com/posts//${articleId}`, {
      method: 'POST',
      body: {
        title, slug, body
      }
    })

    res.status(200).json(json);
  } catch (error) {
    // Log to Sentry or other error tracking service.
    // e.g., Sentry.captureException(error);
    // e.g., console.error(error);

    res.status(500).json({
      error: 'Something went wrong.'
    });
  }

```

### Note on API architecture in Next.js

Next.js API routes are bare-bones Express.js routes; they each handle a request and return a response, but there's no implemented standard for API architecture (e.g., REST, GraphQL, etc). So if you use them as-is, it's on you to decide how you want to structure your API.

For simple apps with just a few API routes, creating your API routes ad-hoc is fine. For larger apps this can become messy, so you'll want to consider using something like [Nest.js](https://nestjs.com/) or [Apollo Server](https://www.apollographql.com/docs/apollo-server) in your API routes to give them some structure and consistency.

At Echobind we use Apollo Server for this purpose in [Bison](https://github.com/echobind/bisonapp), our boilerplate around Next.js. We've found it to work extremely well.




## Using static site generation (SSG) in Next.js

Pages are statically generated in Next.js by default; that is, as much of the page as possible is converted to static HTML when you deploy the site. This makes the pages in your Next.js load much faster, and makes them much more SEO friendly. So whenever you have content that doesn't need to change every time someone visits it, leverage SSG as much as possible.

SSG relies on two important functions in Next.js: `getStaticProps` and `getStaticPaths`. Both run once each time the site is deployed.

Both are async functions exported from the top-level of your page file; they're **not** defined within your page component.

### `getStaticProps()`

`getStaticProps` is used to calculate or fetch the data for the page at build time—from an API, the filesystem, or anywhere. Use it when any of page's data won't change from request to request.

On this site's [article list](/articles) page for example, I use getStaticProps() to load the article list. I don't add articles in real time—I deploy each time I write a new one. So this page only needs to regenerate when I deploy.

Here's how getStaticProps() works in this case (condensed):

```js
//
// pages/articles/index.js
//
import { Link } from 'components/Link';

// Note the function signature.
export async function getStaticProps() {
  // This could pull data from an API, a database, or any other
  // source. It could also do and calculations or transformations
  // that you want to happen at build time.
  const data = await fetch('http://my-api.com/articles');
  const articles = await data.json();

  // Note that we have to return the data within the `props` property;
  // I forget this part now and then!
  return {
    props: {
      articles,
    },
  };
}


export default function ArticlesIndexPage({
  // Now the articles prop is available in the page component.
  articles,
}) {
  return (
    <>
      <h1>Articles</h1>
      <ul>
        {/* Loop through and display links to each article page. */}
        {articles.map({ slug, id, title } => (
          <li key={id}>
            <Link href={`/articles/${slug}`}>
              {title}
            </Link>
          </li>
        ))}
      </ul>
    </>
  );
}

```

### `getStaticPaths()`

The `getStaticPaths()` works in conjunction with `getStaticProps()` for pages that have dynamic routes. It tells Next.js the full list of pages to generate static HTML for at build time.

If a page like the above `/articles/[slug].js` has a dynamic route segment (the `slug`), Next.js needs to know the different possible values for that segment so it can generate them. `getStaticPaths()` is the place to put that information.

```js
//
// pages/articles/[slug].js
//
import { Link } from 'components/Link';

// Similar function signature to getStaticProps().
export async function getStaticPaths() {
  const data = await fetch('http://my-api.com/articles');
  const articles = await data.json();
  const paths = articles.map({ slug } => ({
    params: {
      id,
      slug,
    }
  }));

  // We return a paths object instead of a props object.
  return {
    paths
  }
}

// getStaticProps() receives the paths object we generated above.
export async function getStaticProps({ params: { id, slug } }) {
  // Get the API data for the single article, and return it as page props.
  const data = await fetch(`http://my-api.com/articles/${id}`);
  const article = await data.json()

  return {
    props: {
      ...article,
    },
  };
}


export default function ArticlePage({
  title, body
}) {
  return (
    <>
      <h1>{ title }</h1>

      {body}
    </>
  );
}

```


---

This is part 1 in what will be a multi-part series. With the above info you can get started creating pages, API routes and static pages with dynamic data.

In [the next section on Next.js basics](/articles/next-js-fundamentals-part-2) we'll talk about some important Next.js components that help make Next.js sites fast with relative ease, like the `<Link>` component and the `<Image>` component.






Next.js Fundamentals

****
Next.js page layouts are great for reusing page outer templates. Instead of having a whole page re-render when you want to switch to another page with the same look and feel, persistent layouts can allow us to re-render only the dynamic portions of the page, resulting in a faster page transition.

But what if we want to to change a small bit of the page layout based on what page we're on - like highlighting the current page in a navigation menu or breadcrumb? This isn't documented in Next.js docs, but it's easy to do.

(Note: You can see all of these techniques in action on this site, and in the codesandbox / stackblitz examples below).

## What are Next.js page layouts?

A quick definition: a page layout in Next.js is a React component that contains elements that you want to reuse on multiple pages. Those elements are typically at the top and/or bottom of the pages.

For example, if you want a batch of pages to be centered, you might have a `CenteredLayout` component that will center any page it's applied to:

```
export const CenteredLayout = ({ children }) => (
  <div style={{ margin: '0 auto', maxWidth: 650 }}>
    {children}
  </div>
)
```
A common use case is to have a header and footer on every page.

```
export const CenteredLayout = ({ children }) => (
  <Header />
    <div style={{ margin: '0 auto', maxWidth: 650 }}>
      {children}
    </div>
  <Footer />
)
```

Note the format of a layout component: it simply takes a React `children` prop, and supplies the layout-specific elements before or after the children.

## Persistent layouts

Now you might think that to use a layout in Next.js you would simply include it on the pages you want to use it on, but don't do it! This will have some unintended consequences.

```
//
// Don't do this!
//
export default function Page1() {
  return (
    <CenteredLayout>
      <h1>Page 1</h1>

      <Link href="/page2">Go to page 2</Link>
    </CenteredLayout>
  )
}

//
// Don't do this!
//
export default function Page2() {
  return (
    <CenteredLayout>
      <h1>Page 2</h1>

      <Link href="/page1">Go to page 1</Link>
    </CenteredLayout>
  )
}
```

What's the problem with this? As Adam Wathan talks about in his article, this will lead to unnecessary re-renders. When navigating from page 1 to page 2, the whole page will re-render, even though they're both using the same layout.

Those two `<CenteredLayout>` components are different instances, and so have different subtrees, which React will re-render separately. So we can solve this by making them the same exact instance.

## Preventing unnecessary re-renders with static `getLayout()` functions

To remedy this, we add the paradigm of using a static `getLayout()` function attached to a page, and tell Next.js to look for this method on a page component when rendering.

First we need a custom `_app.js` to the `pages` directory, as per the [docs](https://nextjs.org/docs/advanced-features/custom-app), and have it check for a `getLayout()` function on the page component.

```
//
// pages/_app.js
//
function MyApp({ Component, pageProps }) {

  // If the component has a getLayout() function, use it. Otherwise just render the page as is.
  const getLayout = Component.getLayout || ((page) => page);

  return getLayout(<Component {...pageProps} />);
}

export default MyApp;
```

In the layout component we'll export a `getLayout()` function that wraps the passed-in children with the layout:

```
//
// layouts/CenteredLayout.js
//
export const CenteredLayout = ({ children }) => (
  <div style={{ maxWidth: 500, background: '#FA9F42', margin: '0 auto' }}>
    {children}
  </div>
);

export const getLayout = (page) => <CenteredLayout>{page}</CenteredLayout>;

```

Now we can set any page to use the same layout by assigning its static `getLayout()` property to be the layout's `getLayout()` function.

```
//
// DO this!
//
// pages/Page1.js
//
import { getLayout } from '../layouts/CenteredLayout'

export default function Page1() {
  return (
    <>
      <h1>Page 1</h1>

      <Link href="/page2">Go to page 2</Link>
    </>
  )
}

Page1.getLayout = getLayout;

//
// DO this!
//
// pages/Page2.js
//
import { getLayout } from '../layouts/CenteredLayout'

export default function Page2() {
  return (
    <>
      <h1>Page 2</h1>

      <Link href="/page1">Go to page 1</Link>
    </>
  )
}
```

Now when navigating, you won't see the layout component re-render. The example above is fairly trivial, but you'll see that it remains true for large layouts as well. Result: more snappy page navigation, which we love Next.js for. 👏🏼


## Nested layouts

Not only can pages have layouts, but your layouts can have layouts. Simplified examples (no imports, minimal styles):

```
//
// layouts/SiteLayout.js
//
export const SiteLayout = ({ children }) => (
  <>
    <Header />
    {children}
    <Footer />
  </>
)

SiteLayout.getLayout = (page) => (<SiteLayout>{children}</SiteLayout>)

//
// layouts/CenteredLayout.js
//
export const CenteredLayout = ({ children }) => (
  <div style={{ margin: '0 auto', maxWidth: 650 }}>
    {children}
  </div>
)

export const getLayout = (page)  => (<CenteredLayout>{page}</CenteredLayout>)

CenteredLayout.getLayout = getLayout

//
// pages/nested.js
//
import { getLayout as getSiteLayout } from '../layouts/SiteLayout'
import { getLayout as getCenteredLayout } from '../layouts/CenteredLayout'

export default function CenteredPageWithHeaderAndFooter() {
  return <h1>This is a centered page with a header and a footer</h1>;
}

CenteredPageWithHeaderAndFooter.getLayout = (page) => {
  return getSiteLayout(getCenteredLayout(page));
};
```

## Dynamic content in Shared Layouts

What if you want to have dynamic content in them? Let's say you have a header in which you want to display the name of the current page you're on. The header is in the main site layout, but needs a `title` prop passed to it. To achieve this we simply augment the `getLayout()` pattern we're using to accept props from the page we're passing in, and pass them along to the layout (which can in turn pass them along to our `Header` component).

We augment `_app.js` so that it passes any page props to `getLayout()`:

```
//
// pages/_app.js
//
function MyApp({ Component, pageProps }) {
  // Use the layout defined at the page level, if available
  const getLayout = Component.getLayout || ((page) => page);

  return getLayout(<Component {...pageProps} />, pageProps);
}
```

Our layouts need to pass the page props along as well:

```
//
// layouts/CenteredLayout.js
//
import { getLayout as getSiteLayout } from './SiteLayout';

export const CenteredLayout = ({ children }) => (
  <div style={{ maxWidth: 500, margin: '0 auto' }}>
    {children}
  </div>
);

export const getLayout = (page, pageProps) =>
  getSiteLayout(<CenteredLayout>{page}</CenteredLayout>, pageProps);

//
// layouts/SiteLayout.js
//


export const SiteLayout = ({ children, title }) => {
  return (
    <div>
      <Header title={title} />
      {children}
      <Footer />
    </div>
  );
};

export const getLayout = (page, { title }) => {
  return <SiteLayout title={title}>{page}</SiteLayout>;
};

```

Our `Header` component accepts the `title` prop and does something with it.

```
export const Header = ({ title }) => (
  <div>
    <h3>Header</h3>

    <div>
      <Link href="/header-footer">Header/Footer Only</Link> <span>|</span>{' '}
      <Link href="/centered">Centered</Link> <span>|</span>{' '}
      <Link href="/">Index Page </Link>
    </div>

    <h3>Page title: {title}</h3>
  </div>
);

```

And of course, lastly our pages need to have a `title` prop. Since this is Next.js, we can opt to do this statically:

```
import { getLayout } from '../layouts/CenteredLayout';

export async function getStaticProps() {
  return {
    props: {
      title: 'Index Page',
    },
  };
}

export default function IndexPage() {
  return <h1>Index page</h1>;
}

IndexPage.getLayout = getLayout;
```


You can see this full example in action [here on StackBlitz](https://stackblitz.com/edit/nextjs-ojsozq).

Next.js Page Layouts and Dynamic Content


Nowadays in React, we use functional components with hooks instead of class-based components. Functional components are the recommended way to write components going forward, and luckily they're even simpler to use.

## Why use functional components in React?

Other than being the official recommendation of the React development team, functional components have a number of benefits over traditional class-based React components:

1. They're easier to read and understand.
2. They're easier to write.
3. They're easier to test.
4. They compose more cleanly.
5. In the future, they'll  run faster.

But don't take my word for it; let's try some out.

## How to write a React functional component

A functional component is simply a function that does two things, at minimum:

1. Accepts some props as parameters
2. Returns JSX to render.

Here's the most trivial example.

```
function MyButton({ children, onClick }) {
  return <button onClick={onClick}>{children}</button>;
}
```

Alternatively this can be written as an anonymous arrow function:

```
const MyButton = ({ children, onClick }) => {
  return <button onClick={onClick}>{children}</button>;
}
```

Or even more concisely without using the `return` statement:

```
const MyButton = ({ children, onClick }) => (<button onClick={onClick}>{children}</button>);
```

All of these achieve the same result; a component that can be called like this:

```
<MyButton onClick={() => alert("Clicked!")}>Click me!</MyButton>
```

Here's [a simple example on CodeSandbox](https://codesandbox.io/s/react-functional-component-javascript-8qtc6).


## A functional component with TypeScript

Adding TypeScript typings is easy. Here's the same example with TypeScript:

```
import "./styles.css";

type MyButtonProps = {
  children: string;
  onClick: () => void;
};

const MyButton = ({ children, onClick }: MyButtonProps): JSX.Element => (
  <button onClick={onClick}>{children}</button>
);

export default function App() {
  return (
    <div className="App">
      <h1>Hello CutIntoTheJamstack</h1>
      <MyButton onClick={() => alert("Clicked")}>Click me!</MyButton>
    </div>
  );
}
```

Here's [the same example on CodeSandbox](https://codesandbox.io/s/react-functional-component-typescript-fj12d?file=/src/App.tsx).

## Adding functionality with hooks

Hooks can be used to do anything class-based components can do. For example managing state inside a component. The `useState` hook replaces the `setState` function:

```
import { useState } from 'react';

const ToggleButton = ({ children, onClick }) => {
  const [active, setActive] = useState(false);

  const style = {
    backgroundColor: active ? 'tomato' : 'gray'
  }

  return (
    <button onClick={onClick} style={style}>
      {children}
    </button>
  )
}

```

Similarly for side effects (things like API calls, other async behavior, etc), in place of lifecycle methods like `componentDidMount` we now use the `useEffect` hook.

```
import { useEffect, useState } from 'react';

const RandomListOfText = () => {
  const [posts, setPosts] = useState([]);

  useEffect(() => {
    fetch('https://jsonplaceholder.typicode.com/posts')
      .then(response => response.json())
      .then(data => setPosts(data))
  }, [])

  return (
    <ul>
      {posts.map(p => <li>{p.title}</li>)}
    </ul>
  )
}
```

In addition to the many hooks included with React, you can define your own custom hooks and pull in others from npm packages others have already created.

## Testing functional React components

The testing process becomes easier and cleaner as well, especially when using [React Testing Library](https://testing-library.com/docs/react-testing-library/intro):

```
import { render, fireEvent } from "@testing-library/react";
import { MyButton } from "./MyButton";

describe("MyButton", () => {
  it("should render", () => {
    const onClick = jest.fn();
    const { getByText } = render(<MyButton onClick={onClick}>Foobar</MyButton>);

    const button = getByText("Foobar");
    expect(button).toBeDefined();

    fireEvent.click(button);
    expect(onClick).toHaveBeenCalled();
  });
});

```

Another sandbox [here](https://codesandbox.io/s/react-functional-component-testing-0p5dp).

















Recent Articles

Building an Email Chip Input Field with Chakra-UI

Next.js Fundamentals Part 2

Next.js Fundamentals

Next.js Page Layouts and Dynamic Content

Modern React Component Structure