DEV Community: cvifli

How do I setup my NextJs development environment

cvifli — Wed, 21 Oct 2020 10:21:36 +0000

In this post, I will introduce how do I setup my development environment for NextJs. My development environments include:

cypress                     // For component testing
cypress-react-unit-test
storybook                   // Quickly view react components
tailwindcss                 // CSS framework
typescript                  // Provide type safety

In this post, I will assume you have NodeJs and yarn installed in your global environment. Also, I am assuming you know why we need those dependencies and won't explain much about them.

TLDR

Just checkout the repository: https://github.com/cuichenli/nextjs-typescript-cypress-storybook-tailwind

Let's start with NextJs

To start with, let's install create-next-app via yarn so we can use it to setup some basic stuff.

yarn global add create-next-app
create-next-app

After you type the above commands in your terminal, create-next-app will ask you the name of the project, I will use my-app here.
Once you are done with the questions, you can run cd to go into the newly created project.

Typescript

There might be some other typescript templates out there, but I chose to do it myself, as I would like to see what are the things we need to do. So, to start with,

yarn add --dev @types/react typescript @types/node

Next we should convert the generated _app.js and index.js in pages directory to tsx file. For _app.js, simple rename it, for index.js, rename it and remove the imported css (you may need some other configurations to use those import, I will not introduce it here) and simplify the index.js file like this:

import React from "react";

export default function Home() {
  return <p>hello</p>;
}

Once the files are renamed, you can run yarn dev to start the NextJs development server. NextJs will kindly help you to generate one simple tsconfig.json and one next-env.d.ts file as it detected you are using TypeScript.

BTW, in this step, I also moved pages into src directory. This is optional of course.

StoryBook

I started with add storybook as global command here, and then use the recommend sb init to initialize the files

yarn global add storybook
yarn sb init

Once the commands finished, you will see two new directories

.storybook: This one contains the main configurations for StoryBook, it is created in the root directory.
stories: This one stores the stories you would like to use. StoryBook will generate a bunch of example stories for you, you can just delete them. In my case, this directory is generated in src directory. And I manually moved it out to root directory.

Configure StoryBook

The generated configurations files .storybook/main.js contains the main configurations for your storybook. In my case, since I moved the generated stories directory, I need to change the entry stories

module.exports = {
  // Update stories to where you would like to store them.
  stories: ["../stories/**/*.stories.mdx", "../stories/**/*.stories.tsx"],
  addons: ["@storybook/addon-links", "@storybook/addon-essentials"],
};

Try StoryBook

I added one simple component to try if the StoryBook is configured correctly.

// src/components/text-input.tsx
import React from "react";

export const TextInputComponent: React.FunctionComponent = () => {
  return (
    <div>
      <input placeholder="type"></input>
    </div>
  );
};

// ./stories/text-input.stories.tsx
import React from "react";
import { TextInputComponent } from "../src/components/text-input";
export default {
  title: "story/text-input",
};

export const Primary: React.FunctionComponent = () => <TextInputComponent />;

Once the above files are added, run

yarn run storybook

and you will see the newly created component.

TailwindCSS

You will soon realize the component is a little bit boring - and it is time to add some style on it to make it a little bit better. So the next step is to configure TailwindCSS.

yarn add tailwindcss
yarn tailwindcss init -p

The above two commands will install tailwind and generate the default configurations for you.

You will see two newly added configuration files - postcss.config.js and tailwind.config.js.
Following the official guidance of tailwind, I added two plugins under postcss.config.js

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

Note: You must use the interoperable object-based format based on the NextJs document (you can find this note at the bottom).
Then add tailwind into styles/globals.css

@tailwind base;

@tailwind components;

@tailwind utilities;

Add style to the component

// ./src/components/text-input.tsx
import React from "react";

export const TextInputComponent: React.FunctionComponent = () => {
  return (
    <div>
      <input
        placeholder="type"
        className="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
      ></input>
    </div>
  );
};

And use it in your main page

// ./src/pages/index.tsx
import { Fragment } from "react";
import { TextInputComponent } from "../components/text-input";

export default function Home() {
  return (
    <Fragment>
      <p>Hello</p>
      <TextInputComponent />
    </Fragment>
  );
}

Then you can start your NextJs server to view it on your main page.

What about StoryBook

Then you start your StoryBook server, and found - the style is not applied. Why? My understanding is that StoryBook does not know we are using tailwind at all - while NextJs knows it because it is imported in the _app.tsx file. So our next step is to let StoryBook be aware of this as well. To achieve this, we should update the .storybook/preview.js file

