Regression in `v1.30.2`? "Error: failed to deserialize; expected an object-like struct named Specifier, found ()"

[gossi]

I'm switching from postcss/CSS Modules to lightningcss. To do so, I need to replace composes feature.

Luckily the trick is on the website itself using custom At-Rules with @mixin.

I copied the code over to my config, it worked hooray 🎉

... until it suddenly stopped with the error:

Error: failed to deserialize; expected an object-like struct named Specifier, found ()

The code in question was this:

@mixin --base {
  color: red;

  & > header {
    color: red;
  }

  &:has(header) {
    padding-block-start: var(--spacing-container0);
  }
}

.page {
  @apply --base;
}

Particularly this caused the error:

  &:not(:has(header)) {
    padding-block-start: var(--spacing-container0);
  }

I searched for the error message and found this issue: nativewind/nativewind#1605 and yeah, once I pinned lightningcss to v1.30.1 it worked.

The error was showing up in v1.30.2.

Here is my config:

const { code, map } = bundle({
  filename: config.input,
  minify: false,
  exclude: Features.Nesting,
  customAtRules: {
    mixin: {
      prelude: '<custom-ident>',
      body: 'style-block'
    },
    apply: {
      prelude: '<custom-ident>'
    }
  },
  visitor: {
    Rule: {
      custom: {
        mixin(rule) {
          mixins.set(rule.prelude.value, rule.body.value);

          return [];
        },
        apply(rule) {
          if (mixins.has(rule.prelude.value)) {
            return mixins.get(rule.prelude.value);
          }

          return [];
        }
      }
    }
  }
});

[bjarkebech]

Ha! Had a very similar issue yesterday, beat me to the case! Spent a good amount of time debugging and arrived at the same conclusion. v1.30.1 also fixed it for me.

Minimum reproducible example

Transforming a @theme at-rule block into :root

Input CSS:

@theme {
  --blue: blue;
  --red: red;
  --primary: var(--blue);
}

Desired output CSS:

:root {
  --blue: blue;
  --red: red;
  --primary: var(--blue);
}

Of course just doing this transformation serves no real benefit, but allows us to consume these CSS variables in JavaScript.

Code:

/**
 * Set up a function that takes input CSS as a string,
 * then returns it after transformation.
 * 
 * In this minimum example, we define a single custom 
 * at-rule, @theme, a declaration list we can iterate
 * over, then transform into a `:root {}` style block.
 * 
 * I.e.:
 * Desired input:       @theme {
 *                        --test-var: #000;
 *                      }
 *     
 * Expected output:     :root {
 *                        --test-var: #000;
 *                      }
 */
const testTransform = (input: string) => {
  let res = transform({
    filename: "test.css",
    code: Buffer.from(input),
    customAtRules: {
      theme: {
        prelude: null,
        body: "declaration-list",
      },
    },
    visitor: {
      Rule: {
        custom: {
          theme(rule) {
            console.log(rule);
            /* ---- Log output: -----------------------------------------------
              {
                name: 'theme',
                prelude: null,
                body: {
                  type: 'declaration-list',
                  value: { importantDeclarations: [], declarations: [Array] }
                },
                loc: { source_index: 0, line: 1, column: 5 }
              }
            ------------------------------------------------------------------ */
            
            /* ----------------------------------------------------------------
             * Return a `style` block containing the same declarations.
             * Add :root as our lone selector.
             ------------------------------------------------------------------ */
            return {
              type: "style",
              value: {
                selectors: [[{ type: "pseudo-class", kind: "root" }]],
                loc: rule.loc,
                declarations: rule.body.value,
              },
            };
          },
        },
      },
    },
  });

  return res;
}

✅ Example one - works fine

/**
 * Example one: 
 * No CSS functions used in variable definitions:
 */

const exampleOne = `
@theme {
  --blue: blue;
  --green: green;
}
`;

console.log(testTransform(exampleOne));
// Works fine. Returns:
// :root {
//   --blue: blue;
//   --green: green;
// }

❌ Example two - breaks on v1.30.2

/**
 * Example two: 
 * Use the var() function inside the at-rule block.
 */

const exampleTwo = `
@theme {
  --blue: blue;
  --green: green;
  --primary: var(--blue);
}
`;

console.log(exampleTwo);
// Breaks.
// Error: failed to deserialize; expected an object-like struct named Specifier, found ()
//     at <anonymous> (test.ts:3:16)
//     at Object.<anonymous> (test.ts:50:32)
//     at Module._compile (node:internal/modules/cjs/loader:1730:14)
//     at Object.transformer (/Users/bjarkebech/.nvm/versions/node/v22.15.0/lib/node_modules/tsx/dist/register-D46fvsV_.cjs:3:1104)
//     at Module.load (node:internal/modules/cjs/loader:1465:32)
//     at Function._load (node:internal/modules/cjs/loader:1282:12)
//     at TracingChannel.traceSync (node:diagnostics_channel:322:14)
//     at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
//     at cjsLoader (node:internal/modules/esm/translators:266:5)
//     at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:200:7) {
//   code: 'InvalidArg'
// }

I don't know exactly what broke this, but the var() statement definitely trips it up.

[mattpilott]

#1065

[mpech]

tldr my fix: visited node {"type":"var","value":{"name":{"ident":"--a","from":null},"fallback":null}} should not be returned as is but as {"type":"var","value":{"type":"dashed-ident","name":{"ident":"--a"}}}

