DEV Community: Karthik Gs

# I Just Published My First npm Package — Here's Everything I Did

Karthik Gs — Wed, 10 Jun 2026 15:14:54 +0000

A complete walkthrough of publishing Cartlify — a React e-commerce UI kit — to npm for the first time.

The Milestone

Yesterday I published Cartlify to npm.

npm install cartlify

It sounds simple. But getting to that one line took more decisions, more configuration, and more trial and error than I expected.

This article covers everything — from setting up the build config to the actual publish command — so you don't have to figure it out the hard way.

What Is Cartlify?

Cartlify is a production-ready React + TypeScript + Tailwind CSS component library focused on e-commerce UI.

4 components that every e-commerce project needs:

ProductCard — 3 layout variants, image gallery, wishlist, sale badges, skeleton loading
CartDrawer — animated slide-in, focus trap, ESC dismiss, quantity stepper
CheckoutStepper — horizontal/vertical, animated connectors, keyboard navigation
PageLoader — 4 animation styles, 3 position modes

Plus 3 utility hooks, 11 tree-shakeable icons, 40+ CSS design tokens, full dark mode, and 141 Jest + React Testing Library tests.

Built so freelance developers and indie makers can skip the painful e-commerce UI layer and ship faster.

Why Publish to npm?

Before npm, Cartlify was only available on Gumroad as a paid download.

That's fine — but npm adds something Gumroad can't:

Developer sees Cartlify →
runs npm install cartlify →
evaluates the compiled output →
trusts the quality →
buys the full source on Gumroad

npm is a credibility and discovery channel — not just a distribution method. A package on npm signals that something is real, maintained, and production-ready.

Also: npmjs.com gets millions of developer searches every month. That's free traffic you can't get from Gumroad alone.

The Build Setup — tsup

The most important decision before publishing is how you bundle your library.

I chose tsup — a zero-config TypeScript bundler built on esbuild. Here's why:

Tool	Config needed	Speed	Output
Rollup	Lots	Medium	ESM + CJS
Webpack	Heavy	Slow	CJS only
Vite lib mode	Some	Fast	ESM + CJS
tsup	Almost zero	Very fast	ESM + CJS + .d.ts

My tsup.config.ts:

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  sourcemap: false,
  clean: true,
  minify: true,
  external: ['react', 'react-dom'],
  esbuildOptions(options) {
    options.alias = {
      '@components': './src/components',
      '@primitives': './src/primitives',
      '@hooks': './src/hooks',
      '@utils': './src/utils',
      '@types': './src/types',
    };
  },
});

Key decisions:

format: ['cjs', 'esm'] — supports both older and modern bundlers
dts: true — generates .d.ts TypeScript type definitions
minify: true — compiled output is minified (buyers get clean source on Gumroad)
sourcemap: false — no source maps in public npm package
external: ['react', 'react-dom'] — don't bundle React itself

After running npm run build, the dist/ folder looks like:

dist/
├── index.js      ← CommonJS
├── index.mjs     ← ES Module
└── index.d.ts    ← TypeScript types

The package.json Setup

This is the most critical file for npm publishing. Every field matters.

{
  "name": "cartlify",
  "version": "1.0.0",
  "description": "Production-ready React e-commerce UI kit — ProductCard, CartDrawer, CheckoutStepper, PageLoader. Built with TypeScript, Tailwind CSS and Storybook.",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": [
    "dist",
    "README.md"
  ],
  "scripts": {
    "build": "tsup src/index.ts",
    "prepublishOnly": "npm run build && npm run lint && npm run test"
  },
  "keywords": [
    "react",
    "typescript",
    "tailwind",
    "ui-kit",
    "ecommerce",
    "cart",
    "product-card",
    "checkout",
    "storybook",
    "component-library",
    "frontend"
  ],
  "author": "Karthik G S <karthikgs.softengg@gmail.com>",
  "license": "MIT",
  "homepage": "https://cartlify.vercel.app",
  "repository": {
    "type": "git",
    "url": "https://github.com/thirumalai77/cartlify"
  },
  "bugs": {
    "url": "https://github.com/thirumalai77/cartlify/issues"
  },
  "peerDependencies": {
    "react": ">=18.0.0",
    "react-dom": ">=18.0.0"
  },
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.0.0"
  }
}

Key fields to get right:

files — only publish what buyers need:

"files": ["dist", "README.md"]

This stops src/, .storybook/, node_modules/, and test files from being included in the npm package.

exports — modern bundler resolution:

"exports": {
  ".": {
    "import": "./dist/index.mjs",
    "require": "./dist/index.js",
    "types": "./dist/index.d.ts"
  }
}