import "../styles/globals.css";
export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
};

Then you start your StoryBook server again, still, you find there is no style (or even worse, you may see error message - I can not recall exactly you will see now.) Basically the reason is StoryBook's webpack component is not using postcss-loader - while NextJs has builtin support for it. To change it, we should update the .storybook/main.js file

module.exports = {
  stories: ["../stories/**/*.stories.mdx", "../stories/**/*.stories.tsx"],
  addons: ["@storybook/addon-links", "@storybook/addon-essentials"],
  webpackFinal: (config) => {
    return {
      ...config,
      module: {
        ...config.module,
        rules: [
          // Filter out the default css loader
          ...config.module.rules.filter((rule) => /\.css$/ !== rule.test),
          {
            test: /\.css/,
            use: [
              {
                loader: "postcss-loader",
                options: {
                  plugins: [require("tailwindcss"), require("autoprefixer")],
                  postcssOptions: {
                    ident: "postcss",
                    sourceMap: true,
                  },
                },
              },
            ],
          },
        ],
      },
    };
  },
};

Note1 We are filtering out one built in css rule here, as the builtin one is not applicable for postcss.
Note2 When speicfy plugins, you can not simply put a string here, it has to be required object.

Once the configurations are placed, you can start your storybook server again and see your styled component.

Cypress and Cypress-React-Unit-Test

To test the newly added component, we can use cypress.

yarn add --dev cypress cypress-react-unit-test

Although in the document of cypress-react-unit-test it says we can initialize cypress with cypress-react-unit-test init command, but I failed to achive it. So I will do it manually. To start, start cypress server once.

yarn cypress open

The above command will initialize your basic cypress configurations - it creates one cypress.json file and one cypress directory.

Then we can follow the document in cypress-react-unit-test to setup it

// cypress.json
{
  "experimentalComponentTesting": true
}

// cypress/support/index.js
import "./commands";
require("cypress-react-unit-test/support");

// cypress/tsconfig.json
{
  "extends": "../tsconfig.json",
  "include": ["./**/*.ts*"],
  "compilerOptions": {
    "baseUrl": ".",
    "jsx": "react",
    "types": ["cypress"]
  }
}

// ./tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": false,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "baseUrl": "src" // <- Add this line
  },
  "include": ["next-env.d.ts", "src"],
  "exclude": ["node_modules", ".storybook"]
}

// ./cypress/global.d.ts
/// <reference types="cypress" />

// ./cypress/plugins/index.js
/// <reference types="cypress" />

module.exports = (on, config) => {
  return config;
};

Note We need to add the baseUrl line to satisfy cypress, otherwise it will complain (sorry I can not recall what it was complaining about exactly).

After that, you can start to write a simple cypress test

// cypress/component/text-input.spec.tsx
import React from "react";
import { mount } from "cypress-react-unit-test";
import { TextInputComponent } from "../../src/components/text-input";
import "../../styles/globals.css";
describe("HelloWorld component", () => {
  it("works", () => {
    mount(<TextInputComponent />);
  });
});

Then you run yarn cypress open and click the test you just added - however, it wont make it. You will see it is complaining that there is no loader for this file. Guess cypress or cypress-react-unit-test does not have builtin support for Typescript - so we need to add the webpack loader manually. In addition, you also want to set the loader for css, as cypress does not support it by default either.

/// <reference types="cypress" />

const webpackPreprocessor = require("@cypress/webpack-preprocessor");
const commonOptions = require("../../webpack.config");

commonOptions.resolve = {
  extensions: [".tsx", ".ts", ".js", ".css"],
};

commonOptions.module.rules.push({
  test: /tsx$/,
  use: [
    {
      loader: "babel-loader",
      options: {
        presets: ["@babel/preset-react", "@babel/preset-typescript"],
      },
    },
  ],
});

commonOptions.module.rules.push({
  test: /css$/,
  use: [
    "style-loader",
    "css-loader",
    {
      loader: "postcss-loader",
      options: {
        plugins: [require("tailwindcss"), require("autoprefixer")],
      },
    },
  ],
});

module.exports = (on, config) => {
  // `on` is used to hook into various events Cypress emits
  // `config` is the resolved Cypress config
  const options = {
    // send in the options from your webpack.config.js, so it works the same
    // as your app's code
    webpackOptions: commonOptions,
    watchOptions: {},
  };

  on("file:preprocessor", webpackPreprocessor(options));
  return config;
};

