DEV Community: Antonio Lo Fiego

Setting up a Next.js Application with TypeScript, JIT Tailwind CSS and Jest/react-testing-library

Antonio Lo Fiego — Fri, 06 Aug 2021 02:15:47 +0000

A few weeks ago, I tweeted about how frustrating of an experience is to set up a Next.js project that includes TypeScript as well as a working testing framework.

Setting up a Next.js TS project with Jest and RTL is beyond frustrating.
I really can't blame folks who are scared to get into the JS world. It really makes no sense how much confusing extra work you need just to make a testing framework work. I lost hours and got nowhere.
— Antonio Lo Fiego ☁️ (he/him) (@antonio_lofiego) July 5, 2021

I tend to use create-next-app over create-react-app because Next is such a pleasure to work with, thanks to its extremely intuitive file-based routing, support for server-side rendering, static site generation and incremental site generation, wonderful components such as the Image optimization and an overall wonderful DX.

Something that create-next-app has been lacking, though, is a single source-of-truth when it comes to setting up testing environments. CRA ships with Jest and React Testing Library out of the box and there's no major tweaking needed to start working on a project using TDD. The Next.js docs are wonderful, but nowhere they mention testing.

Moreover, Next makes it so easy and straightforward to use TypeScript. You could just run yarn create next-app --typescript new-project and all the setup is done for you. One feature I absolutely love about TypeScript are path aliases, as they make it so easy to work with larger React projects without having to deal with a jungle of ../../../../s. While adding TypeScript to Next is nice and easy, it just adds more complexity when trying to set it up with Jest and RTL.

Even more headaches are added if we want to include Tailwind CSS, arguably the best CSS framework out there right now. With their newly released JIT compiler, it has become such a pleasure to style your apps without writing a single line of traditional CSS, but setting it up along the rest of the tools is also another head scratcher.

After banging my head on this for quite some time, I finally put together a solid template that you can use to start your Next project with this wonderful stack and in this article I'll walk you through how I did it, so you can understand where certain complexities arose.

create-next-app

The first step is to get a boilerplate Next app using create-next-app with the --typescript flag. That will take care of all the TS-related dependencies and configurations and get us started with the initial bits of components.

$ yarn create next-app --typescript new-project

Path Aliases

As mentioned, I love using TS path aliases in my React projects, as it means that whenever I am building my pages I can just import my components from @components instead of manually writing relative imports.

To do this, we can open our tsconfig.json file, and add a couple of extra lines:

