DEV Community: Yenpeng chen (Ethan)

Painless development setup for React Part 2: Linting & Formatting

Yenpeng chen (Ethan) — Tue, 17 May 2022 08:10:57 +0000

In the previous blog, we set up a basic React development environment using Parcel. Parcel enables us to write modern Javascript and JSX without having to set up a transpiler like Babel manually, and it also provides a development server with hot reloading and hot module replacement if we only change the CSS. This drastically improves the development experience.
We will build on top of the setup we had previously configured and add linter and code formatter.

Code formatting with Prettier

Code formatting is essential for teams that want to maintain a codebase with a consistent style. These code style choices might include whether or not to use the semicolon (given that it is optional in Javascript), single quote vs double quote for strings etc. Most of these decisions have little influence on the logic of the code and are based on stylistic preference and thus can be pretty subjective. It's not difficult to imagine how tedious it is to manually add a semicolon to each statement's end. Fortunately, we have code formatting tools like Prettier, which enable us to configure our preference in the JSON file, and it will do the heavy lifting to format the code for us.

Let's install Prettier as a dev dependency

npm i -D prettier

Create a Prettier config file that allows us to specify our stylistic preferences.

.prettierrc

{
  "semi": false,
  "singleQuote": true
}

Here I configure Prettier to format our code to use a single quote instead of the double quote and omit the semicolon. Prettiter offers a lot of options.

To run Prettier against all our Javascript and JSX files, let's set up an npm script.

  "scripts": {
    "start": "parcel",
    "build": "parcel build",
    "format": "prettier --write \"src/**/*.{js, jsx}\""
  },

Here we find all files recursively in with the src ending with either js or jsx. You can refer to here for more about pattern matching.

Linting with ESLint

Now we have configured our formatter, it's time to set up a linter.
In contrast to a formatter, which takes care of stylistic problems, a linter takes care of code quality. It ensures our code follows certain best practices, for example, not having unused variables floating around, using let or const rather than var for variable declarations ...etc.

Install ESlint as a dev dependency.

npm i -D eslint

First, create an ESLint config file .eslintrc.json with an empty object.

{}

To see how ESlint can help, let's create a Javascript file with a bunch of bad code.

src/badcode.js

var a = 'asdf'
var b = 'qwer'
const c = '123'

if (1) {
  console.log('Hello')
}

function f() {
  b = 123
}

f()

To run ESLint against our bad code, let's run npx eslint src/badcode.js

The result is nothing. No warning or error message.

Even though we have ESlint installed, we have not told ESlint what linting rules we want to use.
By default, no rules apply.

Let's configure ESLint to check for unused variables.

{
  "rules": {
    "no-unused-vars": "error"
  }
}

Now ESLint is shouting at us that our code violates the no-unsed-vars we defined in the config file.

The number of rules can be overwhelming and impractical to configure it one by one. Fortunately, there are many pre-existing configurations presets for us to use directly, eslint:recommended is one of them and provides a good starting point.

To use eslint:recommended, we specify it using the extends key.

https://eslint.org/docs/developer-guide/shareable-configs

.eslintrc.json

{
  "extends": "eslint:recommended"
}

Let execute ESlint to check our src/badcode.js again.

Notice that despite the errors for unused variables, it also reports other errors. Extending eslint:recommended automatically enables a bunch of rules.

Side note:
If you are using VSCode, I recommend installing ESLint extension. Once you enable the extension, there will be a red squiggly line underneath the parts that violates the rules.

Tip:
If you prefer not to be distracted by the pop-up menu when you hover, you can disable the default setting by opening the setting.json file.

{
    ...
    "editor.hover.enabled": false,
}

And map your key preferred key binding to trigger the pop-up.

keybindings.json

    {
        "key": "shift+k", // Your preferred key binding.
        "command": "editor.action.showHover",
        "when": "editorTextFocus"
    },

Specifying environment and `parserOptions`