Forgive the bad naming, I am really lazy to change it atm.

You may notice that the loader used here is different to the ones we used in StoryBook, because if we use the same configuration as the ones in StoryBook, it wont work. I am still unsure why this is happening.

OK, with all the configuration above, you can now use cypress without any issue.

Main Take Away

WebPack is really important.

Understand Basic Lifetime Annotation in Rust

cvifli — Mon, 03 Jun 2019 13:29:24 +0000

Lifetime annotation in rust is a relatively unique concept and it is hard to understand (at least for me). Spent some time on it and just want to share my understanding.

TL;DR

Every reference should have a lifetime.
The compiler wants to know the lifetime of every reference.
When the returned value is a reference, the compiler may fail to know its lifetime.
So, we should specify it.

Ok, let's start with the example from The Book.

fn longest(x: &str, y: &str) -> &str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

This code will not be compiled. The error message is as follwoing:

error[E0106]: missing lifetime specifier
 --> src/main.rs:1:33
  |
1 | fn longest(x: &str, y: &str) -> &str {
  |                                 ^ expected lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `x` or `y`

well, according to The Book, the reason is:

Rust can’t tell whether the reference being returned refers to x or y

Based on this statement, I started to think, what if I did not return things relates to x and y? So I wrote this code:

fn longest(x: &str, d: & str) -> & str {
    "ddd"
}

This time I got the same error and help message as before. So I started to think what is behind the help message. Then I noticed that at the very beginning, it suggests

this function's return type contains a borrowed value ...

So maybe this should be the main reason instead of the x and y stuff 🤔? Ok, it suggested borrowed value, and yes I intended to return one borrowed value &str. But where could the borrowed value come from and what lifetime should the returned value have? Remember according to The Book, every reference should have a lifetime.

I guess from the compiler's perspective, this borrowed value can mainly from two sources. The first one is the parameter this function got, and the second one is any value created within the function (surely it could also be from global variables, e.g. constant). So what is the lifetime of these situations? Let's investigate them one by one. And we start with return value created within the function.

If we want to return a reference to inner scope variables, the reference should have a long lifetime. Otherwise, the reference would be dropped once the function scope is ended. This reminds me of the static lifetime specifier (surely it can also be 'a ). According to documentation, this specifier means the variable has the life time as long as the whole project. So I changed the code to

fn longest(x: &str, d: & str) -> &'static str {
    "ddd"
}

Luckily this program compiled and returned me the expected result 🆒. But what if I want to return a reference to a String ? So I changed the code to

fn longest(x: &str, d: & str) -> &'static str {
    &String::from("ddd")
}

This time I got some different error message, which is

2 |     &String::from("ddd")
  |     ^-------------------
  |     ||
  |     |temporary value created here
  |     returns a reference to data owned by the current function

This error message is easy to understand, the created memory for this String struct in heap would be dropped once the function's scope is ended. In that case, the reference would become one dangling reference, which violates the compiler's rule.

Ok now let's have a look at get reference from parameters. Again, let's think about what compiler would think when it saw the signature. It saw two parameters, but the question is that these two parameters might have different lifetime. In that case, which lifetime should the compiler use to create the reference? We don't know, neither the compiler, and that is why it complains. In that case, we should specify the lifetime of them. So we can just paste the code provided from The Book.

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

Based on the code above we can see that we are telling the compiler that both x, y, and the returned value have a lifetime of 'a. 'a is just one generic statement, it tells the lifetime of x and y. In the meantime, it also tells the compiler that the returned value should live at least as long as lifetime a. Hence, the compiler would be happy. It got all the information it needs.

One thing should be noticed is that we usually add 'a to all parameter, which is not necessary. In the above case, it was because the returned value could either be x or y, no one knows it until runtime. But if we are sure about which one would be returned, say x, we can just specify the lifetime of x

fn longest<'a>(x: &'a str, y: str) -> &'a str {
    x
}

We can also specify a different lifetime for the different parameter, but it should be noted that the returned value's lifetime can only be one.

fn longest<'a, 'b>(x: &'a str, y: &'b str) -> &'b str {
    y
}

So, in conclusion, we should inform the compiler every reference's lifetime, otherwise, it will complain. Although some times the compiler can infer it, sometimes we should tell it explicitly.

Rust Tutorial - Lifetime Specifiers Explained

Rust Lifetimes

Validating References with Lifetimes