Forem: Vinodh Kumar

Building a minimal i18n library for react app - Part 2

Vinodh Kumar — Sat, 19 Aug 2023 06:02:39 +0000

Translations fetch util

Create a utility method to dynamically import the translations JSON for the given locale.

touch src/translations/translations-fetch.util.ts

/* eslint-disable @typescript-eslint/no-explicit-any */
import { TranslationsMap } from './translations.interfaces'

const isObject = (data: any) => data && typeof data === 'object'

const mergeDeep = (
  target: Record<string, any>,
  ...sources: Record<string, any>[]
): Record<string, any> => {
  if (!sources.length) return target
  const source = sources.shift()
  if (isObject(target) && isObject(source)) {
    for (const key in source) {
      if (isObject(source[key])) {
        if (!target[key]) {
          Object.assign(target, { [key]: {} })
        }
        mergeDeep(target[key], source[key])
      } else {
        Object.assign(target, {
          [key]: source[key],
        })
      }
    }
  }
  return mergeDeep(target, ...sources)
}

export const getTranslations = ({
  translationsMap = { en: () => Promise.resolve({}) },
  locale,
  defaultLocale,
}: {
  translationsMap?: TranslationsMap,
  locale: string,
  defaultLocale: string,
}) => {
  if (locale === defaultLocale || !translationsMap[locale]) {
    return translationsMap[defaultLocale]()
  }

  return Promise.all([
    translationsMap[defaultLocale](),
    translationsMap[locale](),
  ]).then(([defaultTranslations, userLocaleTranslations]) =>
    mergeDeep({}, defaultTranslations, userLocaleTranslations)
  )
}

Responsibilities:

The "getTranslations" method dynamically imports and returns the translation for the default locale if the user locale and default locale are the same or the user locale does not have an entry in the translations map config.
The "getTranslations" method dynamically imports the translations for both the user locale and default locale and returns the merged translations of both locales if they are different.

Setting up the Translations wrapper

Create the translations component which is going to act as a wrapper for our app and pass in the translation context to all the components.

touch src/translations/translations.tsx

/* eslint-disable @typescript-eslint/no-explicit-any */
import { ReactNode, useEffect, useState } from 'react'
import { TranslationsContext } from './translations-context'
import { TranslationsMap } from './translations.interfaces'
import { getTranslations } from './translations-fetch.util'

interface TranslationsProps {
  children: ReactNode;
  defaultLocale: string;
  initLocale?: string;
  translationsMap?: TranslationsMap;
}

export const Translations = ({
  children,
  defaultLocale,
  initLocale = '',
  translationsMap,
}: TranslationsProps) => {
  const [isLoading, setIsLoading] = useState(true)
  const [locale, setLocale] = useState(initLocale)
  const [translations, setTranslations] = useState({})

  useEffect(() => {
    if (locale) {
      setIsLoading(true)
      getTranslations({ translationsMap, locale, defaultLocale }).then((response) => {
        setTranslations(response)
        setIsLoading(false)
      })
    }
  }, [defaultLocale, locale, translationsMap])

  return (
    <TranslationsContext.Provider
      value={{ locale, setLocale, isLoading, translations, defaultLocale }}
    >
      {children}
    </TranslationsContext.Provider>
  )
}

Input props:

defaultLocale - The primary locale which is expected to have a valid JSON with entries for all the translation keys used in the project.

initLocale - This is an optional prop, if provided the translations component will load the given locale translations during the app load time itself. The reason for keeping this as an optional prop is sometimes the user locale information might be obtained from the backend server via API, that time use the setLocale helper method of the useTranslation hook once the information is fetched.

translationsMap - This should be an object that contains the supported locales as a key and its corresponding dynamic import loader as the value.

Responsibilities:

Have a local state to keep track of the translations loading state.
Have a local state to keep the user-selected locale
Whenever the user-selected locale is changed, update the loader state and load the translations using the "getTranslations" utility method.
Wraps the given children inside the translation context provider.

Translate helper util

Create a utility method to traverse the given translation key and return the corresponding value.

touch src/translations/translate-helper.util.ts

/* eslint-disable @typescript-eslint/no-explicit-any */
import { TranslateOptions, TranslateParams } from './translations.interfaces'

const ESCAPE_KEYS: Record<string, string> = {
  '&': '&amp;',
  '<': '&lt;',
  '>': '&gt;',
  '"': '&quot;',
  "'": '&#39;',
  '/': '&#x2F;',
}

const hasOwnProperty = (data: any, property: string) =>
  data && typeof data === 'object' && Object.prototype.hasOwnProperty.call(data, property)

const getPlural = (count: number, locale: string) => {
  if (typeof Intl == 'object' && typeof Intl.PluralRules == 'function') {
    return new Intl.PluralRules(locale).select(count)
  }
  return count === 0 ? 'zero' : count === 1 ? 'one' : 'other'
}

