CSS Browser Support Linter

Common errors

• Error: Cannot find module 'doiuse/lib/DoIUse.js'

  cause Attempting to import the `DoIUse` class incorrectly, often from the main package entry point or with a wrong path.
  fix Ensure you are importing from the correct path: `import DoIUse from 'doiuse/lib/DoIUse.js';` for ESM or `const DoIUse = require('doiuse/lib/DoIUse');` for CommonJS.

• SyntaxError: Unexpected token 'export' (for ESM usage in CJS context) OR require() of ES Module (for CJS usage in ESM context)

  cause Mixing ESM `import` statements with CommonJS `require()` or vice-versa, or running a module type in an incompatible environment.
  fix For ESM, ensure your project is configured with `"type": "module"` in `package.json` and use `import` statements. For CommonJS, use `require()` and ensure files are `.js` or `.cjs`. Doiuse v6.x is largely ESM-first, so adjust your imports accordingly.

• TypeError: doiuse is not a function

  cause This typically happens when trying to call `doiuse` directly after a `require('doiuse')` which returns the CLI function, not the PostCSS plugin or stream constructor.
  fix For programmatic use, ensure you are importing the specific PostCSS plugin or stream entry point: `const doiusePlugin = require('doiuse/lib/DoIUse');` or `const doiuseStream = require('doiuse/stream');`.

Warnings

• breaking Version 6.0.0 of `doiuse` dropped support for Node.js v12 and v14. Projects must upgrade to Node.js v16 or higher.
  Fix: Upgrade your Node.js environment to version 16 or newer. For projects that cannot upgrade Node.js, remain on `doiuse` v5.x or earlier.
• breaking Older versions of `doiuse` (prior to v4.3.0) dropped support for Node.js versions older than 10.x and 4.x respectively. Ensure your Node.js version meets the minimum requirements for your `doiuse` version.
  Fix: Check the `engines` field in `package.json` for the specific `doiuse` version you are using. Upgrade Node.js or `doiuse` as necessary.
• gotcha The `doiuse` package uses specific import paths for its PostCSS plugin and stream API (e.g., `doiuse/lib/DoIUse.js`, `doiuse/stream`). Direct `import DoIUse from 'doiuse'` or `require('doiuse')` will not work for programmatic usage as intended for the plugin or stream.
  Fix: For the PostCSS plugin, use `import DoIUse from 'doiuse/lib/DoIUse.js'` (ESM) or `const DoIUse = require('doiuse/lib/DoIUse');` (CJS). For the stream, use `import doiuse from 'doiuse/stream'` or `const doiuse = require('doiuse/stream');`.
• gotcha The feature detection in `doiuse` is described as 'quite naive,' primarily relying on regex/substring matches of property and value names. It may not catch all nuanced browser compatibility issues, especially those involving complex CSS interactions or JavaScript polyfills.
  Fix: Treat `doiuse` as a strong first line of defense for basic property/value support. Supplement its findings with actual browser testing and more advanced linting tools if detailed interaction compatibility is critical. Manually inspect the `data/features.js` file for specifics on how features are detected.

Install

• npm install doiuse npm
• yarn add doiuse yarn
• pnpm add doiuse pnpm

Imports

• DoIUse
  wrong:

  import { DoIUse } from 'doiuse';

  correct:

  import DoIUse from 'doiuse/lib/DoIUse.js';

  The primary PostCSS plugin class is a default export from its specific path, not a named export from the main package. This is due to its internal structure.
• doiuse
  wrong:

  import { doiuse } from 'doiuse';

  correct:

  import doiuse from 'doiuse/stream';

  When using doiuse as a transform stream, the function is a default export from the 'doiuse/stream' entry point. The main 'doiuse' package itself primarily exposes the CLI.
• require('doiuse')
  wrong:

  const { DoIUse } = require('doiuse');

  correct:

  const doiuseCli = require('doiuse');

  The main 'doiuse' export is primarily for the CLI. For programmatic use, prefer `doiuse/lib/DoIUse.js` for PostCSS or `doiuse/stream` for stream-based processing, especially since v6.x for better ESM compatibility.
• DoIUse (CommonJS)
  wrong:

  const DoIUse = require('doiuse');

  correct:

  const DoIUse = require('doiuse/lib/DoIUse');

  For CommonJS environments, the PostCSS plugin class is found at `doiuse/lib/DoIUse`. Note the missing `.js` extension for CommonJS imports often works, but explicit is better for clarity.

Quickstart

This quickstart demonstrates how to use `doiuse` as a PostCSS plugin to lint CSS for browser compatibility, targeting specific browser versions and logging unsupported feature usages to the console.

import postcss from 'postcss';
import DoIUse from 'doiuse/lib/DoIUse.js';

const cssInput = `
a { 
  background-size: cover; 
  display: flex; /* flexbox support */
  user-select: none;
  scroll-snap-align: start;
}

.gradient {
  background-image: conic-gradient(white, black);
}
`;

postcss(new DoIUse({
  browsers: ['last 2 chrome versions', 'ie 11'], // Target specific browsers
  ignore: ['flexbox', 'user-select-none'], // Optional: ignore specific features by 'caniuse' ID
  ignoreFiles: ['**/node_modules/**'], // Optional: ignore files matching these globs
  onFeatureUsage: (usageInfo) => {
    // Log detailed information about each unsupported feature found
    console.log(`[doiuse] ${usageInfo.message} in ${usageInfo.feature} for ${usageInfo.browsers.join(', ')} at ${usageInfo.source.start.line}:${usageInfo.source.start.column}`);
  }
})).process(cssInput, { from: 'example.css' })
  .then(result => {
    console.log('\nProcessed CSS (no changes made by doiuse):\n', result.css);
  })
  .catch(error => {
    console.error('PostCSS processing failed:', error);
  });