nuxt-rebar

🤘 Rock-solid generic & extensible components in Nuxt w/ the power of UnoCSS, Untheme, & Radix.

✨  Release Notes

Configuration

1. Install the module

pnpm add nuxt-rebar

2. Create a config

// ~/rebar.config.ts
import { defineRebarConfig } from "rebar";
import { useTailwindColorPack } from "untheme/kit";

const tw = useTailwindColorPack();

export default defineRebarConfig({
  // optional component prefix
  prefix: "z",

  // extend `nuxt-cereal` config
  cereal: {
    constants: {
      example: "Example",
    },
    enums: {
      alphabet: ["a", "b", "c", "d"],
    },
    options: {
      colorMode: [
        {
          key: "light",
          label: "Light Mode",
        },
        {
          key: "dark",
          label: "Dark Mode",
        },
      ],
    },
  },

  // extend `nuxt-rebar` icons
  icons: {
    example: "i-ic-twotone-home",
  },

  // extend `untheme` themes & roles
  untheme: {
    themes: {
      example: {
        ...tw.aliases("ui", {
          primary: "orange",
          secondary: "yellow",
          tertiary: "fuchsia",
          surface: "neutral",
          error: "red",
        }),
      },
    },
    roles: {
      buttonColor: "ui-primary-500",
    },
  },
});

3. Activate the module

// ~/nuxt.config.ts
import rebar from "./rebar.config";

export default defineNuxtConfig({
  modules: ["nuxt-rebar"],
  rebar,
});

4. Go listen to your favorite band, your application UI is ready to rock!

Features

nuxt-rebar installs a set of modules to your Nuxt application that we use to build a generic & extensible component library.

We also expose utilities that you can use to build your own components or extend the components that already exist.

Modules

| Module | Description | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | @unocss/nuxt | unocss provides Tailwind-like utility classes & provides the basis for the design system. | | nuxt-untheme | A tokenized theme manager that is converted into utility classes to implement dynamic themes. | | nuxt-cereal | Cereal-ize JSON into literally-typed constants, enums, & options for building type-safe components. | | @vueuse/nuxt | A bunch of extremely helpful Vue utils. |

Icons

Icon classes are handled by unocss and nuxt-rebar can create aliases for these icons to help improve DX. These aliases are converted to a literally-typed alias key that can be passed around by components & eventually swapped for an icon class in either the Icon component or by using the useIcon() composable.

Icons are provided by Iconify, we currently support the following sets:

| Icon Set | Description | | --------------------------------- | ---------------------------------------------------------------------------- | | @iconify-json/ic | Material symbols w/ variants like outline, twotone, rounded, & sharp | | @iconify-json/simple-icons | A simple set of company/technology logos | | @iconify-json/circle-flag-icons | A set of circle flag icons for every country/region |

Components

Components are built using a consistent formulae that provides maximum extensibility & customization.

| Component | Props | Slots | Emits | Description | | ---------------- | ----- | ----- | ----- | ------------------------------------------------------------------------------------- | | <A /> | | | | Renders a link. | | <Accordion /> | | | | Renders a list of items that can be expanded/collapsed to display additional content. | | <Article /> | | | | Renders an article tag that styles child elements by tag. | | <Avatar /> | | | | Renders an image styled as a circular avatar. | | <Bar /> | | | | Renders an application bar w/ flexible slots & styling. | | <Blockquote /> | | | | Renders a styled blockquote element. | | <Button /> | | | | Renders a styled button w/ variants like primary, outlined, text, & tonal | | <Card /> | | | | Renders a simple styled card. | | <Code /> | | | | Renders a styled code element for displaying code w/ syntax highlighting. | | <Command /> | | | | Renders a searchable list of options for a user to select from to perform an action. | | <Dialog /> | | | | Renders a dialog window that can be triggered by a slotted component. | | <Heading /> | | | | Render a heading (h1, h2, h3, etc...) tag w/ a copy button for hash anchors. | | <Icon /> | | | | Render a given icon alias. | | <Input /> | | | | Render an input element for user-added text or numbers. | | <Kbd /> | | | | Renders a styled kbd element for displaying keyboard shortcuts. | | <Links /> | | | | Render a list of selectable links. | | <Main /> | | | | Render a styled main element that wraps a nuxt-rebar application. | | <Pane /> | | | | Render a pane w/ content slots for building web pages. | | <Popover /> | | | | Render a popup box on hover/click events. | | <Tabs /> | | | | Render a set of selectable tabs. | | <Tooltip /> | | | | Render a text tooltip on hover. |

Utilities

| Function | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | isIcon(alias) | Determine if a string is a valid icon alias. | | useIcon(alias) | Exchange an icon alias for a icon class. | | defineComponentUI(config) | Define a component UI configuration that uses tailwind-variants to provide an overwritable/extendable style object. |

Take a look at the component recipes to see how defineComponentUI can be used to create component styles.

License

MIT License © 2024-PRESENT Alexander Thorwaldson