export const translate = (
  translations: Record<string, any> = {},
  locale: string,
  key: string,
  params: TranslateParams = {},
  options: TranslateOptions = { escapeValue: true }
): string => {
  let result: any = translations
  let currentKey = key

  const { count } = params
  if (hasOwnProperty(params, 'count') && typeof count === 'number') {
    const plural = getPlural(count, locale)
    if (count === 0) {
      currentKey += '.zero'
    } else if (plural === 'other') {
      currentKey += '.many'
    } else {
      currentKey += `.${plural}`
    }
  }

  currentKey.split('.').forEach((k: string) => {
    if (result[k]) {
      result = result[k]
    }
  })

  if (typeof result !== 'string') {
    console.warn(`Missing translation for ${key}`)
    return ''
  }

  const getParamValue = (paramKey: string) => {
    console.log(paramKey, params)
    const value = params[paramKey]
    return options.escapeValue && typeof options === 'string'
      ? value.replace(/[&<>"'\\/]/g, (key: string) => ESCAPE_KEYS[key])
      : value
  }

  return Object.keys(params).length
    ? result.replace(/\${(.+?)\}/gm, (_, varName) => getParamValue(varName))
    : result
}

Responsibilities:

Should throw a 'Missing key' console warning if the given key is not present in the translations object.
Should replace the params specified in the translation file with the value provided by the user.
Should sanitize the param value for any HTML syntax if the "escapeValue" option is true and ignore otherwise.
Should pluralize the translation if the params have a special param named count.

Translation hook setup

Create the useTranslation hook which will return the following props that can be used in the child components.
setLocale method will update the locale when called.
isLoading returns true when the translations are getting loaded.
t helper method will return the translated value for the given key in the current locale.

  touch src/translations/use-translation.tsx

import { useContext } from 'react'
import { TranslationsContext } from './translations-context'
import { TranslateOptions, TranslateParams } from './translations.interfaces'
import { translate } from './translate-helper.util'

type THelper = (key: string, params?: TranslateParams, options?: TranslateOptions) => string

export interface UseTranslation {
  isLoading: boolean;
  locale: string;
  setLocale: (language: string) => void;
  t: THelper;
}

export const useTranslation = (): UseTranslation => {
  const { setLocale, isLoading, translations, locale } = useContext(TranslationsContext)

  return {
    isLoading,
    locale,
    setLocale,
    t: (key, params = {}, options) => translate(translations, locale, key, params, options),
  }
}

Render translations with HTML support

Create a custom component that can render the HTML tags present in the translation parameters.

touch src/translations/render-translation-with-html.tsx

import { TranslateParams } from './translations.interfaces'
import { useTranslation } from './use-translation'

export const RenderTranslationWithHtml = ({
  tKey,
  params,
  className,
}: {
  tKey: string,
  params?: TranslateParams,
  className?: string,
}) => {
  const { t } = useTranslation()

  const htmlString = t(tKey, params, { escapeValue: false })

  return (
    <span
      className={className}
      dangerouslySetInnerHTML={{
        __html: htmlString,
      }}
    />
  )
}

Export the translations component from the root

touch src/translations/index.ts

export * from './translations'
export * from './use-translation'
export * from './render-translation-with-html'

That's it. We have created our translation library with some basic features. Let's integrate it into our app and verify it.

Integrate the app with translations

Let's wrap our react app inside the Translations component by updating the main.tsx like below,

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import { Translations } from './translations';
import { TRANSLATIONS_MAPPING } from './locales/index.ts';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Translations
      defaultLocale="en"
      initLocale="en"
      translationsMap={TRANSLATIONS_MAPPING}
    >
      <App />
    </Translations>
  </React.StrictMode>
);

Create an app header component with the language change dropdown.

import { ChangeEvent } from 'react'
import { useTranslation } from './translations'

export const AppHeader = () => {
  const { setLocale, locale } = useTranslation()
  return (
    <select
      value={locale}
      onChange={(event: ChangeEvent<HTMLSelectElement>) => setLocale(event.target.value)}
    >
      <option value="en">English</option>
      <option value="fr">French</option>
    </select>
  )
}

Update the App.tsx file to use the translated values instead of strings.

import { AppHeader } from './AppHeader'
import { useTranslation } from './translations'

const App = () => {
  const { t, isLoading } = useTranslation()
  return isLoading ? (
    <>Loading...</>
  ) : (
    <>
      <AppHeader />
      <h1>{t('app.heading')}</h1>
    </>
  )
}

export default App

Demo

Sample repo

The code for this post is hosted in Github here.

Please take a look at the Github repo and let me know your feedback, and queries in the comments section.

Building a minimal i18n library for react app - Part 1

Vinodh Kumar — Fri, 18 Aug 2023 05:30:42 +0000

Introduction

In this blog post, we will explore the process of integrating a basic translation functionality into your React application. However, it's important to clarify that this approach falls short of the capabilities offered by third-party plugins like react-i18next. If your requirements are confined to the following items, then the insights shared here can be quite valuable.

Basic translation support
Willing to craft your custom translation solution
Simply interested to know how these translation libraries work under the hood

When I examine the source code of well-known third-party libraries, I often find them intricate and convoluted. Understanding them proves challenging, almost as if they're composed in a different programming language altogether. The complexity far surpasses what I would have done to address a similar issue. so, here is my simple take on solving it.

Key features of this library

Dynamic values

To support dynamic values inside the translated content, provide the dynamic values object as the second argument to the t helper as shown below.

Examples:

{
  "greeting": "Hello, ${name}"
}

import { useTranslation } from './translations'

export const App = () => {
  const { t } = useTranslation()
  return <h1>{t('greeting', { name: 'Vinodh' })}</h1>
}

Default translation fallback

If the translation key is missing in the selected locale JSON then the value from the default locale is returned as a fallback.

Examples:

en.json

{
  "greeting": "Hello, ${name}",
  "learnMore": "Click on the Vite and React logos to learn more"
}

fr.json

{
  "greeting": "Bonjour, ${name}"
}

Component

import { useTranslation } from './translations'

export const App = () => {
  const { t } = useTranslation()
  return (
    <>
      <h1>{t('greeting', { name: 'Vinodh' })}</h1>
      <p>{t('learnMore')}</p>
    </>
  )
}

Result

The compiled HTML for the French translation will be something like this.

<h1>Bonjour, Vinodh</h1>
<p>Click on the Vite and React logos to learn more</p>

As the 'learnMore' key is not present in the fr.json, the corresponding default locale en.json value is returned.

Pluralization

Pluralization is supported using a special property called count.
To make it work, you need to provide both zero, one, and many values to your JSON files.

Examples:

{
  "items": {
    "zero": "Your cart is empty",
    "one": "You have one item in your cart",
    "many": "You have {count} items in your cart"
  }
}

import { useState } from 'react'
import { useTranslation } from './translations'

export const Cart = () => {
  const { t } = useTranslation()
  const [itemsCount, setItemsCount] = useState(0)
  return (
    <>
      <h1>{t('items', { count: itemsCount })}</h1>
      <button onClick={() => setItemsCount((count) => count + 1)}>Add item</button>
    </>
  )
}

HTML support:

Supports HTML sanitization by default.
To support HTML tags, add them in the translation params alone and explicitly set the "escapeValue" translation param to true.
HTML tags inside the translations JSON are not supported as it will make the JSON vulnerable to security attacks.

Examples:

{
  "greeting": "Hello, ${name}. Your role is ${role}"
}

Using the t helper

import { useTranslation } from './translations'

export const App = () => {
  const { t } = useTranslation()
  const role = 'Admin'

  return (
    <>
      {t(
        'greeting',
        {
          name: '<span className="font-medium">Vinodh</span>',
          role: `<span className="text-gray">${role}</span>`,
        },
        {
          escapeValue: false,
        }
      )}
    </>
  )
}

To simplify this usage, the library has a custom component that escapes the param values by default internally.

  <RenderTranslationWithHtml
    tKey={'greeting'}
    params={{
      name: '<span className="ca-font-medium">Vinodh</span>',
      role: `<span className="ca-font-medium">${role}</span>`
    }}
  />,

Now that we know what we are going to build, let's start with our app setup.

App setup

Let's quickly create a react app using Vite bundler.

pnpm create vite i18n-app --template react-ts
cd i18n-app
pnpm install && pnpm update
pnpm run dev

Your app should be available at http://localhost:5173/.

PS: If you want to create a react app with complete bells and whistles then check out this Create a react app using Vite](https://dev.to/vinomanick/modern-way-to-create-a-react-app-using-vite-part-1-32ol) blog.

Translation files

Create a locales folder that is going to have all our translation JSONs and create the translation JSONs for 'English' and 'French' language.

mkdir locales
touch locales/en.json
touch locales/fr.json

Update the en.json with the following content.

{
  "app": {
    "heading": "Translation supported app"
  }
}

Update the fr.json with the following content.

{
  "app": {
    "heading": "Application prise en charge par la traduction"
  }
}

Create an index.ts file that is going to export a translation map that contains the supported locales and its corresponding dynamic import loader.

touch locales/index.ts

/* eslint-disable @typescript-eslint/no-explicit-any */
export const TRANSLATIONS_MAPPING: Record<string, () => Promise<any>> = {
  en: () => import('./en.json'),
  fr: () => import('./fr.json'),
}

Translations Library

Create a translations folder inside the src to keep all our translation-related code.

mkdir src/translations

Create an interface file to store all our common interfaces.

mkdir src/translations/translations.interfaces.ts

/* eslint-disable @typescript-eslint/no-explicit-any */

export interface TranslationsObject {
  [key: string]: any;
}

export interface TranslationsMap {
  [x: string]: () => Promise<TranslationsObject>;
}

export interface TranslateParams {
  count?: number;
  [key: string]: any;
}

export interface TranslateOptions {
  escapeValue?: boolean;
}

Setting up the context

We are going to need a React context to store our translations object which can be used in all the child components.

touch src/translations/translations-context.tsx

import { createContext } from 'react'
import { TranslationsObject } from './translations.interfaces'

interface TContext {
  locale: string;
  isLoading: boolean;
  setLocale: (language: string) => void;
  translations: TranslationsObject;
  defaultLocale: string;
}

export const TranslationsContext =
  createContext <
  TContext >
  {
    locale: '',
    isLoading: true,
    setLocale: () => null,
    translations: {},
    defaultLocale: '',
  }

Our basic setup is done for the translations library, let's start building our Translation provider and "useTranslation" hook in the next part.

React micro-frontend in ember app - Part 2

Vinodh Kumar — Wed, 16 Aug 2023 10:04:56 +0000

Ember app

Let's create our Ember app inside the apps folder using the Ember CLI.

cd apps
ember new web-app --skip-npm --skip-bower --no-welcome --skip-git
cd ../
pnpm install
npm pkg set scripts.app="pnpm --filter web-app"

To start the ember web app in the dev server run pnpm app start.

Routes setup

Update the ember router.js to create 2 new routes, unlike React Ember which comes with a router by default. one normal route where the logic is present in ember and another admin route where we are going to mount our admin MFE.

Router.map(function () {
  this.route('dashboard')
  this.route('admin', function () {
    this.route('item', { path: '*' })
  })
})

We don't have to simulate the exact routing structure present in the React MFE. Instead, we can load the app in the admin route and react will take care of transitioning to the child routes and updating the browser URL.

But the problem is when a user enters the URL '/admin/groups' the host app will throw an error as it is not a valid route according to that. To avoid this, we created a dummy child route called item inside admin with a glob pattern.

Navbar setup

Let's create a navigation component so that we can navigate between host and MFE routes from the nav bar and validate the SPA.

touch apps/web-app/app/components/app-nav.hbs
touch apps/web-app/app/components/app-nav.js

app-nav.hbs

<nav>
  <LinkTo @route='dashboard'>Dashboard</LinkTo>
  <button {{on 'click' this.handleAdminClick}}>Admin</button>
</nav>

app-nav.js

import Component from '@glimmer/component'
import { action } from '@ember/object'
import { service } from '@ember/service'

export default class AppNavComponent extends Component {
  @service router

  @action handleAdminClick() {
    if (this.router.currentURL.startsWith('/admin')) {
      window.postMessage({ type: 'navigateToAdminMfeHome' }, window.location.origin)
    }
    this.router.transitionTo('/admin')
  }
}

Note:
Ember only knows the admin route, if the user has navigated to the admin/groups page in React, Ember will not be aware of it even though the browser URL is updated by React.

If the user clicks on the admin nav link then it won't do anything because according to Ember the user is still on the same admin page, to avoid this we need to send an event to React forcing it to transition to the root route if the user clicks on the Admin nav link when they are inside any admin route.

If they are on some other router then normal transitioning itself will work.

Update the application.hbs file to add the AppNav component.

{{page-title 'WebApp'}}
<AppNav />
{{outlet}}

Listener for messages from react

Just like how the host app is sending events to react to handle a few cases, react also will send events to capture that we need to have a listener at the app level so let's create one.

touch apps/web-app/app/routes/application.js

import Route from '@ember/routing/route'
import { service } from '@ember/service'
export default class ApplicationRoute extends Route {
  @service router

  setupController() {
    super.setupController(...arguments)
    const { router } = this

    window.addEventListener('message', function (event) {
      console.log('inside host app listener', event.data)
      const { data } = event
      if (!data.type) {
        return
      }
      if (data.type === 'navigateToHost') {
        router.transitionTo(data.payload.route)
      }
    })
  }
}

If you want to navigate to an ember route from react then we need to send a post message with type as navigateToHost with the route info so that ember can do the required transition.

Route templates

Create the route templates for the 2 routes as planned and update the content as below,

touch apps/web-app/app/templates/dashboard.hbs
touch apps/web-app/app/templates/admin.hbs

dashboard.hbs

Dashboard page present in ember <LinkTo @route="admin.item" @model="groups">Groups</LinkTo>

We can create navigation links from ember to react routes using this admin.item route and passing the model prop.

admin.hbs

<div {{admin-mfe-mount}}></div>
{{outlet}}

This div present in this file is going to act as a root div where we are going to mount the react web component app for all the admin and its child routes.

Admin MFE mount modifier

We are going to make use of the ember modifier package to attach the react app to a div present in ember.
so let's install the ember modifier package.

pnpm app add -D ember-modifier

Create the admin-mfe-mount modifier,

mkdir apps/web-app/app/modifiers
touch apps/web-app/app/modifiers/admin-mfe-mount.js

import Modifier from 'ember-modifier'

export default class AdminMFEMountModifier extends Modifier {
  modify(element) {
    import('http://localhost:4173/admin-mfe.js').then((module) => {
      module.mountApp({
        element,
        options: {
          basename: '/',
          baseURL: 'http://localhost:4173/',
        },
      })
    })
  }
}

Now run the ember server and validate the admin MFE is successfully rendered in the given element.

Demo:

Pros & Cons

Having used React MFE inside an Ember app, let's discuss the pros and cons of using the above-mentioned approach to integrate React into Ember.js applications.

Pros

Incrementally migrate an Ember codebase to React
Easy to split the app into multiple MFEs and have a dedicated team for each Micro-frontend.
Provides an opportunity to get away from an unstable legacy code and slowly convert the old code to the latest technologies.
Since it is rendered as a web component, the cookies and session will be extended from the host app so no need to have a dedicated authentication mechanism in the MFE while still achieving the encapsulation provided by the iFrame approach.
The whole release and deployment cycle for the MFE can be decoupled from the host app process.

Cons

Framework footprint of an extra 40 KB (React runtime) in your production bundles

Sample repo

The code for this series is hosted in Github here.

Please take a look at the Github repo and let me know your feedback, and queries in the comments section. If you feel there are more pros and cons to be added here, please do let us know also.

References

Invoking React components from your Ember apps

Rajasegar Chandran ・ Jan 31 '23

#react #ember #javascript #webpack

Create a monorepo using PNPM workspace

Vinodh Kumar — Tue, 15 Aug 2023 09:12:55 +0000

Objective

To create a mono repo using the PNPM package manager and its workspace feature.

The main advantage of the PNPM workspace when compared to the yarn workspace is common packages are not hoisted to the root directory thereby making all the workspace packages completely isolated.

Technologies/Features used

The mono repo we are going to build will have the following features. Again this is my set of tools feel free to change it based on your preference.

Feature	Technology used
Package manager	PNPM
Programming language	Typescript
Basic linting	ESLint
Code formatting	Prettier
Pre-commit hook validator	Husky
Linting only staged files	lint-staged
Lint git commit subject	commitlint

Prerequisites

Tools

You will need the following things properly installed on your computer.

Git
Node.js

PNPM install

If you have installed the latest v16.x or greater node version in your system, then enable the pnpm using the below cmd

corepack enable
corepack prepare pnpm@latest --activate

If you are using a lower version of the node in your local system then check this page for additional installation methods https://pnpm.io/installation

Repo basic setup

Initialize git if you want and enforce the node version with some info in the README.md.

  mkdir pnpm-monorepo
  cd pnpm-monorepo
  pnpm init
  git init
  echo -e "node_modules" > .gitignore
  npm pkg set engines.node=">=22.11.0" // Use the same node version you installed
  npm pkg set type="module"
  echo "#PNPM monorepo" > README.md

Specify the latest PNPM version to use for this project by setting the packageManager property in the package.json file.

  npm pkg set packageManager="pnpm@9.12.3"
  pnpm -v

Run pnpm -v to check whether the desired version of PNPM is installed correctly. If the version is not available in your system then it will automatically ask you to download it from web, simply enter y to download it.

! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-9.12.3.tgz
? Do you want to continue? [Y/n]

Code formatter

I'm going with Prettier to format the code. Formatting helps us to keep our code uniform for every developer.

Installation

Let's install the plugin and set some defaults. Here I'm setting the single quote to be true, update it according to your preference.

  pnpm add -D prettier
  echo '{\n  "singleQuote": true\n}' > .prettierrc.json
  echo -e "coverage\npublic\ndist\npnpm-lock.yaml\npnpm-workspace.yaml" > .prettierignore

VS Code plugin

If you are using VS Code, then navigate to the Extensions and search for Prettier - Code formatter and install the extension.

Extension link: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

Let's update the workspace to use the prettier as the default formatter and automatically format the file on save.
Create the VS Code workspace settings JSON and update it with the following content.

mkdir .vscode && touch .vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Linting

Linter statically analyses your code to quickly find problems. ESLint is the most preferred tool for linting the Javascript code.

ESLint

  pnpm create @eslint/config@latest

The ESLint will ask you a set of questions to set up the linter as per your needs. This is the configuration I've chosen for this project.

? How would you like to use ESLint? …
  To check syntax only
❯ To check syntax and find problems

? What type of modules does your project use? …
❯ JavaScript modules (import/export)
  CommonJS (require/exports)
  None of these

? Which framework does your project use? …
  React
  Vue.js
❯ None of these

Does your project use TypeScript? › No / Yes
- Yes

Where does your code run?
✔ Browser
  Node

The config that you`ve selected requires the following dependencies:
eslint, globals, @eslint/js, typescript-eslint

? Would you like to install them now? › No / Yes
- Yes

? Which package manager do you want to use? …
  npm
  yarn
❯ pnpm
  bun

Update the eslint config with the ignores list to let the ESLint know which files to not format.

/** @type {import('eslint').Linter.Config[]} */
export default [
  ...
  {
    // Note: there should be no other properties in this object
    ignores: ['coverage', '**/public', '**/dist', 'pnpm-lock.yaml', 'pnpm-workspace.yaml'],
  },
  ...
]

Integrating Prettier with ESLint

Linters usually contain not only code quality rules but also stylistic rules. Most stylistic rules are unnecessary when using Prettier, but worse – they might conflict with Prettier!

We are going to use Prettier for code formatting concerns, and linters for code-quality concerns. So let's make the linter run the stylistic rules of 'Prettier' instead.

Install the necessary plugins

  pnpm add -D eslint-config-prettier eslint-plugin-prettier

Add the eslintPluginPrettierRecommended as the last element in the array.

import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'

/** @type {import('eslint').Linter.Config[]} */
export default [
  ...,
  eslintPluginPrettierRecommended,
]

For more info on this: https://prettier.io/docs/en/integrating-with-linters.html

Let's create scripts for running the linter and prettier in the package.json file.

  npm pkg set scripts.lint="eslint ."
  npm pkg set scripts.format="prettier --write ."

Run the pnpm lint cmd to run the ESLint and pnpm format cmd to format the files.

Pre-commit hook validation

Even if we added all these linter and formatter mechanisms to maintain the code quality, we can't expect all the developers to use the same editor and execute the lint and format command whenever they are pushing their code.

To automate that we need some kind of pre-commit hook validation. That's where husky and lint-staged plugins come in handy let's install and set them up.

Install the husky, commitlint, and lint-staged NPM package and initialize it as shown below,

  pnpm add -D @commitlint/cli @commitlint/config-conventional
  echo -e "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs
  pnpm add -D husky lint-staged
  pnpm exec husky init
  echo "pnpm lint-staged" > .husky/pre-commit
  echo "npx --no -- commitlint --edit \${1}" > .husky/commit-msg

Update the package.json file and include the following property. This will run the ESLint on all the script files and Prettier on the other files.

  "lint-staged": {
    "**/*.{js,ts,tsx}": [
      "eslint --fix"
    ],
    "**/*": "prettier --write --ignore-unknown"
  },

Workspace config

Create pnpm-workspace.yaml file and add the following content

touch pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'packages/*'

Create the apps and packages directories in the root.

mkdir apps packages

Sample package - Common

Create a sample package that can be used in the workspace apps.

cd packages
pnpm create vite common --template vanilla-ts
cd ../
pnpm install
npm pkg set scripts.common="pnpm --filter common"

Update the main.ts file with the following content to create a simple isBlank util.

/* eslint-disable @typescript-eslint/no-explicit-any */
export const isEmpty = (data: any) => data === null || data === undefined

export const isObject = (data: any) => data && typeof data === 'object'

export const isBlank = (data: any) =>
  isEmpty(data) ||
  (Array.isArray(data) && data.length === 0) ||
  (isObject(data) && Object.keys(data).length === 0) ||
  (typeof data === 'string' && data.trim().length === 0)

Delete the sample files

cd packages/common
rm -rf src/style.css src/counter.ts .gitignore
cd ../../

Library mode

Vite by default builds the assets in app mode with index.html as the entry file. But we want our app to expose our main.ts file as the entry file, so let's update the Vite config to support that.

Before that let's install the Vite package to auto-generate the type definitions from the library.

pnpm common add -D vite-plugin-dts

Create the vite.config.ts file and update it like this,

 touch packages/common/vite.config.ts

import { defineConfig } from 'vite'
import { resolve } from 'path'
import dts from 'vite-plugin-dts'

// https://vitejs.dev/config/
export default defineConfig({
  build: { lib: { entry: resolve(__dirname, 'src/main.ts'), formats: ['es'] } },
  resolve: { alias: { src: resolve('src/') } },
  plugins: [dts()],
})

The resolve property helps us to use absolute import paths instead of relative ones. For example:

import { add } from 'src/utils/arithmetic'

Update the common package package.json file with the entry file for our script as well as the typings.

{
 ...
 "main": "./dist/common.js",
 "types": "./dist/main.d.ts",
}

Sample app - Web app

Create a sample app that can make use of the workspace package common.

cd apps
pnpm create vite web-app --template react-ts
cd ../
pnpm install
npm pkg set scripts.app="pnpm --filter web-app"

Install the common package as a dependency in our web app by updating the web-app package.json.

"dependencies": {
 "common": "workspace:*",
 ...
 }

Run pnpm install again so that 'web-app' can symlink the common package present in the workspace
Run pnpm common build so that the common package can be found by the web-app server.
Update the App.tsx like below,

import { isBlank } from 'common'

const App = () => {
  return (
    <>
      <p>undefined isBlank - {isBlank(undefined) ? 'true' : 'false'}</p>
      <p>false isBlank - {isBlank(false) ? 'true' : 'false'}</p>
      <p>true isBlank - {isBlank(true) ? 'true' : 'false'}</p>
      <p>Empty object isBlank - {isBlank({}) ? 'true' : 'false'}</p>
    </>
  )
}

export default App

Run pnpm app dev and check whether the common package util is successfully linked to the app.

That's it. We have successfully created a PNPM mono repo from scratch with typescript support.

Dev mode

Most of the time, you just need to build the common package once and use it in the repo apps. But if you are actively making changes in your common package and want to see that in the 'web-app' immediately you can't build the common app again and again for every change.

To avoid this, let's run the common package in watch mode so that any change in the code will rebuild automatically and reflect in the 'web-app' in real-time.

Run these commands in different terminals.

pnpm common build --watch
pnpm web-app dev

Linter update

Now we have a typescript utility library and a react application in our mono-repo. In the ESLint v9.x the ESLint team recommends keeping a single linter file for all the packages but that will not go well with the monorepo architecture, see the discussion for more info. The ESLint team acknowledged this and built a experimental feature to support multiple config files which will be stable in v10.x, you can enable the feature and try it out but for production apps that is not recommended.
So for now we will try to merge the web app linting config created using the vite starter template to the root config file by moving the linting dependencies from web app to the root and updating the config file.

pnpm add -D -w eslint-plugin-react-hooks eslint-plugin-react-refresh eslint-plugin-react
pnpm app remove eslint-plugin-react-hooks eslint-plugin-react-refresh eslint @eslint/js globals typescript-eslint

This is how the final eslint config will look like,

import globals from 'globals'
import pluginJs from '@eslint/js'
import tseslint from 'typescript-eslint'
import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import react from 'eslint-plugin-react'

/** @type {import('eslint').Linter.Config[]} */
export default [
  { files: ['**/*.{js,mjs,cjs,ts}'] },
  {
    languageOptions: { ecmaVersion: 2020, globals: globals.browser },
  },
  {
    // Note: there should be no other properties in this object
    ignores: ['coverage', '**/public', '**/dist', 'pnpm-lock.yaml', 'pnpm-workspace.yaml'],
  },
  {
    files: ['apps/web-app/**/*.{ts,tsx}'],
    settings: { react: { version: '18.3' } },
    languageOptions: {
      // other options...
      parserOptions: {
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: './apps/web-app',
      },
    },
    plugins: {
      react,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    rules: {
      ...react.configs.recommended.rules,
      ...react.configs['jsx-runtime'].rules,
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
    },
  },
  pluginJs.configs.recommended,
  ...tseslint.configs.recommended,
  eslintPluginPrettierRecommended,
]

Feel free to remove the eslint.config.js present in the web-app package as it is no longer needed or comment it out and keep it for reference.
Checkout the web app Readme.md file created by Vite and follow the recommendations if needed.

Advantages:

All your code will be in one single repo with proper isolation.
Only a one-time effort is needed to set up the repo with proper linting, formatting, and pre-commit hook validations which will be extended by the workspace packages.
All the packages will have a similar setup, look and feel.

Tips:

Check out my blog on creating a TS Util library and React app for creating repo packages with all the bells and whistles. Ignore the prettier, pre-commit hook validations in those packages as they are already handled in the root workspace of this mono repo.

Sample repo

The code for this post is hosted in Github here

Please take a look at the Github repo and let me know your feedback, and queries in the comments section.

Create a typescript utility library using Vite

Vinodh Kumar — Tue, 15 Aug 2023 04:58:53 +0000

In this post, we are going to look at how to create a typescript utility library using the Vite bundler.

Why?

There could be many reasons to build a library

To share the code inside your organization
To contribute to the open-source community by creating an NPM package
To extract a common piece of code in a mono repo so that multiple apps can reuse the same logic inside the mono repo.

Technologies/Features used

The library we are going to build will have the following features. Again this is my set of tools feel free to change it based on your preference.

Feature	Technology used
Package manager	PNPM
Package bundler	Vite
Programming language	Typescript
Basic linting	ESLint
Code formatting	Prettier
Pre-commit hook validator	Husky
Linting only staged files	lint-staged
Lint git commit subject	commitlint

Prerequisites

Tools

You will need the following things properly installed on your computer.

Git
Node.js

PNPM install

If you have installed the latest v16.x or greater node version in your system, then enable the pnpm using the below cmd

corepack enable
corepack prepare pnpm@latest --activate

If you are using a lower version of the node in your local system then check this page for additional installation methods https://pnpm.io/installation

App creation

Let's create the app by running these commands.

  pnpm create vite <app-name> --template vanilla-ts
  cd <app-name>
  pnpm install && pnpm update

Run pnpm dev and check out the app.

Initialize git if you want and enforce the node version along with some info in the README.md.

  git init
  echo -e "node_modules\ncoverage" > .gitignore
  npm pkg set engines.node=">=22.11.0" // Use the same node version you installed
  echo "#Typescript utility library" > README.md

Specify the latest PNPM version to use for this project by setting the packageManager property in the package.json file.

  npm pkg set packageManager="pnpm@9.12.3"
  pnpm -v

Code formatter

I'm going with Prettier to format the code. Formatting helps us to keep our code uniform for every developer.

Installation

Let's install the plugin and set some defaults. Here I'm setting the single quote to be true, update it according to your preference.

  pnpm add -D prettier
  echo '{\n  "singleQuote": true\n}' > .prettierrc.json
  echo -e "coverage\npublic\ndist\npnpm-lock.yaml" > .prettierignore

VS Code plugin

If you are using VS Code, then navigate to the Extensions and search for Prettier - Code formatter and install the extension.

Extension link: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

Let's update the workspace to use the prettier as the default formatter and automatically format the file on save.
Create the workspace settings JSON and update it with the following content.

mkdir .vscode && touch .vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Now open the src/main.ts in your VSCode editor and save it. If the semicolons are automatically created then it confirms that our auto formatting is working fine.

Linting

Linter statically analyses your code to quickly find problems. ESLint is the most preferred tool for linting the Javascript code.

ESLint

  pnpm create @eslint/config@latest

The ESLint will ask you a set of questions to set up the linter as per your needs. This is the configuration I've chosen for this project.

? How would you like to use ESLint? …
  To check syntax only
❯ To check syntax and find problems

? What type of modules does your project use? …
❯ JavaScript modules (import/export)
  CommonJS (require/exports)
  None of these

? Which framework does your project use? …
  React
  Vue.js
❯ None of these

Does your project use TypeScript? › No / Yes
- Yes

Where does your code run?
✔ Browser
  Node

The config that you`ve selected requires the following dependencies:
eslint, globals, @eslint/js, typescript-eslint

? Would you like to install them now? › No / Yes
- Yes

? Which package manager do you want to use? …
  npm
  yarn
❯ pnpm
  bun

Update the eslint config with the ignores list to let the ESLint know which files to not format.

/** @type {import('eslint').Linter.Config[]} */
export default [
  ...
  {
    // Note: there should be no other properties in this object
    ignores: ['coverage', 'public', 'dist', 'pnpm-lock.yaml'],
  },
  ...
]

Integrating Prettier with ESLint

Linters usually contain not only code quality rules but also stylistic rules. Most stylistic rules are unnecessary when using Prettier, but worse – they might conflict with Prettier!

We are going to use Prettier for code formatting concerns, and linters for code-quality concerns. So let's make the linter run the stylistic rules of 'prettier' instead.

Install the necessary plugins

  pnpm add -D eslint-config-prettier eslint-plugin-prettier

Add the eslintPluginPrettierRecommended as the last element in the array.

import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'

/** @type {import('eslint').Linter.Config[]} */
export default [
  ...,
  eslintPluginPrettierRecommended,
]

For more info on this: https://prettier.io/docs/en/integrating-with-linters.html

Let's create scripts for running the linter and prettier in the package.json file.

  npm pkg set scripts.lint="eslint ."
  npm pkg set scripts.format="prettier --write ."

Run the pnpm lint cmd to run the ESLint. If it throws, errors like below then our linter prettier integration is working as expected.

To fix it just run pnpm format cmd and run the pnpm lint --fix cmd again. Now the errors should be gone.

Pre-commit hook validation

To automate that we need some kind of pre-commit hook validation. That's where husky and lint-staged plugins come in handy let's install and set them up.

Install the husky, commitlint, and lint-staged NPM package and initialize it as shown below,

  pnpm add -D @commitlint/cli @commitlint/config-conventional
  echo -e "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs
  pnpm add -D husky lint-staged
  pnpm exec husky init
  echo "pnpm lint-staged" > .husky/pre-commit
  echo "npx --no -- commitlint --edit \${1}" > .husky/commit-msg

Update the package.json file and include the following property. This will run the ESLint on all the script files and Prettier on the other files.

  "lint-staged": {
    "**/*.{js,ts}": [
      "eslint --fix"
    ],
    "**/*": "prettier --write --ignore-unknown"
  },

Absolute path import support

We often move around the files to make it more meaningful, when we are doing that, it would be great if we don't have to update the import statements. To do that,

Install the @types/node NPM package

 pnpm add -D @types/node

Create the vite.config.ts file and update it like this,

 touch vite.config.ts

import { defineConfig } from 'vite'
import { resolve } from 'path'

// https://vitejs.dev/config/
export default defineConfig({
  resolve: { alias: { src: resolve('src/') } },
})

Update the tsconfig.json file with the baseUrl for the imports to work in the editor.

{
  "compilerOptions": {
    "baseUrl": "./",
    ....
  }
}

The resolve property helps us to use absolute import paths instead of relative ones. For example:

import { add } from 'src/utils/arithmetic'

App code cleanup:

Update the main.ts file with the following content,

export const add = (a: number, b: number) => a + b
export const sub = (a: number, b: number) => a - b

Delete the sample files

rm -rf src/style.css src/counter.ts

Vite library mode

Vite by default builds the assets in app mode with index.html as the entry file. But we want our app to expose our main.ts file as the entry file, so let's update the Vite config to support that.

import { defineConfig } from 'vite'
import { resolve } from 'path'

// https://vitejs.dev/config/
export default defineConfig({
  build: { lib: { entry: resolve(__dirname, 'src/main.ts'), formats: ['es'] } },
  resolve: { alias: { src: resolve('src/') } },
})

Local dev server update

We can make use of the local dev server to verify our utility library. To do that let's update the index.html file, do note that it will not be exposed to the outside world.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + TS</title>
  </head>
  <body>
    <script type="module" src="/src/main.ts"></script>
    <script type="module">
      import { add, sub } from './src/main'

      const addOutput = document.getElementById('addOutput')
      const subOutput = document.getElementById('subOutput')
      const input1 = document.getElementById('input1')
      const input2 = document.getElementById('input2')
      const getNumber = (element) => parseInt(element?.value)
      const eventHandler = () => {
        const firstVal = getNumber(input1)
        const secondVal = getNumber(input2)
        if (addOutput && subOutput) {
          addOutput.innerText = add(firstVal, secondVal).toString()
          subOutput.innerText = sub(firstVal, secondVal).toString()
        }
      }
      eventHandler()
      input1?.addEventListener('change', eventHandler)
      input2?.addEventListener('change', eventHandler)
    </script>

    <input id="input1" type="number" value="4" />
    <input id="input2" type="number" value="3" />
    <p>Sum of two numbers = <span id="addOutput"></span></p>
    <p>Diff of two numbers = <span id="subOutput"></span></p>
  </body>
</html>

Run the dev server, you should be able to see the library methods in action.

Unit testing

Vitest is a new framework that is gaining popularity with the developers who are using Vite. Let's see how to configure it for our project.

Install the necessary packages

pnpm add -D vitest @vitest/coverage-v8

Create a test file for main component and update it like the below,

touch src/main.test.ts

import { add, sub } from './main'
import { describe, expect, test } from 'vitest'

describe('Utility | Main', () => {
  test('add - should add the given two numbers', async () => {
    expect(add(4, 2)).toEqual(6)
  })

  test('sub - should subtract the given two numbers', async () => {
    expect(sub(4, 2)).toEqual(2)
  })
})

Update the package scripts for running tests

npm pkg set scripts.test="vitest"
npm pkg set scripts.test:cov="vitest run --coverage"

Create the src/setupTests.ts file and update it with the below content.

 touch src/setupTests.ts

import { beforeAll, beforeEach, afterAll, afterEach } from 'vitest'

beforeAll(() => {
  // Add your global beforeAll logics
})

beforeEach(() => {
  // Add your globalbeforeEach logics
})

afterAll(() => {
  // Add your global afterAll logics
})

afterEach(() => {
  // Add your global afterEach logics
})

Update the vite.config.ts file to add the test configs.

import { defineConfig } from 'vitest/config';

// https://vitejs.dev/config/
export default defineConfig({
  ...,
  test: {
    setupFiles: ['src/setupTests.ts'],
    coverage: {
      exclude: ['*.config.*', '*.d.ts'],
    },
  },
});

Run the tests

  pnpm test

Run the tests with coverage

  pnpm test:cov

To run a particular test use the -t param.

  pnpm test -- -t "add"

Sample repo

The code for this post is hosted in Github here.

Please take a look at the Github repo and let me know your feedback, and queries in the comments section.

Create a react app using Vite - Part 3

Vinodh Kumar — Tue, 15 Aug 2023 04:57:28 +0000

Unit testing

Vitest is a new framework that is gaining popularity with the developers who are using Vite. Let's see how to configure it for our project.

Install the necessary packages

pnpm add -D vitest @vitest/coverage-v8
pnpm add -D @testing-library/react jsdom @testing-library/jest-dom

Create the src/setupTests.ts file and update it with the below content.

 touch src/setupTests.ts

// This import will add the DOM related assertions support to the expect statement.
import { beforeAll, beforeEach, afterAll, afterEach } from 'vitest'

import '@testing-library/jest-dom/vitest'

beforeAll(() => {
  // Add your global beforeAll logics
})

beforeEach(() => {
  // Add your globalbeforeEach logics
})

afterAll(() => {
  // Add your global afterAll logics
})

afterEach(() => {
  // Add your global afterEach logics
})

Configure the test environment in the vite.config.ts.
- Change the import path of the defineConfig from vite to vitest/config.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  ...,
  test: {
    environment: 'jsdom',
    setupFiles: ['src/setupTests.ts'],
    coverage: {
      exclude: ['*.config.*', '*.d.ts'],
    },
  },
});

