diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index b6ac525..678c2d0 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -191,8 +191,8 @@ export default withPwa(defineConfig({ text: 'Date Support', link: '/guide/date', }, { - text: 'SASS Modern Compiler', - link: '/guide/sass-modern-compiler', + text: 'SASS Customization', + link: '/guide/sass-customization', }, { text: 'FAQ', link: '/guide/faq', diff --git a/docs/guide/sass-customization.md b/docs/guide/sass-customization.md new file mode 100644 index 0000000..acf19a8 --- /dev/null +++ b/docs/guide/sass-customization.md @@ -0,0 +1,70 @@ +# SASS Customization + +From version `0.17.0`, this module will configure Nuxt to use the new SASS modern compiler (`modern-compiler`). You don't need to change anything in your configuration to use it: +- update `vite` version to `v5.4.0` or higher (if you're using Nuxt `3.12.4` or higher, you don't need to update `vite`) +- replace your `sass` dependency with `sass-embedded` + +If the `sass-embedded` dependency is not installed, the module will configure the `modern` compiler for you. In case you get errors, enable the `disableModernSassCompiler` option in the module configuration to fall back to the `legacy` compiler. + +Check [Build Performance](https://vuetifyjs.com/en/features/sass-variables/#build-performance) in Vuetify docs for more details. + +## Overriding SASS Variables + +Vuetify allows for [overriding global and component-level SASS variables](https://vuetifyjs.com/en/features/sass-variables/). Setting these up requires configuration that is slightly different from the Vuetify +documentation while using this Nuxt module. + +1) In your styles directory (for this example, we'll use `${srcDir}/assets/css`), create two files - `${srcDir}/assets/css/globals.scss` and `${srcDir}/assets/css/components.scss` + +2) In the `globals.scss` file, we'll want to add +```scss +@use 'vuetify' with ( + // Global Vuetify SASS variable overrides. For example: + // $utilities: false, + // $reset: false, + // $color-pack: false, + // $body-font-family: sans-serif +) +``` + +3) In the `components.scss` file, we'll want to add +```scss +// $button-text-transform-override: capitalize; + +@forward 'vuetify/settings' with ( + // Component Vuetify SASS variable overrides. See https://vuetifyjs.com/en/features/sass-variables/#variable-api + + // For example -- overriding button font capitalization (as seen at the bottom of the v-btn guide here https://vuetifyjs.com/en/api/v-btn/): + // $button-text-transform: $button-text-transform-override, +); +``` + +4) In your `nuxt.config.ts`, add a `css` entry to the `defineNuxtConfig` configuration object that points to `globals.scss` like so: +```javascript +export default defineNuxtConfig({ + css: ['@/assets/css/globals.scss'] + // other options +}) +``` + +> [!TIP] +> The [css](https://nuxt.com/docs/getting-started/styling#the-css-property) property within your `defineNuxtConfig` will import all styles from the file that you specify (in our case, `globals.scss`) into all components for convenience. Any styles appended to the `globals.scss` file in addition to the Vuetify Global Variables override will also be imported into all of your components. If you would like more fine-grained control, consider using a different file for your non-Vuetify global styles, like a separate `main.scss` that you import on a component-by-component basis. + +5) Again in your `nuxt.config.ts`, under the Vuetify module options, disable the Vuetify Styles import for components and instead import the `components.scss` override file: +```javascript +export default defineNuxtConfig({ + css: ['@/assets/css/globals.scss'], + vuetify: { + moduleOptions: { + /* module specific options */ + /* https://www.youtube.com/watch?v=aamWg1TuC3o */ + disableVuetifyStyles: true, + styles: { + configFile: '@/assets/css/components.scss' + }, + }, + } + // other options +}) +``` + +You should now be able to override your [global Vuetify SASS variables](https://github.com/vuetifyjs/vuetify/blob/master/packages/vuetify/src/styles/settings/_variables.scss) as well as your [component-level Vuetify SASS variables](https://vuetifyjs.com/en/features/sass-variables/#variable-api). For a full list of variables, check out [all of the imports in the index](https://github.com/vuetifyjs/vuetify/blob/master/packages/vuetify/src/styles/settings/_index.sass). diff --git a/docs/guide/sass-modern-compiler.md b/docs/guide/sass-modern-compiler.md deleted file mode 100644 index a1191a7..0000000 --- a/docs/guide/sass-modern-compiler.md +++ /dev/null @@ -1,9 +0,0 @@ -# SASS Modern Compiler - -From version `0.17.0`, this module will configure Nuxt to use the new SASS modern compiler (`modern-compiler`). You don't need to change anything in your configuration to use it: -- update `vite` version to `v5.4.0` or higher (if you're using Nuxt `3.12.4` or higher, you don't need to update `vite`) -- replace your `sass` dependency with `sass-embedded` - -If the `sass-embedded` dependency is not installed, the module will configure the `modern` compiler for you. In case you get errors, enable the `disableModernSassCompiler` option in the module configuration to fall back to the `legacy` compiler. - -Check [Build Performance](https://vuetifyjs.com/en/features/sass-variables/#build-performance) in Vuetify docs for more details. diff --git a/docs/guide/server-side-rendering.md b/docs/guide/server-side-rendering.md index 4dd9fa6..072aa2b 100644 --- a/docs/guide/server-side-rendering.md +++ b/docs/guide/server-side-rendering.md @@ -50,6 +50,8 @@ export default defineNuxtConfig({ }) ``` +For a more detailed example, see [Overriding SASS Variables](/guide/sass-customization.md#overriding-sass-variables). + ## Vuetify Themes If you're using multiple Vuetify Themes with SSR enabled, Vuetify [useTheme](https://vuetifyjs.com/en/api/use-theme/) will not work since there is no way to know which theme to use in the server (the server will use the default theme).