Skip to content

Guía ​

En esta sección, instalaremos EffCSS y veremos cómo usarlo.

Instalar ​

Escribe en tu terminal:

sh
# npm
npm i effcss

# pnpm
pnpm add effcss

# yarn
yarn add effcss

Tipado 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:

sh
npm i -D csstype

Luego, combínalo con EffCSS

ts
// 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:

ts
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:

ts
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:

ts
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:

ts
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:

ts
// ❌ 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:

ts
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:

ts
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:

ts
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:

ts
const size = variable({ initialValue: '12px', syntax: '<length>', inherits: false });

Puedes obtener y establecer el valor inicial de una variable mediante los métodos correspondientes:

ts
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 funcional

INFO

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:

ts
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:

ts
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:

ts
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:

ts
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:

ts
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:

ts
// 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:

ts
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 variable

serialize ​

serialize convierte todas las hojas de estilo creadas en una cadena HTML de etiquetas <style>:

ts
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):

ts
// 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:

html
<head>
  <!-- EFFCSS_INJECT -->
</head>

El plugin admite las siguientes opciones:

OpciónTipoValor predeterminadoDescripción
verbosebooleanfalseRegistro detallado (verbose logging)
entrystring—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
placeholderstring'<!-- 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:

ts
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:

ts
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:

ts
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 contexto

getContexts 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):

ts
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.

Publicado bajo la Licencia Apache 2.0