Intuitive and performant BEM in Vue files via directive syntax 🛠
✔️ Supports Vue 2 / 3
both;
✔️ Supports Nuxt 2 / 3
both;
✔️ Provides a composable to use with Composition API;
✔️ Best BEM practices for single-file-components;
✔️ Small footprint (1kb gzipped).
- What's the point, what does it do?
- Installation
- Usage
- Usage with Nuxt
- Configuration
- How does it work
- Recipes
- Known limitations
The package helps level out one of BEM's biggest problems - its verbosity.
It also allows you to have more confidence that there are no errors in the block name,
and that nothing unnecessary has been added to the component's classes that relate to other components.
Implementation details are described in the "How does it work" section, more examples and recipes are shown in the "Recipes" section, here is just a self-explanatory code example:
Using the package, if you provide the code like that...
<template>
<div v-bem>
<div v-bem:header>
<div v-bem:title="{ size: 'large', wide: true }">
Some title
</div>
</div>
</div>
</template>
<script setup>
defineOptions({ name: 'the-block' });
</script>
...it will be rendered into the following:
<div class="the-block">
<div class="the-block__header">
<div class="
the-block__title
the-block__title--size-large
the-block__title--wide
">
Some title
</div>
</div>
</div>
You can also use variables for modifiers or elements, making it easier than ever to handle states.
[!CAUTION] Requirements:
- Node version:
>= 18.0.0
;- Nuxt version (if used):
>= 2.17.0 || >= 3.5.0
;- Any bundler is required:
vite
,esbuild
,webpack
,rollup
are supported via unplugin.The plugin will not work if you are using a Node or Nuxt version less than the specified ones.
yarn add @morev/v-bem-transformer
npm install @morev/v-bem-transformer
pnpm add @morev/v-bem-transformer
bun add @morev/v-bem-transformer
[!Note] You may skip this section if you are going to use the module with Nuxt.
Go to "Usage with Nuxt" section.
First, you need to attach the plugin to your builder (vite
is used here in the example):
[!IMPORTANT] The plugin SHOULD be the first in the chain to work correctly.
import { defineConfig } from 'vite';
import pluginVue from '@vitejs/plugin-vue';
import { vitePlugin as pluginVBem } from '@morev/v-bem-transformer';
export default defineConfig({
plugins: [
pluginVBem({
// custom options described below (and also fully typed via TS right here)
}),
pluginVue(),
],
});
The packages provides plugins for vite
, rollup
, webpack
and esbuild
.
[!NOTE] This guide illustrates how to use it with
Vue 3
.
Connecting toVue 2
follows the same algorithm, except for the specifics of installing plugins - you need to useVue.use()
instead ofapp.use()
.
import { createApp } from 'vue';
import App from './App.vue';
import { vuePlugin as pluginVBem } from '@morev/v-bem-transformer/vue';
const app = createApp(App)
app.use(pluginVBem({
// custom options described below (and also typed with TS right here)
}));
app.mount('#app');
If you are going to use the function generating BEM classes directly (quite rarely used to be honest) and you need a type inside a component,
add the following to your tsconfig.json
:
{
"compilerOptions": {
"types": [
"@morev/v-bem-transformer/types/vue-globals.d.ts"
]
}
}
[!WARNING]
vue-globals.d.ts
registers a property namedb
.
If you are going to use a different property name - you must provide the appropriate types yourself.
If you need to access BEM generator function within <script setup>
, you can create you own useBem
composable this way:
// ~/composables/use-bem.ts
import { useBemFactory } from '@morev/v-bem-transformer/use-bem-factory';
export const useBem = useBemFactory({
// custom options described below
});
[!TIP] You can find this composable template with typings here.
The package supports both Nuxt 2
and Nuxt 3
.
Nuxt 2 support without Bridge is slightly limited - the module will not automatically register the useBem
composable
(but you still can do it yourself, for example if you are using @nuxtjs/composition-api
).
Install the package, next add @morev/v-bem-transformer/nuxt
to the modules
section of your nuxt.config
:
export default defineNuxtConfig({
modules: [
'@morev/v-bem-transformer/nuxt',
],
vBemTransformer: {
// Optional configuration options described below.
}
});
// ...or using the tuple syntax:
export default defineNuxtConfig({
modules: [
['@morev/v-bem-transformer/nuxt', {
// Optional configuration options described below.
}],
],
});
Using Nuxt 3, no additional steps are required, just start using the v-bem
directive and composable useBem
within your components.
It will be fully typed by default.
All methods have built-in documentation via TS, source types are available here.
The package works in two steps:
- Registers a global mixin that provides a BEM class name generator bound to each component.
You can check it out here. - At build time, using regular expressions, replaces
v-bem
directives with class declarations (preserving existing ones, if any) that call the method added using the mixin in the previous step:
<!-- Before the transformation -->
<div v-bem>
<div v-bem:element="{ modifier: true }">
<div v-bem:inner :class="dynamicClass"></div>
</div>
</div>
<!-- After the transformation -->
<div :class="b(null)">
<div :class="b('element', { modifier: true })">
<div :class="[dynamicClass, b('inner')]"></div>
</div>
</div>
A directive is a separate entity with its own lifecycle, so using it actually for each DOM element is overkill.
If we use transformation, we just get class bindings.
Also directives require separate processing at the SSR level, which adds complexity and points of failure (especially in Vue 2).
How to use with static classnames?
There are two use cases: writing static classes via the directive modifier syntax, or using the native `class` attribute.
Input:
<template>
<div v-bem.static.another-static>
<div v-bem:element class="is-active"></div>
</div>
</template>
<script lang="ts" setup>
defineOptions({ name: 'the-block' });
</script>
Output:
<div class="the-block static another-static">
<div class="the-block__element is-active"></div>
</div>
How to use with dynamic static classnames?
As well as in the previous case, you have two options: writing via the dynamic directive modifier syntax, or using the native `class` attribute.
Input:
<template>
<div v-bem.[dynamicClassBinding]>
<div v-bem:element :class="dynamicClassBinding"></div>
</div>
</template>
<script lang="ts" setup>
defineOptions({ name: 'the-block' });
const dynamicClassBinding = ref('is-active');
</script>
Output:
<div class="the-block static another-static">
<div class="the-block__element is-active"></div>
</div>
Handling states with dynamic modifier bindings
Input:
<template>
<div v-bem>
<div v-bem:element="{ active: isActive }"></div>
<button type="button" @click="isActive = !isActive">Toggle</button>
</div>
</template>
<script lang="ts" setup>
defineOptions({ name: 'the-block' });
const isActive = ref(false);
</script>
Initial output:
<div class="the-block">
<div class="the-block__element"></div>
<button type="button">Toggle</button>
</div>
Output after click on the button:
<div class="the-block">
<div class="the-block__element the-block__element--active"></div>
<button type="button">Toggle</button>
</div>
All variables within v-bem
directive are fully reactive.
As the module manipulates the source code via a trivial regular expression, there is no support for JSX/TSX and programmatically created elements
(using Vue's h()
method for example).
You still can use useBem()
composable using Composition API and this.b()
to access bemFunction
,
but transforming as a directive will only work in Vue files that do not use a custom syntax like pug
.
How to deal with JSX/TSX using Composition API?
<script lang="ts" setup>
defineOptions({ name: 'the-block' });
const $b = useBem();
const render = () => (
<div class={$b()}>
<div class={$b('inner-element')}></div>
</div>
);
</script>
How to deal with render function using Options API?
<script lang="ts">
import { h } from 'vue';
export default {
name: 'the-block',
render() {
return h('div', { class: this.b() }, [
h('div', { class: this.b('element') }, 'Some content')
])
}
}
</script>