My NextJS Setup

If you are starting out with Next.js and Server Side Rendering for the first time, then the initial project setup may take a significant amount of your time. It is not likely that you will be working with plain Next.js. You should require some tooling and a manageable and scalable project structure. In this post, I will share a Next.js boilerplate structure that I am using.

Next.js is a React framework that offers Server-Side Rendering (SSR) and Static Site Generation (SSG) along with some other handy features like:

Incremental Static Generation
TypeScript Support
Fast Refresh
Filesystem-based Routing
API Routes
Built-in CSS Support
Code Splitting and Bundling

I will give a brief overview of my Next.js setup with TypeScript, ESLint, Jest, and TailwindCSS from scratch. This will give you a good starting point for your Next.js projects. So, If you are starting a new project in Next but you are not sure how to set it up then this post is for you. This might save you some time on the initial setup and get you up and running quickly. Let's get started.

Installing NextJS

We will use create-next-app to generate your Next.js application. You need to have NodeJS 10.13 or later installed. We will use npm as a package manager.

npx create-next-app my_next_app

This will create a fresh Next.js application in the my_next_app directory. The folder-structure of your app should look like this:

my_next_app
├── node_modules
├── package.json
├── package-lock.json
├── pages
│   ├── api
│   │   └── hello.js
│   ├── _app.js
│   └── index.js
├── public
│   ├── favicon.ico
│   └── vercel.svg
├── README.md
└── styles
    ├── globals.css
    └── Home.module.css

Now, we will change this structure a little bit. We will create a directory called src in the root of our project and move pages, public and styles directories in the src directory. We can also make directories like components, helpers, 'lib' etc in the src directory to organize everything properly. Now start our dev server.

npm run dev

This will run the Next.js development server on 127.0.0.1:3000. If everything is fine then you should see the Next.js project starter page on your localhost:3000.

Setting Up TypeScript

It is very easy to set up TypeScript in your Next.js project. First, install TypeScript along with React and Node types.

npm install --save-dev typescript @types/react @types/node

Now, we can change the .js files to .ts(x) files.

src/pages/api/hello.js -> hello.ts
src/pages/_app.js -> _app.tsx
src/pages/index.js -> index.tsx

Hope you get the idea. Now replace the content of your src/pages/_app.tsx with the following code:

/* 
 * _app.tsx file
 */
import { AppProps } from 'next/app'

function App({ Component, pageProps }: AppProps ){
  return <Component {...pageProps} />
}

export default App

Like the above, we need to replace all the js code to its equivalent ts code. After that stop the dev server (if it's running) and start it again. Next.js will automatically detect TypeScript and generate a tsconfig.json file and a next-env.d.ts file for you. Your basic TypeScript setup is done.

Setting up ESLint

For large TypeScript of JavaScript projects code consistency and following the best practices are very important. That's where ESLint comes in. To setup ESLint in your Next.js application install ESLint as a devDependency

npm i -D eslint eslint-plugin-react @typescript-eslint/eslint-plugin @typescript-eslint/parser

Then we have to create a eslintrc.json file and put the following content in it.

// eslintrc.json file
{
  "env": {
    "browser": true,
    "es6": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/eslint-recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "globals": {
    "Atomics": "readonly",
    "SharedArrayBuffer": "readonly",
    "React": "writable"
  },
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaFeatures": {
      "jsx": true
    },
    "ecmaVersion": 2018,
    "sourceType": "module"
  },
  "plugins": ["react", "@typescript-eslint"],
  "rules": {
    "react/react-in-jsx-scope": "off"
  }
}

Setting up Jest for Testing

Now it's time to set up the testing framework Jest. Jest works pretty well with React and Next. First, install Jest as a devDependency.

npm i -D jest ts-jest babel-jest react-test-renderer @types/jest @testing-library/react @testing-library/jest-dom

Now, we create a .babelrc file with the following:

# .babelrc file
{
    "presets": ["next/babel"]
}

Then we shall create a jest.config.js file with the following content:

// jest.config.js file
module.exports = {
    collectCoverageFrom: [
      "**/*.{js,jsx,ts,tsx}",
      "!**/*.d.ts",
      "!**/node_modules/**",
    ],
    setupFilesAfterEnv: ["<rootDir>/setupTests.js"],
    testPathIgnorePatterns: ["/node_modules/", "/.next/"],
    transform: {
      "^.+\\.(js|jsx|ts|tsx)$": "<rootDir>/node_modules/babel-jest",
      "^.+\\.css$": "<rootDir>/config/jest/cssTransform.js",
    },
    transformIgnorePatterns: [
      "/node_modules/",
      "^.+\\.module\\.(css|sass|scss)$",
    ],
    moduleNameMapper: {
      "^.+\\.module\\.(css|sass|scss)$": "identity-obj-proxy",
    },
    //additional prop from a github issue: https://github.com/zeit/next.js/issues/8663
    preset: "ts-jest",
    testEnvironment: "jsdom",
    globals: {
      // we must specify a custom tsconfig for tests because we need the typescript transform
      // to transform jsx into js rather than leaving it jsx such as the next build requires.  you
      // can see this setting in tsconfig.jest.json -> "jsx": "react"
      "ts-jest": {
        tsConfig: "tsconfig.jest.json",
      },
    },
  }