Create a test file for the app component and update it like the below,

touch src/App.test.tsx

import { render, screen } from '@testing-library/react'
import { App } from './App'
import { describe, expect, test } from 'vitest'

describe('Component | App', () => {
  test('should render the app component', () => {
    render(<App />)
    expect(screen.getByText('Rendered from react app')).toBeInTheDocument()
  })
})

Update the package scripts for running tests

npm pkg set scripts.test="vitest"
npm pkg set scripts.test:cov="vitest run --coverage"

Run the tests

  pnpm test

To run a particular test use the -t param.

  pnpm test -- -t "add"

Sample repo

The code for this series is hosted in Github here.

Please take a look at the Github repo and let me know your feedback, and queries in the comments section.

Create a react app using Vite - Part 2

Vinodh Kumar — Tue, 15 Aug 2023 04:57:15 +0000

Styling

I'm going with TailwindCSS as my default styling utility library. Skip this if you have other preferences.

Tailwindcss

Install the TailwindCSS and initialize it using the below commands.

  pnpm add -D tailwindcss postcss autoprefixer
  npx tailwindcss init
  touch postcss.config.js

The init command will create a tailwind.config.js file in the root directory where we can configure the tailwind library. Update the config file content property to process the HTML, and TS files in src and public directory as follows.

