tnc-utils

Package frontend cho React / Next.js: utils (xử lý data), helpers (tương tác browser), hooks, và providers (React Query, Devtools, Toast).

• TypeScript strict
• ESM
• SSR-safe cho storage / cookie / hooks
• Mỗi hàm một file, nhóm rõ theo thư mục

Cài đặt

bun add tnc-utils

# peers khi dùng hooks / providers
bun add react @tanstack/react-query @tanstack/react-query-devtools sonner

| Peer | Khi nào cần | |------|-------------| | react | hooks, providers | | @tanstack/react-query | providers | | @tanstack/react-query-devtools | React Query Devtools | | sonner | Toast |

Entry points

| Import | Nội dung | |--------|----------| | tnc-utils | utils + helpers | | tnc-utils/utils | xử lý data thuần | | tnc-utils/helpers | localStorage, cookie | | tnc-utils/hooks | React hooks ("use client") | | tnc-utils/providers | AppProviders, Query, Toast | | tnc-utils/react | alias → hooks |

import { cn, parseCurrency } from "tnc-utils/utils";
import { storage, cookies } from "tnc-utils/helpers";
import { useDebounce, useLocalStorage } from "tnc-utils/hooks";
import { AppProviders, toast, useQuery } from "tnc-utils/providers";

Utils — tnc-utils/utils

cn

Merge class names (clsx + tailwind-merge):

cn("px-2 py-1", isActive && "bg-black", "p-4"); // → "bg-black p-4"

String

| Hàm | Mô tả | |-----|--------| | capitalize | Viết hoa chữ cái đầu | | slugify | Chuỗi URL-safe (bỏ dấu tiếng Việt) | | truncate | Cắt chuỗi + omission | | isBlank | null / undefined / chỉ whitespace |

Number

| Hàm | Mô tả | |-----|--------| | clamp | Giới hạn trong [min, max] | | roundTo | Làm tròn theo số chữ số thập phân | | inRange | Kiểm tra nằm trong khoảng |

Array

| Hàm | Mô tả | |-----|--------| | unique | Loại phần tử trùng | | chunk | Chia mảng theo size | | groupBy | Nhóm theo key | | compact | Bỏ falsy (0, "", false, null, …) |

Object

| Hàm | Mô tả | |-----|--------| | pick | Lấy subset keys | | omit | Bỏ keys | | isPlainObject | Plain object? |

Async

| Hàm | Mô tả | |-----|--------| | sleep | Delay Promise | | debounce | Debounce (+ cancel / flush) | | throttle | Throttle | | retry | Retry với backoff |

Format

| Hàm | Mô tả | |-----|--------| | formatNumber | Intl.NumberFormat | | formatCurrency | Số → chuỗi tiền | | parseCurrency | Chuỗi tiền → số (ngược formatCurrency) | | formatPercent | Phần trăm | | formatDate | Ngày giờ | | formatBytes | Bytes → KB/MB/… |

formatCurrency(1_500_000, "vi-VN", "VND");
parseCurrency("1.500.000 ₫", "vi-VN", "VND"); // 1500000

URL

| Hàm | Mô tả | |-----|--------| | toQueryString | Object → query string | | parseQueryString | Query string → object | | withQuery | Gắn query vào URL (giữ hash) |

Type guards

| Hàm | Mô tả | |-----|--------| | isNil | null | undefined | | isEmpty | Empty string/array/object/Map/Set | | assertNever | Exhaustiveness check |

Helpers — tnc-utils/helpers

Tương tác browser, SSR-safe (no-op khi không có document / localStorage).

Storage (localStorage)

import { storage } from "tnc-utils/helpers";

storage.set("theme", "dark");
storage.get<string>("theme"); // "dark"
storage.has("theme");         // true
storage.remove("theme");

Cũng export: storageGet, storageSet, storageRemove, storageHas, getLocalStorage.

Cookie

import { cookies } from "tnc-utils/helpers";

cookies.set("theme", "dark", {
  maxAge: 60 * 60 * 24 * 30,
  path: "/",
  sameSite: "Lax",
});
cookies.get("theme");
cookies.has("theme");
cookies.remove("theme");

Cookie attributes: path, domain, maxAge, expires (Date hoặc số ngày), secure, sameSite.

Cũng export: cookieGet, cookieSet, cookieRemove, cookieHas, parseCookies, canUseCookies.

Hooks — tnc-utils/hooks

Tất cả là client components ("use client").

| Hook | Mô tả | |------|--------| | useIsClient | true sau khi mount (tránh hydration mismatch) | | usePrevious | Giá trị trước đó | | useToggle | Boolean toggle | | useDebounce | Debounce value | | useDebouncedCallback | Debounce callback (tự cancel khi unmount) | | useLocalStorage | State đồng bộ localStorage | | useCookie | State đồng bộ cookie | | useMediaQuery | Subscribe CSS media query | | useEventListener | Event listener + cleanup | | useClickOutside | Click ngoài element | | useCopyToClipboard | Copy text (Clipboard API) |

import { useDebounce, useLocalStorage, useCookie } from "tnc-utils/hooks";

const debounced = useDebounce(query, 300);
const [theme, setTheme, removeTheme] = useLocalStorage("theme", "light");
const [locale, setLocale] = useCookie("locale", "vi", { maxAge: 60 * 60 * 24 * 365 });

Providers — tnc-utils/providers

Gồm TanStack Query, React Query Devtools, và Sonner toast.

Setup Next.js App Router

// app/providers.tsx
"use client";

import { AppProviders } from "tnc-utils/providers";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AppProviders toasterProps={{ position: "top-right" }}>
      {children}
    </AppProviders>
  );
}

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="vi">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Toast

import { toast } from "tnc-utils/providers";

toast.success("Đã lưu");
toast.error("Có lỗi xảy ra");
toast.message("Hello");

React Query

import { useQuery, createQueryClient } from "tnc-utils/providers";

const { data, isPending } = useQuery({
  queryKey: ["users"],
  queryFn: () => fetch("/api/users").then((r) => r.json()),
});

createQueryClient() mặc định:

• staleTime: 60s
• gcTime: 5 phút
• retry: 1 (queries), 0 (mutations)
• refetchOnWindowFocus: false

Devtools

• React Query Devtools: bật mặc định khi non-production (withDevtools). Tắt bằng withDevtools={false}.
• React Developer Tools (Chrome/Firefox extension): cài trên browser, không cấu hình trong code.

Exports chính

| Export | Mô tả | |--------|--------| | AppProviders | Query + Devtools + Toast | | QueryProvider | Chỉ React Query (+ Devtools) | | ToastProvider | Chỉ Sonner <Toaster /> | | createQueryClient | Factory QueryClient | | toast | API Sonner | | useQuery, useMutation, useQueryClient, … | Re-export từ TanStack Query |

Cấu trúc source

src/
  utils/       cn, string, number, array, object, async, format, url, type
  helpers/     storage, cookie
  hooks/       use*
  providers/   AppProviders, QueryProvider, ToastProvider, createQueryClient, toast
  index.ts     re-export utils + helpers

Scripts

bun install
bun test
bun run typecheck
bun run build

License

MIT