peerDependencies — don't bundle React:

"peerDependencies": {
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0"
}

prepublishOnly — runs before every publish automatically:

"prepublishOnly": "npm run build && npm run lint && npm run test"

This saved me from accidentally publishing broken code.

The .npmignore File

Create this in your root to stop unnecessary files from being published:

src/
.storybook/
*.stories.tsx
*.test.tsx
*.test.ts
node_modules/
.eslintrc.json
.prettierrc
tsconfig.json
tailwind.config.js
tsup.config.ts
coverage/
.github/

Without .npmignore, npm would publish your entire project including source code, test files, and config — making your package unnecessarily large.

Path Aliases — The Tricky Part

Cartlify uses path aliases to avoid ../../ imports:

import { Button } from '@primitives/Button';
import { cn } from '@utils/cn';
import type { Product } from '@types';

This works fine in development. But when you build for npm, the compiled output still has the alias references — and they break for the end user.

The fix is in tsup.config.ts:

esbuildOptions(options) {
  options.alias = {
    '@components': './src/components',
    '@primitives': './src/primitives',
    '@hooks': './src/hooks',
    '@utils': './src/utils',
    '@types': './src/types',
  };
},

This tells tsup to resolve aliases during compilation — the output dist/ files have no aliases, just clean relative paths.

Creating the npm Account

Go to npmjs.com → Sign Up
Verify your email
Enable 2FA — npm now requires this for publishing
Login in terminal:

npm login

It opens a browser for 2FA confirmation. Once verified:

npm whoami
# → yourusername

The Dry Run — Always Do This First

Before publishing for real:

npm publish --dry-run

This shows exactly what will be uploaded without actually publishing:

npm notice 📦  cartlify@1.0.0
npm notice === Tarball Contents ===
npm notice 2.1kB  README.md
npm notice 18.4kB dist/index.js
npm notice 16.2kB dist/index.mjs
npm notice 8.9kB  dist/index.d.ts
npm notice === Tarball Details ===
npm notice name:          cartlify
npm notice version:       1.0.0
npm notice filename:      cartlify-1.0.0.tgz
npm notice package size:  12.3 kB
npm notice unpacked size: 45.6 kB
npm notice total files:   4

Check two things:

Only dist/ and README.md are listed ✅
No source files, test files, or config files ✅

The Publish Command

npm publish --access public

Output:

npm notice Publishing to https://registry.npmjs.org/
+ cartlify@1.0.0

That's it. Live at npmjs.com/package/cartlify.

Adding npm Badges to README

After publishing, add these to your README.md:

