DEV Community: Kiran Mantha

Generating a Custom Chakra UI v3 Theme from Design Tokens: A Complete Guide

Kiran Mantha — Fri, 31 Oct 2025 03:21:00 +0000

A practical, framework-agnostic guide to generating a **Chakra UI v3* theme from Figma design tokens — adaptable to any token format.*

Chakra UI v3 introduced a new theming system based on tokens, semantic tokens, conditions, and recipes. While the official docs are great, many teams struggle with automating theme generation from Figma in a scalable, maintainable way.

This guide walks you through:

The exact structure Chakra UI v3 expects in themeConfig.json
What goes into tokens vs semanticTokens
How to support responsive values, multiple themes, and text styles
How to integrate the generated theme into your React app

No Figma plugin or proprietary format required — just JSON design tokens and a Node.js script.

Let's start by creating a json called themeConfig.json which defines the final chakra theme.

Important: Chakra UI v3 Uses Panda CSS Under the Hood

Chakra UI v3 is built on top of Panda CSS — a CSS-in-JS engine that powers its styling, theming, and component system.

This means:

Your themeConfig.json is not just Chakra-specific — it's a Panda CSS config.
The tokens, semanticTokens, conditions, and recipes you define are fully compatible with Panda CSS.
You can reuse the same theme in non-React projects (Vue, Svelte, etc.) via Panda.

Official Docs to Bookmark

Resource	Link
Chakra UI v3 Docs	https://chakra-ui.com
Panda CSS Docs	https://panda-css.com
Panda Theme Tokens	https://panda-css.com/docs/concepts/theme-tokens
Chakra + Panda Integration	https://chakra-ui.com/docs/styled-system/theming

Pro Tip: Read both docs — Chakra handles the React layer, Panda handles the CSS engine.

Critical Rule: No Token References in Final Output

themeConfig.json must contain only **fully resolved values — never {primitives.colors.blue.500}**

Wrong (Do Not Do This)

{
  "colors": {
    "brand": {
      "500": { "value": "{primitives.colors.blue.500}" }
    }
  }
}

Correct (Required)

{
  "colors": {
    "brand": {
      "500": { "value": "#0ea5e9" }
    }
  }
}

Why?

Panda CSS does not resolve references at runtime
Your build script must resolve all {...} references
Final output must be static, predictable, and framework-ready

Your transformation script is responsible for:

Detecting {path.to.token}

Traversing the token tree

Recursively resolving nested references