One thing that might surprise you is that ESLint complains about console not existing.

ESLint does not have any assumption on the environment your code is running in and thus does not know what global variables shall be available.
Since our code will be running in the browser, let's tell ESLint.

{
  "extends": "eslint:recommended",
  "env": {
    "browser": true
  }
}

Now the error is gone.

https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments

Now suppose are want to use syntax in modern JS like const and let.

The editor shows Parsing error.

And instead of giving as linting error it actually break.

This is because ESLint cannot parse our code. By default, ESLint expect ES5 syntax. And let and const are part of the ES6 syntax.
https://eslint.org/docs/user-guide/configuring/language-options#specifying-parser-options

To fix that, we have to tell ESLint the version of Javascript we want it to support by setting the parserOption.

.eslintrc.json

{
  "extends": "eslint:recommended",
  "parserOptions": {
    "ecmaVersion": 2022
  },
  "env": {
    "browser": true
  }
}

Now ESLint should be working as expected.

Let's also configure ESLint to support global variables in ES6; these include things like Promise.

.eslintrc.json

{
  "extends": "eslint:recommended",
  "parserOptions": {
    "ecmaVersion": 2022
  },
  "env": {
    "browser": true,
    "es6": true
  }
}

Like what we did for Prettier, let's add an NPM script for linting our code.

  "scripts": {
    "start": "parcel",
    "build": "parcel build",
    "format": "prettier --write \"src/**/*.{js,jsx}\"",
    "lint": "eslint --fix \"src/**/*.{js,jsx}\""
  },

Now we have a basic setup for our code formatter and linter.

In the next part of the series, I will dive into React specific linter setup and git hook for running Prettier and ESLint automatically before each commit.

Until next time, bye.

References

https://parceljs.org/features/development/
https://dev.to/myogeshchavan97/how-to-configure-eslint-for-your-project-from-scratch-4kg
https://btholt.github.io/complete-intro-to-react-v7/lessons/js-tools/prettier
https://prettier.io/docs/en/comparison.html

Painless development setup for React using Parcel (Part 1)

Yenpeng chen (Ethan) — Mon, 09 May 2022 10:32:04 +0000

Painless development setup for React using Parcel (Part 1)

Configuring a frontend development setup can be very daunting for a beginner. There are simply too many concepts to understand besides Javascript, CSS and HTML:

Which bundler to choose?
Why do we need to transpile our code?
What linting rules should I apply?
What even is a linter?

This blog series is about building a setup with a minimum amount of configuration for React using Parcel. Parcel is an opinionated Javascript bundler that brands itself as a zero config build tool.

Project setup

Source code for demo: https://github.com/EthanChenYen-Peng/parcel-react-setup

mkdir parcel-react-setup
cd parcel-react-setup
npm init -y
git init
touch .gitignore

.gitignore

node_modules/
dist/
.parcel-cache

Install Parcel

Install Parcel as dev dependency

npm i -D parcel

Let's try it out. We first create a src/index.html file, which sources some CSS (src/style.css) and Javascript(src/index.js) see if work.

src/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="style.css" />
    <title>Document</title>
  </head>
  <body>
    <script type="module" src="index.js"></script>
  </body>
</html>

src/style.css

#root {
  color: blue;
}

src/index.js

const root = document.createElement('div')
root.id = 'root'
root.textContent = 'Inserted by JS'
document.body.appendChild(root)

Start our development server using npx parcel src/index.html. Here we are instructing Parcel to use src/index.html as our entry point. For more general syntax, you can refer to here

It works, both CSS and Javascript are sourced in correctly.

Side note:
parcel is a command-line interface provided by the Parcel package when we installed it as a development dependency. It is just a script file written in NodeJS file and can be found in <project_dir>/node_modules/.bin/parcel. In other words, you can start the development server using the command ./node_modules/.bin/parcel src/index.html. However, using npx (Node package running) is shorter and is what you will find in documentation and tutorials.

