Sass in production and when to use native CSS

// Builds the app with Vite, lists what the build wrote, and checks the CSS source maps in the dev server.
// Run it in this folder after `npm install` in the examples folder: node build.mjs
import { readFileSync, readdirSync, statSync } from 'node:fs';
import { createRequire } from 'node:module';
import { join, relative } from 'node:path';
import { build, createServer } from 'vite';

// Which Sass packages are installed: Vite uses sass-embedded when it can load it, and sass otherwise.
const require = createRequire(import.meta.url);
for (const name of ['sass-embedded', 'sass']) {
  try {
    const main = require.resolve(name);
    const dir = main.slice(0, main.lastIndexOf(`node_modules/${name}/`) + `node_modules/${name}/`.length);
    console.log(`${name} ${JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version} is installed`);
  } catch {
    console.log(`${name} is not installed`);
  }
}

await build({ logLevel: 'silent' });
const files = (dir) => readdirSync(dir).flatMap((f) => (statSync(join(dir, f)).isDirectory() ? files(join(dir, f)) : [join(dir, f)]));
console.log('\nThe build wrote:');
for (const file of files('dist').sort()) console.log(`  ${file.padEnd(34)} ${String(statSync(file).size).padStart(5)} bytes`);
const css = files('dist').find((f) => f.endsWith('.css'));
console.log(`\n${css}:\n${readFileSync(css, 'utf8')}`);
console.log(`CSS source map in the build: ${files('dist').some((f) => f.endsWith('.css.map')) ? 'yes' : 'no'}`);

// The dev server: the CSS it serves for app.scss, with css.devSourcemap on.
const server = await createServer({ logLevel: 'silent', server: { middlewareMode: true, ws: false }, appType: 'custom' });
const served = await server.transformRequest('/src/styles/app.scss');
await server.close();
const map = /sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+/=]+)/.exec(served.code);
const sources = map ? JSON.parse(Buffer.from(map[1], 'base64').toString()).sources.map((s) => relative('.', s)) : [];
console.log(`CSS source map in the dev server: ${map ? `yes, inline, with the sources ${sources.join(' and ')}` : 'no'}`);

sass-embedded 1.105.1 is installed
sass 1.105.1 is installed

The build wrote:
  dist/assets/index-BTOKGPD_.js        796 bytes
  dist/assets/index-BTOKGPD_.js.map    448 bytes
  dist/assets/index-CntIoS7G.css       146 bytes
  dist/index.html                      359 bytes