Replacing with final value (#0ea5e9, 1.5rem, etc.)

function resolveReference(ref: string, tokens: any): any {
  if (!ref.startsWith('{') || !ref.endsWith('}')) return ref;
  const path = ref.slice(1, -1).split('.');
  let value = tokens;
  for (const key of path) {
    value = value?.[key];
    if (!value) throw new Error(`Unresolved token: ${ref}`);
  }
  return typeof value === 'object' && 'value' in value
    ? resolveReference(value.value, tokens)
    : value;
}

This is a sample function for token value resolution. The logic will vary on your figma design tokens structure.
Always resolve before writing to themeConfig.json

Prerequisites

Node.js ≥ 18
Chakra UI v3 (@chakra-ui/react@3.3.1 or later)
Design tokens exported as JSON (from Figma, Tokens Studio, etc.)

Step 1: Understand Chakra UI v3 Theme Structure

Chakra v3 uses a token-based system powered by Panda CSS. Your theme config must follow this shape:

interface ChakraThemeConfig {
  breakpoints: Record<string, string>;
  tokens: {
    colors: Record<string, any>;
    fonts: Record<string, string>;
    fontWeights: Record<string, any>;
    spacing: Record<string, any>;
    borders: Record<string, any>;
    radii: Record<string, any>;
    shadows: Record<string, any>;
    gradients: Record<string, any>;
    letterSpacings: Record<string, any>;
  };
  semanticTokens: {
    colors: Record<string, any>;
    spacing: Record<string, any>;
    fontSizes: Record<string, any>;
    lineHeights: Record<string, any>;
    grid: Record<string, any>;
  };
  textStyles: Record<string, { value: any }>;
  themes: Record<string, string>; // for CSS variable scoping
}

Let’s break down each section.

`breakpoints`

Define your responsive breakpoints in rem.

"breakpoints": {
  "base": "0rem",
  "sm": "40rem",
  "md": "48rem",
  "lg": "64rem",
  "xl": "80rem"
}

Use min-width values from your design system.

`tokens` — Primitive Design Tokens

These are raw, reusable values. Think of them as CSS variables.

`colors`

Primitive color palette (not semantic):

"colors": {
  "brand": {
    "50": { "value": "#f0f9ff" },
    "500": { "value": "#0ea5e9" },
    "900": { "value": "#0c4a6e" }
  },
  "gray": { ... },
  "transparent": { "value": "transparent" }
}

Use { value: ... } wrapper — required by Panda CSS.

`fonts`

Font families:

"fonts": {
  "heading": { "value": "'Inter', sans-serif" },
  "body": { "value": "'Inter', sans-serif" },
  "mono": { "value": "'Fira Code', monospace" }
}

Always wrap in { value: ... }

`fontWeights`, `letterSpacings`, `spacing`, `borders`, `radii`, `shadows`, `gradients`

All follow the same pattern:

"spacing": {
  "4": { "value": "1rem" },
  "8": { "value": "2rem" }
},
"radii": {
  "md": { "value": "0.375rem" }
},
"shadows": {
  "sm": { "value": "0 1px 3px rgba(0,0,0,0.1)" }
}

Convert px to rem using base 16: px / 16 = rem

`semanticTokens` — Meaningful, Contextual Tokens

These are design decisions, not raw values.

Use when you want:

Responsive values
Theme-aware values (light/dark)
Semantic meaning (text.primary, bg.card)

Responsive Values (via object)

"fontSizes": {
  "display.xl": {
    "value": {
      "base": "2.5rem",
      "sm": "3rem",
      "md": "3.75rem",
      "lg": "4.5rem"
    }
  }
}

base and sm = mobile

md = tablet (optional)

lg+ = desktop

Single Value (non-responsive)

"fontSizes": {
  "body": { "value": "1rem" }
}

`grid` — Responsive Layout Tokens

"grid": {
  "gutterSize": {
    "value": { "base": "1rem", "lg": "2rem" }
  },
  "count": {
    "value": { "base": 4, "lg": 12 }
  }
}

`textStyles` — Reusable Typography

Define complete text styles:

"textStyles": {
  "heading.h1": {
    "value": {
      "fontSize": "{fontSizes.display.xl}",
      "lineHeight": "{lineHeights.tight}",
      "fontWeight": "{fontWeights.bold}",
      "fontFamily": "{fonts.heading}",
      "letterSpacing": "{letterSpacings.tight}",
      "textTransform": "uppercase"
    }
  }
}

Use token references with {path.to.token}

Use textCaseToTransform() to map Figma UPPERCASE to uppercase

`themes` — Multi-Theme Support (Light/Dark/Minimal/Contrast)

Chakra v3 supports CSS-scoped themes via [data-theme] or css classes. Below is an example with data-theme.

"themes": {
  "lightTheme": "[data-theme=light] &",
  "darkTheme": "[data-theme=dark] &",
  "minimalTheme": "[data-theme=minimal] &",
  "contrastTheme": "[data-theme=contrast] &"
}

Same can be replicated using css classes:

"themes": {
  "lightTheme": ".light &",
  "darkTheme": ".dark &",
  "minimalTheme": ".minimal &",
  "contrastTheme": ".contrast &"
}

then set the defined data-theme or classname to the body tag for different views.

Use in semanticTokens.colors like:

"colors": {
  "bg.page": {
    "value": {
      "_light": "#ffffff",
      "_darkTheme": "#0f172a",
      "_minimalTheme": "#f8f9fa",
      "_contrastTheme": "#000000"
    }
  }
}

_light is default

Use _themeNameTheme for custom themes

Final `themeConfig.json` Example

{
  "breakpoints": { ... },
  "tokens": {
    "colors": {
      "brand": {
        "500": { "value": "#0ea5e9" }
      }
    },
    "fonts": { ... },
    "spacing": { ... }
  },
  "semanticTokens": {
    "colors": {
      "text.primary": {
        "value": { "_light": "#1f2937", "_darkTheme": "#f1f5f9" }
      }
    },
    "fontSizes": {
      "display.xl": { "value": { "base": "2.5rem", "lg": "4.5rem" } }
    }
  },
  "textStyles": {
    "heading.h1": { "value": { ... } }
  },
  "themes": {
    "lightTheme": "[data-theme=light] &",
    "darkTheme": "[data-theme=dark] &",
    "minimalTheme": "[data-theme=minimal] &",
    "contrastTheme": "[data-theme=contrast] &"
  }
}

No {...} references — all values fully resolved

Step 2: Generate `themeConfig.json` (Any Format to Chakra)

Write a Node.js script that:

Reads your Figma JSON
Resolves all {references}
Converts px to rem
Maps to Chakra/Panda structure
Outputs dist/themeConfig.json

Your input format doesn’t matter — only the output does.

Example Script Skeleton

// generate-theme.ts
import fs from 'fs/promises';
import path from 'path';

const pxToRem = (px: number) => `${px / 16}rem`;

function resolveReference(ref: string, tokens: any): any {
  if (!ref.startsWith('{') || !ref.endsWith('}')) return ref;
  const path = ref.slice(1, -1).split('.');
  let value = tokens;
  for (const key of path) {
    value = value?.[key];
    if (!value) throw new Error(`Unresolved token: ${ref}`);
  }
  return typeof value === 'object' && 'value' in value
    ? resolveReference(value.value, tokens)
    : value;
}

async function generateTheme() {
  const input = JSON.parse(await fs.readFile('tokens.json', 'utf-8'));

  const theme: any = {
    breakpoints: { base: '0rem', sm: '40rem', md: '48rem', lg: '64rem', xl: '80rem' },
    tokens: { colors: {}, fonts: {}, spacing: {} },
    semanticTokens: { colors: {}, fontSizes: {} },
    textStyles: {},
    themes: {
      lightTheme: '[data-theme=light] &',
      darkTheme: '[data-theme=dark] &',
      minimalTheme: '[data-theme=minimal] &',
      contrastTheme: '[data-theme=contrast] &'
    }
  };

  // Map your tokens to Chakra/Panda
  // Use resolveReference() everywhere
  // ...

  await fs.mkdir('dist', { recursive: true });
  await fs.writeFile('dist/themeConfig.json', JSON.stringify(theme, null, 2));
}

generateTheme();

Step 3: Use in React App

// theme.ts
import * as themeConfig from './dist/themeConfig.json';
import { createSystem, defaultConfig, defineConfig } from '@chakra-ui/react';

const customConfig = defineConfig({
  theme: {
    ...(themeConfig as any),
    recipes: { /* your component recipes */ },
    slotRecipes: { /* your slot recipes */ },
  },
  conditions: themeConfig.themes as any,
});

export const system = createSystem(defaultConfig, customConfig);
export const { ThemeProvider, theme } = system;

App Entry

// App.tsx
import { ThemeProvider, theme } from './theme';
import { Theme } from '@chakra-ui/react';

export default function App() {
  return (
    <ThemeProvider>
      <Theme accentColor="brand.500">
        <YourApp />
      </Theme>
    </ThemeProvider>
  );
}

Switching Themes at Runtime

<button onClick={() => document.documentElement.dataset.theme = 'minimal'}>
  Minimal Mode
</button>

Chakra automatically picks up [data-theme=minimal]

Best Practices

Do	Don't
Resolve all `{...}` references	Leave references in output
Use `{ value: ... }` everywhere	Use raw strings in tokens
Convert px to rem	Keep px values
Use `semanticTokens` for responsive values	Put responsive values in `tokens`
Use `themes` object for multi-theme	Hardcode light/dark in tokens
Reference tokens with `{path}` in `textStyles`	Duplicate values

Tools & Resources

Conclusion

You now have a complete, scalable pipeline:

Figma to JSON Tokens => generate-theme.ts => themeConfig.json (resolved) to Chakra UI v3

This system:

Works with any token format
Supports responsive, multi-theme, semantic design
Is fully automated and type-safe
Scales to large design systems
Powered by Panda CSS — future-proof and framework-agnostic
Zero runtime token resolution

Share your ideas in the comments.

Happy theming!

Kiran 👋 👋

PlumeJS - No fuss web-components framework

Kiran Mantha — Tue, 16 Apr 2024 10:49:23 +0000

Hello Everyone.

Have you considered writing HTML in this manner?

`<button onclick=${() => { alert('hello world'); }}>click me</button>`

unlike any other framework out there (upto my broad knowledge. i may miss one), binding events don't require any special syntax. It's just plain string interpolation. Wondering how? I would like to introduce you to a new kid in Framework Town: PlumeJS.

PlumeJS is a framework that relies on web components. As you are all aware, the browser defines and regulates the life cycle of a web component. PlumeJS is a lightweight framework out there due to this.

This framework provides the ability to create reusable web components, routing and dependency injection for sharing data across components all in a ~27kb package (~8kb when brotli compressed) which includes routing and forms support.

PlumeJS has very few to zero external dependencies. That means, you can make use of the latest importmaps to include PlumeJS and use just like that. Sounds exiting right??

So how a typical component declaration looks like in PlumeJS?

import { Component } from '@plumejs/core';

@Component({
  selector: 'app-root'
})
class AppComponent {
  render() {
     return `<h1>hello world</h1>`;
  }
}

Looks familiar? Yes, it adopts angular-like component declarations and react-like HTML in JS coding style.

You can re-write the above code in another way too..

import { Component } from '@plumejs/core';

class AppComponent {
  render() {
     return `<h1>hello world</h1>`;
  }
}
Component({
  selector: 'app-root'
})(AppComponent)

This helps to reduce the bundle size by not including decorator snippets at the beginning of the files benefiting the final build size.

Just like angular, any change in class variables trigger change detection. PlumeJS uses queueMicroTask to re-render the component upon any changes.

For example, this is how a simple counter component looks like:

import { Component, html } from '@plumejs/core';

@Component({
  selector: 'app-counter'
})
class Counter {
  count = 0;

  render() {
    return html`<h1>Hello world</h1>
    <button onclick=${() => {
      this.count--;
    }}>
      -
    </button>
      <span>${this.count}</span>
    <button onclick=${() => {
      this.count++;
    }}>
      +
    </button>`;
  }
}

Components can talk to each other either by parent-child relation or by services or by routing.

We all know that web-components excel at scoping html, javascript and css. PlumeJS extends one helping hand to this by incorporating CSSStyleSheet Constructor and adoptedStyleSheets for true css encapsulation and sharing global styles. If incase CSSStyleSheet is not supported by your browser, PlumeJS automatically resorts to css emulation.

The entire framework is available as a single file from cdn in either IIFE / ES Module / UMD formats if you want to use it via importmaps or it is also availble on npm as scoped-packages.

Yes for better maintainability, PlumeJS has 4 main scoped packages and 1 addon scoped package

Main packages:

@plumejs/core : This is the main and core package that helps us to create components / services.
@plumejs/router : As the name implies, this scoped package helps us to enable routing.
@plumejs/forms : This scoped package helps us to create robust forms.
@plumejs/testing : A scoped package for wrting unit tests based on vitest and JSDom.

Addon package:

@plumejs/ui : This scoped package contains a collection of UI components like dialogs, multi-select, notifications, toggles.

PlumeJS has a user-friendly Yeoman generator to ease project setup based on either vite or webpack.

For more info on usage docs, please visit PlumeJS Wiki.

I hope you like my attempt to make web-components great.

Drop a star or contribute a pull request if you like 😊.

Hoping to see your feedback,
See you again,
Kiran 👋 👋

How to setup Kafka locally

Kiran Mantha — Thu, 07 Mar 2024 06:56:59 +0000

I came across 2 reliable ways to setup kafka locally:

And that's how we can setup kafka locally.

See you in next article,
Kiran 👋 👋

How to create a framework-agnostic nx monorepo

Kiran Mantha — Fri, 23 Feb 2024 11:17:07 +0000

Yes i'm not talking about creating an angular / react / vue monorepo. There is enough material out there including official nx articles.

What if you are a 90's kid like me who love jquery and want a monorepo?

What if you are so much fond of building your own webpack / vite based webapplications using vanilla js / lit-element etc and want a monorepo?

Nope those are not articulated..

That's why i want to bring this to you.

Necessity is mother of invention

Ask me what encouraged me to do this. I built my own framework PlumeJS and thought of creating a monorepo style code base. This is what encouraged me to explore the possibility.

The outcome? Fantastic.. and know what, the steps I followed are framework agnostic. Means you too can create your own favorite UI tech stack based nx monorepo.

Freedom can be felt if you are out of the cage.

Enough quotes and blabbering. Show me real stuff.

Yea.. this is just warm up. Now lets dive 😄

For simplicity I'm using:

Jquery for interactions,
Vite for bundler
Tailwind (cdn) for styling
serve (to run static server on dist)

Steps:

Step 1: Create Shell

NOTE: By defualt @nx/js:library has tsconfig module type as commonjs. change this to ESNext for better tree shaking.

Create nx workspace with typescript preset:

npx create-nx-workspace@latest <your-monorepo-name> --preset=ts

I'm naming the monorepo as jquery-monorepo. After you run the above command, it should roughly create the below folder structure:

jquery-monorepo/
├── nx.json
├── package.json
└── tsconfig.base.json

As we're using jquery, lets install it by:
1. run npm i jquery -s
2. run npm i @types/jquery serve -D
This will install jquery and its types for the sake of typescript.
Now lets create new packages folder. the updated folder structure should be as below:

jquery-monorepo/
├── packages
├── nx.json
├── package.json
└── tsconfig.base.json

add esModuleInterop: true to tsconfig.base.json
Now lets create a Shell that load our web application. Shell don't hold any logic other than including common styles and libraries.
To create the shell, run below commands:
```
npx nx generate @nx/js:library shell \
--directory=packages/shell \
--publishable \
--importPath=@jquery-monorepo/shell
```
choose vitest or none for test-runners and vite as bundler. we're going to use the same options going forward.
This will create a shell folder under packages and update the references in nx.json and tsconfig.base.json. The updated folder structure should be:

jquery-monorepo/
├── packages/
│   └── shell
├── nx.json
├── package.json
└── tsconfig.base.json

Great. But one problem. @nx/js:library create a library but not a web app. In our case, shell is created as library. So we're going to make few changes to shell to make it as web app.

navigate to shell and

a. create folder styles with styles.css. add the below styles:

.border-b-2 {
    border-bottom-width: 2px;
}

.tab-container [data-tab-target] {
    border-color: transparent;
}
.tab-container .active-tab {
    color: rgb(63 131 248);
    border-color: rgb(63 131 248);
}

b. delete lib folder under src
c. add index.html under root with below content:

    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Jquery monorepo</title>
        <link rel="stylesheet" href="./styles/styles.css"/>
        <script src="https://cdn.tailwindcss.com"></script>
    </head>
    <body>
        <div class="container mx-auto py-8">
            <h1 class="text-3xl font-bold underline text-center mb-4">Hello world!</h1>
            <section id="tabs"></section>
        </div>
        <script type="module" src="./src/index.ts"></script>
    </body>
    </html>

d. delete lib section under build in vite.config.ts
e. add server section to vite config. the final vite config should be like this:

    /// <reference types='vitest' />
    import { defineConfig } from 'vite';
    import dts from 'vite-plugin-dts';
    import * as path from 'path';
    import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

    export default defineConfig({
    root: __dirname,
    cacheDir: '../../node_modules/.vite/packages/shell',

    plugins: [
        nxViteTsPaths(),
        dts({
        entryRoot: 'src',
        tsConfigFilePath: path.join(__dirname, 'tsconfig.lib.json'),
        skipDiagnostics: true,
        }),
    ],

    // Uncomment this if you are using workers.
    // worker: {
    //  plugins: [ nxViteTsPaths() ],
    // },

    // Configuration for building your library.
    // See: https://vitejs.dev/guide/build.html#library-mode
    build: {
        outDir: '../../dist/packages/shell',
        reportCompressedSize: true,
        commonjsOptions: {
        transformMixedEsModules: true,
        },
        rollupOptions: {
        // External packages that should not be bundled into your library.
        external: [],
        },
    },

    server: {
        host: true,
        port: 3001,
        open: '/'
    },

    test: {
        globals: true,
        cache: {
        dir: '../../node_modules/.vitest',
        },
        environment: 'node',
        include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],

        reporters: ['default'],
        coverage: {
        reportsDirectory: '../../coverage/packages/shell',
        provider: 'v8',
        },
    },
    });

