Instalación de SISASS

Proyecto HTML, CSS y JavaScript

En un proyecto tradicional, instala sass como dependencia de desarrollo para disponer del compilador local:

npm install --save-dev sass

Después, ejecuta el instalador normal desde la raíz del proyecto consumidor. Este comando crea la carga distribuida en assets/scss/core/:

npm explore sisass -- npm run init

Crea un punto de entrada, por ejemplo assets/main.scss, e importa el módulo público de SISASS. La ruta sisass/src/sisass corresponde al árbol actual del paquete; si el paquete publicado incorpora un punto de entrada Sass, utiliza ese punto de entrada validado.

@use "sisass/src/sisass" as s;
@use "core/variables" as variables;

.installation_check {
    @include s.text((align: center));
    color: variables.$c2;
}

Compila el archivo con la carpeta del proyecto y el paquete como rutas de carga:

npx sass assets/main.scss assets/css/main.css \
    --load-path assets \
    --load-path node_modules

Enlaza assets/css/main.css desde tu HTML. Para observar cambios durante el desarrollo, puedes sustituir la compilación puntual por el modo --watch.

React sin Vite

React no define por sí mismo cómo se procesan los archivos SCSS. Esta ruta utiliza Webpack como ejemplo de un proyecto React existente. Si tu proyecto usa otra herramienta, conserva el procedimiento del instalador y sigue la integración Sass específica de esa herramienta.

npm install --save-dev sass sass-loader
npm explore sisass -- npm run init -- --path ../../src/

Verifica que Webpack tenga disponibles css-loader y style-loader. La regla para SCSS debe encadenar esos loaders con sass-loader:

module.exports = {
    module: {
        rules: [
            {
                test: /\.s[ac]ss$/i,
                use: [
                    "style-loader",
                    "css-loader",
                    "sass-loader"
                ]
            }
        ]
    }
};

Importa un archivo como src/main.scss desde tu entrada JavaScript o JSX:

import "./main.scss";

Para estilos globales usa un archivo SCSS normal. Si el proyecto ya tiene CSS Modules, puedes usar la extensión .module.scss y consumir las clases mediante el objeto que devuelve el import.

React con Vite

Vite tiene soporte incorporado para archivos .scss y .sass; solo necesitas instalar un compilador Sass. La opción recomendada es sass-embedded y sass es una alternativa compatible. No necesitas instalar un plugin específico de Vite para procesar Sass.

Ejecuta los siguientes comandos desde la raíz del proyecto para instalar el compilador Sass y el procesador de SVG. SISASS ya se instaló en el paso común; el último comando copia su carga distribuida en src/assets/scss/core/:

npm install --save-dev sass-embedded
npm install --save-dev postcss-inline-svg
npm explore sisass -- npm run init -- --path ../../src/

El instalador crea la carga distribuida en src/assets/scss/core/. Por su parte, npm instala el paquete en node_modules/sisass/, donde su punto de entrada Sass es src/_sisass.scss. La ruta ../../src/ funciona porque npm explore sisass ejecuta el instalador desde node_modules/sisass/.

Ambas formas de uso parten de la misma instalación. La diferencia está en cómo cada archivo SCSS accede a los módulos de SISASS: mediante un alias explícito, llamado namespace, o de forma global mediante additionalData. Configura primero las rutas de carga en vite.config.js, en la raíz del proyecto, al mismo nivel que package.json. Si el proyecto usa TypeScript, utiliza vite.config.ts:

import { defineConfig } from "vite";
import postcss_inline_svg from "postcss-inline-svg";
import { resolve } from "node:path";

export default defineConfig({
    css: {
        postcss: {
            plugins: [
                postcss_inline_svg({
                    paths: [resolve(process.cwd(), "src/assets/img/svg")]
                })
            ]
        },
        preprocessorOptions: {
            scss: {
                loadPaths: [
                    "./node_modules/sisass",
                    "./src/assets/scss"
                ]
            }
        }
    }
});

Forma 1: con namespace (recomendada)

La forma recomendada importa SISASS en cada archivo que lo necesita y le asigna un namespace, por ejemplo sisass. Así queda claro de dónde provienen los mixins y se reducen las colisiones con otros módulos del proyecto. Esta variante no utiliza additionalData:

@use "src/sisass" as sisass;
@use "core/variables" as variables;

.installation_check {
    @include sisass.text((align: center));
    color: variables.$c2;
}

