@morev/v-bem-transformer
v1.2.5
Published
Intuitive and performant BEM in Vue files via directive syntax
Downloads
74
Readme
@morev/v-bem-transformer
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).
Table of contents
- What's the point, what does it do?
- Installation
- Usage
- Usage with Nuxt
- Configuration
- How does it work
- Recipes
- Known limitations
What's the point, what does it do?
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.
Installation
[!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.
Using yarn
yarn add @morev/v-bem-transformer
Using npm
npm install @morev/v-bem-transformer
Using pnpm
pnpm add @morev/v-bem-transformer
Using bun
bun add @morev/v-bem-transformer
Usage
[!Note] You may skip this section if you are going to use the module with Nuxt.
Go to "Usage with Nuxt" section.
Step 1: Bundler plugin
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
.
Step 2: Vue plugin
[!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');
Step 3: Types for b()
method (if needed)
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.
Step 4: Composable (if needed)
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.
Usage with Nuxt
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.
Configuration
All methods have built-in documentation via TS, source types are available here.
How does it work
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>
Why not just use directives?
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).
Recipes
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>
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>
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.
Known limitations
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
.
<script lang="ts" setup>
defineOptions({ name: 'the-block' });
const $b = useBem();
const render = () => (
<div class={$b()}>
<div class={$b('inner-element')}></div>
</div>
);
</script>
<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>