@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
• Automatic integration with Nuxt routing
• supports Nuxt 4

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.

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.

Also, the onyx locales will automatically be registered depending on which locales you are using / defining in your project.

WARNING

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

Setup

In order for the onyx module to detect which locales to register, you must define your locales either by defining the code as IETF's BCP47 name (e.g. en-US, de-DE etc.) or by providing the language property. So any of the following configs will work correctly:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@sit-onyx/nuxt", "@nuxtjs/i18n"],
  i18n: {
    defaultLocale: "en-US",
    locales: [
      { code: "en-US", file: "en-US.json", name: "English" },
      // in the "de" example, the langauge property is necessary because the "de" code is not a valid IETF's BCP47 code
      // alternatively, you could remove the language property and change to code to "de-DE"
      { code: "de", language: "de-DE", file: "de-DE.json", name: "Deutsch" },
    ],
  },
});

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":

i18n/locales/en-US.json

{
  "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:

i18n/locales/customLang.ts

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.