{
    "compilerOptions": {
        {...}
        "baseUrl": ".",
        "paths": {
            "@components/*": ["components/*"],
            "@styles/*": ["styles/*"],
            "@pages/*": ["pages/*"],
            "@hooks/*": ["hooks/*"]
        }
    {...}
}

Note that these are the shortcuts I use, but you can change the actual path alias to whatever you'd prefer (E.g: @/Components/* or #components/).

Tailwind CSS and JIT Mode

We can move on to Tailwind CSS. I specifically want to enable the JIT compiler as it works wonders and makes my CSS development so much smoother.

First of all, let's install the dependencies:

$ yarn add -D tailwindcss@latest postcss@latest autoprefixer@latest postcss-cli

After that, we can run npx tailwindcss init -p to get an empty Tailwind CSS config file as well as the appropriate PostCSS configuration. Given that we are using JIT, we don't specifically need to add the folders to purge in the configuration, but in case we decide to stop using JIT, this will take care of the production build. Our tailwind.config.js file should look like this:

module.exports = {
    mode: 'jit',
    purge: ['./pages/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'],
    darkMode: false, // or 'media' or 'class'
    theme: {
        extend: {},
    },
    variants: {
        extend: {},
    },
    plugins: [],
};

In the styles folder that create-next-app generated for us, we can get rid of the Home.module.css file and clear the globals.css file. We will add a tailwind.css file which will only contain the Tailwind directives:

@tailwind base;
@tailwind components;
@tailwind utilities;

Finally, we need to add two scripts to our package.json that will take care of building new classes as we work in our application as well as building the final CSS package.

{
    {...}
    "scripts": {
        "dev": "next dev",
        "build": "next build",
        "start": "next start",
        "lint": "next lint",
        "css:dev": "TAILWIND_MODE=watch postcss ./styles/tailwind.css -o ./styles/globals.css --watch",
        "css:build": "postcss ./styles/tailwind.css -o ./styles/globals.css",
    },
    {...}

The css:dev script will run PostCSS in watch mode, and Tailwind will listen for changes in our component classes to build new utilities classes on the go. Once everything is done, we can build the final version of the CSS by running our css:build script.

NOTE: On Windows, the dev script might not work because of how environment variables are declared on Windows. A simple solution is to add another package called cross-env, which handles for you all the platform idiosyncrasies while setting environment variables. Just add cross-env before TAILWIND_MODE and you're all set!

Let's now test if Tailwind works properly. Replace the content of your pages/index.tsx file with:

const Home = () => {
    return (
        <>
            <main>
                <div className='h-[100vh] flex flex-col justify-center align-middle text-center'>
                    <h1 className='text-[72px] bg-clip-text text-transparent bg-gradient-to-r from-green-400 to-blue-500 font-extrabold'>
                        Batteries Included Next.js
                    </h1>
                    <h2 className='text-2xl max-w-md mx-auto'>
                        A Next.js Boilerplate with TypeScript, Tailwind CSS and testing
                        suite enabled
                    </h2>
                </div>
            </main>
        </>
    );
}

export default Home;

Now, in two terminal windows, run both yarn dev and yarn css:dev and on http://localhost:3000 you should see:

Setting up Jest and React Testing Library

We need to install a few dependencies to make Jest and RTL work properly with TypeScript.

$ yarn add -D @testing-library/dom @testing-library/jest-dom @testing-library/react @testing-library/user-event babel-jest jest jest-dom node-mocks-http ts-jest ts-loader

Specifically:

All the @testing-library packages allow us to render our React components in what basically can be thought as a virtual browser and test their functionality
jest is a testing framework, that we will use to write, run and structure our test suites
babel-jest is used to transform and compile our code
ts-jest and ts-loader allow us to test TypeScript-based code in Jest
node-mocks-http will help us generate mocks of our request and response objects when testing our Next API routes

We need to create a file called setupTests.js at the root of our project, similar to what you would find in a CRA-generated app. This file will have a single line of code:

import "@testing-library/jest-dom/extend-expect";

We also need to create a .babelrc file. It will contain the following:

{
  "presets": ["next/babel"]
}

Let's now create the configuration file for jest, called jest.config.js at the root of our project:

module.exports = {
    testPathIgnorePatterns: ['<rootDir>/.next/', '<rootDir>/node_modules/'],
    setupFilesAfterEnv: ['<rootDir>/setupTests.js'],
    transform: {
        '^.+\\.(js|jsx|ts|tsx)$': '<rootDir>/node_modules/babel-jest',
    },
};

As mentioned in the jest docs, we don't usually need to use CSS files during tests, so we can mock them out the test suites by mapping every .css import to a mock file. To do this, let's create a new subfolder in our styles folder called __mocks__, and let's create a very simple file inside of it called styleMock.js, which will export an empty object:

module.exports = {}

We have to let Jest know that whenever it encounters a css file import it should instead import this styleMock.js file. To do that, let's add another line to our jest.config.js file:

module.exports = {
    {...},
    moduleNameMapper: {
        '\\.(css|less|scss|sass)$': '<rootDir>/styles/__mocks__/styleMock.js',
    },
}

We also need to make Jest aware of the path aliases that we defined in our tsconfig.json file. To our moduleNameMapper object, let's add two more lines:

module.exports = {
    {...},
    moduleNameMapper: {
        '\\.(css|less|scss|sass)$': '<rootDir>/styles/__mocks__/styleMock.js',
        '^@pages/(.*)$': '<rootDir>/pages/$1',
        '^@components/(.*)$': '<rootDir>/components/$1',
    },

This will tell Jest that whenever it finds an import that starts with either @pages or @component, it should actually import from the pages and components folders in the root directory.

Let's test out our setup! I'll create a folder called, unsurprisingly, tests at the root of my project. I will mirror the organization of my project, meaning that I will have a components folder as well as a pages folder which also contains an api folder.

In the pages folder, let's write our first test for the newly created index.tsx, in a file called index.text.tsx:

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

describe('App', () => {
    it('renders without crashing', () => {
        render(<App />);
        expect(
            screen.getByRole('heading', { name: 'Batteries Included Next.js' })
        ).toBeInTheDocument();
    });
});

Let's start the test script by running yarn test and... We get an error.

  ● App › renders without crashing

    The error below may be caused by using the wrong test environment, see https://jestjs.io/docs/configuration#testenvironment-string.
    Consider using the "jsdom" test environment.

    ReferenceError: document is not defined

That ReferenceError is an issue that is caused by how Next.js renders its pages. Given that it tries to pre-render every page on the server side for better optimization and SEO, the document object is not defined, as it is a client-side only. According to RTL's docs about the render function:

By default, React Testing Library will create a div and append that div to the document.body and this is where your React component will be rendered.

But we do not have a document to begin with, so this fails! Luckily, jest suggests a solution for this in the error message.

Consider using the "jsdom" test environment.

Let's add a jest-environment string at the top of our index.test.tsx:

/**
 * @jest-environment jsdom
 */

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

describe('App', () => {
    it('renders without crashing', () => {
        render(<App />);
        expect(
            screen.getByRole('heading', { name: 'Batteries Included Next.js' })
        ).toBeInTheDocument();
    });
});

Now the tests will pass without any problem! Also, notice how we can import the App component from '@pages/index thanks to our moduleNameMapper work we did earlier.

Let's now test the API route. The default API example that create-next-app generates has a simple JSON response of {"name": "John Doe"}. In our tests/pages/api folder we can create a new file called hello.test.ts to mimic the hello API name:

import { createMocks } from 'node-mocks-http';
import handler from '@pages/api/hello';

describe('/api/hello', () => {
    test('returns a message with the specified name', async () => {
        const { req, res } = createMocks({
            method: 'GET',
        });

        await handler(req, res);

        expect(res._getStatusCode()).toBe(200);
        expect(JSON.parse(res._getData())).toEqual(
            expect.objectContaining({
                name: 'John Doe',
            })
        );
    });
});

As you can see, we don't need to change the environment to jsdom as we are only using server-side code. In order to test our API route, we also need to mock the request and response that we pass to the API handler. In order to do this, we import the createMocks function from node-mocks-http, which helps us simulate a request and response object in a very intuitive manner and test it with Jest.

Let's run again yarn test and everything works just fine!

Conclusion

There were a very large number of moving parts in putting together this template. A lot of the issues came with correctly choosing the jest related packages, as most were either incompatible with TypeScript or just weren't boding well with Next.js.

The template is available on my GitHub as Batteries-Included-Next.js. If this has helped you or you start using this template, let me know what you are working on as I would be extremely curious to know!

If you like this article, I'd suggest you to follow me on Twitter and give a listen to my new podcast, cloud, code, life| where we chat about these technologies and more every week! Thanks for reading and good luck in your Next.js adventures!

The Hitchhiker’s Guide to the Containers: A Foolproof, Hands-on Docker Tutorial (Part 1)

Antonio Lo Fiego — Sun, 02 Aug 2020 01:34:31 +0000

For a beginner, it is not an easy task to understand Docker. I will admit that I have struggled with using and understanding containers for a long time and I still have a lot to work on. There is a ton of subtleties that goes into solidly grasping the concepts behind Docker, why it is so revolutionary, and why even a budding programmer might benefit from learning it and using it.

This is my humble attempt to channel hours and hours of headaches, despair, and a-ha! moments into a beginner-friendly, digestible format. This is the first in a series of articles, and I hope it will give you a headstart in your Docker journey!

Some history

The typical way of writing software was simple. A developer works on his local machine, installing a bunch of packages, setting up the environment, etc. Once the necessary code was in good shape, our dev friend shares the code to the ops folks, and... it doesn't work.

Ops: Your code doesn't work.

Dev: Hey it worked on my machine!

Ops: What version of XXX do you run?

Dev: I have no idea, man...

As you can imagine, a very long time was spent troubleshooting dev environments instead of shipping features and improvements.

The solution found was in hypervisors and Virtual Machines (VMs). With VMs, you can package and ship a fully configured operating system along with your code, and spin up as many development and test environments as you see fit with it. Coding becomes just booting up a VM, configuring the environments as you need them, develop software, test it, and your job is done! But how does all of this work? What are VMs? Let's look at the architecture of a computer running VMs.

There are a lot of terms that you might not know, so let's go through them. The infrastructure is the computer hardware, meaning CPU, RAM, SSDs and hard disks, motherboards, and anything else is part of the physical components of the host machine. The Host OS is the operating system that is installed on the infrastructure. As an example, if you were to purchase a MacBook, the aluminum shell and all the components are part of the infrastructure, while MacOS is the Host Os.

The hypervisor is a piece of software that handles the creation of Virtual Machines. Each of these VMs can run their independent process, as they believe they are using the hardware resources from the infrastructure. In reality, the hypervisor allocates hardware from the pool of resources that the infrastructure makes available. In simplest terms, it creates a virtual representation of portions of the Host Machine hardware and lets Virtual Machine run on those, managing the resources.

As you can see from the diagram, are two types of hypervisors, depending on where they sit in the system architecture.

Bare-Metal Hypervisors (Type 1):

The hypervisor software is installed directly on the hardware and embedded in its components. In this case, there is no Host OS on these infrastructures. These are the most common type of hypervisors used in production environments, as they are more secure and have a higher performance by being so close to the machine level.

Hosted Hypervisors (Type 2):

The hypervisor software is installed on an operating system. If you have played with VMs, this is most likely the type of hypervisor that you have used. Simply think of Oracle VirtualBox, Parallels Desktop, VMWare Fusion, or any of the major VM providers.

The important point to note here is that, while a hypervisor provides all the resources and virtualized hardware, it does not provide an operating system. This is where the Guest OS plays its part, as the OS that is running on the VM. These are fully-fledged OS, including all the additional pieces of software needed to make the system run. This introduces a ton of additional bloat to the process and reduces the number of VMs that a single host can run.

Think about installing any OS. A fresh installation of Windows, for example, also comes with all the usual additional applications and supporting software. I doubt that our production-grade Nginx server will make plenty of use of a shiny copy of Paint 3D.

Enter Docker

A container solves the timeless problem of "IDK, man. It works on my machine" and the performance overheads of VMs by providing you a portable, replicable image of your development environment that can run on any OS. When an application is containerized, it is bundled with all of its dependencies. In this way, if I want to run the application on a different machine, I don't need to install anything else other than Docker, as all that makes my application tick comes embedded with the Docker Image.

The reason why this works is that Docker runs its containers directly on our machine's kernel. The kernel is the very low-level program that has complete control over both software and hardware in your computer, allowing the two to communicate.

All of the Docker container's processes run along with the main operating system's processes, albeit in a logically isolated fashion. This isolation is made possible by utilities in the Linux kernel, specifically LXC (LinuX Containers), cgroups (control group), and namespaces. The specifics of how these work are a little tricky, but we will explore them in a future tutorial.

Docker is built off of these utilities, extending them and making them easy to use with a high-level API, called the Docker Engine. The Docker Engine is a REST API that can be accessed via HTTP or, most commonly, through a command-line interface. It sends instructions to the Docker Daemon, a constantly running background process that manages every interaction between Docker containers and the machine's kernel.

Comparing Docker with VMs

Let's look again at the VM architectural diagram and let's compare it to how Docker does its things.

This is where Docker has an advantage over VMs. Given that, as we explained before, the containers use the kernel of the host to run their processes, there is no overhead to run a container. A container has no kernel booting to do, it uses only the processes that are necessary to run the containerized application, it stops whenever my application stops and does not occupy hardware resources while not in use.

TL;DR

Docker is a quick way to package applications in the environment that they were developed in, making sure that they can run no matter the underlying infrastructure, configuration, or OS.

Even more TL;DR

Some Docker jargon

We explained what Docker is why it is great, but you surely have heard of Dockerfiles, Docker images, Docker containers, and maybe others. Let's clarify what those things mean.

Docker Image

Docker images are read-only files that are to build containers. They include everything that the containerized process needs to run, such as source code, dependencies, runtimes, and objects. Most crucially, it provides a private filesystem to the container. Images are lightweight, portable, and can be used to deploy applications quickly and at scale. Every image is built from a Docker-specific script called a Dockerfile.

Dockerfile

A Dockerfile is a recipe that provides mostly clear and sequential instructions on how to build an image. A Dockerfile is composed of a series of [action] [target] commands, each of which creates a new layer. We will cover layers in a later installment of this series, but for now, we can think of these as building blocks that can be individually cached (i.e. saved to memory) for future builds.

Docker Container

Once we build an image from a Dockerfile, we can finally deploy it as a container. Containers are nothing more than instances of Docker images. Multiple containers can run at the same time on the same machine and multiple containers can be instantiated from the same Docker image. Containers live for the time it takes for their processes to run or until they fail.

Combined with an extremely fast start time, we can see why they are valuable in environments that need to scale quickly. We can start as many containers as our underlying infrastructure can handle or as much as our manually allocated resources allow and we can get rid of them just as quickly.

Docker Registry

If we want to control every detail of our services on our own, we can write a Dockerfile that specifies every single step of the way to get there. But in most use cases we might be interested in running pre-built images of services that we use daily. For that reason, we can browse Docker Hub, an online registry of pre-built images of various software, from commonly used applications like databases (MySQL, Redis, Postgres, etc...), web servers (Nginx, Apache), or CMS (WordPress) to development environments in most languages (Python, Node.js, Java, etc...).

The images that you build through your Dockerfiles can be pushed to the various registries, either to DockerHub if we want to make them publicly available or registries like AWS Elastic Container Registry, Azure Container Registry, or GCP Container Registry if we want to keep them private. If we want our images to be uber-private, we can also host our private registry by running a local instance of the Docker Registry, which is available as a Docker image on Docker Hub.

We have now a better idea of the basic building blocks of Docker. We can also identify the cycle of Docker containers, from creation to instantiation.

Next steps?

Whew! That was already a lot of information to digest! Make sure you understand the underlying concepts of Docker and why so many developers love the fact that it is in this world. In Part 2 of this series, we will start getting our feet wet with the Docker CLI, pull a few images from Docker Hub, and get experience with properly running containers in various use cases.

For now, if you want, keep in touch with me via Twitter and let me know what you think about this guide. I hope you liked your first steps with Docker because it's gonna be a hike!