add start script to shell package.json:

// shell/package.json
{
  ...
  "scripts": {
    "start": "vite"
  }
}

Update the scripts section in our monorepo level package.json:

// jquery-monorepo/package.json
{
  ...
  "scripts": {
    "nx": "nx",
    "start": "nx start shell",
    "graph": "nx graph",
    "build": "nx build shell",
    "serve": "serve -s dist/packages/shell"
  }
}

Finally, navigate to our monorepo root and run yarn start. Boom the application starts running on localhost:3001

Awesome. We created our own custom web application in nx monorepo. But this is just a starting step. lets create a ui lib that have Tab component using jquery. feed the tab content from products and about libs. This implies the folder structure as below:

jquery-monorepo/
├── packages/
│   ├── ui/
│   │   └── tab component
│   ├── products/
│   │   └── products component
│   ├── about/
│   │   └── about component
│   └── shell/
│       ├── src/
│       │   └── index.ts
│       └── index.html
├── nx.json
├── package.json
└── tsconfig.base.json

This inturn implies, shell will depend on ui, products and about libs.

lets create these libs one-by-one.

Step 2: UI Lib - Tab component

To create the ui library, let's run below commands: bash npx nx generate @nx/js:library ui \ > --directory=packages/ui \ > --publishable \ > --importPath=@jquery-monorepo/ui Choose vitest and vite in options.

This will create the ui folder under packages. As this is a lib, no need to make any changes to vite.config.ts.

under src folder, delete the lib folder and create tabs folder with below structure:

ui/
├── src/
│   ├── tabs/
│   │   ├── tabs.ts
│   │   └── index.ts
│   └── index.ts
└── package.json

Let's create a reusable tabs component as below: ```typescript // ui/src/tabs/tabs.ts import $ from 'jquery';

function createToken(): string {
return Math.random().toString(36).substring(2);
}

export interface TabItem {
label: string;
content: JQuery | string;
}