export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: { extend: {} },
  plugins: [],
}

Now we should let the postcss preprocessor know that we are using tailwindcss in our project. To do that, open the postcss.config.js file and add the 'tailwindcss' option to the plugins list.

export default {
  plugins: { tailwindcss: {}, autoprefixer: {} },
}

Open /src/index.css file and update it with the following content

@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

Run the server now pnpm dev and check whether the tailwind style is applied.

Rendering icons

SVGs are the best image format for rendering icons for the following reasons.

They are small in size
The same icon can be used in different places in different sizes without losing the quality, that's why it's called Scalable Vector Graphics.
A monochromatic icon can be rendered in different colors just by applying CSS

To render the icons inline I'm using this SVGR plugin along with vite-plugin-svgr to transform the SVGs to react components and then import it wherever necessary just like importing a normal react component.

Install the necessary packages

 pnpm add -D @svgr/core @svgr/plugin-svgo vite-plugin-svgr

Update the Vite config to automatically convert the SVGs into react components.

export default defineConfig({
  ...,
  plugins: [
    ...,
    svgr({
      svgrOptions: {
        plugins: ['@svgr/plugin-svgo', '@svgr/plugin-jsx'],
        svgoConfig: {
          plugins: ['preset-default'],
        },
      },
     }),
  ]
});

