nuxt-colors v1.0.11

Nuxt Colors

A simple module for managing a dynamic color scheme through CSS root variables made dynamic through app.config.ts.

Features

• 🎨 Start with Tailwind colors
• 🖍️ Extend w/ your own colors
• ⚙ Define custom CSS variables
• ✨ Auto-magic updates driven through app.config

Quick Setup

1. Add nuxt-colors dependency to your project

# Using pnpm
pnpm add -D nuxt-colors

# Using yarn
yarn add --dev nuxt-colors

# Using npm
npm install --save-dev nuxt-colors

2. Add nuxt-colors to the modules section of nuxt.config.ts

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

3. Configure nuxt-colors in the colors section of app.config.ts

export default defineAppConfig({
  // use the `root` configuration to define any additional CSS vars you would like to control
  root: {
    "--example-max-width": "400px",
  },
  colors: {
    // apply a specific prefix to your root vars i.e. `--my-prefix-emerald-400`
    // defaults to `color`
    prefix: "my-prefix",
    // configure color variants w/ default schemes applied
    scheme: {
      primary: "emerald",
      secondary: "cyan",
      content: "wakiwa",
      contrast: "slate",
    },
    // infinitely extend available schemes
    extend: {
      wakiwa: {
        50: "#f2f7fb",
        100: "#e7f0f8",
        200: "#d3e2f2",
        300: "#b9cfe8",
        400: "#9cb6dd",
        500: "#839dd1",
        600: "#6a7fc1",
        700: "#6374ae",
        800: "#4a5989",
        900: "#414e6e",
        950: "#262c40",
      },
    },
  },
});

That's it! You can now use Nuxt Colors in your Nuxt app ✨

Usage

nuxt-colors ships with some utility functions that can enable interactivity w/ CSS variables and the active color scheme:

// interact w/ root variables
const { root, keys, setRoot } = useRootVariables();
console.log(root); // { '--example-var': '10px '}
console.log(keys); // [ '--example-var' ]
setRootKey("--example-var", "20px");

// interact w/ color variables
const { prefix, scheme, keys, options, setScheme } = useColorVariables();
console.log(prefix); // 'vc'
console.log(scheme); // { 'primary': 'emerald' }
console.log(keys); // [ 'primary' ]
console.log(options); // [ 'red', 'blue', 'emerald' ]
setScheme("primary", "blue");

The root variables are driven by the app.config.ts file, which means they can be accesed using the built-in Nuxt composable:

const { root, colors } = useAppConfig();
root["--example-max-width"] = "500px";
colors.scheme.primary = "rose";
colors.scheme.background = "stone";

It is recommended to use the built-in utilities to take advantage of strong type enforcement rather than modifying app.config directly.

Compatibility

nuxt-colors should be compatible w/ any UI component library or module. It can add new custom variables for internal usage or overwrite variables provided by a separate package as the plugin uses the append strategy to be loaded after other plugins.

You can explicitly overwrite variables used by other packages by definiting them in your root object:

export default defineAppConfig({
  root: {
    "--any-externally-defined-css-var": "var(--color-primary-500)",
  },
  colors: {
    scheme: {
      primary: "rose",
    },
  },
});

The variables can always be referenced as you would any other CSS var and are available globally throughout the application:

/* CSS 3 */
button {
  background-color: var(--color-primary-500);
}

<!-- Tailwind -->
<template>
  <div class="min-h-screen min-w-screen bg-[var(--color-primary-500)]" />
</template>

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm run dev:prepare

# Develop with the playground
pnpm run dev

# Build the playground
pnpm run dev:build

# Run ESLint
pnpm run lint

# Run Vitest
pnpm run test
pnpm run test:watch

# Release new version
pnpm run release

Todo

• Consider an option to use cookies to save changes & re-apply on refresh
• A site to upload & share color configs that can be easily imported into projects