export function Tabs(tabItems: Array) {
let lastActiveTabPanel: JQuery;
const token = createToken();
const tabId = tab-container-${token};
const container = $('').attr('id', tabId).addClass('tab-container mb-4');
const tabList = $('

').append( $('') .addClass(

inline-block p-4 rounded-t-lg border-b-2 ${

            index === 0 ? 'active-tab' : ''

          }

) .attr('data-tab-target', #${token}-${index}) .text(label) ) ); const tabContents = tabItems.map(({ content }, index) => { const panel = $('') .attr('id', ${token}-${index}) .addClass(tab-panel ${index === 0 ? '' : 'hidden'}); typeof content === 'string' ? panel.html(content) : panel.append(content); return panel; }); lastActiveTabPanel = tabContents[0]; tabList.append(items); container.append(tabList); container.append($('').attr('id', '').append(tabContents)); container.find('[data-tab-target]').on('click', (e) => { container.find('[data-tab-target]').removeClass('active-tab'); const targetTabPanelId = $(e.target).attr('data-tab-target') || ''; $(e.target).addClass('active-tab'); lastActiveTabPanel.addClass('hidden'); lastActiveTabPanel = $(targetTabPanelId).toggleClass('hidden'); }); return container; }

// ui/src/tabs/index.ts
export * from './tabs';

// ui/src/index.ts
export * from './tabs';


* Cool now in our shell, lets update the index.ts:

```typescript
// shell/src/index.ts

import $ from 'jquery';
import { Tabs, TabItem } from '@jquery-monorepo/ui';

const tabItems: TabItem[] = [
  {
    id: 'tab-1',
    label: 'Tab 1',
    content: 'Tab content 1',
  },
  {
    id: 'tab-2',
    label: 'Tab 2',
    content: 'Tab content 2',
  },
];

$(() => {
  $('#tabs').append(Tabs(tabItems));
});

now run yarn start on our monorepo. Boom our tabs component is live
With this, we created our own jquery ui library with tabs component and used that library in our shell. As you see shell is the dummy consumer.

Step 3: Products & About Libs

This step is very simple.

Create 2 libs with names products and about with below commands:

# products
npx nx generate @nx/js:library products \
--directory=packages/products \
--publishable \
--importPath=@jquery-monorepo/products

# about
npx nx generate @nx/js:library about \
--directory=packages/about \
--publishable \
--importPath=@jquery-monorepo/about

delete lib folder in those 2 above packages and update their index.ts files as below:

// about/src/index.ts

import $ from 'jquery';

export function About() {
    const aboutContainer = $('<div>').html('About Container');
    return aboutContainer;
}

// products/src/index.ts
import $ from 'jquery';

export function Products() {
    const productsContainer = $('<div>').html('Products Container');
    return productsContainer;
}

Now in shell: ```typescript // shell/src/index.ts import $ from 'jquery'; import { Tabs, TabItem } from '@jquery-monorepo/ui'; import { About } from '@jquery-monorepo/about'; import { Products } from '@jquery-monorepo/products';

const tabItems: TabItem[] = [
{
label: 'About',
content: About(),
},
{
label: 'Products',
content: Products(),
},
];

$(() => {
$('#tabs').append(Tabs(tabItems));
});


Excellent. `shell` is now able to display tabs component from `ui` populated by `about` and `product` libs.

For instance, if you run `yarn graph` on monorepo this is what you see:


![nx graph showcasing shell, products, about and ui](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ca1ko987pdtt3bj8tg0h.png)

But we need to ensure when we build this monorepo and deploy, it should work. 

How to check this?

If you remember, we have `build` and `serve` scripts in our monorepo package.json.

Run `yarn build && yarn serve` and navigate to `localhost:3000`. Marvelous, our distribution package worked :smile:

> NOTE: If the build is success and you see a message _Cannot call a namespace ("$")._ then change the module type in all tsconfig.json files to ESNext and set esModuleInterop to true in tsconfig.base.json 

Qudos if you make this far. As you see we created a nx monorepo for our jquery project. Now in place of JQuery, use `lit-element` or `web-components` or anything. The process is same. 

You can fine tune the folder structure by splitting `packages` into `apps` and `libs` where `apps` hold multiple `shell` folders and `libs` have all the common logic. 

Checkout the source code [here](https://github.com/KiranMantha/jquery-monorepo).

Post your comments after experimenting or facing any issues. 

Thanks for reading and see you next time,
Happy coding,
Kiran :wave: :wave:

Pub-Sub using ES6 Promise

Kiran Mantha — Mon, 30 Oct 2023 05:10:18 +0000

Impossible !!

A Promise just resolve one value but not a stream of values.

Telling lies 🤨?? no papa

Out of curiosity I was exploring the possibility of a Publish-Subscribe model using Promises. The result is very interesting and it really brushed up my knowledge on call by value and call by reference too.

So here's the idea. create a function that return a tuple containing an object to subscribe(this returns a function to unsubscribe), reset and a resolver function to emit values to subscribers.

function promisedPubSub() {
  let callbackRegistery = Object.create(null);

  const subscriptions = {
    subscribe: (callback) => {
       const token = `uid_${Math.random().toString(36).substring(2)}`;
      callbackRegistery[token] = fn;
      return () => {
        delete callbackRegistery[token];
      };
    },
    reset: () => {
       callbackRegistery = Object.create(null);
    }
  }

  return [subscriptions, () => {}]
}

// usage
const [subscriptions, resolver] = promisedPubSub();

subscriptions.subscribe((val) => { console.log('a', val); })
subscriptions.subscribe((val) => { console.log('b', val); })

resolver(1);

You can see that we can add subscribers using subscriptions.subscribe but when we call resolver, it is doing nothing as it is a blank function.

So let's modify the above implementation:

function promisedPubSub() {
  let instance, resolver, callbackRegistery = Object.create(null);

  const subscriptions = {
    subscribe: (fn) => {
      const token = `uid_${Math.random().toString(36).substring(2)}`;
      callbackRegistery[token] = fn;
      return () => {
        delete callbackRegistery[token];
      };
    },
    reset: () => {
       callbacks = [];
    }
  }

  function initiate() {
    instance = null;
    resolver = null;
    instance = new Promise((resolve) => {
       resolver = resolve;
    });

    instance.then((val) => {
       const callbacks = Object.values(callbackRegistery);
       callbacks.forEach((callback) => {
         callback(val);
       });
    })
  }

  initiate();

  return [subscriptions, (val) => { resolver(val); }]
}

Yea that's a mouthful. Let me explain what we're doing here.

We created an internal function initiate that create a new Promise. As Promise constructor invokes immediately, the resolver variable got the resolve function reference.

Now when we execute the usage code, it logs a 1 b 1 means, when we emit 1 all the subscribers received that value. but if you try to emit another value nothing happen.

You already know the answer for why nothing happen.

Promise only resolve once.

So how to emit multiple values?

Answer: Recursion.

Remember we wrote an internal function initate? we need to call the same function when the promise is resolved.

So this is how the final code looks like:

const promisedPubSub = () => {
  let instance,
    resolver,
    callbackRegistery = Object.create(null);

  const subscriptions = {
    subscribe: (fn) => {
      const token = `uid_${Math.random().toString(36).substring(2)}`;
      callbackRegistery[token] = fn;
      return () => {
        delete callbackRegistery[token];
      };
    },
    reset: () => {
      instance = null;
      resolver = null;
      callbackRegistery = Object.create(null);
    },
  };

  function initiate() {
    instance = null;
    resolver = null;
    instance = new Promise((resolve) => {
      resolver = resolve;
    });
    instance.then((val) => {
      const callbacks = Object.values(callbackRegistery);
      callbacks.forEach((callback) => {
        callback(val);
      });
      setTimeout(() => {
        initiate();
      });
    });
  }

  initiate();

  return [
    subscriptions,
    (val) => {
      if(resolver) {
        resolver(val);
      }
    },
  ];
};

And this is the working example:

Congratulations we made the impossible a possible 🤩

And that's it.

See you in next article.

Thanks,
Kiran 👋 👋

Error boundary with react-i18next and router

Kiran Mantha — Fri, 04 Aug 2023 09:50:15 +0000

Helloo everyone. I did some bad programming and got one page crash landed.

QA engineer raised red flag What the heck is this? 🤨

Now what??

chill. calm down. 😶 meditate a bit. 😑 let's create an ErrorBoundary component together.

My react project support multiple langugaes. So i used react-i18next package to display a generic error message following with error message.

I did a bit of background work on how to create a ErrorBoundary. As per React docs:

Error boundaries work like a JavaScript catch {} block, but for components. Only class components can be error boundaries. In practice, most of the time you’ll want to declare an error boundary component once and use it throughout your application.

based on this primary info let's start by creating a class component namedErrorBoundary.

import { TFunction } from 'i18next';
import { Component, ReactElement } from 'react';
import { withTranslation } from 'react-i18next';

class Boundary Component<Readonly<{
    children: ReactElement | ReactElement[];
    t: TFunction<'translation', undefined, 'translation'>;
  }>, Record<string, string | boolean>> {

  constructor(props: {
    children: ReactElement | ReactElement[];
    t: TFunction<'translation', undefined, 'translation'>;
  }) {
    super(props);

    this.state = {
      hasError: false,
      errorMessage: ''
    };
  }
  render() {
    return this.state.hasError ? (
      <fieldset>
        <legend>
          {this.props.t('common.errorBoundaryMessage')} 
        </legend>
        <pre>
          <code>{this.state.errorMessage}</code>
        </pre>
      </fieldset>
    ) : (
      this.props.children
    );
  }
}

const ErrorBoundary = withTranslation()(Boundary);
export { ErrorBoundary };

Woww that's literally a mounthful. if you ignore all the typings, we basically created a simple class component that accepts 2 props (for now).

children
a t function for translation purpose.

Now we used a HOC withTranslation to wrap our class component for translation purposes. This step is not needed if you create a simple react app. Our component display the fieldset showing Something went wrong message in case of any error occured in children.

Let's out this to test:

function ToublesomeComponent() {
   useEffect(() => {
     throw Error('I intentionally broke this.')
   }, [])

   return <h1/>Hello world</h1>
}

//App.tsx

....
return <ErrorBoundary>
  <ToublesomeComponent />
</ErrorBoundary>;
....

cool. 🤓 this display Something went wrong from our translations.

Now here comes the next part. We are using react-router for navigation. This means, a sidebar with all routes and main section to display page contents.

So the App component is like this:

for breivity I'm not writing full logic. just the basics.

//App.tsx

....
return <main>
  <aside></aside>
  <section>
    <ErrorBoundary>
      <Outlet />
    </ErrorBoundary>
  </section>
</main>;
....

And inside my page

// About.tsx

export function About() {
  return <ToublesomeComponent />
}

Cool. the page is not broken.

but wait.. the navigation went haywire 🤯 . a developer's curse: You fix one thing, it will break other. 🙁

key issue is, the hasError flag inside our ErrorBoundary class is true for all pages on error. That means we need to reset this flag on route changes.

That's a piece of cake. Let's use useLocation and check the current route and prev route... 🥳

Hold on.. we are forgetting something. Our Errorboundary component is a class component. so we cannot use hooks inside a class component. 😲

Solution: create a functional HOC and return our class component from it. Then why waiting lets jump to it:

let's add location prop to our ErrorBoundary and create the HOC.

// ErrorBoundary.tsx
import { Component, ComponentType, ReactElement } from 'react';
import { Location, useLocation } from 'react-router';

function withRouter(
  Component: ComponentType<{
    children: ReactElement | ReactElement[];
    location: Location;
    t: TFunction<'translation', undefined, 'translation'>;
  }>
) {
  function ComponentWithRouterProp(props: {
    children: ReactElement | ReactElement[];
    t: TFunction<'translation', undefined, 'translation'>;
  }) {
    const location = useLocation();
    return <Component {...props} location={location} />;
  }
  return ComponentWithRouterProp;
}

class Boundary extends Component<
  Readonly<{
    children: ReactElement | ReactElement[];
    location: Location;
    t: TFunction<'translation', undefined, 'translation'>;
  }>,
  Record<string, string | boolean>
> {
  constructor(props: {
    children: ReactElement | ReactElement[];
    location: Location;
    t: TFunction<'translation', undefined, 'translation'>;
  }) {
    super(props);

    this.state = {
      hasError: false,
      errorMessage: ''
    };
  }

....
}

const ErrorBoundary = withTranslation()(withRouter(Boundary));
export { ErrorBoundary };

Again.. 😵‍💫 adfiwaeproadjp... explain..

we created the withRouter HOC which accept our class component as prop and return a unnamed functional component that forward the props to our class component along with location from useLocation hook.

fine. but we need to reset the flag.. yea i'm coming to that point.

In our class component, lets add this life-cycle method:

 componentDidUpdate() {
    if (this.props.location.pathname !== this.state.prevPath) 
    {
      this.setState({ 
        hasError: false, 
        errorMessage: '', 
        prevPath: this.props.location.pathname 
      });
    }
  }

self explaining. in this method, we are checking if current path is equal to prev path or not. if not reset the state.

with this even one page is broken, we can still able to navigate to other pages.

This is how the entire component looks like:

import { TFunction } from 'i18next';
import { Component, ComponentType, ReactElement } from 'react';
import { withTranslation } from 'react-i18next';
import { Location, useLocation } from 'react-router';
import { ErrorContainer } from './ErrorBoundary.styles';

function withRouter(
  Component: ComponentType<{
    children: ReactElement | ReactElement[];
    location: Location;
    t: TFunction<'translation', undefined, 'translation'>;
  }>
) {
  function ComponentWithRouterProp(props: {
    children: ReactElement | ReactElement[];
    t: TFunction<'translation', undefined, 'translation'>;
  }) {
    const location = useLocation();
    return <Component {...props} location={location} />;
  }
  return ComponentWithRouterProp;
}

class Boundary extends Component<
  Readonly<{
    children: ReactElement | ReactElement[];
    location: Location;
    t: TFunction<'translation', undefined, 'translation'>;
  }>,
  Record<string, string | boolean>
> {
  constructor(props: {
    children: ReactElement | ReactElement[];
    location: Location;
    t: TFunction<'translation', undefined, 'translation'>;
  }) {
    super(props);

    this.state = {
      hasError: false,
      errorMessage: ''
    };
  }

  componentDidUpdate() {
    if (this.props.location.pathname !== this.state.prevPath) {
      this.setState({ hasError: false, errorMessage: '', prevPath: this.props.location.pathname });
    }
  }

  componentDidCatch(error: Error) {
    this.setState({ hasError: true, errorMessage: error.message });
  }

  render() {
    return this.state.hasError ? (
      <ErrorContainer>
        <fieldset>
          <legend>{this.props.t('common.errorBoundaryMessage')}</legend>
          <pre>
            <code>{this.state.errorMessage}</code>
          </pre>
        </fieldset>
      </ErrorContainer>
    ) : (
      this.props.children
    );
  }
}
const ErrorBoundary = withTranslation()(withRouter(Boundary));
export { ErrorBoundary };

Again if you don't need translations, you can omit withTranslation HOC, t prop.

QA engineer is happy now 👍 => I'm happy 🤟

Hope this helps you as well..

See you again 👋 👋
Kiran

How to set active class on NavLink for multiple react routes

Kiran Mantha — Wed, 05 Jul 2023 13:27:25 +0000

I recently got into one use case of highlighting the navlink for multiple routes.

Lets say we have two routes

customer listing (/customers).
customer details (/customer-details/:customerId).

The entry point in ui is customer listing and when you click on any record, we will be navigated to customer details page.

Now i have a navlink like this

<NavLink to={PATHS.CUSTOMERS}>Customers</Navlink>

The use case is for both the routes, the navlink should be in active state. And this is the logic i implemented:

import { NavLink, matchPath, useLocation } from "react-router-dom";

export function NavigationBar() {
  const { pathname } = useLocation();
  const setNavlinkClasses = (paths: string[]) =>
    paths.some((path) => matchPath(path, pathname))
    ? "navlink active"
    : "navlink";

  return (
    <nav>
      <NavLink
        to={PATHS.CUSTOMERS}
        className={setNavlinkClasses([PATHS.CUSTOMERS, PATHS.CUSTOMER_DETAILS])}
      >Customers</NavLink>
    </nav>
  );
}

And that's it.

Hope it helps 😄
Kiran 👋 👋

Implementing and Unit testing Graphql in React using msw

Kiran Mantha — Tue, 23 May 2023 04:44:55 +0000

There are pretty good articles on using msw for graphql / rest unit testing for react out there. And this is my implementation with a protip at the end 😉 so don't miss a detail 😊

TL'DR If you want to skip this biggg reading, here is the source code

This is a no-explanation article. simply copy paste the code and it will work.

This implementation has 3 stages.

Stage 1 => Implementing graphql
Stage 2 => Writing unit tests with msw
Stage 3 => Using msw as development server

As ususal let's start with Stage 1.

Stage 1: Implementing graphql

Step - 1: App scaffolding
Create a react app using CRA and typescript, assuming you installed cra globally:

run yarn create react-app my-app --template typescript

Step - 2: Folder structure
This is my folder structure

.
├── src/
│   ├── api/
│   │   ├── gql/
│   │   │   ├── interceptors/
│   │   │   │   ├── interceptor.ts
│   │   │   │   ├── utils.ts
│   │   │   │   └── index.ts
│   │   │   ├── models/
│   │   │   │   ├── users.model.ts
│   │   │   │   └── index.ts
│   │   │   ├── queries/
│   │   │   │   ├── users.ts
│   │   │   │   └── index.ts
│   │   │   └── requests/
│   │   │       ├── users.ts
│   │   │       └── index.ts
│   │   ├── mockhandler/
│   │   │   ├── queries
│   │   │   └── index.ts
│   │   └── testUtils/
│   │       └── index.tsx
│   ├── Users.tsx
│   ├── Users.spec.tsx
│   ├── App.tsx
│   ├── App.spec.tsx
│   ├── index.tsx
│   └── jest.setup.ts
├── jest.config.ts
├── setupApiTests.ts
├── global.d.ts
└── package.json

Step - 3: Packages
let's add following packages
yarn add @tanstack/react-query graphql-request @testing-library/jest-dom @testing-library/react @testing-library/user-event @testing-library/jest-dom @types/jest ts-jest ts-node msw identity-obj-proxy

Step - 4: Setting up Jest
Add the following to

jest.config.ts

//jest.config.ts

export default {
  displayName: "react-graphql-unittesting",
  testEnvironment: "jsdom",
  transform: {
    "^.+\\.tsx?$": "ts-jest",
  },
  setupFilesAfterEnv: [
    "<rootDir>/src/jest.setup.ts",
    "<rootDir>/setupApiTests.ts",
  ],
  moduleNameMapper: {
    '^.+\\.(css|less)$': 'identity-obj-proxy'
  },
  collectCoverageFrom: [
    'src/**/*{js,jsx,ts,tsx}',
    '!src/**/index.ts',
    '!<rootDir>/node_modules/',
  ],
  coverageReporters: ["clover", "json", "lcov", "text", "html"],
};

setupApiTests.ts

//setupApiTests.ts

const { setupServer } = require('msw/node');
const { handler } = require('./src/api/mockHandler');
const server = setupServer(...handler);
// Establish API mocking before all tests.
beforeAll(() => server.listen());
// Reset any request handlers that we may add during the tests,
// so they don't affect other tests.
afterEach(() => server.resetHandlers());
// Clean up after the tests are finished.
afterAll(() => server.close());

export {};

jest.setup.ts

//jest.setup.ts

import '@testing-library/jest-dom';
jest.setTimeout(30000);

Step - 4: Implementing sample graphql api

Let's use graphqlZero for sample graphql api.

a. lets add interceptor

// interceptor/utils.ts

enum QueryType {
  QUERY = 'query',
  MUTATION = 'mutation'
}

const extractNameFromQuery = (query: string) => {
  const keywordIndex =
    query.indexOf(QueryType.QUERY) !== -1
      ? query.indexOf(QueryType.QUERY) + QueryType.QUERY.length
      : query.indexOf(QueryType.MUTATION) + QueryType.MUTATION.length;
  return query.substring(keywordIndex, query.indexOf('(')).replace(/ /g, '');
};

export { extractNameFromQuery };

// interceptor/interceptor.ts

import { GraphQLClient } from 'graphql-request';
import { extractNameFromQuery } from './utils';

const getGraphQLClient = (
  _queryName: string,
  optionalHeader?: Record<string, string | number | boolean>
): GraphQLClient => {
  let globalHeaders = {};

  if (optionalHeader) {
    globalHeaders = {
      ...optionalHeader,
      ...globalHeaders
    };
  }
  return new GraphQLClient('https://graphqlzero.almansi.me/api', {
    headers: { ...globalHeaders } as Record<string, string>
  });
};

const GQLInteraction = async <T,>(
  schema: string,
  variables?: Record<string, string[] | number | number[] | unknown> | undefined,
  optionalHeader: Record<string, string | number | boolean> = {}
): Promise<T> => {
  try {
    const queryDescription = extractNameFromQuery(schema);
    const client = getGraphQLClient(queryDescription, { ...optionalHeader });
    return await client.request(schema, variables);
  } catch (err) {
    console.log('error', err);
    throw err;
  }
};

export { GQLInteraction };

// interceptor/index.ts

export * from './interceptor';

b. lets add the query

// queries/users.ts

export const getUser = `
query user($id: ID!){
  user(id: $id) {
    id
    username
    email
    address {
      geo {
        lat
        lng
      }
    }
  }
}
`;

// queries/index.ts

export * from './users';

c. lets add the response type

// models/users.model.ts

export interface User {
  id: string;
  username: string;
  email: string;
  address: {
    geo: {
      lat: string;
      lng: string;
    };
  };
}

export interface UserResponse {
    user: User
}

// models/index.ts

export * from "./users.model";

d. lets create a request to fetch the user

// requests/users.ts

import { UseQueryResult, useQuery } from "@tanstack/react-query";
import { GQLInteraction } from "../interceptors";
import { User, UserResponse } from "../models";
import { getUser } from "../queries";

export const useGetUser = (userid: string): UseQueryResult<User, unknown> => {
  const options = {
    refetchOnWindowFocus: false,
    retry: 0,
    select: (response: UserResponse): User => {
      return response.user;
    },
  };

  return useQuery(
    ["user"],
    () => GQLInteraction<UserResponse>(getUser, { id: userid }),
    options
  );
};


// requests/index.ts

export * from './users';

Step - 5: Consuming api in component
a. consume request in Users component

// Users.tsx

import { useGetUser } from "./api/gql/requests";

export function Users() {
  const { data, isFetching } = useGetUser("1");
  return !isFetching && data ? (
    <h1 data-testid="username">{data.username}</h1>
  ) : (
    <div data-testid="loading">loading</div>
  );
}

b. update App component as below

// App.tsx

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import "./App.css";
import { Users } from "./Users";

function App() {
  const queryClient = new QueryClient();

  return (
    <QueryClientProvider client={queryClient}>
      <Users />
    </QueryClientProvider>
  );
}

export default App;

Finally we integrated graphql in our react application.

Oops.. App.spec.tsx is failing. lets modify it as below:

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

describe("App", () => {
  it("should renders learn react link", () => {
    render(<App />);
    const loaderElement = screen.getByTestId("loading");
    expect(loaderElement).toBeInTheDocument();
  });
});

Huff now looks good.

Now it's time for implementing Stage 2.

Stage 2: Writing unit tests with msw

Step - 1: implementing mock handler.

In stage 1 when we run unit tests, jest didn't get terminated properly. this is because our component tries to make api call as if in real browser. But it didn't get any response hence jest didn't get terminated properly. To fix this lets implement the mock handlers that provide mock api response.

// mockhandler/queries/users.ts

import { graphql } from "msw";

export const UsersQueries = [
  graphql.query("user", (_req, res, ctx) => {
    return res(
      ctx.data({
        user: {
          id: "1",
          username: "Antonette",
          email: "Shanna@melissa.tv",
          address: {
            geo: {
              lat: -43.9509,
              lng: -34.4618,
            },
          },
        },
      })
    );
  }),
];


// mockhandler/queries/index.ts

export * from './users';

// mockhandler/index.ts

import { UsersQueries } from "./queries";

const handler = [...UsersQueries];

export { handler };

That's it. now if we run tests again, the msw provides mock api response to user query and jest will terminate properly.

As usual there's scope for improvement.

Lets refactor this a little bit.

// testUtils/index.tsx

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ComponentType, ReactNode } from "react";

const createTestQueryClient = () =>
  new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,
      },
    },
  });

