@aumnidigital/bms

Runtime MDX renderer with built-in shadcn/ui components for React applications. Perfect for blogs, CMS, and content-heavy applications.

Features

• 🎨 50+ shadcn/ui components - Pre-configured and ready to use in MDX
• ⚡ Runtime MDX compilation - No build step required for content
• 🎯 TypeScript support - Full type safety
• 🌗 Dark mode ready - Works with any Tailwind + shadcn setup
• 📦 Tree-shakeable - Only bundle what you use
• 🔧 Customizable - Override default components
• 🚀 Zero CSS bundle - Uses your Tailwind configuration

Installation

npm install @aumnidigital/bms @mdx-js/mdx remark-gfm

Or with pnpm:

pnpm add @aumnidigital/bms @mdx-js/mdx remark-gfm

Peer Dependencies

This package requires:

• react ^18.0.0 || ^19.0.0
• react-dom ^18.0.0 || ^19.0.0
• @mdx-js/mdx ^3.0.0
• remark-gfm ^4.0.0 (for GitHub Flavored Markdown support - tables, strikethrough, task lists, etc.)

Quick Start

import { MDXRenderer } from '@aumnidigital/bms';

function BlogPost({ content }) {
  return (
    <article>
      <MDXRenderer content={content} />
    </article>
  );
}

Example MDX Content

# My Blog Post

This is a paragraph with **bold** and *italic* text.

<Alert>
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>
    This is an important notice.
  </AlertDescription>
</Alert>

## Features

<Card>
  <CardHeader>
    <CardTitle>Amazing Feature</CardTitle>
    <CardDescription>Check this out</CardDescription>
  </CardHeader>
  <CardContent>
    <p>Some content here</p>
  </CardContent>
</Card>

<CTASection
  title="Ready to get started?"
  description="Contact us today"
  primaryAction={{ label: "Get Started", href: "/signup" }}
  secondaryAction={{ label: "Learn More", href: "/about" }}
/>

| Feature | Supported |
|---------|-----------|
| MDX     | ✅        |
| Tables  | ✅        |

Setup Requirements

1. Tailwind CSS Configuration

For Tailwind v4 (Recommended)

Import the package's styles.css in your main CSS file. This enables Tailwind to scan the package's classes:

@import "tailwindcss";
@import "@aumnidigital/bms/styles.css";

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    /* ... rest of CSS variables ... */
  }
}

For Tailwind v3 (with tailwind.config.js)

Add the package to your Tailwind content array:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@aumnidigital/bms/dist/**/*.{js,cjs}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

2. CSS Variables

Add these CSS variables to your global stylesheet (required for shadcn components):

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;
    --secondary: 217.2 32.6% 17.5%;
    --secondary-foreground: 210 40% 98%;
    --muted: 217.2 32.6% 17.5%;
    --muted-foreground: 215 20.2% 65.1%;
    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;
    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 210 40% 98%;
    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
    --ring: 212.7 26.8% 83.9%;
  }
}

API Reference

MDXRenderer

interface MDXRendererProps {
  /** Raw MDX content string */
  content: string;
  /** Custom components to override defaults */
  components?: Record<string, React.ComponentType<any>>;
  /** Variables/data to pass into MDX scope */
  scope?: Record<string, unknown>;
  /** MDX compile options */
  options?: Omit<CompileOptions, "outputFormat">;
  /** Loading fallback component */
  fallback?: ReactNode;
  /** Error callback */
  onError?: (error: Error) => void;
}

Custom Components

Override default components or add your own:

import { MDXRenderer } from '@aumnidigital/bms';
import { MyCustomComponent } from './components/MyCustomComponent';

function BlogPost({ content }) {
  return (
    <MDXRenderer
      content={content}
      components={{
        // Override default button
        Button: (props) => <button className="my-custom-btn" {...props} />,

        // Add custom component
        MyCustomComponent,
      }}
    />
  );
}

Pass Variables to MDX

<MDXRenderer
  content={content}
  scope={{
    authorName: "John Doe",
    publishDate: "2024-01-15",
  }}
/>

Then in MDX:

Written by {authorName} on {publishDate}

Available Components

UI Components (shadcn/ui)

All standard shadcn/ui components are included:

• Buttons: Button
• Cards: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter
• Alerts: Alert, AlertTitle, AlertDescription, AlertDialog
• Forms: Input, Textarea, Label, Checkbox, Select, RadioGroup, Switch, Form
• Layout: Separator, Tabs, Accordion, Collapsible, ScrollArea, Sheet, Dialog
• Navigation: Breadcrumb, DropdownMenu
• Data Display: Table, Badge, Avatar, Progress, Skeleton
• Overlays: Tooltip, Popover, HoverCard
• Media: AspectRatio, Calendar

Custom Components

CTAButtonGroup

<CTAButtonGroup
  buttons={[
    { label: "Get Started", href: "/signup", variant: "default" },
    { label: "Learn More", href: "/docs", variant: "outline" }
  ]}
/>

CTASection

<CTASection
  title="Ready to get started?"
  description="Join thousands of users today"
  variant="highlight"
  primaryAction={{ label: "Sign Up", href: "/signup" }}
  secondaryAction={{ label: "Learn More", href: "/about" }}
/>

Variants: default, highlight, minimal

Enhanced HTML Elements

The renderer automatically styles standard HTML elements:

• Headings (h1 - h6)
• Paragraphs (p)
• Lists (ul, ol, li)
• Links (a)
• Code blocks (pre, code)
• Blockquotes (blockquote)
• Tables (table, tr, th, td)
• Horizontal rules (hr)

Advanced Usage

Loading State

<MDXRenderer
  content={content}
  fallback={<div>Loading content...</div>}
/>

Error Handling

<MDXRenderer
  content={content}
  onError={(error) => {
    console.error('MDX compilation failed:', error);
    // Send to error tracking service
  }}
/>

Custom Remark/Rehype Plugins

import remarkGfm from 'remark-gfm';
import rehypeHighlight from 'rehype-highlight';

<MDXRenderer
  content={content}
  options={{
    remarkPlugins: [remarkGfm],
    rehypePlugins: [rehypeHighlight],
  }}
/>

TypeScript Support

Full TypeScript support with exported types:

import type {
  MDXRendererProps,
  MDXComponents,
  MDXScope
} from '@aumnidigital/bms';

Publishing to npm

This package is published to npm under the @aumnidigital scope.

Manual Publishing

# Build the package
cd packages/bms
pnpm build

# Test the build
npm publish --dry-run

# Publish
npm publish --access public

Automated Publishing

Push a git tag to trigger automated publishing:

git tag @aumnidigital/[email protected]
git push --tags

Requirements

• Node.js: >=18.0.0
• React: ^18.0.0 || ^19.0.0
• Tailwind CSS: v3+ or v4+
• @mdx-js/mdx: ^3.0.0

License

MIT

Contributing

Contributions are welcome! This package is part of a Turborepo monorepo.

Support

For issues and questions, please open an issue on GitHub.