Running npx commandname automatically finds the correct reference of the command inside the node_modules folder of a project, without needing to know the exact path, and without requiring the package to be installed globally and in the user's path.
https://nodejs.dev/learn/the-npx-nodejs-package-runner

Having to typenpx parcel src/index.html each time we start a development server can be time-consuming and error-prone. Fortunately, we can leverage NPM script, to make our command more declarative.

  "scripts": {
    "start": "parcel src/index.html",
    "build": "parcel build src/index.html",
  },

For more information about NPM script I recommend reading this blog post
Mastering NPM Scripts.

To start a development server, simply run npm run start. Note: Parcel also provides another way for specifying the entry point using source, which offers two major advantages:

It accepts an array and can be helpful in the case of having multiple entry points.
We don't have to duplicate the entry points when running the production build setup.

  "source": ["src/index.html"],
  "scripts": {
    "start": "parcel",
    "build": "parcel build"
  },

Setup React

If you have experience with setting up a React project using Webpack, then you must be somewhat familiar with Babel, a Javascript transpiler that transpile modern Javascript you wrote into versions that can be understood by older browsers. To use the modern Javascript syntax, you would typically need to install @babel/preset-env. In addition to that, in order to use JSX in react, you would need to install @babel/preset-react as well.

Fortunately, Parcel saves us from all these troubles by providing a built-in transpiler with functionalities equivalent to @babel/preset-env and @babel/preset-react.
https://parceljs.org/languages/javascript/#default-presets

Therefore, to use React, we simply install the dependencies.

npm i react react-dom

Add a container div for our React app in our index.html. Notice we also change the file extension to jsx for our Javascript entry file.
index.html

<body>
  <div id="app"></div>
  <script type="module" src="index.jsx"></script>
</body>

Rename our Javascript entry point from src/index.js to src/index.jsx.

import { createRoot } from 'react-dom/client'

function App() {
  return <div>Hello from React</div>
}

const container = document.querySelector('#root')
const root = createRoot(container)

root.render(<App />)

That's it. That is everything we need to get up and running with React.🤯

To appreciate how much Parcel is doing behind the scene, let's compare it to a basic setup using Webpack.

webpack.config.json

const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')