export function createWrapper(node: ReactNode): ComponentType {
  const testQueryClient = createTestQueryClient();
  return function MockComponent() {
    return (
      <QueryClientProvider client={testQueryClient}>{node}</QueryClientProvider>
    );
  };
}

Lets update Users component

// Users.tsx

import { useGetUser } from "./api/gql/requests";

export function Users() {
  const { data, isFetching } = useGetUser("1");
  return (
    <div data-testid="users-component">
      {!isFetching && data ? (
        <h1 data-testid="username">{data.username}</h1>
      ) : (
        <div data-testid="loading">loading</div>
      )}
    </div>
  );
}

Let's update the App.spec.ts

// App.spec.ts

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

describe("App", () => {
  it("should renders learn react link", () => {
    render(<App />);
    const usersComponent = screen.getByTestId("users-component");
    expect(usersComponent).toBeInTheDocument();
  });
});

Now let's create a spec file for users component.

// Users.spec.ts

import { render, screen, waitFor } from "@testing-library/react";
import { Users } from "./Users";
import { createWrapper } from "./api/testUtils";

describe("Users", () => {
  const Component = createWrapper(<Users />);

  it("should render users component", () => {
    render(<Component />);
    expect(screen.getByTestId("users-component")).toBeInTheDocument();
  });

  it("should display user name from api", async () => {
    render(<Component />);
    await waitFor(() => {
      expect(screen.getByText(/Antonette/i)).toBeInTheDocument();
    });
  });
});