[![npm version](https://badge.fury.io/js/cartlify.svg)](https://npmjs.com/package/cartlify)
[![npm downloads](https://img.shields.io/npm/dm/cartlify.svg)](https://npmjs.com/package/cartlify)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

They render as clickable badges on GitHub — adds credibility instantly.

The Free npm + Paid Source Model

Cartlify uses a split model:

npm install cartlify (free)
→ Compiled dist/ output
→ ESM + CJS + TypeScript types
→ All 4 components usable

Gumroad ($29 one-time)
→ Full TypeScript source code
→ Storybook documentation
→ All hooks, icons, design tokens
→ README + usage examples
→ Future updates

The npm package gives developers everything they need to use Cartlify in a project. The Gumroad source lets them read, modify, and fully own the code.

This is the same model used by shadcn/ui, Tailwind UI, and most successful component libraries — free to use, paid to own fully.

What I Learned

1. tsup is the right tool for libraries.
Zero config, fast, outputs exactly what npm needs. Don't overthink the build setup.

2. prepublishOnly is your safety net.
It runs your build, lint, and tests automatically before every publish. You can't accidentally publish broken code.

3. Path aliases need special handling.
They work in development but break in compiled output without the esbuildOptions.alias config.

4. Always dry run first.
npm publish --dry-run saves you from publishing the wrong files. Run it every time.

5. files in package.json matters.
Without it, npm publishes your entire project. Specify exactly what should ship.

6. npm is a credibility signal.
A package on npm feels more legitimate than a Gumroad ZIP alone. Developers trust it more.

Try Cartlify

npm install cartlify

🔗 npm → npmjs.com/package/cartlify

🔗 GitHub → github.com/thirumalai77/cartlify

🔗 Live Storybook → cartlify.vercel.app

🛒 Full source on Gumroad ($29) → karthiksoftengg.gumroad.com/l/cartlify-react-ui-kit

What's Next

Now that Cartlify is on npm, next steps are:

Product Hunt launch
Grow npm downloads and Gumroad sales
Write more tutorials around the components

Will post a 30-day update with real numbers — downloads, views, and sales.

If you've published an npm package before — what do you wish you'd known? Drop it in the comments.

Built by Karthik G S — Senior Frontend Engineer with 10+ years in React, TypeScript, and React Native. Building Cartlify as an indie product alongside a full-time role.

Tags: #react #typescript #npm #webdev #javascript #tutorial #showdev #indiehacker

# How I Built a Production-Ready CartDrawer in React — With Accessibility, Animations, and Tests

Karthik Gs — Tue, 09 Jun 2026 15:18:27 +0000

A complete walkthrough of building the CartDrawer component inside Cartlify — a React e-commerce UI kit.

Why CartDrawer Is Harder Than It Looks

On the surface, a cart drawer sounds simple.

A panel slides in from the right. Shows some items. Has a checkout button.

But when you start building it properly — for a real client project — the requirements stack up fast:

Smooth slide-in animation without an external library
Backdrop overlay with click-to-close
Focus trap — keyboard stays inside the drawer when it's open
ESC key closes it
Scrollable item list with fixed header and footer
Quantity stepper with min/max controls
Empty state
Auto-calculated subtotal
WCAG 2.1 accessible throughout
Fully tested

Most developers spend 2–3 days getting all of this right. This article shows you exactly how I built it inside Cartlify — so you don't have to figure it out from scratch.

What We're Building

By the end of this article you'll have a fully functional CartDrawer component with:

✅ Slide-in animation from right
✅ Backdrop overlay with fade
✅ Focus trap (keyboard accessibility)
✅ ESC key to close
✅ Scrollable items with fixed header/footer
✅ Quantity stepper (min 1)
✅ Remove item button
✅ Empty cart state
✅ Auto subtotal calculation
✅ TypeScript strict types
✅ Jest + React Testing Library tests

Tech Stack

React 18
TypeScript (strict mode)
Tailwind CSS v3
Jest + React Testing Library

Step 1 — Define Your Types

Start with TypeScript interfaces. Clear types make everything else easier.

// src/types/index.ts

export interface Product {
  id: string;
  name: string;
  price: number;
  image: string;
  category?: string;
}

export interface CartItem extends Product {
  quantity: number;
}

export interface CartDrawerProps {
  isOpen: boolean;
  onClose: () => void;
  items: CartItem[];
  title?: string;
  currency?: string;
  emptyStateMessage?: string;
  onQuantityChange: (id: string, quantity: number) => void;
  onRemoveItem: (id: string) => void;
  onCheckout: () => void;
  onContinueShopping?: () => void;
}

Step 2 — Build the useDisclosure Hook

Every open/close interaction in Cartlify uses a shared hook. Build this once, use it everywhere.

// src/hooks/useDisclosure.ts

import { useState, useCallback } from 'react';

interface UseDisclosureReturn {
  isOpen: boolean;
  onOpen: () => void;
  onClose: () => void;
  onToggle: () => void;
}

export const useDisclosure = (
  initialState = false
): UseDisclosureReturn => {
  const [isOpen, setIsOpen] = useState(initialState);

  const onOpen = useCallback(() => setIsOpen(true), []);
  const onClose = useCallback(() => setIsOpen(false), []);
  const onToggle = useCallback(
    () => setIsOpen((prev) => !prev), 
    []
  );

  return { isOpen, onOpen, onClose, onToggle };
};

Usage:

const { isOpen, onOpen, onClose } = useDisclosure();

<button onClick={onOpen}>Open Cart</button>
<CartDrawer isOpen={isOpen} onClose={onClose} ... />

Step 3 — Build the Focus Trap

This is the most important accessibility feature — and the most commonly skipped.

When the drawer is open, pressing Tab should cycle through elements inside the drawer only. Not the page behind it.

// src/hooks/useFocusTrap.ts

import { useEffect, useRef } from 'react';

const FOCUSABLE_SELECTORS = [
  'a[href]',
  'button:not([disabled])',
  'input:not([disabled])',
  'select:not([disabled])',
  'textarea:not([disabled])',
  '[tabindex]:not([tabindex="-1"])',
].join(', ');

export const useFocusTrap = (isActive: boolean) => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!isActive || !containerRef.current) return;

    const container = containerRef.current;
    const focusableElements = Array.from(
      container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTORS)
    );

    if (focusableElements.length === 0) return;

    const firstElement = focusableElements[0];
    const lastElement = 
      focusableElements[focusableElements.length - 1];

    // Focus first element when drawer opens
    firstElement.focus();

    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key !== 'Tab') return;

      if (e.shiftKey) {
        // Shift+Tab — going backwards
        if (document.activeElement === firstElement) {
          e.preventDefault();
          lastElement.focus();
        }
      } else {
        // Tab — going forwards
        if (document.activeElement === lastElement) {
          e.preventDefault();
          firstElement.focus();
        }
      }
    };

    container.addEventListener('keydown', handleKeyDown);
    return () => {
      container.removeEventListener('keydown', handleKeyDown);
    };
  }, [isActive]);

  return containerRef;
};