After that, we have to create a tsconfig.jest.json file like the following:

// tsconfig.jest.json
{
    "extends": "./tsconfig.json",
    "compilerOptions": {
      "jsx": "react"
    }
}

Now, we have to create a setupTests.js file like the following:

/*
 * setupTests.js file
 */
// optional: configure or set up a testing framework before each test
// if you delete this file, remove `setupFilesAfterEnv` from `jest.config.js`

// used for __tests__/testing-library.js
// learn more: https://github.com/testing-library/jest-dom
import '@testing-library/jest-dom/extend-expect'

The last file we need to create for Jest is a cssTransform.js in the config/jest directory.

/*
 * cssTransform.js file
 */
module.exports = {
    process() {
      return 'module.exports = {};'
    },
    getCacheKey() {
      return 'cssTransform'
    },
}

Then finally in our package.json file, we have to add the following two scripts.

// package.json file
{
  ...,
  "scripts": {
    ...,
    "test": "jest --watch",
    "test:ci": "jest --ci"
  },
  ...
}

The Jest framework is set up now. We will add a simple test now. For this, we will create a small component and test if that component renders without any error. Here I used the Avatar component which simply shows an avatar image. My src/components/avatar.tsx file looks like the following:

// src/components/avatar.tsx file
function Avatar() {
    return (
        <div className="avatar">
            <img src="/avatar.png" alt=""/>
        </div>
    )
}

export default Avatar

We will render this component in our Index page which is the src/pages/index.tsx file. To test this component let us create a src/components/__tests__/avatar.test.tsx file.

// src/components/__tests__/avatar.test.tsx file
import React from "react"
import Avatar from "../avatar"
import TestRenderer from "react-test-renderer"
import { cleanup } from "@testing-library/react"

afterEach(cleanup);

describe('Avatar', () => {
    it('should render without throwing an error', () => {
        const testRenderer = TestRenderer.create(<Avatar />);
        expect(testRenderer.toJSON()).toMatchSnapshot();
    });
})

To run the test use

npm run test

Setting up TailwindCSS

TailwindCSS is a utility-first CSS framework and it works well with React and Next. We will add Tailwind as a PostCSS plugin to our project. To install TailwindCSS and PostCSS:

npm i -D tailwindcss postcss-preset-env postcss-flexbugs-fixes

Now, we have to create a tailwind.config.js file and a postcss.config.js file in our project root.

// tailwind.config.js file
module.exports = {
  future: {
    removeDeprecatedGapUtilities: true,
  },
  purge: ['./src/components/**/*.{js,ts,jsx,tsx}', './src/pages/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        'accent-1': '#333',
      },
    },
  },
  variants: {},
  plugins: [],
}

// postcss.config.js file
module.exports = {
  plugins: [
    'tailwindcss',
    'postcss-flexbugs-fixes',
    [
      'postcss-preset-env',
      {
        autoprefixer: {
          flexbox: 'no-2009',
        },
        stage: 3,
        features: {
          'custom-properties': false,
        },
      },
    ],
  ],
}

Now replace everything from your src/styles/globals.css with the following:

@tailwind base;

/* Write your own custom base styles here */

/* Start purging... */
@tailwind components;
/* Stop purging. */

/* Write you own custom component styles here */

/* Start purging... */
@tailwind utilities;
/* Stop purging. */

Now, import this globals.css file in your src/pages/_app.tsx file like:

// src/pages/app.tsx file
import '../styles/globals.css'

We are all set up now and ready to start building our Next.js application. One final thing I want to do is to add some Tailwind utility classes to our page. Here is our src/pages/index.tsx

// src/pages/index.tsx

import Head from 'next/head'
import Avatar from '../components/avatar'

export default function Home() {
  return (
    <div className="flex h-screen items-center justify-center">
      <Head>
        <title>My Next App</title>
      </Head>
      <Avatar />
    </div>
  )
}

Finally, we are done setting up everything and testing that they are all working properly. Now, you can start building your awesome Next.js app on top of this boilerplate. You can also find the project boilerplate on Github. Hope this will help you get started with Next.js quickly. Happy coding.

My NextJS Setup

Comments (2)

More from this blog

Attempt to Learn Elixir: Functions and Patterns

Back to the Blog: Returning to Technical Writing After a Long Hiatus

AI Agents: Unlocking Future Workflows

I switched to Neovim from VSCode as my main IDE

Installing NextJS

Setting Up TypeScript

Setting up ESLint

Setting up Jest for Testing

Setting up TailwindCSS

Command Palette

Comments (2)

More from this blog

Installing NextJS

Setting Up TypeScript

Setting up ESLint

Setting up Jest for Testing

Setting up TailwindCSS