css.preprocessorOptions type error with sass importers

[morganney]

Describe the bug

I'm trying to use the sass pkg: importers by configuring a NodePackageImporter instance from sass-embedded in my css.preprocessorOptions but am encountering a type error:

Type 'NodePackageImporter' is not assignable to type 'NodePackageImporter | Importer<"async"> | FileImporter<"async">'.

If I use NodePackageImporter from sass instead, I get this error:

[vite:css] [sass] Error: TypeError: importer.findFileUrl is not a function

I saw this discussion reported a similar error: #17948

Reproduction

None

Steps to reproduce

My vite.config.ts configuration looks like this:

import {defineConfig} from 'vite';
import {NodePackageImporter} from 'sass-embedded';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        importers: [
          new NodePackageImporter(),
        ],
      },
    },
  },
});

The importers option seems to be typed from the sass package and not sass-embedded, so I do this to get around the type error:

import {defineConfig} from 'vite';
import {NodePackageImporter} from 'sass-embedded';
import {NodePackageImporter as DartSassPackageImporter} from 'sass';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        importers: [
          new NodePackageImporter() as unknown as DartSassPackageImporter,
        ],
      },
    },
  },
});

System Info

System:
    OS: macOS 15.4.1
    CPU: (14) arm64 Apple M4 Pro
    Memory: 2.64 GB / 24.00 GB
    Shell: 3.2.57 - /bin/bash
  Binaries:
    Node: 22.15.0 - ~/n/bin/node
    npm: 10.9.2 - ~/n/bin/npm
    pnpm: 10.9.0 - ~/n/bin/pnpm
  Browsers:
    Chrome: 137.0.7151.68
    Safari: 18.4
  npmPackages:
    @vitejs/plugin-react: ^4.5.0 => 4.5.0 
    vite: ^6.3.5 => 6.3.5

Used Package Manager

pnpm

Logs

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a Vite issue and not a framework-specific issue. For example, if it's a Vue SFC related bug, it should likely be reported to vuejs/core instead.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[sapphi-red]

Probably this has to be swapped as Vite prefers sass-embedded over sass.
https://github.com/vitejs/vite/blob/7dfcb316ee64aca0a98a1d2905deb1dfd113ae6d/packages/vite/types/internal/cssPreprocessorOp
tions.d.ts#L19-L22

[morganney]

Vite lists sass as a peerDependency albeit optional. sass-loader also lists sass as a peerDependency.

The project I discovered this in is using pnpm workspaces, and by default peer deps are auto installed: https://pnpm.io/next/settings#autoinstallpeers. The project also uses vite for storybook stuff, and rspack with sass-loader for the main build, so the sass peer dep has been installed (default pnpm settings).

In this case IsAny<DartSassStringOptionsAsync> extends false will always be true so people importing from sass-embedded will still have there options typed against dart sass due to the lines you mentioned:

type SassStringOptionsAsync =
  IsAny<DartSassStringOptionsAsync> extends false
    ? DartSassStringOptionsAsync
    : SassEmbeddedStringOptionsAsync

So the assumption // @ts-ignore `sass` may not be installed behind the above logic fails in the default case for pnpm workspaces using vite or sass loader.

[sapphi-red]

Vite and sass-loader both marks sass as an optional peer dep. pnpm only automatically installs peer deps that is not optional.

When true, any missing non-optional peer dependencies are automatically installed.

[morganney]

That is what the pnpm documentation states, but it doesn't seem to be behaving that way. In the project I'm working on it is still installing the optional peer deps.

morgan@mactop ~/code/vortex-app/frontend (chore/ws-refactor)$ pnpm why -r sass
Legend: production dependency, optional only, dev only

storybook@0.0.0 /Users/morgan/code/vortex-app/frontend/apps/storybook (PRIVATE)

devDependencies:
@storybook/react-vite 9.0.0
├─┬ @joshwooding/vite-plugin-react-docgen-typescript 0.6.0
│ └─┬ vite 6.3.5 peer
│   └── sass 1.89.0 peer
├─┬ @storybook/builder-vite 9.0.0
│ └─┬ vite 6.3.5 peer
│   └── sass 1.89.0 peer
└─┬ vite 6.3.5 peer
  └── sass 1.89.0 peer
@vanilla-extract/vite-plugin 5.0.1
├─┬ @vanilla-extract/compiler 0.1.2
│ ├─┬ vite 6.3.5
│ │ └── sass 1.89.0 peer
│ └─┬ vite-node 3.1.3
│   └─┬ vite 6.3.5
│     └── sass 1.89.0 peer
└─┬ vite 6.3.5 peer
  └── sass 1.89.0 peer
@vitejs/plugin-react 4.5.0
└─┬ vite 6.3.5 peer
  └── sass 1.89.0 peer
vite 6.3.5
└── sass 1.89.0 peer

vortex-frontend@1.0.0 /Users/morgan/code/vortex-app/frontend/apps/vortex (PRIVATE)

devDependencies:
sass-loader 16.0.5
└── sass 1.89.0 peer

@gl/app@1.0.0 /Users/morgan/code/vortex-app/frontend/packages/app (PRIVATE)

devDependencies:
@storybook/react-vite 9.0.0
├─┬ @joshwooding/vite-plugin-react-docgen-typescript 0.6.0
│ └─┬ vite 6.3.5 peer
│   └── sass 1.89.0 peer
├─┬ @storybook/builder-vite 9.0.0
│ └─┬ vite 6.3.5 peer
│   └── sass 1.89.0 peer
└─┬ vite 6.3.5 peer
  └── sass 1.89.0 peer
morgan@mactop ~/code/vortex-app/frontend (chore/ws-refactor)$ pnpm --version
10.9.0

The pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'packages/*'
onlyBuiltDependencies:
  - core-js
  - esbuild

The pnpm-lockfile.yaml has this at the beginning, so maybe something with legacy entries:

lockfileVersion: '9.0'

settings:
  autoInstallPeers: true

I'll try to find some time to set up a minimal reproduction using pnpm workspaces. I have confirmed though that your suggestion fixes this for me, that is to reverse the order of checking sass options:

type SassStringOptionsAsync =
  IsAny<SassEmbeddedStringOptionsAsync> extends false
    ? SassEmbeddedStringOptionsAsync
    : DartSassStringOptionsAsync

[morganney]

Perhaps the autoInstallPeers setting of pnpm is referring to optionalDependencies and peerDependenciesMeta does not matter?

I'll try https://pnpm.io/settings#ignoredoptionaldependencies tomorrow and see if it also helps.

[sapphi-red]

I think pnpm installing optional peer dep automatically with autoInstallPeers=true is a bug in pnpm.

That aside, even if both sass-embedded and sass is installed, Vite is supposed to prefer the types from sass-embedded.
So if the type change works for you, feel free to send a PR.

[morganney]

What version should this PR target? For instance v7.0.0-beta.0 removes the api option. I can target the latest commit against v6.3.5 and keep the api option intact.

This seems to provide the direction y'all want to move in: #17728 (comment)