module.exports = {
  entry: path.resolve(__dirname, './src/index.jsx'),
  module: {
    rules: [
      {
        test: /\.(ts|js)x?$/,
        exclude: /node_modules/,
        use: ['babel-loader'],
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
  output: {
    path: path.resolve(__dirname, './build'),
    filename: 'bundle.js',
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: path.resolve(__dirname, './src/index.html'),
    }),
  ],
  mode: 'development',
  devtool: 'cheap-module-source-map',
}

And the development dependencies it required.

  "devDependencies": {
    "@babel/preset-env": "^7.17.10",
    "@babel/preset-react": "^7.16.7",
    "babel-loader": "^8.2.5",
    "css-loader": "^6.7.1",
    "html-webpack-plugin": "^5.5.0",
    "style-loader": "^3.3.1",
    "webpack": "^5.72.0",
    "webpack-cli": "^4.9.2",
    "webpack-dev-server": "^4.9.0"
  },

As can seem, the configuration file in Webpack tends to be very explicit. In Webpack, everything is treated as a module, and it, by default, can only understand JavaScript and JSON file. To process file types other than these two, a loader is required. Here, we use

css-loader to enable Webpack to load CSS.
style-loader to inject CSS into the output HTML.
babel-loader to use Babel to transpile modern Javascript and JSX into an older version; it will source config from a configuration file ie (.babelrc.json).

{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}

Conclusion

Parcel seems to be an excellent bundler for beginners to start with. Its out-of-box functionality gives it a surprisingly low barrier of entry for people beginning web development. This is very important as there are already simply too many concepts to understand besides the topic of asset bundling. Spending too much time digression on bundler configuration might not be time well spent.

In the next post, I'll set up the linter and code formatter, which are crucial for ensuring code consistency and best practices.

Bye for now.

Learn about stacking context

Yenpeng chen (Ethan) — Fri, 06 May 2022 11:40:07 +0000

Learn about stacking context

A stacking context is one of the topics that I find a bit difficult to get my head around; therefore, I think it makes a perfect topic to write about.

Considering this example, boxes A, B and C are all fixed positioned.

<body>
  <div class="box box-a">A</div>
  <div class="box box-b">B</div>
  <div class="box box-c">c</div>
</body>

.box {
  width: 250px;
  height: 250px;
  font-size: 4rem;
  display: flex;
  justify-content: center;
  align-items: center;
  position: fixed;
}

.box-a {
  background-color: var(--color-gray);
  top: 200px;
  left: 200px;
}

.box-b {
  background-color: var(--color-pewter);
  top: 350px;
  left: 350px;
}
.box-c {
  background-color: var(--color-seashell);
  top: 550px;
  left: 300px;
}

The result is not surprising, since all three elements are positioned fixed, the stacking order is determined by their DOM ordering, in this case, C comes after B, which comes after A, as a result, C is on top of B, which is on top of A.

Now, suppose we somehow need to reverse their stacking over. One approach is simply to reverse their DOM ordering.

<body>
  <div class="box box-c">c</div>
  <div class="box box-b">B</div>
  <div class="box box-a">A</div>
</body>

This might not be the ideal approach, but it does get the job done.

A more suitable method is to use z-index to manually control the stacking order.

.box-a {
  ...
  z-index: 3;
}

.box-b {
  ...
  z-index: 2;
}

.box-c {
  ...
  z-index: 3;
}

Now consider another example, but this time rather than having all three elements in the layer(being siblings nodes), let's position box A within a blue container

<body>
  <div class="blue-container">
    <div class="box box-a">A</div>
  </div>
  <div class="box box-b">B</div>
  <div class="box box-c">c</div>
</body>

.blue-container {
  width: 60%;
  height: 300px;
  background-color: var(--color-blue-gray);
}

And then, a new requirement comes in, we are asked to make a decorative element on the top right of the blue container.

<body>
  <div class="blue-container">
    <div class="box box-a">A</div>
    <div class="circle"></div>
  </div>
  <div class="box box-b">B</div>
  <div class="box box-c">c</div>
</body>

.blue-container {
  width: 60%;
  height: 300px;
  background-color: var(--color-blue-gray);
  position: relative;
  overflow: hidden;
}

.circle {
  border-radius: 100%;
  background-color: var(--color-seashell);
  width: 250px;
  height: 250px;
  font-size: 4rem;
  display: flex;
  justify-content: center;
  align-items: center;
  position: absolute;
  top: -125px;
  right: -125px;
}

To make the circle appear on the top-right edge of the blue container, we have set the container to positive: relative.

After a while, we were asked to add another decorative element, a grey vertical bar.

<body>
  <div class="blue-container">
    <div class="box box-a">A</div>
    <div class="circle"></div>
  </div>
  <div class="box box-b">B</div>
  <div class="box box-c">c</div>
  <div class="verticalbar"></div>
</body>

.verticalbar {
  width: 35%;
  height: 100px;
  background-color: var(--color-dark-gray);
  position: fixed;
  left: 400px;
  transform: rotate(90deg);
}

But then, we don't want our blue container to be below the vertical grey bar. How can we do that?
Here is what we know:

Both the blue container and the vertical grey bar are positioned elements, and thus the stacking order depends on the DOM order.
To manual set the DOM order, we can use the z-index property, and the default z-index is 0.
We don't want box B, which has z-index: 2, to be underneath the blue container. Given the above constraints, to place the blue container above the vertical grey bar and below box B, we can set z-index to 1.

.blue-container {
  ...
  z-index: 1;
}

It works. The blue container is above the vertical grey bar and below box B, but something unexpected happened; box B appears to be on top of box A.

That's a bit surprising, isn't it? In the last few steps, we didn't even touch either box A or box B; we simply added a few CSS properties to a parent element of box A (i.e., the blue container) for some layout purposes. How is it possible we somehow altered the stacking order between box A and box B?

Stacking context

To understand why we first have to understand the stacking context.
Taken directly from the excellent book CSS-in-depth by Keith

A stacking context consists of an element or a group of elements that are painted together by the browser.

The critical point here is that elements are being painted together. It implies that no other elements from a different stacking context can be stacked between two elements within the same stacking context.

In other words, z-index only works for elements within the same stacking context.

There are many ways to create a stacking context.
Among those, two are more related to our example.
A stacking context is created on an element if :

It is relatively positioned and has set z-index value.
It is fixed positioned.

In our case, the vertical grey bar and all three boxes, A, B and C, are fixed positioned, creating their own stacking context. Moreover, our blue container is relatively positioned and has a set z-index: 1; therefore, it also creates a stacking context.

Let's review our markup and denote stacking with the prefix "S" and the value for z-index.

<html lang="en">
  # S0
  <head>
    ...
  </head>
  <body>
    <div class="blue-container">
      # S1 z: 1
      <div class="box box-a">A</div>
      . # S2 z: 3
      <div class="circle"></div>
    </div>
    <div class="box box-b">B</div>
    # S3 z: 2
    <div class="box box-c">c</div>
    # S4 z: 1
    <div class="verticalbar"></div>
    # S5 z: 0
  </body>
</html>

Here we have four elements with stacking contexts S1, S3, S4 and S5 within the stacking context created by the root element S0. Thus, their stacking order will be determined by their z-index and DOM order.

S3 has a higher z-index than S1; therefore, box B appears on top of everything within the blue container. Remember, the blue container creates a stacking context and everything within that stacking context is painted together, in this case, box A and the top-right quarter circle.

This explains why box A is below box B even though it has a higher z-index. Its parent element creates a stacking context that has a lower stacking order than box B.

Conclusion

Our artificial example showed how tricky the stacking context can be, and the problem tends to happen very implicitly. In this case, we unintentionally created a stacking context by adding some decorative elements, which broke the original stacking order.

In the future post, I'll address a few common approaches and good practices about managing stacking context.

Bye for now.

References

Front-end bundling: Transpilation

Yenpeng chen (Ethan) — Thu, 02 Sep 2021 07:03:28 +0000

In today's post, I'll briefly explore the topic of Javascript transpilation. Many people might be familiar with the word "compilation" which in the world of software it refers to the process of transforming your higher-level code into machine code which is what computers can understand.

But what about "transpilation"? They sound similar. Are they the same thing? Not quite, otherwise, the term "transpilation" might be deemed redundant. The difference between the two lies in "the level of abstraction". Let's see an example to get what I mean.

Compilation ( C → machine code and C→assembly)

main.c

#include <stdio.h>

int add(int a, int b) {
    return a + b;
}

int main() {
    int x = 2;
    int y = 23;
    int sum = add(x, y);
    printf("%d + %d = %d", x, y, sum);
    return 0;
}

Compile to machine code.

gcc main.c  // produce a.out (binary code)
gcc -S -o main.s main.o // product main.s (assembly code)

Let's print out a section from complied code.

a.out

main.s

As you can see, the result of a.out is indecipherable, and to understand main.s requires deep knowledge of computer system assembly code. The point is that both a.out and main.s are at a lower layer of abstraction than main.c; they are closer to the machine.

Transpilation (ES6 → ES5)

In contrast to compilation, which transforms your source code into something that is at a lower lever, transpilation, on the other hand, keeps the layer of abstraction approximately the same. It is also referred to as "source-to-source compilation". For example, converting a program from python2 to python3 or ES6 to ES5, notice both the source code and output code pretty stay at the same level of abstraction.

As we are focusing on JavaScript here, let's see an example of transpilation using Babel.

npm init -y

mkdir src
touch src/person.js
touch src/index.js

Let's use ES6 class use in person.js. Notice the use of import and export syntax from the ES6 modules.

src/person.js

class Person{
  constructor(name){
    this.name = name
  }

  hello(){
    return `Hello from ${this.name}`
  }
}

export default Person

src/index.js

import Person from './person'

const p = new Person('Ethan')

console.log(p.hello())

Approach 1 : Using directly babel/core in a script.

First we install the dependencies.

npm i -D @babel/core @babel/preset-env

@babel/core is the core module that acts as a wrapper wraps everything in Babel transformation API. Think of it as a tool that provides an entry point to your transformation pipeline.

@babel/core itself does not know how to transform your code. This is where "plugins" come in handy. Babel plugins (or "presets", which is a group of plugins) are the ones that actually do the code transformation. Here I'll be using @babel/preset-env, enabling us to use the latest JavaScript features.

To use @babel/core, we first have to set up a local configuration file.

// ./babel.config.json
{
    "presets": [
        "@babel/preset-env"
    ]
}

Here is a short script to use babel to transform every file in the src directory and output transformed code to the dist directory.

// ./babel-example.js
const path = require('path')
const fs = require('fs')
const babel = require('@babel/core')

const srcPath = path.resolve(__dirname, './src')
const distPath = path.resolve(__dirname, './dist')

if (!fs.existsSync(distPath)){
  fs.mkdirSync(distPath)
}

fs.readdir(srcPath, function(err, files) {
  files.forEach(function(fileName) {
    const srcFilePath = path.resolve(srcPath, `./${fileName}`)
    const distFilePath = path.resolve(distPath, `./${fileName}`)

    let code = babel.transformFileSync(srcFilePath , {}).code;
    fs.writeFileSync(distFilePath, code, { flag: 'w+' })
  })
})

Run node babel_example.js to execute to script.

Let's have a peek into the transformed dist/perform.js file.

"use strict";

Object.defineProperty(exports, "__esModule", {
  value: true
});
exports["default"] = void 0;

function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }

