npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

mdx-blog-ui

v0.1.0

Published

Copy-paste blog UI templates for Next.js + mdx-blog-core, installed via CLI.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

theanupambistatheanupambista

Keywords

mdxblognextjsreact

Readme

mdx-blog-ui

Copy-paste blog UI for Next.js (App Router) apps that use mdx-blog-core for data and types.

This package ships a small CLI that copies TypeScript/React source files into your repository (similar to the outcome of shadcn/ui, but without a hosted shadcn registry). After running add, you own the code and can change styles, props, and behaviour freely.

What you get

  • Post list, card, URL-based search (?q=), keyboard prev/next, share menu, inline TOC (collapsible).
  • Imports mdx-blog-core for Post, useFilteredPosts, TOCItemType, etc.
  • Imports your UI primitives at paths aligned with components.json (shadcn-style aliases).

This package does not load MDX or read the filesystem. Use mdx-blog-core (createBlogSource, etc.) for that.

Requirements

  • Node.js 20+
  • Next.js 14+ (App Router), React 18+
  • Tailwind CSS (templates use utility classes)
  • mdx-blog-core installed in the same app
  • components.json (recommended) so the CLI can rewrite @/lib/utils, @/components/ui/..., and @/hooks/... to match your aliases

Install

npm install mdx-blog-ui mdx-blog-core
# or
pnpm add mdx-blog-ui mdx-blog-core
# or
yarn add mdx-blog-ui mdx-blog-core

Peer dependencies (mdx-blog-ui)

These are declared on the package; your app should satisfy them:

| Package | Range | Notes | | ----------------- | ------- | ------------------------------------------ | | mdx-blog-core | ≥0.1.0 | Types, useFilteredPosts, TOC types | | next | ≥14 | Image, Link, useRouter where used | | react | ≥18 | | | react-dom | ≥18 | |

Additional dependencies (per feature)

The CLI prints hints after each add. Typical installs:

| You use | Also install (examples) | | ------------------------------- | ------------------------------------------------------------ | | post-item | date-fns | | use-search-query, search list | nuqs | | post-search-input | nuqs, lucide-react, react-hotkeys-hook | | post-keyboard-shortcuts | react-hotkeys-hook | | post-share-menu | lucide-react, sonner | | inline-toc | lucide-react |

Add the shadcn/ui (or compatible) primitives the templates import:

  • Button, Input — post-search-input
  • Button, DropdownMenu — post-share-menu
  • Collapsible — inline-toc

nuqs in the App Router

Search components use useQueryState from nuqs. Wrap your app (or the blog layout) with the Next.js adapter, for example:

import { NuqsAdapter } from "nuqs/adapters/next/app"

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

See the nuqs Next.js docs for details.

CLI

Run from your Next.js project root (where components.json and package.json live).

npx mdx-blog-ui list
npx mdx-blog-ui add <component> [--dir <path>] [--cwd <path>]

| Command | Description | | ------- | ----------- | | list | Print all component ids you can add. | | add | Copy the component and its dependencies into your tree. |

| Option | Description | | ------- | ----------- | | --dir | Output directory relative to cwd (default: components/mdx-blog). | | --cwd | Project root (default: current working directory). |

Examples

npx mdx-blog-ui add post-list-with-search
npx mdx-blog-ui add post-search-input --dir src/components/mdx-blog
npx mdx-blog-ui add inline-toc --dir src/components/blog --cwd .

Import path rewriting

If components.json exists and defines aliases (e.g. utils, ui, hooks), the CLI rewrites:

  • @/lib/utils → your aliases.utils
  • @/components/ui/... → under your aliases.ui
  • @/hooks/... → under your aliases.hooks

If the file is missing, defaults match a typical shadcn layout (@/components, @/lib/utils, @/components/ui, @/hooks).

Available components

| Id | Purpose | | -- | ------- | | post-item | Post card: image, title, date, optional “new” dot. Props include basePath (default "/blog") for post links. | | post-list | Two-column grid + empty state; passes basePath to each item. | | use-search-query | Hook: nuqs state for the q search param. | | post-list-with-search | Client list filtered with useFilteredPosts from mdx-blog-core/react. | | post-search-input | Search field + clear; optional onQueryChange (debounced) for analytics. | | post-keyboard-shortcuts | Left/Right arrow prev/next using next/navigation. | | post-share-menu | Copy link, X / LinkedIn intents, Web Share API when available; sonner toasts. | | inline-toc | Collapsible on-page TOC from TOCItemType[] (from mdx-blog-core / getTableOfContents). |

Transitive files are included automatically (e.g. add post-list-with-search also copies post-list, post-item, and hooks/use-search-query.ts).

Integration sketch

  1. Install mdx-blog-core, mdx-blog-ui, and peers (see above).
  2. Add shadcn button, input, dropdown-menu, collapsible if you do not have them.
  3. Ensure NuqsAdapter wraps routes that use search.
  4. Run npx mdx-blog-ui add … into e.g. src/components/mdx-blog.
  5. In a Server Component, load posts with createBlogSource from mdx-blog-core/node and pass them into client components as needed.
  6. Style and tweak the copied files to match your site.

Monorepo (this workspace)

{
  "devDependencies": {
    "mdx-blog-ui": "workspace:*"
  }
}

Template sources live in packages/mdx-blog-ui/templates/. To refresh a consumer app after editing templates, run add again with the same --dir or merge manually.

Publishing to npm (maintainers)

  1. Ensure package.json "files" includes everything needed on the registry:

    • bin/, templates/, manifest.json

  2. Version with semver, then publish:

    npm publish --access public

  3. Publishing requires npm 2FA or a token allowed to publish (see npm’s docs if you see 403 on PUT).

License

MIT