DEV Community: Hung Viet Nguyen

Setup Jest to React Typescript Vite project, also SWC (part 1)

Hung Viet Nguyen — Tue, 15 Mar 2022 01:44:52 +0000

Motivation

Web applications are becoming an indispensable part of our lives. We can build literally everything on the web app nowadays from reading the news, composing email, learning, to video conferences, even gaming. Going hand in hand with that development is the growth in complexity and the unpredictable quality of web applications. Speaking of web application, Create React App (CRA) used to be the first choice when it comes to bootstrapping a React application and it fulfilled its duty. Now CRA is in maintenance mode and the ecosystem gives us a lot of good tools to start a React project like Vite, Parcel, NextJS... I had a chance to use Vite in my daily work and I’m very happy with that, my Developer Experience (DX) and productivity have increased dramatically, it’s blazing fast. However, speed is not the only factor to make a high quality web application. We also need tests. Even though I’m happy with Vite, it took me a while to successfully integrate Jest with Vite. In this post, I am going to setup Jest to a React Typescript Vite project (spoiler alert: swc)

You can find the final code here: https://github.com/nvh95/jest-with-vite

Integrating Jest to Vite

First, generate React Typescript project using Vite. I’m gonna using npm, you can use yarn or pnpm:
```
npm init vite@latest
```
Then, install the main dependency jest:
```
npm i jest --save-dev
```
Install react-testing-library packages:

@testing-library/jest-dom: provides a set of custom jest matchers that you can use to extend jest (e.g: toBeInTheDocument())
@testing-library/react: say no to implementation details testing
@testing-library/user-event: interacts with our UI (fun fact: it can be used in production for real interaction!)
```
npm i @testing-library/jest-dom @testing-library/react @testing-library/user-event --save-dev
```
Exclude test files from typescript type checking when building for production, you don’t want a typescript error in your test file breaks your build in production.

Create tsconfig.prod.json which inherits tsconfig.json, exclude test files from the project:
```
// tsconfig.prod.json
{
  "extends": "./tsconfig",
  "exclude": [
    "./src/__tests__/**",
    "./src/__mocks__/**",
    "./src/test-utils"
  ]
}
```
Use tsconfig.prod.json when building:
```
// Package.json
-"build": "tsc && vite build",
+"build": "tsc -p tsconfig.prod.json && vite build",
```

Add a script test to package.json :

// package.json
+  "test": "NODE_ENV=test jest"

Let’s write a sample test. However, just comment out the render statement for now:

// src/__tests__/App.test.tsx
import { render, screen } from "@testing-library/react";
import App from "../App";

describe("App", () => {
  it("should work as expected", () => {
    // render(<App />);
    expect(1 + 1).toBe(2);
  });
});

Attempt to run it, this error will show up

Jest encountered an unexpected token
Jest failed to parse a file. This happens e.g. when your code or its dependencies use non-standard JavaScript syntax, or when Jest is not configured to support such syntax.
Out of the box Jest supports Babel, which will be used to transform your files into valid JS based on your Babel configuration.
By default "node_modules" folder is ignored by transformers.
...
Details:

