[Bug]: PurgeCSS ESM Loader Fails on Windows Drive Letters

[iamrobert]

Describe the bug

When using PurgeCSS 7.x (ESM) on Windows, running purgecss --config some-path\purgecss.config.js throws an error about "Only URLs with a scheme in: file, data, and node are supported by the default ESM loader".

Specifically, Node sees D: as a custom protocol, which PurgeCSS doesn't handle, resulting in Received protocol 'd:'.

To Reproduce

1. Install PurgeCSS v7 (Globally or Locally):

npm install -g purgecss@latest
# or locally
npm install --save-dev purgecss@latest

2. Place a purgecss.config.js in D:\projects\my-site\.

3. Attempt:

purgecss --config .\purgecss.config.js

Expected Behavior

PurgeCSS should load the config file without error, just as in older versions.

What I've Tried

• Renaming the config to .cjs or .mjs
• Using export default vs module.exports
• Using relative paths, absolute paths, and file:///D:/...
• Defining "type": "commonjs" in package.json
• Installing PurgeCSS locally and calling via npx

All approaches result in the same error on Windows. The only workaround is to downgrade to PurgeCSS 4.1.3 (pre-ESM).

Environment

• Windows 11
• Node.js v20.x
• PurgeCSS v7.x.x (Global or Local Installation)
• Drive-based path (e.g., D:\projects\my-site\purgecss.config.js)

Add any other context about the problem here

Workarounds

Downgrade to PurgeCSS 4.1.3

npm uninstall purgecss
npm install --save-dev purgecss@4.1.3

A fix in PurgeCSS’s CLI to handle Windows drive letters would help.

Code of Conduct

• I agree to follow this project's Code of Conduct

[aubreyz]

Is indeed broken in Windows. Broken too in 4.1.3

[kylichist]

What is the current state of this issue?

[jediwade]

@iamrobert @aubreyz @kylichist I was encountering the same issue and I fixed it locally.

Best I can tell is there are two main issues.

The first is referenced here and here. The issue is related to how dynamic imports are handled (possibly an issue exclusive to NodeJS because the MDN docs show examples without protocol paths).

The second issue is that file handling has hardcoded expectations for forward slashed paths and doesn't account for Windows backslash paths.

Below are the changes I made on the most recent release if you want to replicate them on your machine.

If you used the global install option, you will find the purgecss.js file here:
C:\Users\{your_user_name}\AppData\Roaming\npm\node_modules\purgecss\bin\purgecss.js

Local installs will be likely just be here: node_modules\purgecss\bin

FIRST CHANGE for handling the dynamic import issue:

options = await import(t);

becomes

options = await import("file://" + t);
options = options?.default ?? options;

.

.

SECOND CHANGE to handle Windows slashes:

if (purged.length === 1 && options.output.endsWith(".css")) {
    await writeCSSToFile(options.output, purged[0].css);
    return;
}
for (const purgedResult of purged) {
    const fileName = (_a = purgedResult === null || purgedResult === void 0 ? void 0 : purgedResult.file) === null || _a === void 0 ? void 0 : _a.split("/").pop();
    await writeCSSToFile(`${options.output}/${fileName}`, purgedResult.css);
}

becomes

if (purged.length === 1 && options.output.endsWith(".css")) {
    await writeCSSToFile(options.output.replaceAll("\\", "/"), purged[0].css);// fix slashes
    return;
}
for (const purgedResult of purged) {
    const fileName = purgedResult?.file.replaceAll("\\", "/").split("/").pop();// fix slashes
    await writeCSSToFile(`${options.output}/${fileName}`, purgedResult.css);
}

.

.
FINAL [optional] CHANGE to deal with folder creation. On my machine, it fails if the output folder doesnt exist, so this handles that issue:

async function writeCSSToFile(filePath, css) {
    try {
        await fs__namespace.promises.writeFile(filePath, css);
    }
    catch (err) {
        if (err instanceof Error) {
            console.error(err.message);
        }
    }
}

becomes

async function writeCSSToFile(filePath, css) {
    const folderPath = filePath.substring(0, filePath.lastIndexOf("/"));
    
    // check if folder path exists first
    try {
        await asyncFs.access(folderPath, fs__namespace.constants.F_OK);
    }
    catch (err) {
        // try to create full folder path
        try {
            await fs__namespace.promises.mkdir(folderPath, {recursive: true});
        }
        catch (suberr) {
            if (suberr instanceof Error) {
                console.error(err.message);
            }
        }
    }
    
    // create file
    try {
        await fs__namespace.promises.writeFile(filePath, css);
    }
    catch (err) {
        if (err instanceof Error) {
            console.error(err.message);
        }
    }
}