Step 4 — Build the CartItem Sub-component

Keep concerns separated. CartItem handles a single item row.

// src/components/CartDrawer/CartItem.tsx

import React from 'react';
import { CartItem as CartItemType } from '../../types';

interface CartItemProps {
  item: CartItemType;
  currency?: string;
  onQuantityChange: (id: string, quantity: number) => void;
  onRemove: (id: string) => void;
}

export const CartItem: React.FC<CartItemProps> = ({
  item,
  currency = '$',
  onQuantityChange,
  onRemove,
}) => {
  return (
    <div
      className="flex items-start gap-3 py-4 border-b 
                 border-gray-100 last:border-0"
      role="listitem"
    >
      {/* Product image */}
      <img
        src={item.image}
        alt={item.name}
        className="w-16 h-16 object-cover rounded-lg 
                   flex-shrink-0 bg-gray-50"
      />

      {/* Product details */}
      <div className="flex-1 min-w-0">
        <p className="text-sm font-medium text-gray-900 
                      truncate">
          {item.name}
        </p>
        <p className="text-sm font-semibold text-gray-900 
                      mt-1">
          {currency}{(item.price * item.quantity).toFixed(2)}
        </p>

        {/* Quantity stepper */}
        <div className="flex items-center gap-2 mt-2">
          <button
            onClick={() =>
              onQuantityChange(item.id, item.quantity - 1)
            }
            disabled={item.quantity <= 1}
            className="w-7 h-7 rounded-md border border-gray-200 
                       flex items-center justify-center text-gray-600
                       hover:bg-gray-50 disabled:opacity-40 
                       disabled:cursor-not-allowed transition-colors"
            aria-label={`Decrease quantity of ${item.name}`}
          >
            −
          </button>

          <span
            className="text-sm font-medium text-gray-900 
                       w-6 text-center"
            aria-label={`Quantity: ${item.quantity}`}
          >
            {item.quantity}
          </span>

          <button
            onClick={() =>
              onQuantityChange(item.id, item.quantity + 1)
            }
            className="w-7 h-7 rounded-md border border-gray-200 
                       flex items-center justify-center text-gray-600
                       hover:bg-gray-50 transition-colors"
            aria-label={`Increase quantity of ${item.name}`}
          >
            +
          </button>
        </div>
      </div>

      {/* Remove button */}
      <button
        onClick={() => onRemove(item.id)}
        className="text-gray-400 hover:text-red-500 
                   transition-colors flex-shrink-0 mt-0.5"
        aria-label={`Remove ${item.name} from cart`}
      >
        <svg
          xmlns="http://www.w3.org/2000/svg"
          className="w-4 h-4"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          strokeWidth={2}
          aria-hidden="true"
        >
          <path
            strokeLinecap="round"
            strokeLinejoin="round"
            d="M19 7l-.867 12.142A2 2 0 0116.138 
               21H7.862a2 2 0 01-1.995-1.858L5 7m5 
               4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 
               1 0 00-1 1v3M4 7h16"
          />
        </svg>
      </button>
    </div>
  );
};

Step 5 — Build the CartDrawer Component

Now assemble everything together:

// src/components/CartDrawer/CartDrawer.tsx

import React, { useEffect, useCallback } from 'react';
import { CartDrawerProps } from '../../types';
import { CartItem } from './CartItem';
import { useFocusTrap } from '../../hooks/useFocusTrap';
import { cn } from '../../utils/cn';