Update the package.json file

  ...,
  "scripts": {
    ...,
    "format:svg": "prettier --write '**/*.svg' --parser 'html'",
    "format": "prettier --write . && pnpm format:svg",
  },
  "lint-staged": {
    "**/*.{js,ts,tsx}": [
      "eslint --fix"
    ],
    "**/*.svg": "prettier --write --ignore-unknown --parser 'html'",
    "**/*": "prettier --write --ignore-unknown"
  },
  ...

Open src/vite-env.d.ts and add the following entry to avoid the ReactComponent SVG error while importing.

/// <reference types="vite-plugin-svgr/client" />

Let's make use of the already available react.svg and see how we can import it as an inline SVG. Update the /src/app.tsx as follows,

import ReactIcon from 'src/assets/react.svg?react'

export const App = () => {
  return (
    <div className="font-semibold text-lg text-green-500">
      <ReactIcon width="24px" height="24px" className="text-green-500" />
      Rendered from react app
    </div>
  )
}

Things to remember

We need to make sure we import SVGs the right way so they are highly customizable and scalable. Rendering the SVGs as inline, allows us to customize the SVG properties such as dimensions, fill color, and stroke color through props.

For the library to properly parse the SVG and allow us to customize it inside our components ensure the following.

The SVG element or the Path should have the fill property as 'currentcolor' or 'inherit' so it's easy to customize this color based on the prop. Please see reference SVG src/assets/react.svg.
The SVG shouldn't have width and height set so we can set them inside our components when used. (They will be overwritten anyways but it's better to avoid width and height in the SVG being added)
Try to open the SVG in the browser and start deleting the unwanted elements present in the SVG by inspecting the elements in the developer console and making sure only valid tags are present and checking for any visual changes. If there are no visual changes we can delete those elements from the SVG.