Forma 2: sin namespace

Si prefieres no repetir los namespaces, añade additionalData dentro de scss. Vite inyectará estos módulos al comienzo de cada archivo SCSS y sus variables, mixins y funciones estarán disponibles sin prefijo:

scss: {
    loadPaths: [
        "./node_modules/sisass",
        "./src/assets/scss"
    ],
    additionalData: "@use \"core\" as *;\n@use \"src/sisass\" as *;\n"
}

Con esta variante, el mismo ejemplo se escribe sin namespace. No combines este código con los @use del ejemplo anterior:

@use "core/fonts" as *;
@use "core/keyframes" as *;
@use "core/layout" as *;

html,
body,
#root {
    min-height: 100%;
}

body {
    @include no-spacing;
    @include bc($c2, $c1);
}

La configuración de postcss-inline-svg es necesaria cuando se usan mixins de SISASS que generan svg-load() o svg-inline(). En este proyecto, los archivos SVG deben estar en src/assets/img/svg/; Vite los convierte en URLs data:image/svg+xml durante la compilación CSS. Si no utilizas esas funciones, puedes omitir el bloque postcss y su dependencia.

En cualquiera de las dos formas, guarda los estilos en src/main.scss e impórtalos desde main.jsx, main.tsx o el componente que actúe como entrada de la aplicación:

import "./main.scss";

Ejecuta el servidor de desarrollo y la construcción de producción para confirmar que Vite resuelve los módulos, procesa los SVG configurados y genera CSS:

npm run dev
npm run build

Estilos locales con CSS Modules

Vite reconoce como CSS Module cualquier archivo SCSS cuyo nombre termine en .module.scss. Crea el archivo junto al componente que va a utilizarlo; así resulta fácil identificar qué estilos le pertenecen. Esta es la estructura del ejemplo:

Ejemplo con namespace: componente ProductCard

Para este ejemplo, ProductCard es un componente ficticio que representa una tarjeta de producto. El ejemplo utiliza explícitamente la forma con namespace: en ProductCard.module.scss, SISASS se importa como s y las variables como variables. Las clases declaradas allí serán locales al componente:

@use "src/sisass" as s;
@use "../../assets/scss/core/variables" as variables;

.product_card {
    @include s.text((align: center));
    background-color: variables.$c1;
    border-radius: 8px;
    padding: 20px;
}

.title {
    color: variables.$c2;
    margin: 0 0 10px;
}

.description {
    margin: 0;
}

En ProductCard.jsx, importa el módulo como styles y accede a cada clase mediante ese objeto. Vite genera nombres únicos durante la compilación, por lo que estas clases no afectan otros componentes:

import styles from "./ProductCard.module.scss";

export function ProductCard() {
    return (
        <article className={styles.product_card}>
            <h2 className={styles.title}>Curso de SISASS</h2>
            <p className={styles.description}>
                Estilos aislados para este componente.
            </p>
        </article>
    );
}

Por último, importa ProductCard desde App.jsx. No necesitas importar nuevamente el SCSS porque el componente ya carga su propio módulo:

import { ProductCard } from "./components/ProductCard/ProductCard";

export default function App() {
    return <ProductCard />;
}

Instalación en SQHTML

El modo SQHTML conserva el destino assets/scss/core/ y aplica ajustes específicos de variables y fuentes.

SQHTML y SQHTML2 usan el compilador sass. Instálalo como dependencia de desarrollo si el proyecto todavía no lo incluye:

npm install --save-dev sass

npm explore sisass -- npm run init -- --dep sqhtml

Si necesitas otra raíz de recursos, combina --dep sqhtml con --path:

npm explore sisass -- npm run init -- --dep sqhtml --path ../../resources/

Después de copiar los archivos, el instalador añade $c3: #1F567B cuando todavía no existe el bloque de ejemplo de SQHTML, configura $f1 con Roboto, ajusta $i1 a ../../img/svg/ y reemplaza el bloque de ejemplo de _fonts.scss por declaraciones de Roboto.

Instalación en SQHTML2

SQHTML2 es una integración especial del instalador. Su destino se fuerza a src/core/ y no depende de --path.

npm explore sisass -- npm run init -- --dep sqhtml2

Además de aplicar los ajustes de SQHTML, el instalador regenera _index.scss a partir de instances.config.js. En la configuración actual, el archivo reenvía variables, base, mediaqueries y mixin.