/jest-vite/src/__tests__/App.test.tsx:1
({"Object.<anonymous>":function(module,exports,require,__dirname,__filename,jest){import { render, screen } from "@testing-library/react";
                                                                                   ^^^^^^

SyntaxError: Cannot use import statement outside a module

  at Runtime.createScriptFromCode (node_modules/jest-runtime/build/index.js:1728:14)

Before moving forward, let’s tip the iceberg on what makes Vite so fast. One of the reasons is the native ECMAScript Modules. In the development mode, build tools such as CRA bundles all of your code into a single file and serves via a dev server. Vite took a different approach by not bundling your code at all. It leverages the native support for ESM of modern browsers. It sends your file directly without being bundled.

So, Vite takes advantage of ESM, on the other hand, Jest uses CommonJS (it actually has experiment support for Native ESM but it’s not 100% ready now - March of 2022). That’s the reason why you see the error message as above when using import and export. So we have a few options here:
1. Use Jest experiment support for ESM
2. Use babel to compile ESM to CommonJS (similar to what CRA does)
3. Use high performance build tools like esbuild and SWC:
a. esbuild: created by Evan Wallace, co-founder of figma. esbuild is written in Go and it is one of core components for the speed of Vite.
b. SWC: created by Donny (강동윤), a young talent developer from Vercel. SWC stands for Speedy Web Compiler and is written in Rust. SWC is adopted by Vercel and replaced babel to be the compiler of NextJS since version 12.

I did try Jest Native ESM support but it’s not stable right now. So the safe option is just to compile ESM to CommonJS. It’s a tough decision to make between esbuild and SWC.

	esbuild	SWC
Pros	- Dependency of Vite already. So addition third party code will not be much. - @swc/jest is developed by author of swc - @swc/jest is in active development	- Used in NextJS
Cons	- esbuild-jest (which is a community package to use esbuild with jest) is not very active. The last commit is March 2021 (This post is published in March 2022)	- another library to install

Choosing a third party package is always a hard problem. So after considerations and experiments, I chose SWC.

Install SWC by this command:

npm i @swc/core @swc/jest --save-dev

Configure swc by creating .swcrc file at the root of the project:

// .swcrc
{
  "jsc": {
    "target": "es2017",
    "parser": {
      "syntax": "typescript",
      "tsx": true,
      "decorators": false,
      "dynamicImport": false
    },
    "transform": {
      "react": {
        "pragma": "React.createElement",
        "pragmaFrag": "React.Fragment",
        "throwIfNamespace": true,
        "development": false,
        "useBuiltins": false,
        "runtime": "automatic"
      },
      "hidden": {
        "jest": true
      }
    }
  },
  "module": {
    "type": "commonjs",
    "strict": false,
    "strictMode": true,
    "lazy": false,
    "noInterop": false
  }
}

Note that if you use JSX runtime (likely that you do) that’s introduced in React 17, you need to set jsc.transform.react.runtime to automatic (as above). If you use React.createElement, you must set it to classic.

Configure Jest

Create a file jest.config.js at the root project:

module.exports = {
  roots: ["<rootDir>/src"],
  collectCoverageFrom: [
    "src/**/*.{js,jsx,ts,tsx}",
    "!src/**/*.d.ts",
    "!src/mocks/**",
  ],
  coveragePathIgnorePatterns: [],
  setupFilesAfterEnv: ["./config/jest/setupTests.js"],
  testEnvironment: "jsdom",
  modulePaths: ["<rootDir>/src"],
  transform: {
    "^.+\\.(ts|js|tsx|jsx)$": "@swc/jest",
    "^.+\\.css$": "<rootDir>/config/jest/cssTransform.js",
    "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)":
      "<rootDir>/config/jest/fileTransform.js",
  },
  transformIgnorePatterns: [
    "[/\\\\]node_modules[/\\\\].+\\.(js|jsx|mjs|cjs|ts|tsx)$",
    "^.+\\.module\\.(css|sass|scss)$",
  ],
  modulePaths: ["<rootDir>/src"],
  moduleNameMapper: {
    "^react-native$": "react-native-web",
    "^.+\\.module\\.(css|sass|scss)$": "identity-obj-proxy",
  },
  moduleFileExtensions: [
    // Place tsx and ts to beginning as suggestion from Jest team
    // https://jestjs.io/docs/configuration#modulefileextensions-arraystring
    "tsx",
    "ts",
    "web.js",
    "js",
    "web.ts",
    "web.tsx",
    "json",
    "web.jsx",
    "jsx",
    "node",
  ],
  watchPlugins: [
    "jest-watch-typeahead/filename",
    "jest-watch-typeahead/testname",
  ],
  resetMocks: true,
};

A lot of magic happens here but I can brief some important points.

Transform code to CommonJS using SWC:

transform: {
    "^.+\\.(ts|js|tsx|jsx)$": "@swc/jest",
...
},

Transform css and files:

transform: {
  "^.+\\.css$": "<rootDir>/config/jest/cssTransform.js",
  "^(?!.*\\.(js|jsx|mjs|cjs|ts|tsx|css|json)$)":
    "<rootDir>/config/jest/fileTransform.js",
...
},

Create config/jest/cssTransform.js and config/jest/fileTransform.js to transform css and files. Those 2 files are from CRA.

// config/jest/cssTransform.js
"use strict";

// This is a custom Jest transformer turning style imports into empty objects.
// http://facebook.github.io/jest/docs/en/webpack.html

module.exports = {
  process() {
    return "module.exports = {};";
  },
  getCacheKey() {
    // The output is always the same.
    return "cssTransform";
  },
};

// config/jest/fileTransform.js
"use strict";

const path = require("path");
const camelcase = require("camelcase");

// This is a custom Jest transformer turning file imports into filenames.
// http://facebook.github.io/jest/docs/en/webpack.html

module.exports = {
  process(src, filename) {
    const assetFilename = JSON.stringify(path.basename(filename));

    if (filename.match(/\.svg$/)) {
      // Based on how SVGR generates a component name:
      // https://github.com/smooth-code/svgr/blob/01b194cf967347d43d4cbe6b434404731b87cf27/packages/core/src/state.js#L6
      const pascalCaseFilename = camelcase(path.parse(filename).name, {
        pascalCase: true,
      });
      const componentName = `Svg${pascalCaseFilename}`;
      return `const React = require('react');
      module.exports = {
        __esModule: true,
        default: ${assetFilename},
        ReactComponent: React.forwardRef(function ${componentName}(props, ref) {
          return {
            $$typeof: Symbol.for('react.element'),
            type: 'svg',
            ref: ref,
            key: null,
            props: Object.assign({}, props, {
              children: ${assetFilename}
            })
          };
        }),
      };`;
    }

    return `module.exports = ${assetFilename};`;
  },
};

Remember to install camelcase as a dev dependency (do not install version 7, since it dropped the support for CommonJS):

npm install --save-dev camelcase@6

Then, add ability to search test files and test names in pattern mode. Note that if you using Jest ≤ 26, please install jest-watch-typeahead@0.6.5, if you use Jest ≥ 27, please use jest-watch-typeahead^1.0.0:

watchPlugins: [
  "jest-watch-typeahead/filename",
  "jest-watch-typeahead/testname",
],

// For jest <= 26
npm i jest-watch-typeahead@0.6.5 --save-dev
// For jest >= 27
npm i jest-watch-typeahead --save-dev

Everything you want to do to your test environment such as extends the jest matchers with @testing-library/jest-dom, mock some APIs that’s not implemented in jdom, you can put to config/jest/setupTests.js:

  setupFilesAfterEnv: ["./config/jest/setupTests.js"],

// config/jest/setupTests.js
import "@testing-library/jest-dom/extend-expect";

window.matchMedia = (query) => ({
  matches: false,
  media: query,
  onchange: null,
  addEventListener: jest.fn(),
  removeEventListener: jest.fn(),
  dispatchEvent: jest.fn(),
  addListener: jest.fn(),
  removeListener: jest.fn(),
});

Object.defineProperty(URL, "createObjectURL", {
  writable: true,
  value: jest.fn(),
});

Uncomment the render in the test file and run npm test.
```
// src/__tests__/App.test.tsx
-    // render(<App />);
+     render(<App />);
```
At this moment, you can run the test successfully.

Using @swc/jest to compile code to CommonJS is much faster than babel-jest, ts-jest which have long cold starts when executing tests in a large project.

Outro

Hooray. Congratulations, you’ve successfully integrated Jest with Vite. But our journey is not over yet. In the next post, we’re going deal with Vite variable environment with special syntax import.meta.env together. And some preview on a blazing fast unit-test framework powered by Vite: Vitest. Stay tuned! Happy coding!

How to choose a third party package

Hung Viet Nguyen — Sat, 04 Dec 2021 15:20:43 +0000

Introduction

A wise man once said "don't reinvent the wheel". It's true for every industry, including software development. When developing a feature, sometimes you are in a situation "I need a third party package". So, how to correctly choose a library or package? In the past, whenever I thought I needed an external library, I just googled it (e.g: react charting libraries), chose a random package, then tried it. If it worked, I used it. But it turned out that this strategy was not optimal. In this article, I will share some personal tips for choosing a javascript package. But these tips can be applied to any other language, framework, or even when choosing a language for your team.

1. Fit your need

It sounds obvious that you should choose a solution that solves your problem. A package usually tries to solve a set of problems in general. Meanwhile, your use case is particular to your situation, and the package might not fit. Please make sure the third party code you are going to install handles sufficiently, but not too much. Don't over-engineer a solution. Many times, DIY is a good option.

2. Easy to adopt

In the industry, you don't work alone. So, pick a solution that your team members are able to adapt to quickly. You don't want to choose a solution that only you can implement and maintain.

3. Popularity

It's usually true that a good solution is a popular one (if a solution is good, why isn't it popular)? I measure the popularity of a javascript package by the number of github stars and the number of weekly downloads on https://npmjs.com. A package with a large community proves that it solves the problem for many people. It comes with the advantage of having better support when we run into an issue. A more popular package will have more maintainers, contributors and users, so it's more mature than a less popular one. It usually has good documentation and tutorials, which help to easily adopt and use it correctly and efficiently.

Bonus: https://stateofjs.com/ is a great resource for you to know about what's trending in javascript each year

4. In active development

It's very important that you are choosing an active project instead of a dead/unmaintained project. An active project improves over time through community feedback. An unmaintained project does not move forward, fix functional bugs or patch security issues. Sometimes, a very popular package can be abandoned and go into a "frozen" state with many open issues and pull requests. It might have been a great solution in the past, but this is a sign that we have to move on. An example is react-loadable. It was a great solution for a very long time for code-splitting in React. I totally loved it. But it's stale now with many issues and PRs since 2018 (this post is written at the end of 2021). Now, if I need to split code in React, I use loadable-components, which is in active development, becoming more popular, patches bugs reported by the community, and most importantly, solves my problems. My personal advice: choose a package that's active in the last 3-6 months, with issues that are being resolved and PRs that are being merged.

5. License

It's very important that the package you install grants you the permission to use it for commercial purpose in production. Packages in the wild are great. But not all of them are free to use.

Let's take an example. If you are working with charts, you might have heard of Highcharts - a rock-solid and incredibly flexible charting library made for developers. You download it from npm, make a chart, it looks great, and you are ready to roll out the feature. But please note that Highcharts is not free for commercial use. So if you are writing code for your company and your company hasn't bought a license to use this package in production, you are basically breaking the law. We don't want that, right? So please buy a license before using Highcharts in production. Myself, I use Recharts instead, a free package powered by D3 with MIT license and in very active development.

Software licenses are quite complicated and go beyond the purpose of this post. But in general, packages with MIT, Apache 2.0 and BSD are safe to use for commercial purpose. If you choose a package with a license that is not one of those, please read the license carefully.

6. Reasonable size

You don't want to bloat your web application's bundle size by installing a 700kb package. Sometimes it is necessary, but most of the time it is not. Please consider the size of a library before making a decision. You need to know about the unpacked size, the bundle size, and the gzipped size. A larger package means you need more hard disk and bandwidth, which means more money you need to pay, also it takes a longer time for users to load your app.

7. DIY

As mentioned in Fit your need, many packages try to solve a general problem (thus the size of the package is large). You may only need a small part of the package. Sometimes, your problem is unique and there are no existing third party packages out there that solve it. In those cases, it's a great time for you to do it yourself. I found myself in the early days in the industry spending much time finding a third party package to help me build features. But over time, I more rarely used external packages for my daily tasks. It doesn't mean that I always reinvent the wheel. It means that I know what I am doing and I can seek help from the community when I truly need to (for example I will never sanitize user input by myself, but use DOMPurify)

Bonus: For some problems, if you cannot find a package that helps you, make one and give it to the world by making it an open source software. The open source sofware community will give you back many things, more than you can expect.

Conclusion

Above are my very personal tips, they might be true and they might not be true. If there's something you don't agree with, that's OK. Just ignore it, or better, let me know why you don't agree. If you have additional tips, please let me know in the comment section. I would love to hear from you. I hope this helps you choose the right packages for you and your team. Happy coding!!