The createWrapper function will help to wrap any individual component which consume graphql in unit tests.

Awesome. all the happy flow is done. but what about error scenerio??

Now it's time for protip

Step - 2: Protip

let's update the setupApiTests file

// setupApiTests.ts

const { setupServer } = require("msw/node");
const { handler } = require("./src/api/mockHandler");
const server = setupServer(...handler);
global.mswServer = server;
// Establish API mocking before all tests.
beforeAll(() => server.listen());
// Reset any request handlers that we may add during the tests,
// so they don't affect other tests.
afterEach(() => server.resetHandlers());
// Clean up after the tests are finished.
afterAll(() => server.close());

export {};

create global.d.ts in root and add the following:

declare module globalThis {
  var mswServer: SetupServer;
}

update tsconfig include property:

// tsconfig.json
{
   ...
   "include": ["src", "global.d.ts"]
}

finally update testutils as below:

// testUtils/index.tsx

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { graphql } from "msw";
import { SetupServer } from "msw/node";
import { ComponentType, ReactNode } from "react";

const createTestQueryClient = () =>
  new QueryClient({
    defaultOptions: {
      queries: {
        retry: false,
      },
    },
  });

export function createWrapper(node: ReactNode): ComponentType {
  const testQueryClient = createTestQueryClient();
  return function MockComponent() {
    return (
      <QueryClientProvider client={testQueryClient}>{node}</QueryClientProvider>
    );
  };
}

export function mockApiResponse(
  queryName: string,
  response: Record<string, unknown> | null,
  throwError = false
) {
  (global.mswServer as SetupServer).use(
    graphql.query(queryName, (_req, res, ctx) => {
      if (throwError) {
        return res(ctx.errors([]));
      }
      return res(ctx.data(response as Record<string, unknown>));
    })
  );
}

Now it's time to test -ve scenerio in users component:

// Users.tsx

import { useGetUser } from "./api/gql/requests";

export function Users() {
  const { data, isFetching, error } = useGetUser("1");
  return (
    <div data-testid="users-component">
      {!isFetching && data ? (
        <h1 data-testid="username">{data.username}</h1>
      ) : (
        <div data-testid="loading">loading</div>
      )}
      {error ? (
        <div data-testid="api-error">Oops something went wrong</div>
      ) : null}
    </div>
  );
}


// Users.spec.tsx

import { render, screen, waitFor } from "@testing-library/react";
import { Users } from "./Users";
import { createWrapper, mockApiResponse } from "./api/testUtils";

describe("Users", () => {
  const Component = createWrapper(<Users />);

  it("should render users component", () => {
    render(<Component />);
    expect(screen.getByTestId("users-component")).toBeInTheDocument();
  });

  it("should display user name from api", async () => {
    render(<Component />);
    await waitFor(() => {
      expect(screen.getByText(/Antonette/i)).toBeInTheDocument();
    });
  });

  it("should display api-error placeholder when api throws error", async () => {
    mockApiResponse("user", null, true);
    render(<Component />);
    await waitFor(() => {
      expect(screen.getByTestId("api-error")).toBeInTheDocument();
    });
  });
});

And that's how we tested api failure case too.