export const CartDrawer: React.FC<CartDrawerProps> = ({
  isOpen,
  onClose,
  items,
  title = 'Your Cart',
  currency = '$',
  emptyStateMessage = 'Your cart is empty',
  onQuantityChange,
  onRemoveItem,
  onCheckout,
  onContinueShopping,
}) => {
  const drawerRef = useFocusTrap(isOpen);

  // Total item count
  const itemCount = items.reduce(
    (sum, item) => sum + item.quantity, 0
  );

  // Auto-calculated subtotal
  const subtotal = items.reduce(
    (sum, item) => sum + item.price * item.quantity, 0
  );

  // ESC key closes drawer
  const handleKeyDown = useCallback(
    (e: KeyboardEvent) => {
      if (e.key === 'Escape') onClose();
    },
    [onClose]
  );

  useEffect(() => {
    if (isOpen) {
      document.addEventListener('keydown', handleKeyDown);
      // Prevent body scroll when drawer is open
      document.body.style.overflow = 'hidden';
    }
    return () => {
      document.removeEventListener('keydown', handleKeyDown);
      document.body.style.overflow = '';
    };
  }, [isOpen, handleKeyDown]);

  return (
    <>
      {/* Backdrop overlay */}
      <div
        className={cn(
          'fixed inset-0 bg-black/50 z-40 transition-opacity duration-300',
          isOpen
            ? 'opacity-100 pointer-events-auto'
            : 'opacity-0 pointer-events-none'
        )}
        onClick={onClose}
        aria-hidden="true"
      />

      {/* Drawer panel */}
      <div
        ref={drawerRef}
        role="dialog"
        aria-modal="true"
        aria-labelledby="cart-drawer-title"
        className={cn(
          `fixed top-0 right-0 h-full w-full sm:w-[400px] 
           bg-white shadow-2xl z-50 flex flex-col
           transform transition-transform duration-300 ease-in-out`,
          isOpen ? 'translate-x-0' : 'translate-x-full'
        )}
      >
        {/* Fixed Header */}
        <div className="flex items-center justify-between 
                        px-5 py-4 border-b border-gray-100 
                        flex-shrink-0">
          <div>
            <h2
              id="cart-drawer-title"
              className="text-lg font-semibold text-gray-900"
            >
              {title}
            </h2>
            <p className="text-sm text-gray-500 mt-0.5">
              {itemCount} {itemCount === 1 ? 'item' : 'items'}
            </p>
          </div>

          <button
            onClick={onClose}
            className="p-2 rounded-lg hover:bg-gray-100 
                       transition-colors text-gray-500 
                       hover:text-gray-700"
            aria-label="Close cart"
          >
            <svg
              xmlns="http://www.w3.org/2000/svg"
              className="w-5 h-5"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              strokeWidth={2}
              aria-hidden="true"
            >
              <path
                strokeLinecap="round"
                strokeLinejoin="round"
                d="M6 18L18 6M6 6l12 12"
              />
            </svg>
          </button>
        </div>

        {/* Scrollable item list */}
        <div
          className="flex-1 overflow-y-auto px-5"
          role="list"
          aria-label="Cart items"
        >
          {items.length === 0 ? (
            // Empty state
            <div className="flex flex-col items-center 
                            justify-center h-full py-16 
                            text-center">
              <div className="w-16 h-16 rounded-full 
                              bg-gray-100 flex items-center 
                              justify-center mb-4">
                <svg
                  xmlns="http://www.w3.org/2000/svg"
                  className="w-8 h-8 text-gray-400"
                  viewBox="0 0 24 24"
                  fill="none"
                  stroke="currentColor"
                  strokeWidth={1.5}
                  aria-hidden="true"
                >
                  <path
                    strokeLinecap="round"
                    strokeLinejoin="round"
                    d="M2.25 3h1.386c.51 0 .955.343 
                       1.087.835l.383 1.437M7.5 14.25a3 
                       3 0 00-3 3h15.75m-12.75-3h11.218
                       c1.121-2.3 2.1-4.684 2.924-7.138
                       a60.114 60.114 0 00-16.536-1.84
                       M7.5 14.25L5.106 5.272M6 20.25a
                       .75.75 0 11-1.5 0 .75.75 0 011.5 
                       0zm12.75 0a.75.75 0 11-1.5 0 
                       .75.75 0 011.5 0z"
                  />
                </svg>
              </div>
              <p className="text-gray-900 font-medium mb-1">
                {emptyStateMessage}
              </p>
              <p className="text-sm text-gray-500">
                Add some items to get started
              </p>
            </div>
          ) : (
            items.map((item) => (
              <CartItem
                key={item.id}
                item={item}
                currency={currency}
                onQuantityChange={onQuantityChange}
                onRemove={onRemoveItem}
              />
            ))
          )}
        </div>

        {/* Fixed Footer */}
        {items.length > 0 && (
          <div className="px-5 py-4 border-t border-gray-100 
                          flex-shrink-0 space-y-3">
            {/* Subtotal */}
            <div className="flex items-center 
                            justify-between">
              <span className="text-sm text-gray-600">
                Subtotal
              </span>
              <span className="text-base font-semibold 
                               text-gray-900">
                {currency}{subtotal.toFixed(2)}
              </span>
            </div>

            {/* Checkout CTA */}
            <button
              onClick={onCheckout}
              className="w-full bg-gray-900 text-white 
                         py-3 px-4 rounded-xl font-medium 
                         text-sm hover:bg-gray-700 
                         active:scale-[0.98] transition-all"
            >
              Checkout — {currency}{subtotal.toFixed(2)}
            </button>

            {/* Continue shopping */}
            <button
              onClick={onContinueShopping ?? onClose}
              className="w-full text-sm text-gray-500 
                         hover:text-gray-700 transition-colors 
                         py-1"
            >
              Continue Shopping
            </button>
          </div>
        )}
      </div>
    </>
  );
};