Next part

In the next part of this series, we will see how to add unit testing support to our app using JEST.

Create a react app using Vite - Part 1

Vinodh Kumar — Tue, 15 Aug 2023 04:56:56 +0000

Introduction

The create-react-app is the go-to approach to quickly set up a react application for a long time. But with the introduction of Vite bundler, things have changed dramatically. With the right set of tools, you will see how much easier and super fast your React app can be built. The developer experience with this is pure bliss compared to the create react app(CRA) because of the following reasons,

CRA abstracts a lot of technologies or tools that are used to deliver the final bundle so as a developer you will have a limited understanding of what is happening under the hood, which is kind of a bummer for your career.
It uses a lot of popular third-party packages internally that are not exposed to the outside world which makes it difficult to customise.
It may not support all the latest libraries or tools that you intend to use.

Objective

The main objective of this article is to get your hands dirty and understand what it takes to build a simple hello-world application from scratch.

Technologies/Features used

The app we are going to build will have the following features. Again this is my set of tools feel free to change it based on your preference.

Feature	Technology used
Package manager	PNPM
Package bundler	Vite
Programming language	Typescript
JS Framework/library	React
CSS library	TailwindCss
Basic linting	ESLint
Code formatting	Prettier
Pre-commit hook validator	Husky
Linting only staged files	lint-staged
Lint git commit subject	commitlint