That's a lot of copy paste but i promise this surely helps you alot.

Now its time for final stage.

Stage 3: Using msw as development server

With very minimal changes we can convert the till now msw setup as development server as well.

Let's see how to do that.

In behind the screens, msw rely on serviceWorker in application public folder to serve mock api responses (check here to know more about this). To setup this service worker let's run the below command (assuming you have msw installed globally. else move the below command to a script in package json and run it).

msw init public --save

This command essentially creates the service worker for us in cra public folder.

After this lets tweak the index.tsx file as below

// index.tsx
...

import { setupWorker } from 'msw';
import { handler } from './api/mockhandler';

if(process.env.NODE_ENV === 'development') {
   setupWorker(...handler).start();   
}

...

That's it. The mock server is up and running. To test this, turn off internet and run the app you will see the data displayed from msw 😊

The process is same for graphql.mutation too.

Are you using rest instead of graphql, no worries. in mockhandler instead of using graphql.query use rest from msw. The official msw docs are good enough to understand using rest with msw.

And That's the end of this article.

Thanks,
Kiran 👋

useLazyQuery for @tanstack/react-query

Kiran Mantha — Mon, 22 May 2023 07:20:31 +0000

As we all know apollo-graphwl client provide an awesome useLazyQuery hook to make queries on demand. But the same is not true for react-query by tanstack. There's also few discussion threads in here and here

i created a custom useLazyQuery hook based on the ideas of above threads and this is the result:

// useLazyQuery.ts

import { GraphQLClient } from 'graphql-request';
import { QueryKey, UseQueryOptions, UseQueryResult, useQuery } from '@tanstack/react-query';
import { useState } from 'react';

interface QueryOptions<TInput, TQueryFnData, TResponse>
  extends Omit<UseQueryOptions<TQueryFnData, unknown, TResponse, QueryKey>, 'onSuccess' | 'onError'> {
  onSuccess?: (data: TResponse, input?: TInput) => void;
  onError?: () => void;
}

const extractNameFromQuery = (query: string) => {
  const keywordIndex =
    query.indexOf(QueryType.QUERY) !== -1
      ? query.indexOf(QueryType.QUERY) + QueryType.QUERY.length
      : query.indexOf(QueryType.MUTATION) + QueryType.MUTATION.length;
  return query.substring(keywordIndex, query.indexOf('(')).replace(/ /g, '');
};

const getGraphQLClient = (
  _queryName: string,
  optionalHeader?: Record<string, string | number | boolean>
): GraphQLClient => {
  return new GraphQLClient(env.REACT_APP_API_URL, {
    headers: { } as Record<string, string>
  });
};

const GQLInteraction = async <T,>(
  schema: string,
  variables?: Record<string, string[] | number | number[] | unknown> | undefined,
): Promise<T> => {
  try {
    const queryDescription = extractNameFromQuery(schema);
    const client = getGraphQLClient(queryDescription, { ...optionalHeader });
    return await client.request(schema, variables);
  } catch (err) {
    console.log('error', err);
    throw err;
  }
};

export function useLazyQuery<TInput extends Record<string, unknown>, TQueryFnData, TResponse = TQueryFnData>(
  queryName: string,
  query: string,
  options: QueryOptions<TInput, TQueryFnData, TResponse> = {}
): [(input: TInput) => void, UseQueryResult<TResponse, unknown>] {
  const [variables, setVariables] = useState<TInput>();
  const queryOptions = {
    refetchOnWindowFocus: false,
    retry: 0,
    enabled: Boolean(variables),
    select: data => {
      let returnValue: unknown = data;
      if (options.select) {
        returnValue = options.select(data);
      }
      return returnValue as never as TResponse;
    },
    onSuccess: (data: TResponse) => {
      options.onSuccess?.(data, variables);
      setVariables(undefined);
    },
    onError: () => {
      options.onError?.();
      setVariables(undefined);
    }
  };
  const queryInfo = useQuery<TQueryFnData, unknown, TResponse, QueryKey>(
    [queryName, variables],
    () => GQLInteraction(query, variables),
    queryOptions
  );
  return [setVariables, queryInfo];
}

And this is how i'm using it:

// queries.ts

const getPersonDetail = `query person(id: $id) {
    getPersonDetail(id: $id) {
        id
        name
    }
}`;
interface Person {
    id: number;
    name: string
}

interface PersonResponse {
    getPersonDetails: Person;
}

export const useGetPersonDetails = (onSuccess: (person: Person) => void, onError?: () => void) => {
    const options = {
      onSuccess: (data: PersonResponse, input?: { personId: number }) => {
        onSuccess(data.getPersonDetails);
      },
      onError: () => {
        onError?.();
      },
    };
    return useLazyQuery<{ personId: number }, PersonResponse>(
      "getPersonDetail",
      getPersonDetail,
      options
    );
};

sometimes we may need to access api payload in success method. in that case, in options.onSuccess that details can be accessed by the optional 2nd parameter input as shown above.

That's it for the day.
Don't forget to share your implementation in comments below 👇

Thanks,
Kiran 👋

How to unit test useSearchParams?

Kiran Mantha — Thu, 11 May 2023 04:36:32 +0000

useSearchParams hook provides flexibility to read, check, modify and delete query parameters at ease. But unfortunately, I found it hard to unit test it. Hence this post 😄

let's start with a code snippet..

// sampleComponent.js

import { useSearchParams } from 'react-router-dom';

function SampleComponent() {
    const [searchParams, setSearchParams] = useSearchParams();

    const updateParam = () => {
        const updatedSearchParams = new URLSearchParams(searchParams.toString());
        if (updatedSearchParams.has('userName')) {
            updatedSearchParams.delete('userName');
        } else { 
            updatedSearchParams.set("userName", "testA"); 
        }
        setSearchParams(updatedSearchParams.toString());
    }

    return (
      <div data-testid='container'>
        userName in searchParams {searchParams.get("userName")}
        <button data-testid='button' onClick={updateParam}>toggle username in params</button>
      </div>
    );
}

in above code we are printing userName from serchParams. On button click, we're toggling userName in queryparams. Most of the times it is not this simple, as we depend on searchParams to perform some complex operations. Now these things make very hard to test in our unit tests if the searchParams is getting updated properly or not.

Whining apart. let's write unit test for above component in jest.

// sampleComponent.spec.js

import {
  render,
  screen
} from "@testing-library/react";

const Wrapper = () => {
    return <MemoryRouter>
        <SampleComponent />
    </MemoryRouter>
}


describe("SampleComponent", () => {
    it('should render component successfully', () => {
        render(<Wrapper />);
        expect(screen.getByTestId("container")).toBeInTheDocument();
    });
});

very basic test. nothing special. As we're using useSearchParams hook, we wrapped our component inside MemoryRouter and checked if container is there in the document or not.

1st Step is done. Now in 2nd step, we need to mock useSearchParams to test the functionality.

let's modify the above spec as below:

// sampleComponent.spec.js

import {
  render,
  screen
} from "@testing-library/react";

let mockSearchParam = '';

jest.mock('react-router-dom', () => ({
  ...jest.requireActual('react-router-dom'),
  useSearchParams: () => {
    const [params, setParams] = useState(new URLSearchParams(mockSearchParam));
    return [
      params,
      (newParams: string) => {
        mockSearchParam = newParams;
        setParams(new URLSearchParams(newParams));
      }
    ];
  }
}));

const Wrapper = () => {
    return <MemoryRouter>
        <SampleComponent />
    </MemoryRouter>
}


describe("SampleComponent", () => {
    it('should render component successfully', () => {
        render(<Wrapper/>);
        expect(screen.getByTestId("container")).toBeInTheDocument();
    })
});

cool. We mocked the react-router-dom package partially overriding the implementation of useSearchParams.

If you observe closely, we declared a global variable mockSearchParam and used useState inside our mock implementation. the mock returns an array that contains the state and a function to update the state. Whenever we call setSearchParams, it update the global variable value which helps us to check if it is getting updated as per expected.

As we're using useState in mockImplementation, it re-renders our component whenever we clicked the button. This is the party trick 😎

Now let's write test for updateParam function in our component.

// sampleComponent.spec.js

...

it("should toggle userName in searchParams on button click", () => {
    render(</Wrapper />);
    const button = screen.getBytestId('button');
    fireEvent.click(button);
    // check if it is adding userName to searchParams
    expect(mockSearchParam).toContain('userName=testA');
    fireEvent.click(button);
    // check if it removed userName from searchParams
    expect(mockSearchParam).not.toContain('userName=testA');
});

...

Excellant. let me tell you how it worked behind the screens. In our spec file, we mocked the implementation of useSearchParams. when our component renders, it read the value from our mock implementation. Now when we trigger click event on button, it fires setParams function in our mock implementation of useSearchParams. along with that, it also update the global mockSearchParam value too. This helps us to read the updated query param string via the global variable in our test.