export default CartDrawer;

Step 6 — The cn Utility

Used throughout for conditional Tailwind classes:

// src/utils/cn.ts

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export const cn = (...inputs: ClassValue[]) => {
  return twMerge(clsx(inputs));
};

Install dependencies:

npm install clsx tailwind-merge

Step 7 — Write the Tests

141 tests ship with Cartlify. Here are the key CartDrawer tests:

// src/components/CartDrawer/CartDrawer.test.tsx

import React from 'react';
import {
  render,
  screen,
  fireEvent,
  waitFor,
} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { CartDrawer } from './CartDrawer';
import { CartItem } from '../../types';

const mockItems: CartItem[] = [
  {
    id: '1',
    name: 'Studio Headphones',
    price: 79.99,
    image: '/headphones.jpg',
    quantity: 2,
  },
  {
    id: '2',
    name: 'Keyboard TKL',
    price: 119.0,
    image: '/keyboard.jpg',
    quantity: 1,
  },
];

const defaultProps = {
  isOpen: true,
  onClose: jest.fn(),
  items: mockItems,
  onQuantityChange: jest.fn(),
  onRemoveItem: jest.fn(),
  onCheckout: jest.fn(),
};

describe('CartDrawer', () => {
  beforeEach(() => jest.clearAllMocks());

  it('renders when open', () => {
    render(<CartDrawer {...defaultProps} />);
    expect(
      screen.getByRole('dialog')
    ).toBeInTheDocument();
  });

  it('shows item count correctly', () => {
    render(<CartDrawer {...defaultProps} />);
    // 2 + 1 = 3 items total
    expect(screen.getByText('3 items')).toBeInTheDocument();
  });

  it('calculates subtotal correctly', () => {
    render(<CartDrawer {...defaultProps} />);
    // (79.99 * 2) + (119.00 * 1) = 278.98
    expect(
      screen.getByText('$278.98')
    ).toBeInTheDocument();
  });

  it('shows empty state when no items', () => {
    render(<CartDrawer {...defaultProps} items={[]} />);
    expect(
      screen.getByText('Your cart is empty')
    ).toBeInTheDocument();
  });

  it('calls onClose when backdrop clicked', () => {
    render(<CartDrawer {...defaultProps} />);
    const backdrop = document.querySelector(
      '[aria-hidden="true"]'
    );
    fireEvent.click(backdrop!);
    expect(defaultProps.onClose).toHaveBeenCalledTimes(1);
  });

  it('calls onClose when ESC key pressed', () => {
    render(<CartDrawer {...defaultProps} />);
    fireEvent.keyDown(document, { key: 'Escape' });
    expect(defaultProps.onClose).toHaveBeenCalledTimes(1);
  });

  it('calls onRemoveItem when remove button clicked', () => {
    render(<CartDrawer {...defaultProps} />);
    const removeButtons = screen.getAllByLabelText(
      /remove/i
    );
    fireEvent.click(removeButtons[0]);
    expect(
      defaultProps.onRemoveItem
    ).toHaveBeenCalledWith('1');
  });

  it('disables minus button at quantity 1', () => {
    const singleItem = [{
      ...mockItems[1], quantity: 1
    }];
    render(
      <CartDrawer {...defaultProps} items={singleItem} />
    );
    const decreaseBtn = screen.getByLabelText(
      /decrease quantity/i
    );
    expect(decreaseBtn).toBeDisabled();
  });

  it('has correct aria attributes', () => {
    render(<CartDrawer {...defaultProps} />);
    const dialog = screen.getByRole('dialog');
    expect(dialog).toHaveAttribute('aria-modal', 'true');
    expect(dialog).toHaveAttribute('aria-labelledby');
  });

  it('hides checkout section when cart is empty', () => {
    render(<CartDrawer {...defaultProps} items={[]} />);
    expect(
      screen.queryByText(/checkout/i)
    ).not.toBeInTheDocument();
  });
});

