@sit-onyx/nuxt

A Nuxt module to easily integrate onyx into Nuxt projects.

Changelog

A full changelog can be found here.

Features

• Auto import of all onyx components
• Automatic setup of global styles
• Automatic integration with @nuxtjs/i18n

Quick Setup

Install the module in your Nuxt application with one command:

npx nuxi module add @sit-onyx/nuxt@beta

If you are also using the @nuxtjs/i18n module, make sure to move @sit-onyx/nuxt before @nuxtjs/i18n.

Afterwards you're able to just use all onyx components inside your app and the global styles will automatically be set up for you.

Themes

The module will use the "onyx" theme by default. To change the theme just specify its name inside the config option onyx.theme.

export default defineNuxtConfig({
  modules: ["@sit-onyx/nuxt"],
  onyx: {
    theme: "lidl",
  },
});

For all supported themes see: Theming

Integration with @nuxtjs/i18n

Onyx features built in translations and the nuxt module extends on that by offering an out of the box integration with @nuxtjs/i18n. If your Nuxt project uses both modules, onyx will automatically detect it and use @nuxtjs/i18n to handle all the translations. This gives you all the bells and whistles of vue-i18n like lazy loading of translations.

Setup

To merge the locales provided by onyx with your own, you need to define a mapping.

export default defineNuxtConfig({
  modules: ["@sit-onyx/nuxt", "@nuxtjs/i18n"],
  i18n: {
    defaultLocale: "en_US",
    locales: [
      { code: "en_US", file: "en-US.json", name: "English (US)" },
      { code: "de", file: "de-DE.json", name: "Deutsch" },
    ],
  },
  onyx: {
    i18n: {
      registerLocales: {
        "de-DE": "de-DE",
        en_US: "en-US",
      },
    },
  },
});

Please register @sit-onyx/nuxt before @nuxtjs/i18n. Otherwise the translations for onyx won't be picked up by @nuxtjs/i18n.

Customizing onyx translations

It might happen that a certain translation provided by onyx doesn't fit your project. As project specific translations will always overwrite the defaults from onyx, you can easily provide your own. Just define the key of the onyx translation inside your own messages scoped to the key "onyx". E.g. this example will remove the default brackets around the translation for "optional":

{
  "foo": "bar",
  "onyx": {
    "optional": "optional"
  }
}

For all available translations / keys please see: i18n

Extending onyx translations

Maybe your project requires a language not supported by onyx. In this case you may provide translations for the keys within the "onyx" scope of your messages.

In case you'd like to use the messages of an existing onyx language, you can import it into your messages and overwrite them as you wish:

import enUS from "sit-onyx/locales/en-US.json";

export default {
  foo: "bar",
  onyx: { ...enUS, optional: "Custom optional" },
};

For more examples on how to customize your projects languages with support for onyx, feel free to take a look at one of our tests: @sit-onyx/nuxt i18n test fixture

Onyx is open source, so if you're missing translations for a language feel free to contribute them so other projects can benefit from it as well.