DEV Community: Leonardo Bravo

Setup React with Typescript and esbuild.

Leonardo Bravo — Tue, 24 Aug 2021 14:39:27 +0000

When we want to develop a React app the number one choice is Create React App (CRA), it is a complete framework ready to develop and ship your app, but this is the Javascript ecosystem and always gonna be a bunch of alternatives so one of them can be a development template similar to CRA based on Typescript and esbuild.

What is esbuild? you ask, well esbuild is like it's homepage describes it: "An extremely fast JavaScript bundler" and this is true, go to the homepage to checkout the benchmarks.

DISCLAIMER: this guide has the purpose to show how you can setup React, Typescript and esbuild as modules bundler, so you can use it in small projects, if this is not your case I strongly recomend use CRA.

Said that, let's go to write some code lines. First checkout the folder structure:

As you see it, within this folder structure are the tipical folders public and src, like CRA src folder contains an entry point index.tsx this one is gonna be used by esbuild to generate the bundles, also includes another files that I explain bellow, the public folder contains the index.html that is used by the development server, the esbuild folder contains the files serve.ts and build.ts that creates the development server and builds the app respectively also includes a config file used by both files, the rest files are config files used by eslint and Jest (yes, this template also includes the popular test runner). Before dive into each folder and their respectives files checkout the package.json and tsconfig.json.

`package.json`

"scripts": {
    "type-check": "tsc",
    "start": "yarn type-check && ts-node esbuild/serve",
    "build": "yarn type-check && ts-node esbuild/build",
    "test": "yarn type-check && jest"
  },
  "dependencies": {
    "@types/node": "^12.0.0",
    "@types/react": "^17.0.0",
    "@types/react-dom": "^17.0.0",
    "esbuild": "^0.12.21",
    "open": "^8.2.1",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "ts-node": "^10.2.1",
    "typescript": "^4.1.2"
  },
  "devDependencies": {
    "@babel/preset-env": "^7.15.0",
    "@babel/preset-react": "^7.14.5",
    "@babel/preset-typescript": "^7.15.0",
    "@testing-library/jest-dom": "^5.14.1",
    "@testing-library/react": "^12.0.0",
    "@testing-library/user-event": "^13.2.1",
    "@types/jest": "^26.0.15",
    "babel-jest": "^27.0.6",
    "eslint": "^7.32.0",
    "eslint-plugin-jest-dom": "^3.9.0",
    "eslint-plugin-jsx-a11y": "^6.4.1",
    "eslint-plugin-react": "^7.24.0",
    "eslint-plugin-react-hooks": "^4.2.0",
    "eslint-plugin-testing-library": "^4.11.0",
    "jest": "^27.0.6"
  }

These are all the dependencies you need to make this template works succesfully, maybe you found unfamiliar the open package, this one is gonna be used by serve.ts to open your default browser, the rest are tipical dependencies you find within a React-Typescript app. As follow, there are the scripts field, the type-check script as you guess is used to run the Typescript compiler before the another scripts. The rest scripts are related with the folders mentioned previously and are gonna be explain each other bellow.

`tsconfig.json`

