Typed BEM

Overview

Typed BEM is an extension of the lightweight and proven easy-bem library. While easy-bem efficiently generates BEM (Block-Element-Modifier) class names, Typed BEM enhances it with TypeScript typings to create a type-safe and scalable approach for managing your CSS.

This library not only ensures correctness at compile time but also allows you to use your TypeScript definitions to drive your SCSS architecture, making it a robust solution for creating and maintaining large-scale BEM-based design systems.

Key Features

• Built on Easy-BEM: Combines the simplicity of easy-bem with the power of TypeScript.
• Type Safety: Guarantees correct usage of blocks, elements, and modifiers at compile time.
• SCSS-Driven Approach: Use TypeScript definitions to programmatically generate SCSS files, ensuring consistent styles.
• Flexible and Scalable: Supports nested elements, complex modifiers, and unified design systems.
• Set-Based Modifiers: Efficiently handles and validates modifiers using Set<string>.
• Lightweight: Minimal overhead with no additional dependencies beyond easy-bem.

Installation

Install using npm or pnpm:

Using npm

npm install typed-bem

Using pnpm

pnpm add typed-bem

Usage

Typed BEM introduces a type-safe way to define and generate BEM class names. Define your BEM structures using TypeScript generics, ensuring correctness and preventing invalid combinations.

Example: Single Component

import typedBem from 'typed-bem';

const bem = typedBem<{
	button: {
		modifiers: Set<'primary' | 'secondary'>;
		elements: {
			icon: {
				modifiers: Set<'small' | 'large'>;
			};
			text: {
				modifiers: never; // No modifiers allowed for `text`
			};
		};
	};
}>();

// Block with modifiers
console.log(bem('button', { primary: true }));
// Output: "button button--primary"

// Element with modifiers
console.log(bem('button', 'icon', { small: true }));
// Output: "button__icon button__icon--small"

// Element without modifiers
console.log(bem('button', 'text'));
// Output: "button__text"

API Documentation

typedBem

Function Signature

typedBem<B extends BemBlocks>(): TypedBemFunction<B>;

Returns

The function returns a BEM generator function that accepts:

• blockName (keyof B): The name of the block.
• blockModifiersOrElementName:
  • A record of block modifiers.
  • Or the name of an element (keyof B[BlockName]['elements']).
• elementModifiers (optional): A record of element modifiers, if applicable.

SCSS Integration

Typed BEM allows you to synchronize your TypeScript definitions with your SCSS structure by generating SCSS files programmatically.

SCSS Generator Script

import fs from 'fs';

const bemDefinition = {
	button: {
		modifiers: new Set(['primary', 'secondary']),
		elements: {
			icon: { modifiers: new Set(['small', 'large']) },
			text: { modifiers: null },
		},
	},
	alert: {
		modifiers: new Set(['success', 'error']),
		elements: {
			container: { modifiers: new Set(['padded']) },
		},
	},
} as const;

const generateScss = (bemDef: typeof bemDefinition, outputPath: string) => {
	const scssLines: string[] = [];

	Object.entries(bemDef).forEach(([block, blockDef]) => {
		scssLines.push(`.${block} {`);
		if (blockDef.modifiers) {
			blockDef.modifiers.forEach((modifier) => {
				scssLines.push(`  &--${modifier} {}`);
			});
		}
		if (blockDef.elements) {
			Object.entries(blockDef.elements).forEach(([element, elementDef]) => {
				scssLines.push(`  &__${element} {`);
				if (elementDef.modifiers) {
					elementDef.modifiers.forEach((modifier) => {
						scssLines.push(`    &--${modifier} {}`);
					});
				}
				scssLines.push(`  }`);
			});
		}
		scssLines.push(`}`);
	});

	fs.writeFileSync(outputPath, scssLines.join('\n'), 'utf8');
};

// Generate SCSS file
generateScss(bemDefinition, './bem-structure.scss');

Example Output (bem-structure.scss)

.button {
	&--primary {
	}
	&--secondary {
	}
	&__icon {
		&--small {
		}
		&--large {
		}
	}
	&__text {
	}
}

.alert {
	&--success {
	}
	&--error {
	}
	&__container {
		&--padded {
		}
	}
}

Why Use typed-bem?

• Built on Easy-BEM: Combines the simplicity of easy-bem with strict TypeScript typing.
• SCSS Synchronization: Generate SCSS files from your TypeScript definitions for consistency.
• Type Safety: Catch invalid combinations of blocks, elements, and modifiers at compile time.
• Scalable Design Systems: Perfect for large projects with multiple components.

License

Typed BEM is licensed under the MIT License.