Run the tests:

npm run test

Step 8 — Storybook Stories

Document every state so buyers (and teammates) can explore without running the app:

// src/components/CartDrawer/CartDrawer.stories.tsx

import type { Meta, StoryObj } from '@storybook/react';
import { CartDrawer } from './CartDrawer';

const meta: Meta<typeof CartDrawer> = {
  title: 'Components/CartDrawer',
  component: CartDrawer,
  parameters: { layout: 'fullscreen' },
};

export default meta;
type Story = StoryObj<typeof CartDrawer>;

const sampleItems = [
  {
    id: '1',
    name: 'Studio Headphones',
    price: 79.99,
    image: 'https://...',
    quantity: 2,
  },
];

export const EmptyCart: Story = {
  args: {
    isOpen: true,
    items: [],
    onClose: () => {},
    onQuantityChange: () => {},
    onRemoveItem: () => {},
    onCheckout: () => {},
  },
};

export const WithItems: Story = {
  args: {
    isOpen: true,
    items: sampleItems,
    onClose: () => {},
    onQuantityChange: () => {},
    onRemoveItem: () => {},
    onCheckout: () => {},
  },
};

The Part Most Tutorials Skip

Body scroll lock. When the drawer opens, the page behind it should not scroll.

useEffect(() => {
  if (isOpen) {
    document.body.style.overflow = 'hidden';
  }
  return () => {
    document.body.style.overflow = '';
  };
}, [isOpen]);

Cleanup on unmount. Always remove event listeners:

useEffect(() => {
  document.addEventListener('keydown', handleKeyDown);
  return () => {
    document.removeEventListener('keydown', handleKeyDown);
  };
}, [handleKeyDown]);

Mobile width. On small screens the drawer should be full width:

w-full sm:w-[400px]

These three details separate a production component from a demo.

What We Built

✅ CartDrawer with slide-in animation
✅ Backdrop overlay with click-to-close
✅ Focus trap for keyboard accessibility
✅ ESC key dismiss
✅ Scrollable items, fixed header + footer
✅ Quantity stepper (disabled at min 1)
✅ Remove item with aria-label
✅ Empty state
✅ Auto subtotal
✅ Body scroll lock
✅ 10 Jest tests covering all states
✅ Storybook stories for every variant
✅ TypeScript strict throughout
✅ WCAG 2.1 AA accessible

Get the Full Source

If you want the complete Cartlify source — including ProductCard, CheckoutStepper, PageLoader, all utility hooks, 141 tests, design tokens, and Storybook docs:

🔗 Live Storybook demo → cartlify.vercel.app

🛒 Get on Gumroad ($29 one-time) → karthiksoftengg.gumroad.com/l/cartlify-react-ui-kit

Built by Karthik G S — Senior Frontend Engineer with 10+ years in React, TypeScript, and React Native. Currently building Cartlify and SaaScase as indie products.

Tags: #react #typescript #webdev #javascript #tutorial #a11y #tailwindcss #testing

Why I Built Cartlify — A Production-Ready E-commerce UI Kit for React

Karthik Gs — Sat, 06 Jun 2026 06:17:30 +0000

After 10+ years of rebuilding the same components, I finally packaged them.

The Problem

Every e-commerce project I've worked on — at Fidelity Investments, OCBC Bank, Mondi Group — started the same way.

Day 1: Build the ProductCard.
Day 2: Build the CartDrawer.
Day 3: Wire up the CheckoutStepper.
Day 4: Fix accessibility issues.
Day 5: Write tests.

And then repeat on the next project.

After doing this enough times, I realized: this is wasted time. These components don't change much between projects. The logic is always the same. The accessibility requirements are always the same. The edge cases are always the same.

So I built Cartlify — a React + TypeScript + Tailwind CSS component library specifically for e-commerce UIs.

What's Inside

🛍️ ProductCard

The component every e-commerce app needs on day one.

3 layout variants — default (vertical), horizontal, compact
Image gallery with thumbnail navigation
Wishlist toggle (filled/outline heart)
Sale / New / Out of Stock badges
Star ratings display
Skeleton loading state with animate-pulse
Automatic discount % calculation from originalPrice

<ProductCard
  product={product}
  variant="default"
  showRating={true}
  showWishlist={true}
  onAddToCart={(p) => addToCart(p)}
  onWishlistToggle={(p) => toggleWishlist(p)}
/>

🛒 CartDrawer