For my case:

❌

const { code } = lightTransform({
  code: Buffer.from('.a{padding: getTruePx(var(--a))}'),
  visitor: {
    Function: {
      getTruePx({ arguments: [value] }) {
        console.log('somelog', JSON.stringify(value))
        return value
      }
    }
  }
})

gives

somelog {"type":"var","value":{"name":{"ident":"--a","from":null},"fallback":null}}
error: failed to deserialize; expected an object-like struct named Specifier, found ()

The problem stems from value.value which should be a dashed-ident (and not directly the value.value passed in)

✅

const { code } = lightTransform({
  code: Buffer.from('.a{padding: getTruePx(var(--a))}'),
  visitor: {
    Function: {
      getTruePx({ arguments: [value] }) {
        const name = value.value.name
        return {
          type:'var',
          value: {
            type: 'dashed-ident', // <-- add type dashed-ident here
            name: {
              ident: name.ident
            }
          }
        }
      }
    }
  }
})

The second problem is that if fallback is null such as above, you can not put it either (fallback being filled for case like (var(--a, 1))

❌

const { code } = lightTransform({
  code: Buffer.from('.a{padding: getTruePx(var(--a))}'),
  visitor: {
    Function: {
      getTruePx({ arguments: [value] }) {
        const name = value.value.name
        const fallback = value.value.fallback // null here
        return {
          type:'var',
          value: {
            type: 'dashed-ident',
            fallback, // will give  failed to deserialize; expected a sequence, found ()
            name: {
              ident: name.ident
            }
          }
        }
      }
    }
  }
})

So you have to ensure its non nullness although ast.d.ts say null is accepted

export interface Variable {
  /**
   * A fallback value in case the variable is not defined.
   */
  fallback?: TokenOrValue[] | null;
  /**
   * The variable name.
   */
  name: DashedIdentReference;
}

✅

const { code } = lightTransform({
  code: Buffer.from('.a{padding: getTruePx(var(--a))}'),
  visitor: {
    Function: {
      getTruePx({ arguments: [value] }) {
        console.log('somelog', JSON.stringify(value))
        const name = value.value.name
        const fallback = value.value.fallback // null here
        return {
          type:'var',
          value: {
            type: 'dashed-ident',
            ...(fallback ? { fallback } : undefined), // <-- do not fill fallback if null
            name: {
              ident: name.ident,
            }
          }
        }
      }
    }
  }
})

---

I ended up with something like

  const customProperty = (varName, fallback) => ({
    type: 'var',
    value: { type: 'dashed-ident', name: { ident: varName }, ...(fallback ? { fallback } : {}) }
  })
  const fixVarType = node => {
    if (node.type === 'var') {
      return customProperty(node.value.name.ident, node.value.fallback ? node.value.fallback.map(fixVarType) : null)
    }
    if (node.type === 'function') {
      return { ...node, value: { ...node.value, arguments: node.value.arguments.map(fixVarType) } }
    }
    return node
  }
  const { code } = lightTransform({
    code: Buffer.from('.a{padding: getTruePx(var(--a, var(--b, 1)))}'),
    visitor: {
      Function: {
        getTruePx({ arguments: [value] }) {
          return {
            type: 'function',
            value: {
              name: 'calc',
              arguments: [
                fixVarType(value),
                { type: 'token', value: { type: 'delim', value: '*' } },
                customProperty('--size-index', [num(2)])
              ]
            }
          }
        }
      }
    }
  })

which does give

padding: calc(var(--a, var(--b, 1)) * var(--size-index, 2));

• I have not handled the "from" next to "ident" property since I never saw it filled, but I guess same undefined trick applies

• Maybe there is a better way to do it

• I still feel it is a bit strange that we can't give back the ast node (in case of var type) passed as is. This forces us to transform the ast to conserve identity

Hopefully this workaround may help some, I lurked this thread for a while thinking my problem is related

[mattpilott]

I was really hoping 1.31.0 would include a fix for this, but alas it does not

[Exagone313]

The version 1.31.0 fixes an issue with minify used along the @mixin customAtRule, but I'm also hit by this regression.

Since I need to use var() for configurable theming, I'm disabling minify and pinning to version 1.30.1.

[reify-benjamin-solum]

Also running into this issue across multiple projects forcing us to pin to 1.30.1.

[reify-benjamin-solum]

@mattpilott , or anyone... any update here? This has been plaguing our app for awhile and it's getting increasingly difficult to pin the version to 1.30.1. Tailwind v4 introduced @theme which is the crux of our issue. If there was someway to allow for custom @ rules it'd be huge.

[mattpilott]

@reify-benjamin-solum no solution as yet, just have to relentlessly set it to 1.30.1 until a fix lands 🙃

[Brentlok]

In my case the issue was "null" values present in objects

function removeNulls(value: unknown): unknown {
    if (Array.isArray(value)) {
        return value.map(v => this.removeNulls(v))
    }

    if (typeof value === 'object' && value !== null) {
        return Object.fromEntries(
            Object.entries(value)
                .filter(([_, value]) => {
                    if (value === null) {
                        return false
                    }

                    return true
                })
                .map(([key, value]) => [key, this.removeNulls(value)]),
        )
    }

    return value
}

Using this simple util helped me, maybe it can help the others

Usage

{
    Rule: {
      container: rule => {
        return removeNulls(rule)
      }
    }
}