A quick guide to Next.js setup

This post originally appeared on my blog.

Install Node

The base requirement to make Next.js run on your computer is to have a working installation of Node.js. The current version of Next.js requires Node 18.17 or higher.

If you’re on MacOS or Linux, a simple way to install Node is with Homebrew.

brew install node@20

For Windows users, Chocolatey is a popular solution.

choco install nodejs-lts --version="20.12.2"

Your first Next.js app

Easy so far, right? Creating a Next.js app is just one command away!

npx create-next-app@latest

When you run the above incantation, you will get presented with a number of configuration options by the install wizard. Here are all of them, displayed at once:

These options can be daunting if you’re not familiar with them. If you’re like me, you’d be tempted to just race through them all by accepting the defaults. And that would be perfectly fine! The Next.js team has done a good job of setting sensible default values.

However you might be interested in a deeper understanding of what these options do and ramifications of each choice. Let’s walk through them one at a time.

Project name

I think this one is self-explanatory. The project name will become the top-level folder of your app (and git repo). Other starter packs I have used will inject the project name in a dozen different places in your app, but create-next-app keeps it simple. The name will only be set in package.json , so it’s super easy to change later.

TypeScript

As you may guess from the name, this option enables TypeScript support. If you choose it, you will get first-class TypeScript support throughout your Next.js app. I highly recommend turning it on for anything more than a scratch project!

If you disable TypeScript and then change your mind later, no biggie. Just rename one of your source files with a .tsx or .ts extension, rebuild with npm run dev, and Next.js will do the setup work to enable TypeScript support.

ESLint

If you’re not familiar with ESLint, it’s a tool for statically analyzing your code to find bugs and optimizations. The ESLint option will install and set up ESLint with a myriad of Next.js custom rules to keep your app in tip-top shape. It’s a popular tool with integrations for most code editors. I would recommend enabling this one too.

Tailwind CSS

Tailwind is an example of a CSS utility library. Utility frameworks provide pre-defined classes that you can use directly in your markup, enabling you to style your pages and components without writing much of your own CSS at all.

Here’s a quick example:

<p class="text-slate-500">You have a new message!</p>

text-slate-500 is a Tailwind class that holds a single CSS attribute color: rgb(100 116 139) - so the text in the <p> tag will turn medium gray. It’s an extremely simple yet powerful concept!

There are many utility libraries, but Tailwind has emerged as one of the most popular and comprehensive options. I use and love Tailwind and recommend enabling this option (the default), as you can still opt out and write your own CSS alongside Tailwind.

src directory

By default, Next.js will place all source files under the app folder at the project root.

Some people prefer to have their code and related files under a single src directory. If you choose this option, your app folder will go under src. Then you’re free to organize other files and folders under src. The initial structure looks like this after installation with src enabled:

Unless you have a specific folder hierarchy in mind, I recommend staying with the convention of using the app folder instead of src .

App router

The release of the App Router marked a big shift in how we build Next apps. As compared to the previous Pages router, the App router allows more server-side optimizations, better performance, and flexible API and routing patterns. See this Stack Overflow answer for a concise comparison between the two routers.

I strongly recommend sticking with the App router. Out of all the options here, this will most strongly affect the future architecture, development, and performance of your app, so choose wisely!

Import alias

Import alias allow you to shorten import statements between files in your project. Aliases are especially useful for deeply nested paths. For example, imagine you had a file structure like this:

/app
  /components
    /nested-a
      /nested-b
        - MyComponent.tsx
    /utils
      - helpers.ts

Now, say you want to import helpers.ts in MyComponent.tsx. Without aliases, you would have to provide a long relative path:

import { helper } from '../../../utils/helpers';

But using aliases allows us to take advantage of a much more readable shortcut:

import { helper } from '@/app/utils/helpers'

In JavaScript and TypeScript apps, the convention is to use @ to represent the root source folder.

With this config option, you can customize @ to be any prefix you like. However, I suggest remaining with the standard since this is what other developers will expect.

Conclusion

Now you understand the ins and outs of creating a Next app! Stay tuned for part 3, where we will explore the structure of a basic Next.js app, including pages and routing.

PS. If you're interested in reading the full guide as it comes out, be sure to subscribe for updates!