This is how the final spec file looks like:

// sampleComponent.spec.js

import {
  render,
  screen
} from "@testing-library/react";
import { useState } from 'react';

let mockSearchParam = '';

jest.mock('react-router-dom', () => ({
  ...jest.requireActual('react-router-dom'),
  useSearchParams: () => {
    const [params, setParams] = useState(new URLSearchParams(mockSearchParam));
    return [
      params,
      (newParams) => {
        mockSearchParam = newParams;
        setParams(new URLSearchParams(newParams));
      }
    ];
  }
}));

const Wrapper = () => {
    return <MemoryRouter>
        <SampleComponent />
    </MemoryRouter>
}


describe("SampleComponent", () => {
    it('should render component successfully', () => {
        render(<Wrapper />);
        expect(screen.getByTestId("container")).toBeInTheDocument();
    });

    it("should toggle userName in searchParams on button click", () => {
        render(</Wrapper />);
        const button = screen.getBytestId('button');
        fireEvent.click(button);
        // check if it is adding userName to searchParams
        expect(mockSearchParam).toContain('userName=testA');
        fireEvent.click(button);
        // check if it removed userName from searchParams
        expect(mockSearchParam).not.toContain('userName=testA');
    });
});

There's definetly a different way to do this too. Don't forget to share that in comments below.

And that's the wrap.
Hope this helps you in your TDD.

See you again,
Kiran 👋

ECMAScript decorators with Vite

Kiran Mantha — Wed, 01 Feb 2023 14:46:11 +0000

I felt very happy when i saw the progress on bringing typescript decorators to vanillajs. I thought to give it a try in my vanillajs + vite application and bammmmm 💥 it broke 🤯 🙇‍♂️.

ESbuild, which comes with OOB of vite, doesn't support decorators yet 🙄 🤷

That only left me the option to go for babel but i don't want to get away from my love, vite 🥺

Then i found the vite-plugin-babel package and made few changes to vite config. It worked wohooooo 🤩

Here's the config:

import { defineConfig } from 'vite';
import babel from 'vite-plugin-babel';

export default defineConfig({
  base: "./",
  plugins: [
    babel({
      babelConfig: {
        babelrc: false,
        configFile: false,
        plugins: [
          [
            "@babel/plugin-proposal-decorators",
            { loose: true, version: "2022-03" },
          ],
        ],
      },
    }),
  ],
  server: {
    host: true,
    port: 3001,
    open: "/",
  },
});

That's it. This resolved my issue and i happily went on using decorators in javascript.

FYI, decorator proposal is in stage3 and one step behind of getting finalized.

Thanks for the read,
Kiran 👋 👋

How to create a custom toolbar addon for Storybook?

Kiran Mantha — Sun, 24 Jul 2022 09:46:00 +0000

Storybook enables faster prototyping of UI elements irrespective of framework. In this article we'll see how to create a toolbar addon for storybook. The example for this topic is toggling theme via a custom toolbar menu addon.

I'm skipping the storybook setup either for new application or an existing application based on any supported framework for time being.

Once you create a new application or added storybook to existing application, run npm run storybook to view storybook for your application.

The main files for storybook are .storybook/main.js and .storybook/preview.js.

Open .storybook/main.js and add "@storybook/addon-toolbars" to addons array if it is not there. This package enables us to add custom addons to storybook toolbar.

As mentioned earlier our intention is to add a theme selector menu to storybook toolbar as custom addon. For that, open preview.js and the below piece of code:

// .storybok/preview.js

export const globalTypes = {
  theme: {
    name: 'Toggle theme',
    description: 'Global theme for components',
    defaultValue: 'light',
    toolbar: {
      icon: 'circlehollow',
      items: ['light', 'dark'],
      showName: true,
      dynamicTitle: true
    }
  }
}

Once saved, the changes will be reflected on your localhost. And you will see a new toolbar menu with options light and dark.

Excellent. We created a new custom menu for storybook toolbar 😎

But it is doing nothing when we select any option from the new menu.

Before going to address this, i want to remind our task at hand. Change the theme for selected UI element. for that let's write a very basic css

// your angular/react application's base.(s)css

:root:not([data-theme='dark']) {
  --bg-color: #fff;
}

[data-theme='dark'] {
  --bg-color: #000;
}

body {
  background-color: var(--bg-color);
}

There's nothing fancy in this. We created a css variable --bg-color and assigned a value to it based on a data attribute data-theme. And atlast we're using that css variable to set body tag background color.

Cool. But where to add that data attribute and how??

The answer for 1st question will showup if we inspect element the rendered UI element. Any UI element in storybook is rendered inside an iframe with id storybook-preview-iframe. We need to add our data attribute data-theme to the body tag inside that iframe.

Very well. Now it is time to answer the 2nd question HOW.

For this, let's add a file useTheme.js inside .storybook folder of the application. And add the below code:

// .storybook/useTheme.js

import { useEffect, useGlobals } from '@storybook/addons';

export const useTheme = (StoryFn) => {
  const [{ theme }] = useGlobals();

  useEffect(() => {
    //document.body refers to body tag inside iframe#storybook-preview-iframe
    document.body.setAttribute('data-theme', theme);
  }, [theme]);

  return StoryFn();
};

That's a mouthful. Let's see what this is doing. Storybook provides an api called decorators. We just created a decorator called useTheme. Previously in main.js we added theme to globalTypes. We can read the selected theme value in our decorator using useGlobals of @storybook/addons. And in useEffect we're setting the selected theme as value to data-theme attribute of iframe body tag.

After creating useTheme decorator we need to use this inside preview.js as:

// .storybook/preview.js
import '<path-to-your-project-theme-or-base-css>';
import {useTheme} from './useTheme';

export const globalTypes = {
  theme: {
    name: 'Toggle theme',
    description: 'Global theme for components',
    defaultValue: 'light',
    toolbar: {
      icon: 'circlehollow',
      items: ['light', 'dark'],
      showName: true,
      dynamicTitle: true
    }
  }
}

export const decorators = [useTheme];

Viola. whenever we select a theme from toolbar menu, the iframe body background color will change.

And that's how we created a custom toolbar addon to change the theme. You can create few more css variables to change the appearance of UI elements based on selected theme.

That's the end of this article. Please post your ideas on toolbar addons in comments section below.

Thanks,
Kiran 👋

PS: here is the link for example react repo and for example angular repo

DEV Community: Kiran Mantha

Generating a Custom Chakra UI v3 Theme from Design Tokens: A Complete Guide

Important: Chakra UI v3 Uses Panda CSS Under the Hood

Official Docs to Bookmark

Critical Rule: No Token References in Final Output

Wrong (Do Not Do This)

Correct (Required)

Why?

Prerequisites

Step 1: Understand Chakra UI v3 Theme Structure

breakpoints

tokens — Primitive Design Tokens

colors

fonts

fontWeights, letterSpacings, spacing, borders, radii, shadows, gradients

semanticTokens — Meaningful, Contextual Tokens

Responsive Values (via object)

Single Value (non-responsive)

grid — Responsive Layout Tokens

textStyles — Reusable Typography

themes — Multi-Theme Support (Light/Dark/Minimal/Contrast)

Final themeConfig.json Example

Step 2: Generate themeConfig.json (Any Format to Chakra)

Example Script Skeleton

Step 3: Use in React App

App Entry

Switching Themes at Runtime

Best Practices

Tools & Resources

Conclusion

PlumeJS - No fuss web-components framework

Main packages:

Addon package:

How to setup Kafka locally

How to create a framework-agnostic nx monorepo

Steps:

Step 1: Create Shell

Step 2: UI Lib - Tab component

Step 3: Products & About Libs

Pub-Sub using ES6 Promise

Error boundary with react-i18next and router

How to set active class on NavLink for multiple react routes

Implementing and Unit testing Graphql in React using msw

Stage 1: Implementing graphql

Stage 2: Writing unit tests with msw

Stage 3: Using msw as development server

useLazyQuery for @tanstack/react-query

How to unit test useSearchParams?

ECMAScript decorators with Vite

How to create a custom toolbar addon for Storybook?

`breakpoints`

`tokens` — Primitive Design Tokens

`colors`

`fonts`

`fontWeights`, `letterSpacings`, `spacing`, `borders`, `radii`, `shadows`, `gradients`

`semanticTokens` — Meaningful, Contextual Tokens

`grid` — Responsive Layout Tokens

`textStyles` — Reusable Typography

`themes` — Multi-Theme Support (Light/Dark/Minimal/Contrast)

Final `themeConfig.json` Example

Step 2: Generate `themeConfig.json` (Any Format to Chakra)