A slide-in cart drawer that handles everything out of the box.

Smooth slide-in from right (or left)
Focus trap — keyboard stays inside the drawer when open
ESC key dismisses the drawer
Quantity stepper with min/max controls
Empty cart state with custom icon support
Auto-calculated subtotal
Fixed header + scrollable items + fixed footer

const { isOpen, onOpen, onClose } = useDisclosure();

<CartDrawer
  isOpen={isOpen}
  onClose={onClose}
  items={cartItems}
  onQuantityChange={handleQuantityChange}
  onRemoveItem={handleRemove}
  onCheckout={handleCheckout}
/>

✅ CheckoutStepper

Multi-step progress indicator for the checkout flow.

Horizontal and vertical orientations
Animated connector lines between steps
Three step states: completed, active, pending
Click on completed steps to go back
Custom icons per step
Keyboard navigation (arrow keys)

<CheckoutStepper
  steps={[
    { id: 'cart', label: 'Cart' },
    { id: 'shipping', label: 'Shipping' },
    { id: 'payment', label: 'Payment' },
    { id: 'confirm', label: 'Confirm' },
  ]}
  currentStep={2}
  orientation="horizontal"
  onStepClick={(index) => setStep(index)}
/>

⏳ PageLoader

4 animation styles (spin, pulse, bounce, dots) with 3 position modes (inline, overlay, fullscreen).

What Else Ships With It

Beyond the 4 components, Cartlify includes:

3 utility hooks — useCart, useDisclosure, useMediaQuery
11 tree-shakeable icons — cart, heart, star, trash, chevrons, and more
40+ CSS design tokens — spacing, colors, radii, shadows
Full dark mode support out of the box
Reusable primitives — Button, Badge, IconButton used internally

Built for Real Production Use

I didn't want this to be a demo library. Every decision was made with production in mind:

Testing

141 Jest + React Testing Library tests covering interactions, accessibility, edge cases, and keyboard behavior.

PASS src/components/CartDrawer/CartDrawer.test.tsx
PASS src/components/ProductCard/ProductCard.test.tsx
PASS src/components/CheckoutStepper/CheckoutStepper.test.tsx
Test Suites: 12 passed
Tests: 141 passed

Accessibility

Every component is WCAG 2.1 AA compliant:

aria-modal, role="dialog" on CartDrawer
aria-current="step" on active stepper step
role="article" on ProductCard
All icon buttons have aria-label
Full keyboard navigation

TypeScript

Strict mode, zero any. Every prop is typed, every event handler is typed.

interface ProductCardProps {
  product: Product;
  variant?: 'default' | 'horizontal' | 'compact';
  showRating?: boolean;
  isWishlisted?: boolean;
  onAddToCart: (product: Product) => void;
  onWishlistToggle?: (product: Product) => void;
}

Bundler Compatibility

Works with Vite, Next.js, Remix — any modern bundler. Ships as ESM + CJS with .d.ts types via tsup.

Tech Stack

Layer	Choice
Framework	React 18
Language	TypeScript (strict)
Styling	Tailwind CSS v3
Documentation	Storybook v7
Testing	Jest + React Testing Library
Build	tsup
Linting	ESLint + Prettier

Folder Structure

src/
├── components/
│   ├── ProductCard/
│   ├── CartDrawer/
│   ├── CheckoutStepper/
│   └── PageLoader/
├── primitives/
│   ├── Button/
│   ├── Badge/
│   └── IconButton/
├── hooks/
│   ├── useCart.ts
│   ├── useDisclosure.ts
│   └── useMediaQuery.ts
├── icons/
├── tokens/
└── types/

Clean path aliases so no ../../ imports anywhere:

import { Button } from '@primitives/Button';
import { useCart } from '@hooks/useCart';
import type { Product } from '@types';

Storybook Documentation

Every component has full interactive Storybook stories covering all variants, states, and edge cases. You can explore the live Storybook before buying.

Live demo → https://cartlify.vercel.app/

Get It

Cartlify is available on Gumroad for $29 — one-time payment, single-site license.

🛒 Gumroad → https://karthiksoftengg.gumroad.com/l/cartlify-react-ui-kit

What's Next

Planning to add:

ProductGrid with filter sidebar
SearchBar with suggestions
ReviewCard + RatingInput
WishlistDrawer
More design token themes

If there's a component you'd love to see, drop it in the comments — I'll prioritize based on demand.

Built by Karthik G S — Senior Frontend Engineer with 10+ years experience in React, TypeScript and React Native.

Tags: react typescript tailwindcss storybook webdev javascript frontend ecommerce opensource