{
  "ts-node": {
    "extends": "ts-node/node14/tsconfig.json",
    "transpileOnly": true,
    "files": true,
    "compilerOptions": {
      "target": "es6",
      "module": "commonjs",
      "esModuleInterop": true,
      "moduleResolution": "node"
    }
  },
  "compilerOptions": {
    "target": "es6",
    "baseUrl": "src",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx"
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

About tsconfig.json the field compilerOptions setups the Typescript compiler when the type-check script runs, ts-node field setups the ts-node package this one allows execute the scripts start and build. Now, checkout the other scripts:

`start`

This script executes the serve.ts file, this file uses the esbuild.serve() method as follow:

function startDevServer() {
  createServer(async (...args) => {
    const res = args[1];
    try {
      const publicHTML = await readFile(join(PUBLIC_PATH, "index.html"), { encoding: "utf-8" });
      res.end(publicHTML);
    } catch (error) {
      console.log(error);
    }
  }).listen(DEV_SERVER_PORT, () => {
    console.log(`Development server is now running at ${DEV_SERVER_URL}`);
  });
}

(async () => {
  const server = await serve(serveOptions, transformOptions);
  const { host: HOST, port: PORT } = server;

  console.log("ESBuild is now serving your files at:");
  console.table({ HOST, PORT });

  startDevServer();
  await open(DEV_SERVER_URL);
})();

First an IIFE is called, then the serve method is called, this method creates a local server that serves the bundled files (js, css and static files) based on serveOptions and transformOptions. This objects are provide by the config file mentioned previously.

`serveOptions`

export const serveOptions: ServeOptions = {
  servedir: "www",
  host: "127.0.0.1",
  port: 8080,
};

serveOptions sets the server, this is http://localhost:8080.

`transformOptions`

export const transformOptions: BuildOptions = {
  entryPoints: ["src/index.tsx"],
  outdir: "www/serve",
  bundle: true,
  format: "esm",
  inject: ["esbuild/config/react-shim.ts"],
  loader: serveLoader,
};

transformOptions sets esbuild that outputs the bundles at URL: http://localhost:8080/serve, this object has two keys, inject and loader. inject uses the file react-shim.ts this file allows auto import React:

`react-shim.ts`

import * as React from "react";
export { React };

loader uses the object serveLoader, this loader sets esbuild to process static files as "dataurl" at development, the other option is process static files as "file" but is more convenient serve files as "dataurl".

const serveLoader: ILoader = {
  ".png": "dataurl",
  ".jpg": "dataurl",
  ".webp": "dataurl",
  ".jpeg": "dataurl",
  ".gif": "dataurl",
  ".svg": "dataurl",
};

Based on the entry point file extension esbuild knows that have to process jsx syntax.

ServeOptions and TransformOptions are types provide by esbuild, ILoader is a type based on Loader type (also provide by esbuild).

`ILoader`

type ILoader = {
  [key: string]: Loader;
};

Until now the template is serving files at http://localhost:8080/serve, open this URL at your browser.

With this in mind, we can create an index.html file at public folder that consumes the files at http://localhost:8080/serve as follow:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta name="description" content="Web app created using React and ESbuild" />
    <link rel="manifest" href="manifest.json" />
    <!--
      Styles sheets provide by your React app are serve by the developement server running at http://localhost:8080/
      this server is created by Esbuild when executes the "start" script.
    -->
    <link rel="stylesheet" href="http://localhost:8080/serve/index.css" />
    <title>React ESbuild template with Typescript</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <!--
      The JS files are serve same way that the style sheets are.
    -->
    <script src="http://localhost:8080/serve/index.js" type="module"></script>
  </body>
</html>

Now only left serve index.html, the function startDevServer at serve.ts takes care of this, first initializates a http server at http://localhost:3000, then reads the index.html and sends this one on each request.

Well done! Now we can develop react apps, you only to do is reload your browser to view the changes you do.

`build`

The build script executes the build.ts file as follow:

import {
  PUBLIC_PATH,
  buildOptions,
  DEV_LINK_TAG,
  DEV_SCRIPT_TAG,
  BUILD_LINK_TAG,
  BUILD_SCRIPT_TAG,
  HTML_COMMENTS,
} from "./config";

const { readFile, writeFile, copyFile } = promises;

async function createHTMLFileAtBuildPath() {
  await copyFile(join(PUBLIC_PATH, "favicon.ico"), join("build", "favicon.ico"));
  await copyFile(join(PUBLIC_PATH, "manifest.json"), join("build", "manifest.json"));
  await copyFile(join(PUBLIC_PATH, "robots.txt"), join("build", "robots.txt"));

  const HTMLFileAtPublicPath = await readFile(join(PUBLIC_PATH, "index.html"), {
    encoding: "utf-8",
  });
  const HTMLFileAtBuildPath = HTMLFileAtPublicPath.replace(
    HTML_COMMENTS,
    "<!--Files generate by ESbuild-->"
  )
    .replace(DEV_LINK_TAG, BUILD_LINK_TAG)
    .replace(DEV_SCRIPT_TAG, BUILD_SCRIPT_TAG);

  writeFile(join("build", "index.html"), HTMLFileAtBuildPath, { encoding: "utf8" });
  console.log("Your build has been created succesfully");
}

buildSync(buildOptions);
createHTMLFileAtBuildPath();

First imports some constants from config, these are used to process the index.html file at build time.

export const DEV_SERVER_PORT = 3000;
export const DEV_SERVER_URL = `http://localhost:${DEV_SERVER_PORT}`;
export const PUBLIC_PATH = "public";
export const HTML_COMMENTS = /<!--[\s\S]*?-->/g;
export const DEV_LINK_TAG = `<link rel="stylesheet" href="http://localhost:8080/serve/index.css" />`;
export const DEV_SCRIPT_TAG = `<script src="http://localhost:8080/serve/index.js" type="module"></script>`;
export const BUILD_LINK_TAG = `<link rel="stylesheet" href="index.css">`;
export const BUILD_SCRIPT_TAG = `<script src="index.js" type="module"></script>`;

Then esbuild.buildSync() method is called, it processes the src/index.tsx file based on buildOptions object and outputs the generate bundles at build folder.

export const buildOptions: BuildOptions = {
  entryPoints: ["src/index.tsx"],
  outdir: "build",
  bundle: true,
  sourcemap: true,
  minify: true,
  format: "esm",
  inject: ["esbuild/config/react-shim.ts"],
  target: ["es6"],
  loader: buildLoader,
};

buildOptions uses a diferent loader, this is because at build time the static files are output at build folder and pointed by esbuild in this path.

const buildLoader: ILoader = {
  ".png": "file",
  ".jpg": "file",
  ".webp": "file",
  ".jpeg": "file",
  ".gif": "file",
  ".svg": "file",
};

After esbuild.buildSync runs createHTMLFileAtBuildPath() is called, first copies the files from public path to build path, then replaces the index.html developent tags by build tags and writes the new index.html at build folder.

`index.html` at build folder

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta name="description" content="Web app created using React and ESbuild" />
    <link rel="manifest" href="manifest.json" />
    <!--Files generate by ESbuild-->
    <link rel="stylesheet" href="index.css">
    <title>React ESbuild template with Typescript</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <!--Files generate by ESbuild-->
    <script src="index.js" type="module"></script>
  </body>
</html>

To run the start and build scripts without any kind of issue we need to add some files at src folder. First a env.d.ts this file allows us use external modules or files eg: the spinning React logo is a .svg file if we not declare this extension Typescript marks as an error, the solution is simple declare ".svg" file at .env.d.ts.

declare module "*.svg" {
  const content: any;
  export default content;
}

You can declare all the external files or modules that you need. Another file we need is jest-setup.ts which allows add some global config like auto import react and testing-library/jest-dom assertions.

import "@testing-library/jest-dom";
import * as React from "react";
window.React = React; // Auto import React

`test`

This template is incomplete if does not include a test runner, as I mentioned later, the files jest.config.ts and .babelrc are for setup Jest. These files:

`jest.config.ts`

import type { Config } from "@jest/types";

const config: Config.InitialOptions = {
  verbose: true,
  testEnvironment: "jsdom",
  setupFilesAfterEnv: ["<rootDir>/src/jest-setup.ts"],
  transform: {
    "^.+\\.[t|j]sx?$": "babel-jest",
  },
  moduleNameMapper: {
    "\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$":
      "<rootDir>/src/__mocks__/file-mock.ts",
    "\\.(css|less)$": "<rootDir>/src/__mocks__/style-mock.ts",
  },
};

export default config;

`.babelrc`

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

Also we must create a mocks folder at src for mocking css and external files see moduleNameMapper at jest.config.ts

`mocks/styles-mock.ts`

export {};

`mocks/file-mock.ts`

export default "test-file-stub";

Nice! You can run your components tests.

Of course eslint is also include at this template.

`.eslintrc`

{
  "extends": [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:jsx-a11y/recommended",
    "plugin:testing-library/react",
    "plugin:jest-dom/recommended"
  ],
  "parserOptions": {
    "sourceType": "module",
    "ecmaVersion": "latest"
  },
  "env": { "browser": true, "es6": true, "jest": true },
  "rules": {
    "react/react-in-jsx-scope": "off",
    "react/prop-types": ["enabled", { "ignore": "ignore", "customValidators": "customValidator" }]
  }
}

And that's it, to develop React apps apart CRA all we need is a modules bundler, and esbuild is a powerful, flexible and faster one. You can find the entire code at Github and go deep at implementation details. Hope this guide results useful for you.

Caveats

When you change any file at src folder esbuild.serve() refresh automatically files at http://localhost:8080/serve but you need to refresh your browser to see the new changes at your app.

Create a voice recorder with React

Leonardo Bravo — Tue, 17 Aug 2021 01:56:10 +0000

When we develop a web app we can think browsers like a swiss knifes, these include a bunch of utilities (APIs), one of them is get media devices access through mediaDevices API from the navigator object, this allows to devs create features related with the user media devices, this features migth be create voice notes, like Whatsapp Web does.

Today we're gonna create an app that records the user's voice and then saves the recorded voice on an <audio> tag will be played later, this app looks like this

Apart mediaDevices API we require

MediaRecorder constructor, this creates a recorder object from the requested media device through mediaDevices.getUserMedia() method.
Blob constructor, this one allows create a blob object from the data adquired from MediaRecorder instance.
URL.createObjectURL(blob) method, this creates a URL, the URL contains the data (voice) create previously from the Blob instance and it is gonna be use like <audio src=URL/.

If you don't understand, don't worry, I'll explain you below. First, look at the <App/> component.

<App/> consumes a custom hook that provides the recorderState and several handlers. If you don't know how to use a custom hook I share with you a post about this.

The recorderState is like this:

recordingMinutes and recordingSeconds are use to show the recording time and initRecording initializates the recorder.
The other parts of the state, mediaStream will be the media device provide by mediaDevices.getUserMedia() and mediaRecorder will be the instance of MediaRecorder, audio will be the URL mentioned previously.

mediaStream is set by the handler startRecording

After set the mediaStream, MediaRecorder instance is created

Then audio is set

To adquire the voice and create the audio mediaRecorder needs create two event listeners ondataavailable and onstop the first one gets chunks of the voice and pushes it to the array chunks and the second one is use to create the blob through chunks then audio is created. The stop event is fired by saveRecording handler or the effect cleanup function, the cleanup function is called when recording is cancel.

Now take a look at the components <RecorderControls/> and <RecordingsList/>.

<RecorderControls/>

<RecorderControls/> have the prop handlers and this is used by the jsx

<RecordingsList/>

<RecordingsList/> receives audio and consumes a custom hook that pushes the audio created previously.

The handler deleteAudio is like this

And that's it! With React we can make use of useEffect to access the user devices and create related features.

Final Notes

You can find the source code here
The Typescript version here

Keep your React Components clean with custom hooks

Leonardo Bravo — Sun, 15 Aug 2021 05:51:14 +0000

In React, custom hooks have the purpose to group the logic related with the state and effects (useState,useEffect and another hooks) so this way the rest of the component (mostly jsx) consumes the data bring by the custom hook. Today, we take a look on this approach by implementing a timer component.

Our component looks like this:

This component is compose by two components more, a <TimerDisplay/> (blue box) and a <TimerControls/> (orange box)

Now, take a detailed look to their respectives codes:

`<App/>` code looks like this.

You notice both the state-effects logic and the jsx are within the component <App/> this is ok but think a moment if our Timer component requires more features is quite likely that state-effects logic grows and ofcourse the jsx too and yes, this becomes in a code hard to read, maintain and scale. And that's not all, make zoom at the return statement:

Like you see, the <TimerControls/> has the prop setTimer, and means this uses the state update function directly.

Don't be scared, it's just a simple component with a few handlers in it, but yes, you guessed it, if the parent component grows <TimerControls/> will too.

So the solution is separate the state-effects logic and handlers and implement them through a custom hook. In this case, our custom hook gonna be useTimer(). Is mandatory add the word use before the hook name this way React knows that the component uses a hook.

`useTimer()` code looks like this.

In this case useTimer() imports the handlers cause each one requires the setTimer() (if you have a handler that doesn't update the state, the handlers can be consume by the component itself and not the custom hook). The new handlers code looks like this.

The one million question is how <App/> consumes useTimer()? Make zoom again but now at the useTimer() return statement:

useTimer() returns an object with timer (the state), alarmRef (it's just a ref attatched to an <audio> tag that plays when timer comes to zero) and the handlers (setMinutes , playOrPauseTimer and resetTimer). About the last ones note that are functions that returns another functions (the handlers imported) aka closures, now see how the components look like:

`<App/>`

`<TimerControls/>`

Conclusions

If you think that your components code gonna grow, separate the state-effects logic and handlers through a custom hook.
If your components handlers require update the state use them within a custom hook.
Don't forget the use word before name your hook.
Some React experts think that React more than an UI library is a mental model, so the most important hook that you can use is useYourImagination

Final notes

You can find the code at Github
Or if you prefer the new Github web editor

DEV Community: Leonardo Bravo

Setup React with Typescript and esbuild.

package.json

tsconfig.json

start

serveOptions

transformOptions

react-shim.ts

ILoader

build

index.html at build folder

test

jest.config.ts

.babelrc

__mocks__/styles-mock.ts

__mocks__/file-mock.ts

.eslintrc