@oluwafemiakinsiku/acme-ui

A small React component library built with tsdown (JS + types) and Tailwind CSS v4 (styles), usable in Next.js and installable by anyone.

npm install @oluwafemiakinsiku/acme-ui

What's in the box

src/
  index.ts            # public entry — the barrel of exports
  theme.css           # Tailwind entry that compiles to dist/style.css (no global reset)
  tokens.css          # brand design tokens (@theme) shared by lib + playground
  lib/cn.ts           # className merge helper (clsx + tailwind-merge)
  components/
    Button.tsx        # cva variants + sizes, forwardRef
    Badge.tsx         # cva tones
    Card.tsx          # compound component (Card / CardTitle / CardBody)
playground/           # dev-only app to SEE components (never published)
tsdown.config.ts      # JS/types build config
postcss.config.mjs    # Tailwind plugin (used by the Vite playground)

Develop (see what you're doing)

npm run dev      # starts the Vite playground at http://localhost:5173

Edit anything under src/ and it hot-reloads instantly. The playground imports from ../src — the exact public API consumers get.

Build (what gets published)

npm run build    # tsdown builds dist/*.js + *.d.ts, then Tailwind builds dist/style.css
npm run lint:pkg # publint + attw: verify the package is publish-ready

Why two tools? A bundler pre-resolves CSS @imports in a way that breaks Tailwind's source scanning, so JS is built by tsdown and CSS by the Tailwind CLI. The library ships utilities without Tailwind's Preflight reset, so it never clobbers the host app's base styles.

Output in dist/:

| file | what it is | | -------------- | ------------------------------ | | index.js | ESM bundle | | index.cjs | CommonJS bundle | | index.d.ts | types for ESM | | index.d.cts | types for CJS | | style.css | compiled Tailwind (import once)|

Publish to npm

# 1. Log in (once per machine)
npm login

# 2. Bump the version (semver) — you can NEVER republish an existing version
npm version patch      # e.g. 0.1.1 -> 0.1.2

# 3. Build + validate, then publish
npm run build
npm run lint:pkg
npm publish            # access:public is already set in package.json publishConfig

package.json "files": ["dist"] means only dist/ is shipped — run npm pack --dry-run to preview the tarball before publishing.

Install and use in another app (e.g. Next.js)

npm install @oluwafemiakinsiku/acme-ui react react-dom

// app/layout.tsx  (Next.js App Router) — import the CSS ONCE, globally
import '@oluwafemiakinsiku/acme-ui/style.css'

// any component
import { Button, Card, CardTitle, CardBody, Badge } from '@oluwafemiakinsiku/acme-ui'

export default function Page() {
  return (
    <Card>
      <CardTitle>Hello</CardTitle>
      <CardBody>Rendered from acme-ui.</CardBody>
      <Badge tone="success">installed</Badge>
      <Button variant="primary">Click me</Button>
    </Card>
  )
}

The consumer does not need Tailwind installed — the styles are prebuilt in @oluwafemiakinsiku/acme-ui/style.css. If the consumer does use Tailwind, our brand-* colors won't collide because they live in our shipped CSS.