Prerequisites

Tools

You will need the following things properly installed on your computer.

Git
Node.js

PNPM install

If you have installed the latest v16.x or greater node version in your system, then enable the pnpm using the below cmd

corepack enable
corepack prepare pnpm@latest --activate

If you are using a lower version of the node in your local system then check this page for additional installation methods https://pnpm.io/installation

App creation

Let's create our app by running these commands.

pnpm create vite react-app-v2 --template react-ts

  pnpm create vite <app-name> --template react-ts
  cd <app-name>
  pnpm install && pnpm update

That's it, your app is ready. Run pnpm dev and check out your app.

Initialize git if you want and enforce the node version with some info in the README.md.

  git init
  echo -e "node_modules\ncoverage" > .gitignore
  npm pkg set engines.node=">=20.11.0" // Use the same node version you installed

Specify the latest PNPM version to use for this project by setting the packageManager property in the package.json file.

  npm pkg set packageManager="pnpm@9.12.3"
  pnpm -v

Code formatter

I'm going with Prettier to format the code. Formatting helps us to keep our code uniform for every developer.

Installation

Let's install the plugin and set some defaults. Here I'm setting the single quote to be true, update it according to your preference.

  pnpm add -D prettier
  echo '{\n  "singleQuote": true\n}' > .prettierrc.json
  echo -e "coverage\npublic\ndist\npnpm-lock.yaml" > .prettierignore

VS Code plugin

If you are using VS Code, then navigate to the Extensions and search for Prettier - Code formatter and install the extension.

Extension link: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

Let's update the workspace to use the prettier as the default formatter and automatically format the file on save.
Create the workspace settings JSON and update it with the following content.

mkdir .vscode && touch .vscode/settings.json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "files.associations": { "*.svg": "html" },
  "[html]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Now open the src/App.tsx in your VSCode editor and save it. If the semicolons are automatically created then it confirms that our auto formatting is working fine.

Linting

Vite react-ts template comes with a built-in ESLint setup which covers the plugins for react and typescript support.

The vite starter template recommends few improvements to the linter for production app in the Readme file so lets add that as well.

Let's add a few more plugins to keep our linting strong.

Install the eslint-plugin-jsx-a11y and eslint-plugin-react

  pnpm add -D eslint-plugin-react eslint-plugin-jsx-a11y

The updated linter configuration will look something like this,

import js from '@eslint/js'
import globals from 'globals'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import tseslint from 'typescript-eslint'
import react from 'eslint-plugin-react'
import jsxA11y from 'eslint-plugin-jsx-a11y'

export default tseslint.config(
  { ignores: ['coverage', 'public', 'dist', 'pnpm-lock.yaml'] },
  {
    extends: [js.configs.recommended, ...tseslint.configs.recommended],
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parserOptions: {
        ecmaFeatures: { jsx: true },
        project: ['./tsconfig.node.json', './tsconfig.app.json'],
        tsconfigRootDir: import.meta.dirname,
      },
      ecmaVersion: 2020,
      globals: globals.browser,
    },
    plugins: {
      'jsx-a11y': jsxA11y,
      react,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      ...react.configs.recommended.rules,
      ...react.configs['jsx-runtime'].rules,
      'react/react-in-jsx-scope': 'off',
      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
    },
    settings: { react: { version: 'detect' } },
  }
)

Integrating Prettier with ESLint

Linters usually contain not only code quality rules but also stylistic rules. Most stylistic rules are unnecessary when using Prettier, but worse – they might conflict with Prettier!

We are going to use Prettier for code formatting concerns, and linters for code-quality concerns. So let's make the linter to run the stylistic rules from prettier instead.

Install the necessary plugins

  pnpm add -D eslint-config-prettier eslint-plugin-prettier

Add the eslintPluginPrettierRecommended as the last element in the array.

import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended'

/** @type {import('eslint').Linter.Config[]} */
export default [
  ...,
  {
    extends: [
      js.configs.recommended,
      ...tseslint.configs.recommended,
      eslintPluginPrettierRecommended,
    ],
    ...
  }
]

For more info on this: https://prettier.io/docs/en/integrating-with-linters.html

Let's create scripts for running the linter and prettier in the package.json file.

  npm pkg set scripts.lint="eslint ."
  npm pkg set scripts.format="prettier --write ."

Run the pnpm lint cmd to run the ESLint. If it throws, errors like below then our linter prettier integration is working as expected.

To fix it just run pnpm format cmd and run the pnpm lint --fix cmd again. Now the errors should be gone.

Pre-commit hook validation

To automate that we need some kind of pre-commit hook validation. That's where husky and lint-staged plugins come in handy let's install and set them up.

Install the husky, commitlint, and lint-staged NPM package and initialize it as shown below,

  pnpm add -D @commitlint/cli @commitlint/config-conventional
  echo -e "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.mjs
  pnpm add -D husky lint-staged
  pnpm exec husky init
  echo "pnpm lint-staged" > .husky/pre-commit
  echo "npx --no -- commitlint --edit \${1}" > .husky/commit-msg

Update the package.json file and include the following property. This will run the ESLint on all the script files and prettier on the other files.

  "lint-staged": {
    "**/*.{js,ts,jsx,tsx}": [
      "eslint --fix"
    ],
    "**/*": "prettier --write --ignore-unknown"
  },

Absolute path import support

We often move around the files to make it more meaningful, when we are doing that, it would be great if we don't have to update the import statements. To do that,

Install the @types/node NPM package

 pnpm add -D @types/node

Open the vite.config.ts file and update it like this,

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { resolve } from 'path'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: { alias: { src: resolve('src/') } },
})

Update the tsconfig.json file with the baseUrl for the imports to work in the editor.

{
  "compilerOptions": {
    "baseUrl": "./",
    ....
  }
}

The resolve property helps us to use absolute import paths instead of relative. For ex:

import { add } from 'src/utils/arithmetic'
import { App } from 'src/components/app'

App code cleanup:

Update the App.tsx with the following content,

export const App = () => {
  return <div className="font-semibold text-lg text-green-500">Rendered from react app</div>
}

Delete the App.css file

  rm -rf src/App.css

Update the Import in the src/main.tsx file

  - import App from "./App";
  + import { App } from "./app";

Run the app and you will see the content in the app.tsx with tailwind classes applied.

  pnpm dev

Next part

In the next part of this series, we will see how to add styling support and image rendering using SVG.

React micro-frontend in ember app - Part 1

Vinodh Kumar — Tue, 15 Aug 2023 04:56:39 +0000

In this post, we are going to look at how to integrate a React application with its routing mechanisms as a micro-frontend in an Ember application. If you are here then I hope you are already aware of these frameworks so let's look at why we want to integrate React app into an Ember app first.

