Guía
En esta sección, instalaremos EffCSS y veremos cómo usarlo.
Instalar
Escribe en tu terminal:
# npm
npm i effcss
# pnpm
pnpm add effcss
# yarn
yarn add effcssTipado CSS
EffCSS incluye autocompletado para propiedades CSS, por lo que puedes escribir las reglas de estilo sin necesidad de configuraciones adicionales.
Nota: El autocompletado sugiere nombres de propiedades, pero no detecta errores tipográficos. Dado que las reglas de estilo admiten claves arbitrarias (como selectores anidados o propiedades personalizadas), un nombre de propiedad mal escrito no se reporta como un error; esto elimina restricciones rígidas, pero exige una mayor atención por tu parte.
Si deseas añadir tus propias propiedades o ampliar el conjunto predefinido —por ejemplo, utilizando las definiciones completas de csstype—, define EffCSS.Properties en tu proyecto mediante la ampliación del espacio de nombres global:
npm i -D csstypeLuego, combínalo con EffCSS
// env.d.ts
import type { Properties as CSSProperties } from 'csstype';
declare global {
namespace EffCSS {
interface Properties extends CSSProperties {}
}
}
export {};Ahora, cada regla de estilo cuenta con autocompletado completo de csstype.
Uso
Para crear estilos con EffCSS, solo tienes que invocar las utilidades. Afortunadamente, hay muy pocas y sus nombres indican claramente su función.
Todas las utilidades de estilo son «perezosas» (lazy) por defecto: los estilos solo se materializan cuando se utiliza un resolver por primera vez (resolver() o resolver + ''). Si los estilos hacen referencia a otros tokens, envuélvelos en una función () => ({...}) para preservar su naturaleza «perezosa».
Analicemos con más detalle el uso de cada una de ellas.
id / className
id crea una única regla CSS con el contenido especificado y devuelve la función resolutora de id:
import { id } from 'effcss';
const badge = id({ backgroundColor: 'red' });
badge(); // 'f_5-0'
'' + badge; // 'f_5-0'className crea una única regla CSS con el contenido especificado y devuelve la función resolutora de nombres de clase:
import { className } from 'effcss';
const btn = className({ color: 'white' });
btn(); // 'f_6-0'
'' + btn; // 'f_6-0'Modificadores
Pasa uno o más modificadores a un resolvedor de selectores (id o className) para crear variantes de una misma regla base. Cada variante obtiene su propio token, almacenado en caché según el conjunto de modificadores. Las pseudoclases y los atributos se añaden al selector; las reglas especiales o at-rules (@media, @container) envuelven la regla en un nivel de anidamiento distinto:
const box = className(() => ({ color: 'red' }));
box(); // 'f_6-0' -> `.f_6-0 { color: red; }`
box(':hover'); // 'f_6-1' -> `.f_6-1:hover { color: red; }`
box('[data-state="open"]'); // 'f_6-2' -> `.f_6-2[data-state="open"] { color: red; }`
box('@media (max-width: 700px)'); // 'f_6-3' -> `@media (max-width: 700px) { .f_6-3 { ... } }`
box('@media (max-width: 700px)', ':hover'); // 'f_6-4' -> `@media (...) { .f_6-4:hover { ... } }`La misma regla básica se reutiliza en todas las variantes: las condiciones se aplican cuando se usa la regla, no se incluyen en su definición.
Estilos y tokens perezosos
Si sus estilos hacen referencia a otros tokens (resolvedores), envuélvalos en una función () => ({...}). Pasar un token ya materializado en un objeto simple arroja un TypeError porque rompe la pereza y crea efectos secundarios en el módulo:
const size = variable('12px');
// ❌ provoca un error al utilizarse: la regla contiene el resultado de un «resolver»
className({ padding: size() });
// ✅ uso diferido («lazy»): el token solo se resuelve cuando se utiliza la regla
className(() => ({ padding: size() }));La definición en sí misma permanece «pura» (pure); el error se produce únicamente cuando se invoca el «resolver» o cuando este se convierte a una cadena de texto. Esto garantiza que la anotación /*#__PURE__*/ funcione correctamente, permitiendo que las definiciones de estilos no utilizadas sean eliminadas mediante tree-shaking en lugar de provocar un fallo en el módulo.
El mecanismo de control es independiente de la clave: evalúa la estructura del token, no una clave de contexto específica; por tanto, también detectará tokens provenientes de otros contextos (o del contexto global).
La verificación se basa en la estructura del token (<clave>_<tipo>-<contador>), por lo que cualquier valor que simplemente se asemeje a un token será un falso positivo. En tales casos, utilice la variante basada en funciones:
// ❌ falso positivo: `_1-x` tiene la apariencia de un token
className({ backgroundImage: 'url(icon_1-x.svg)' })();
// ✅ la variante basada en funciones no está sujeta a esta verificación
className(() => ({ backgroundImage: 'url(icon_1-x.svg)' }))();Esto es aplicable a todas las utilidades que aceptan un objeto que contiene tokens: className, id, style y animation.
Anidamiento de CSS nativo
Cualquier objeto de estilo admite selectores anidados, lo que permite añadir pseudoclases, atributos, elementos hijos y combinadores. El símbolo & hace referencia al selector actual:
const card = className({
padding: '1rem',
'&:hover': { boxShadow: '0 0 8px' }, // `.f_6-0:hover`
'&[data-active]': { borderColor: 'blue' }, // `.f_6-0[data-active]`
'& > .title': { fontWeight: 600 } // `.f_6-0 > .title`
});Dentro de las formas funcionales, es posible incluso pasar selectores (tokens) completos como claves anidadas; estos se resuelven de forma diferida (lazily) cuando se utiliza la regla:
const card = className(() => ({
padding: '1rem',
['& > ' + btn]: { marginTop: '1rem' } // `& > .f_6-0`
}));variable
variable crea una única regla CSS @property y devuelve una función de resolución de variables:
import { variable } from 'effcss';
const accent = variable('#ff0');
'' + accent; // '--f_2-0'
accent(); // 'var(--f_2-0)'
accent('green'); // 'var(--f_2-0, green)'Puedes pasar un objeto de configuración para establecer syntax, inherits e initialValue:
const size = variable({ initialValue: '12px', syntax: '<length>', inherits: false });Puedes obtener y establecer el valor inicial de una variable mediante los métodos correspondientes:
const size = variable('12px');
size(); // materializar la variable
size.get(); // '12px'
size.set('24px'); // actualiza la regla @property
size.set((prev) => prev.replace('px', 'rem')); // actualización funcionalINFO
Los métodos set/get solo funcionan una vez que la variable se ha materializado (resolver() o resolver + ''). Antes de eso, get() devuelve una cadena vacía y set() no tiene ningún efecto.
animation
animation crea una única regla @keyframes de CSS y devuelve un resolutor de nombres de keyframes:
import { animation } from 'effcss';
const spin = animation({ from: { transform: 'rotate(0)' }, to: { transform: 'rotate(360deg)' } });
spin(); // 'f_3-0'
'' + spin; // 'f_3-0'
// forma de función cuando los fotogramas clave hacen referencia a tokens de EffCSS
const grow = animation(() => ({ from: { height: size() }, to: { height: '100px' } }));
grow(); // 'f_3-1'container
container crea una única regla CSS @container. La conversión a cadena devuelve la regla @container, mientras que su invocación devuelve name / type:
import { container } from 'effcss';
const card = container('inline-size');
'' + card; // '@container f_4-0'
card(); // 'f_4-0 / inline-size'
// Si no se especifica un tipo, se utiliza el valor predeterminado.
const plain = container();
'' + plain; // '@container f_4-1'
plain(); // 'f_4-1 / normal'font
font crea una única regla CSS @font-face y devuelve una cadena invocable que contiene el nombre de la familia tipográfica, junto con alternativas opcionales:
import { font } from 'effcss';
const Inter = font({ src: "url('/inter.woff2')" });
Inter(); // 'f_1-0'
Inter('sans-serif'); // 'f_1-0, sans-serif'
Inter('Arial', 'sans-serif'); // 'f_1-0, Arial, sans-serif'layers
layers crea una única regla de declaración @layer de CSS que incluye todas las capas proporcionadas. Devuelve un objeto con funciones de resolución de capas, una por cada nombre de capa:
import { layers } from 'effcss';
const myLayers = layers(['reset', 'base']);
myLayers.reset(); // '@layer f_0-0'
'' + myLayers.reset; // '@layer f_0-0'
myLayers.base(); // '@layer f_0-1'style
style crea estilos arbitrarios y devuelve una función resolutora que, al ser invocada por primera vez, inyecta dichos estilos y retorna una cadena vacía:
import { style } from 'effcss';
const custom = style({ body: { margin: 0 } });
custom(); // '' (los estilos se inyectan)
'' + custom; // ''
// usar función cuando se utilizan tokens dentro del estilo
const themed = style(() => ({ body: { color: accent(), ['& > ' + btn]: { marginTop: '1rem' } } }));
themed(); // ''style admite el anidamiento nativo de CSS y valores especiales:
// los valores del array se aplanan en declaraciones
style(() => ({ body: { margin: ['0', 'auto'] } }));
// un array de objetos genera varias reglas con la misma clave
// (funciona a cualquier nivel)
style({
'@font-face': [
{ fontFamily: '"Bitstream Vera Serif Bold"', src: 'url("fira.woff2")' },
{ fontFamily: '"MyHelvetica"', src: 'local("Helvetica Neue Bold")', fontWeight: 'bold' }
]
});
// un valor de cadena vacío genera una declaración de «at-rule» sin contenido
style(() => ({ '@layer custom': '' })); // @layer custom;
// Las propiedades en camelCase se convierten a formato kebab-case
style(() => ({ body: { fontFamily: 'serif' } }));theme
theme agrupa variables y sus valores en variantes de tema para simplificar el cambio dinámico de estilos. Devuelve un objeto controlador con los métodos vars, list, get y set:
import { theme } from 'effcss';
const myTheme = theme({
vars: { bg: '#eff', fg: 'black' },
options: {
light: { bg: '#eff', fg: 'black' },
dark: { bg: '#111', fg: 'white' }
},
initial: 'light'
});
myTheme.get(); // 'light'
myTheme.set('dark'); // true
myTheme.get(); // 'dark'
myTheme.vars.bg(); // 'var(--f_2-0)'
myTheme.vars.bg.get(); // '#111'
myTheme.vars.bg.set('#eee'); // override a single variableserialize
serialize convierte todas las hojas de estilo creadas en una cadena HTML de etiquetas <style>:
import { className, serialize } from 'effcss';
className({ color: 'white' })();
// insertar las etiquetas `<style>` generadas en tu HTML
const html = serialize();
// '<style data-effcss-key="f-6" data-effcss-count="1">.f_6-0 { color: white; }</style>'De este modo, los estilos pueden prepararse en el servidor y reutilizarse en el cliente. Esto resulta especialmente útil para SSG/SSR.
Para CSR (renderizado en el cliente), puedes utilizar vite-plugin-effcss (v2). Este plugin captura el CSS generado por EffCSS a través del pipeline de SSR de Vite y lo inserta directamente en el HTML. Permite eliminar el FOUC (destello de contenido sin estilo) y acelerar el primer renderizado gracias a la hidratación de estilos. Funciona tanto en modo de desarrollo como en modo de construcción (build), sin requerir ninguna dependencia adicional (sin esbuild, sin tsx, sin cargadores extra):
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import effcss from 'vite-plugin-effcss';
export default defineConfig({
plugins: [react(), effcss()],
});Opcionalmente, puedes añadir un marcador de posición en tu HTML que indique la ubicación de destino para la inserción:
<head>
<!-- EFFCSS_INJECT -->
</head>El plugin admite las siguientes opciones:
| Opción | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
verbose | boolean | false | Registro detallado (verbose logging) |
entry | string | — | Punto de entrada explícito (p. ej., /src/main.tsx). Si se omite, se detecta automáticamente a partir de <script type="module" src="..."> en index.html |
placeholder | string | '<!-- EFFCSS_INJECT -->' | Marcador de posición HTML que se sustituirá por <style> |
injectTo | 'head' | 'head-prepend' | 'head' | Posición de inserción alternativa en caso de que no se encuentre el marcador de posición |
setConfig / getConfig
getConfig devuelve la configuración actual del contexto de estilos global. setConfig modifica la configuración y afecta a la generación de estilos si se invoca antes de que se cree la primera hoja de estilos:
import { setConfig, getConfig } from 'effcss';
setConfig({ key: 'app' }); // debe invocarse antes del primer uso
getConfig(); // { key: 'app' }setConfig devuelve true si se aplica, o false si el proveedor ya se ha utilizado. La clave debe comenzar con una letra y contener únicamente letras, dígitos, _ o -.
clear
clear elimina todos los estilos generados y restablece los contadores:
import { clear } from 'effcss';
clear();context
context permite crear un grupo independiente de estilos, devolviendo un objeto que contiene el conjunto de utilidades de EffCSS, a excepción de context mismo. Cada contexto posee una clave única, contadores y hojas de estilo, de modo que los tokens nunca entran en conflicto entre distintos contextos:
import { context } from 'effcss';
const ctx = context({ key: 'app' });
const btn = ctx.className({ color: 'white' });
btn(); // 'app_6-0'
ctx.serialize(); // '<style data-effcss-key="app-6" data-effcss-count="1">...</style>'
ctx.getConfig(); // { key: 'app' }
ctx.clear(); // elimina los estilos, mantiene el contexto utilizable
ctx.dispose(); // destruye permanentemente el contextogetContexts devuelve todos los contextos locales activos, indexados por su clave. Se excluyen los contextos que han sido descartados o eliminados por el recolector de basura (las referencias se mantienen de forma débil):
import { getContexts } from 'effcss';
const ctx = context({ key: 'app' });
getContexts(); // { app: ctx }Dado que los estilos de un context pueden serializarse e hidratarse de forma independiente, es posible utilizar esta funcionalidad para aislar los estilos entre micro-frontends. Además, un context implementa Symbol.dispose, por lo que puede emplearse junto con la sentencia using.