function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }

function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); return Constructor; }

var Person = /*#__PURE__*/function () {
  function Person(name) {
    _classCallCheck(this, Person);

    this.name = name;
  }

  _createClass(Person, [{
    key: "hello",
    value: function hello() {
      return "Hello from ".concat(this.name);
    }
  }]);

  return Person;
}();

var _default = Person;
exports["default"] = _default;

Method 2 : Using babel-cli

Writing a script to transform JS code is doable for a trivial example like this, but as you can imagine, it will get pretty complicated very quickly as your project grows.

Fortunately, Babel does come with a CLI package that provides us with a much easier interface to work with.

npm i -D @babel/cli

package.json

"scripts": {
    "build": "babel src -d dist"
 }

Simply run npm run build. The result produced is exactly the same as in the previous method but is much easier and less error-prone.

That's it for today's post. Bye for now.

References

https://stackoverflow.com/questions/44931479/compiling-vs-transpiling

https://en.wikipedia.org/wiki/Source-to-source_compiler

https://nodejs.org/docs/latest-v13.x/api/esm.html#esm_enabling

https://babeljs.io/docs/en/babel-core

DEV Community: Yenpeng chen (Ethan)

Painless development setup for React Part 2: Linting & Formatting

Code formatting with Prettier

Linting with ESLint

Specifying environment and parserOptions

References

Painless development setup for React using Parcel (Part 1)

Painless development setup for React using Parcel (Part 1)

Project setup

Install Parcel

Setup React

Conclusion

Learn about stacking context

Learn about stacking context

Stacking context

Conclusion

References

Front-end bundling: Transpilation

Compilation ( C → machine code and C→assembly)

Transpilation (ES6 → ES5)

Approach 1 : Using directly babel/core in a script.

Method 2 : Using babel-cli

References

Specifying environment and `parserOptions`