feat!: safely parse mangled CSS with postcss-safe-parser (#225)

joshfester · web-flow · commit 7dc4979a8d89 · 2026-01-20T16:05:58.000Z
diff --git a/package.json b/package.json
@@ -37,6 +37,7 @@
     "@antfu/eslint-config": "7.1.0",
     "@codspeed/vitest-plugin": "5.0.1",
     "@types/node": "24.10.9",
+    "@types/postcss-safe-parser": "^5.0.4",
     "@vitest/coverage-v8": "3.2.4",
     "bumpp": "10.4.0",
     "changelogithub": "14.0.0",
diff --git a/packages/beasties/README.md b/packages/beasties/README.md
@@ -140,6 +140,7 @@ All optional. Pass them to `new Beasties({ ... })`.
   - `"all"` inline all keyframes rules
   - `"none"` remove all keyframes rules
 - `compress` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Compress resulting critical CSS _(default: `true`)_
+- `safeParser` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Use PostCSS safe parser for fault-tolerant CSS parsing. Handles legacy code with syntax errors _(default: `true`)_
 - `logLevel` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Controls [log level](#loglevel) of the plugin _(default: `"info"`)_
 - `logger` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Provide a custom logger interface [logger](#logger)
 
diff --git a/packages/beasties/package.json b/packages/beasties/package.json
@@ -42,7 +42,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "scripts": {
     "build": "unbuild && node -e \"require('fs/promises').cp('src/index.d.ts', 'dist/index.d.ts')\"",
@@ -58,7 +58,8 @@
     "htmlparser2": "^10.0.0",
     "picocolors": "^1.1.1",
     "postcss": "^8.4.49",
-    "postcss-media-query-parser": "^0.2.3"
+    "postcss-media-query-parser": "^0.2.3",
+    "postcss-safe-parser": "^7.0.1"
   },
   "devDependencies": {
     "@types/postcss-media-query-parser": "0.2.4",
diff --git a/packages/beasties/src/css.ts b/packages/beasties/src/css.ts
@@ -19,14 +19,18 @@ import type { Child, Root } from 'postcss-media-query-parser'
 import type Root_ from 'postcss/lib/root'
 import { parse, stringify } from 'postcss'
 import mediaParser from 'postcss-media-query-parser'
+import safeParser from 'postcss-safe-parser'
 
 /**
  * Parse a textual CSS Stylesheet into a Stylesheet instance.
  * Stylesheet is a mutable postcss AST with format similar to CSSOM.
  * @see https://github.com/postcss/postcss/
  * @private
  */
-export function parseStylesheet(stylesheet: string) {
+export function parseStylesheet(stylesheet: string, options?: { safeParser?: boolean }) {
+  if (options?.safeParser) {
+    return safeParser(stylesheet)
+  }
   return parse(stylesheet)
 }
 
diff --git a/packages/beasties/src/index.d.ts b/packages/beasties/src/index.d.ts
@@ -64,6 +64,7 @@ export interface Options {
   fonts?: boolean
   keyframes?: string
   compress?: boolean
+  safeParser?: boolean
   logLevel?: 'info' | 'warn' | 'error' | 'trace' | 'debug' | 'silent'
   reduceInlineStyles?: boolean
   logger?: Logger
diff --git a/packages/beasties/src/index.ts b/packages/beasties/src/index.ts
@@ -494,8 +494,8 @@ export default class Beasties {
     if (!sheet)
       return
 
-    const ast = parseStylesheet(sheet)
-    const astInverse = options.pruneSource ? parseStylesheet(sheet) : null
+    const ast = parseStylesheet(sheet, { safeParser: this.options.safeParser !== false })
+    const astInverse = options.pruneSource ? parseStylesheet(sheet, { safeParser: this.options.safeParser !== false }) : null
 
     // a string to search for font names (very loose)
     let criticalFonts = ''
diff --git a/packages/beasties/src/types.ts b/packages/beasties/src/types.ts
@@ -100,6 +100,10 @@ export interface Options {
    * Compress resulting critical CSS _(default: `true`)_
    */
   compress?: boolean
+  /**
+   * Use PostCSS safe parser for fault-tolerant CSS parsing _(default: `true`)_
+   */
+  safeParser?: boolean
   /**
    * Controls {@link LogLevel log level} of the plugin _(default: `"info"`)_
    */
diff --git a/packages/beasties/test/parse.test.ts b/packages/beasties/test/parse.test.ts
@@ -74,3 +74,75 @@ describe('selector normalisation', () => {
     expect(warnSpy).not.toHaveBeenCalled()
   })
 })
+
+describe('safe parser', () => {
+  it('should handle malformed CSS by default', async () => {
+    const beasties = new Beasties()
+    const html = `
+      <html>
+        <head>
+          <style>
+            .test { color: red
+          </style>
+        </head>
+        <body>
+          <div class="test">Test</div>
+        </body>
+      </html>
+    `
+
+    // Should not throw an error with malformed CSS
+    const result = await beasties.process(html)
+
+    // Verify the HTML was processed without throwing
+    expect(result).toContain('Test')
+    expect(result).toContain('data-beasties-container')
+    // Verify the CSS was recovered and applied
+    expect(result).toContain('color')
+  })
+
+  it('should throw with malformed CSS when safeParser is disabled', async () => {
+    const beasties = new Beasties({ safeParser: false })
+    const html = `
+      <html>
+        <head>
+          <style>
+            .test { color: red
+          </style>
+        </head>
+        <body>
+          <div class="test">Test</div>
+        </body>
+      </html>
+    `
+
+    // Should throw an error with malformed CSS when safeParser is disabled
+    await expect(beasties.process(html)).rejects.toThrow()
+  })
+
+  it('should parse valid CSS correctly with safeParser disabled', async () => {
+    const beasties = new Beasties({ safeParser: false })
+    const html = `
+      <html>
+        <head>
+          <style>
+            .test { color: red; }
+            .unused { color: blue; }
+          </style>
+        </head>
+        <body>
+          <div class="test">Test</div>
+        </body>
+      </html>
+    `
+
+    const result = await beasties.process(html)
+
+    // Verify the HTML was processed correctly
+    expect(result).toContain('Test')
+    expect(result).toContain('data-beasties-container')
+    // Verify only the used CSS is included
+    expect(result).toContain('color:red')
+    expect(result).not.toContain('color:blue')
+  })
+})
diff --git a/packages/vite-plugin-beasties/package.json b/packages/vite-plugin-beasties/package.json
@@ -27,7 +27,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "scripts": {
     "build": "unbuild",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