Why?

The world is moving towards the micro-frontend(MFE) architecture. Ember is best suited for large-scale applications, it has everything you need to create a robust enterprise application, whereas React is a lightweight library with tons of open-source plugins which makes it highly customizable and perfectly fit our MFE need.

Yes, I hear you. There are other frameworks like SolidJs, SvelteJs which are gaining popularity and can be a tough competition to React. These frameworks don't ship any extra framework-related code in your bundle and do most of the heavy lifting at the compile time instead of the browser which makes it extremely lightweight even than React itself. But we all know, React is an undisputed leader in the JavaScript Framework space and the sheer amount of developers who know and already worked on React is mind-boggling. So we picked 'React' to be the framework of choice for the MFE.

Prerequisites

Tools

You will need the following things properly installed on your computer.

Git
Node.js

PNPM install

If you have installed the latest v16.x or greater node version in your system, then enable the PNPM using the below cmd

corepack enable
corepack prepare pnpm@latest --activate

If you are using a lower version of a node in your local system then check this page for additional installation methods https://pnpm.io/installation

Ember CLI install

Ember CLI is the command line tool provided by Ember to create the Ember app. So let's install it globally.

 npm install -g ember-cli
 ember -v

Setting up the Repo

We are going to set up a mono repo using PNPM workspaces for this POC. If you are trying to add this MFE to an existing app, I highly recommend keeping your apps in a separate Repo. We surely don't want any outdated tools and setup to become a blocker from using the latest technologies for our new MFE.

This is how I set up the mono repo structure using the command line.

mkdir ember-react-mfe
cd ember-react-mfe
pnpm init
git init
echo -e "node_modules" > .gitignore
echo "Monorepo with react MFE in ember app" > README.md

Workspace config

Create a pnpm-workspace.yaml file and add the following content

touch pnpm-workspace.yaml

packages:
  - 'apps/*'

Create the apps directories in the root.

mkdir apps

Our basic mono repo setup is now done. Let's create our React app first.

React app

We are going to use Vite bundler to create our React app.

cd apps
pnpm create vite admin-app --template react-ts
cd ../
pnpm install
npm pkg set scripts.admin="pnpm --filter admin-app"

To start the react admin app in the dev server run pnpm admin dev.
Let's add the routing capability to our react app by installing the react-router-dom npm package.

pnpm admin add react-router-dom

Sample pages

Create the router file with all the necessary routings. For simplicity purposes, I have added all the components in this same file instead of creating separate files.

In an ideal world, it should be lazy-loaded to support code splitting from separate folders and files. Whatever you do in a normal React application can be done without any issues.

touch apps/admin-app/src/router.tsx

Copy the content from router.tsx file from this gist.
https://gist.github.com/vinomanick/919ad40ab98716695837c207526ee156

Update the main.tsx file, to support the routing instead of rendering the default App component.

import React from "react";
import ReactDOM from "react-dom/client";
import "./index.css";
import { RouterProvider } from "react-router-dom";
import { generateRouter } from "./router.tsx";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <RouterProvider router={generateRouter({ basename: "/" })} />
  </React.StrictMode>
);

Run the server and make sure all the routes are working as expected.
Let's remove the App component-related files and update the index.css as follows.

rm -rf apps/admin-app/src/App.tsx apps/admin-app/src/App.css

Copy the content of index.css from index.css file from this gist. https://gist.github.com/vinomanick/919ad40ab98716695837c207526ee156

Convert the react app to a web component

The react app can be directly rendered in the ember app but it is best to wrap the entire application in a web component to have strong encapsulation of styles between the host and the MFE.
The main.tsx file is responsible for mounting the react app to the element with id as root on load. We need to change that logic and mount the react app inside an element present in the web component shadow DOM and also load the styles inside the web component as shown below.

import React from 'react'
import ReactDOM from 'react-dom/client'
import indexStyle from './index.css?inline'
import { RouterProvider } from 'react-router-dom'
import { generateRouter } from './router.tsx'

class AdminMFE extends HTMLElement {
  constructor() {
    super()
  }

  connectedCallback() {
    console.debug('Admin MFE element added to app')
    const mountPoint = this.createMountPoint()
    const props: Record<string, any> = this.getProps(this.attributes)
    this.addStyles()
    this.mountReactApp(mountPoint, props.options)
  }

  /**
   *  Creates a mount point and attach it to the shadow dom
   */
  createMountPoint() {
    const mountPoint = document.createElement('div')
    mountPoint.setAttribute('id', 'admin-mfe')
    mountPoint.style.height = '100%'
    mountPoint.style.overflow = 'auto'
    this.attachShadow({ mode: 'open' }).appendChild(mountPoint)
    return mountPoint
  }

  /**
   *  Mounts the react app in to the given element
   */
  mountReactApp(element: HTMLElement, { basename = '' }: { basename: string }) {
    ReactDOM.createRoot(element).render(
      <React.StrictMode>
        <RouterProvider router={generateRouter({ basename })} />
      </React.StrictMode>
    )
  }

  /**
   * Adds the style to the web component as an inline tag
   */
  addStyles() {
    const id = 'admin-style'
    const style = document.createElement('style')
    style.id = id
    style.appendChild(document.createTextNode(indexStyle))
    this.shadowRoot?.appendChild(style)
  }

  getProps(attributes: NamedNodeMap) {
    return [...attributes]
      .filter((attr) => attr.name !== 'style')
      .map((attr) => this.convert(attr.name, attr.value))
      .reduce((props, prop) => ({ ...props, [prop.name]: prop.value }), {})
  }

  convert(attrName: string, attrValue: any) {
    let value: any = attrValue
    if (attrValue === 'true' || attrValue === 'false') {
      value = attrValue === 'true'
    } else if (!isNaN(attrValue) && attrValue !== '') {
      value = +attrValue
    } else if (/^{.*}/.exec(attrValue)) {
      value = JSON.parse(attrValue)
    }
    return { name: attrName, value: value }
  }
}

customElements.define('admin-mfe', AdminMFE)

Local dev server update

Update the index.html by removing the root div and adding the web component. The body should be something like this.

<body>
  <script type="module" src="/src/main.tsx"></script>
  <admin-mfe />
</body>

Run the dev server and inspect the DOM, you should be able to see the whole app rendered inside and the web component.

Exposing the web component as a loadable script

For Vite bundler, the entry file is the index.html so leaving that all the other compiled assets are automatically fingerprinted. So we won't be able to simply call the bundled index-<hash>.js from the host app. To solve that we need to do the followings,

Update the Vite configuration to produce a manifest file with all the fingerprinted assets and its location.

export default defineConfig({
  plugins: [react()],
  build: { manifest: true },
})

Create a new entry point to our app in the public folder. Anything added in the public folder will be copied to the dist folder by Vite.

touch apps/admin-app/public/admin-mfe.js

Update it with the following content,

export const mountApp = ({ element, options }) => {
  const { baseURL, ...rest } = options;
  if (!baseURL) {
    throw Error(
      'Please provide the baseURL in the options for the admin MFE to load'
    );
  }
  fetch(`${baseURL}manifest.json`)
    .then((res) => res.json())
    .then((data) => {
      import(`${baseURL}${data['index.html'].file}`).then(() => {
        const adminMfe = document.createElement('admin-mfe');
        adminMfe.setAttribute('options', JSON.stringify(rest));
        element.appendChild(adminMfe);
      });
    });
};

This will expose a method called mountApp which can be used by the host app to attach the web component to the host app element.

Building the react app and making it available for the ember app

Build the react app in watch mode

pnpm admin build --watch

Open a new terminal, run the preview command

pnpm admin preview

The preview command will run a static server at http://localhost:4173 that points to the react app dist folder.

so the host app has to request http://localhost:4173/fw-chat-admin.js which will act as an entry point for our MFE.

Congrats if you made it here, with this we are done with the setup for react application. Let's see how to link and load this app inside the ember app in the next part.