dist/assets/index-CntIoS7G.css:
.btn{border-radius:6px}.btn--sm{font-size:.875rem}.btn--md{font-size:1rem}.btn--lg{font-size:1.25rem}.btn--primary{color:#fff;background:#0b5fff}

CSS source map in the build: no
CSS source map in the dev server: yes, inline, with the sources src/styles/app.scss and src/styles/_tokens.scss

// Times a compile of all of Bootstrap 5.3.8 with sass-embedded and with the pure-JavaScript sass package, through a
// long-lived async compiler as Vite uses them, and with sass's synchronous API. Medians of 5 runs after 2 warm-ups.
// Run it in this folder after `npm install` in the examples folder: node bench.mjs
import * as sass from 'sass';
import * as embedded from 'sass-embedded';

const SOURCE = '@use "pkg:bootstrap";';
const options = (pkg) => ({ importers: [new pkg.NodePackageImporter(process.cwd())], quietDeps: true, style: 'compressed', logger: pkg.Logger.silent });
const median = (list) => [...list].sort((a, b) => a - b)[Math.floor(list.length / 2)];

async function time(compile) {
  for (let i = 0; i < 2; i++) await compile();
  const runs = [];
  for (let i = 0; i < 5; i++) {
    const start = performance.now();
    await compile();
    runs.push(performance.now() - start);
  }
  return Math.round(median(runs));
}

const embeddedCompiler = await embedded.initAsyncCompiler();
const jsCompiler = await sass.initAsyncCompiler();
const results = [
  ['sass-embedded, async compiler', await time(() => embeddedCompiler.compileStringAsync(SOURCE, options(embedded)))],
  ['sass, async compiler', await time(() => jsCompiler.compileStringAsync(SOURCE, options(sass)))],
  ['sass, synchronous compileString()', await time(() => sass.compileString(SOURCE, options(sass)))],
];
await embeddedCompiler.dispose();
await jsCompiler.dispose();

console.log(`All of Bootstrap 5.3.8, compressed, Dart Sass ${sass.info.split('\t')[1]} on Node.js ${process.versions.node}:`);
for (const [label, ms] of results) console.log(`  ${label.padEnd(34)} median ${String(ms).padStart(5)} ms`);
console.log(`sass-embedded was ${(results[1][1] / results[0][1]).toFixed(1)} times as fast as sass through the same async API.`);

All of Bootstrap 5.3.8, compressed, Dart Sass 1.105.1 on Node.js 24.21.0:
  sass-embedded, async compiler      median  1201 ms
  sass, async compiler               median  6587 ms
  sass, synchronous compileString()  median  1525 ms
sass-embedded was 5.5 times as fast as sass through the same async API.

// Compiles the same stylesheet with Sass 1.78.0 (the version Bootstrap 5.3.8 pins) and with Sass 1.105.1, then
// compares the CSS. Needs both: npm install sass@1.105.1 sass-1.78@npm:sass@1.78.0, then: node upgrade.mjs
import * as newSass from 'sass';
import * as oldSass from 'sass-1.78';
import { installBootstrap } from './vendor.mjs';

installBootstrap('.');
const compile = (sass, style) => sass.compile('custom.scss', { loadPaths: ['node_modules'], style, logger: sass.Logger.silent }).css;
const version = (sass) => sass.info.split('\t')[1];

for (const style of ['compressed', 'expanded']) {
  const before = compile(oldSass, style).length;
  const after = compile(newSass, style).length;
  console.log(`${style.padEnd(10)} Sass ${version(oldSass)}: ${before.toLocaleString('en')} bytes, Sass ${version(newSass)}: ${after.toLocaleString('en')} bytes (${after > before ? '+' : ''}${(after - before).toLocaleString('en')})`);
}

// Line by line, in expanded output.
const a = compile(oldSass, 'expanded').split('\n');
const b = compile(newSass, 'expanded').split('\n');
const changed = a.map((line, i) => [line.trim(), b[i]?.trim()]).filter(([x, y]) => x !== y);
const percentRgb = changed.filter(([, y]) => /rgb(?:\(|%28)[\d.]+%/.test(y));
console.log(`\n${a.length} lines each; ${changed.length} differ, ${percentRgb.length} of them because a colour is now written as rgb() percentages.`);
for (const [x, y] of changed.slice(0, 3)) console.log(`- ${x}\n+ ${y}`);
const inSvg = changed.filter(([, y]) => y.includes('data:image/svg+xml'));
console.log(`\n${inSvg.length} of the changed lines are SVG icons in data: URLs, for example:\n- ${inSvg[0][0]}\n+ ${inSvg[0][1]}`);

compressed Sass 1.78.0: 229,554 bytes, Sass 1.105.1: 234,800 bytes (+5,246)
expanded   Sass 1.78.0: 273,128 bytes, Sass 1.105.1: 278,384 bytes (+5,256)

11895 lines each; 127 differ, 127 of them because a colour is now written as rgb() percentages.
- --bs-primary-text-emphasis: #062f2c;
+ --bs-primary-text-emphasis: rgb(2.3529411765%, 18.5098039216%, 17.2549019608%);
- --bs-secondary-text-emphasis: #2b2f32;
+ --bs-secondary-text-emphasis: rgb(16.9411764706%, 18.3529411765%, 19.6078431373%);
- --bs-success-text-emphasis: #0a3622;
+ --bs-success-text-emphasis: rgb(3.9215686275%, 21.1764705882%, 13.1764705882%);

4 of the changed lines are SVG icons in data: URLs, for example:
- --bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='%2387bbb7'/%3e%3c/svg%3e");
+ --bs-form-switch-bg: url("data:image/svg+xml,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='-4 -4 8 8'%3e%3ccircle r='3' fill='rgb%2852.9411764706%, 73.137254902%, 71.568627451%%29'/%3e%3c/svg%3e");

// Runs the Vitest suite and prints each test with its result (from Vitest's JSON report, without timings). Then it
// changes the default root size of rem() to 10px, as a careless edit might, runs the suite again and puts the file
// back. Run it in this folder after `npm install` in the examples folder: node run-tests.mjs (or npx vitest run)
import { readFileSync, writeFileSync } from 'node:fs';
import { startVitest } from 'vitest/node';

async function run(title) {
  console.log(`=== ${title}`);
  const vitest = await startVitest('test', [], { watch: false, reporters: [['json', { outputFile: 'report.json' }]] });
  await vitest.close();
  const report = JSON.parse(readFileSync('report.json', 'utf8'));
  for (const file of report.testResults) {
    for (const test of file.assertionResults) {
      console.log(`${test.status === 'passed' ? 'PASS' : 'FAIL'}  ${test.ancestorTitles.join(' > ')} > ${test.title}`);
      // The assertion and the two values; the stack trace after them is left out.
      for (const message of test.failureMessages) {
        const lines = message.split('\n');
        const end = lines.findIndex((l) => l.startsWith('    at '));
        console.log(lines.slice(0, end === -1 ? undefined : end).filter((l) => l.trim()).map((l) => `      ${l}`).join('\n'));
      }
    }
  }
  console.log(`${report.numPassedTests} passed, ${report.numFailedTests} failed\n`);
  return report.numFailedTests;
}

const failedAsIs = await run('The library as it is');
const original = readFileSync('_functions.scss', 'utf8');
let failedAfterEdit = 0;
try {
  writeFileSync('_functions.scss', original.replace('$root: 16px', '$root: 10px'));
  failedAfterEdit = await run('After changing the default root size of rem() to 10px');
} finally {
  writeFileSync('_functions.scss', original);
}
// Vitest sets a failing exit status for the second run; this script succeeds when the suite passes as it is and
// catches the edit.
process.exitCode = failedAsIs === 0 && failedAfterEdit > 0 ? 0 : 1;

=== The library as it is
JSON report written to report.json
PASS  rem() > divides by the 16px root
PASS  rem() > accepts another root size
PASS  tint() > returns white at 100%
PASS  tint() > keeps the colour at 0%
PASS  focus-ring > writes an outline and an offset
5 passed, 0 failed

=== After changing the default root size of rem() to 10px
JSON report written to report.json
FAIL  rem() > divides by the 16px root
      AssertionError [ERR_ASSERTION]: divides by the 16px root [type: assert-equal] -- numbers may need to be rounded before comparison
      - Expected
      + Received
      - [number] 1.5rem
      + [number] 2.4rem
PASS  rem() > accepts another root size
PASS  tint() > returns white at 100%
PASS  tint() > keeps the colour at 0%
PASS  focus-ring > writes an outline and an offset
4 passed, 1 failed

// Lints the SCSS files with stylelint and prints each problem as file:line:column, rule and message.
// Run it in this folder after `npm install` in the examples folder: node lint.mjs (or npx stylelint "src/**/*.scss")
import stylelint from 'stylelint';

const { results } = await stylelint.lint({ files: 'src/**/*.scss', configFile: 'stylelint.config.mjs' });
let count = 0;
for (const result of [...results].sort((a, b) => a.source.localeCompare(b.source))) {
  const file = result.source.slice(result.source.lastIndexOf('/src/') + 1);
  for (const w of [...result.warnings].sort((a, b) => a.line - b.line || a.column - b.column)) {
    count++;
    console.log(`${file}:${w.line}:${w.column}  ${w.rule}\n  ${w.text.replace(` (${w.rule})`, '')}`);
  }
}
console.log(`\n${count} problems in ${results.length} files`);
process.exitCode = 0;

src/_card.scss:1:15  scss/at-use-no-unnamespaced
  Unexpected @use without namespace
src/_card.scss:4:1  scss/no-unused-private-members
  Expected usage of private member "$-unused-gap" within the stylesheet
src/_card.scss:8:14  scss/no-global-function-names
  Expected map.get instead of map-get
src/_card.scss:11:17  scss/no-global-function-names
  Expected color.adjust($color, $lightness: -$amount) instead of darken($color, $amount)
src/_legacy.scss:1:1  at-rule-disallowed-list
  Disallowed at-rule "@import"
src/_legacy.scss:1:10  scss/partial-no-import
  Unexpected @import in a partial

6 problems in 3 files

// Compares the two versions of the button: what each one ships, and how large it is minified.
// Run it in this folder after `npm install` in the examples folder: node compare.mjs
import { readFileSync } from 'node:fs';
import { transform } from 'lightningcss';
import * as sass from 'sass';

const fromSass = sass.compile('button.scss', { style: 'expanded' }).css;
const native = readFileSync('button.css', 'utf8');
const minify = (css) => transform({ filename: 'x.css', code: Buffer.from(css), minify: true }).code.toString();

console.log(`=== What button.scss compiles to:\n${fromSass}\n`);
const rules = (css) => (minify(css).match(/\{/g) ?? []).length;
for (const [name, css] of [['button.scss, compiled', fromSass], ['button.css', native]]) {
  console.log(`${name.padEnd(22)} ${String(minify(css).length).padStart(4)} bytes minified, ${rules(css)} rule blocks`);
}

// Is button.css plain CSS? Sass's CSS parser rejects every Sass-only feature.
try {
  sass.compileString(native, { syntax: 'css' });
  console.log('\nbutton.css parses as plain CSS: yes');
} catch (error) {
  console.log(`\nbutton.css parses as plain CSS: no (${error.message.split('\n')[0]})`);
}

// Computed colours recorded in three browser engines (computed.json, recorded with Playwright on page.html).
const recorded = JSON.parse(readFileSync('computed.json', 'utf8'));
const same = recorded.rows.every((r) => new Set(Object.values(r.scss)).size === 1 && new Set(Object.values(r.native)).size === 1);
console.log(`\nComputed in ${recorded.engines.join(', ')} (${recorded.recordedWith}), ${same ? 'identical in all three' : 'differing between engines'}:`);
console.log(`${'button'.padEnd(28)} ${'state'.padEnd(15)} ${'button.scss'.padEnd(12)} button.css`);
for (const r of recorded.rows) {
  const [scss, native] = [Object.values(r.scss)[0], Object.values(r.native)[0]];
  console.log(`${r.button.padEnd(28)} ${r.state.padEnd(15)} ${scss.padEnd(12)} ${native}${scss === native ? '' : '   <- differs'}`);
}

=== What button.scss compiles to:
.btn {
  display: inline-flex;
  padding: 0.5rem 1rem;
  border: 0;
  border-radius: 6px;
  color: white;
}
.btn--primary {
  background: #0b5fff;
}
.btn--primary:hover {
  background: rgb(3.6666666667%, 31.6666666667%, 85%);
}
.btn--success {
  background: #15803d;
}
.btn--success:hover {
  background: rgb(7%, 42.6666666667%, 20.3333333333%);
}
.btn--danger {
  background: #b91c1c;
}
.btn--danger:hover {
  background: rgb(61.6666666667%, 9.3333333333%, 9.3333333333%);
}
.btn:focus-visible {
  outline: 3px solid rgb(42.5882352941%, 62.3529411765%, 100%);
  outline-offset: 2px;
}

button.scss, compiled   360 bytes minified, 8 rule blocks
button.css              310 bytes minified, 5 rule blocks

button.css parses as plain CSS: yes

Computed in Chromium 153, Firefox 155, WebKit 26.6 (Playwright 1.63.0), identical in all three:
button                       state           button.scss  button.css
.btn--primary                normal          #0b5fff      #0b5fff
.btn--primary                :hover          #0951d9      #0951d9
.btn--success                normal          #15803d      #15803d
.btn--success                :hover          #126d34      #126d34
.btn--danger                 normal          #b91c1c      #b91c1c
.btn--danger                 :hover          #9d1818      #9d1818
.btn--primary inside .promo  normal          #0b5fff      #7c3aed   <- differs
.btn--primary inside .promo  :hover          #0951d9      #6931c9   <- differs
.btn--primary                :focus-visible  #6d9fff      #6d9fff

// Sample tests for the exercise: the token generator, the native alert.css and your True tests.
// Run it in this folder after `npm install` in the examples folder: node check.mjs
import { existsSync, readFileSync } from 'node:fs';
import { transform } from 'lightningcss';
import * as sass from 'sass';
import sassTrue from 'sass-true';

const EXPECTED = ['--color-info', '--color-warning', '--color-danger', '--color-surface', '--color-ink', '--space-1', '--space-2', '--space-3'];
const tokens = sass.compile('tokens/tokens.scss').css;
const props = Object.fromEntries([...tokens.matchAll(/(--[\w-]+):\s*([^;]+);/g)].map((m) => [m[1], m[2].trim()]));

/** Replaces var(--name) and var(--name, fallback) with the values tokens.css defines. */
const resolve = (css) => css.replace(/var\((--[\w-]+)(?:,\s*([^()]+))?\)/g, (all, name, fallback) => props[name] ?? fallback ?? all);

/** Every declaration as "selector { property: value }", with nesting expanded and values written one way. */
function declarations(css) {
  // Targets without CSS nesting make Lightning CSS expand it; minifying writes every value the same way.
  const flat = transform({ filename: 'alert.css', code: Buffer.from(css), minify: true, targets: { chrome: 100 << 16 } }).code.toString();
  const out = [];
  for (const [, selector, body] of flat.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
    for (const d of body.split(';').filter(Boolean)) out.push(`${selector} { ${d} }`);
  }
  return out.sort();
}

/** True's Sass tests, run with a describe() and it() of our own instead of a test runner's. */
function trueTests(file) {
  const results = [];
  const names = [];
  const describe = (name, body) => {
    names.push(name);
    body();
    names.pop();
  };
  const it = (name, body) => {
    try {
      body();
      results.push({ name: [...names, name].join(' > '), ok: true });
    } catch (error) {
      results.push({ name: [...names, name].join(' > '), ok: false, why: error.message.split('\n')[0] });
    }
  };
  sassTrue.runSass({ describe, it }, file);
  return results;
}

const native = existsSync('components/alert.css') ? readFileSync('components/alert.css', 'utf8') : null;
let plain = false;
let plainWhy = 'components/alert.css does not exist';
if (native !== null) {
  try {
    sass.compileString(native, { syntax: 'css' });
    plain = true;
  } catch (error) {
    plainWhy = error.message.split('\n')[0];
  }
}
const literals = native === null ? [] : native.replace(/\/\*[\s\S]*?\*\//g, '').match(/#[0-9a-f]{3,8}\b|\b(?:rgb|hsl|oklch|lab)a?\(/gi) ?? [];
let same = false;
let sameWhy = 'nothing to compare';
if (plain) {
  const want = declarations(sass.compile('components/alert.scss').css);
  const got = declarations(resolve(native));
  const missing = want.filter((d) => !got.includes(d));
  const extra = got.filter((d) => !want.includes(d));
  same = !missing.length && !extra.length;
  sameWhy = `${missing.length ? `missing ${missing[0]}` : ''}${missing.length && extra.length ? '; ' : ''}${extra.length ? `unexpected ${extra[0]}` : ''}`;
}
let tests = [];
let testsWhy = 'test/palette.test.scss does not exist';
if (existsSync('test/palette.test.scss')) {
  try {
    tests = trueTests('test/palette.test.scss');
    testsWhy = tests.length < 2 ? `${tests.length} test found` : tests.filter((t) => !t.ok).map((t) => `${t.name}: ${t.why}`).join('; ');
  } catch (error) {
    testsWhy = error.message.split('\n')[0];
  }
}

const results = [
  ['tokens/tokens.scss writes the eight custom properties', EXPECTED.every((p) => p in props), `missing ${EXPECTED.filter((p) => !(p in props)).join(', ')}`],
  ['components/alert.css is plain CSS', plain, plainWhy],
  ['alert.css takes every colour from a custom property', native !== null && literals.length === 0, native === null ? 'no file' : `found ${literals.join(', ')}`],
  ['alert.css gives the same declarations as alert.scss', same, sameWhy],
  ['test/palette.test.scss has two or more passing True tests', tests.length >= 2 && tests.every((t) => t.ok), testsWhy],
];

let failed = 0;
for (const [name, ok, why] of results) {
  if (!ok) failed++;
  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${ok ? '' : ` (${why})`}`);
}
console.log(`\n${results.length - failed} of ${results.length} tests pass`);
process.exitCode = failed ? 1 : 0;

PASS  tokens/tokens.scss writes the eight custom properties
FAIL  components/alert.css is plain CSS (components/alert.css does not exist)
FAIL  alert.css takes every colour from a custom property (no file)
FAIL  alert.css gives the same declarations as alert.scss (nothing to compare)
FAIL  test/palette.test.scss has two or more passing True tests (test/palette.test.scss does not exist)

1 of 5 tests pass