matchmediaquery

Common errors

• ERR_REQUIRE_ESM: require() of ES module /path/to/node_modules/matchmediaquery/index.js from /path/to/your/app.js not supported.

  cause Attempting to use `require()` in an ES module (type: 'module' in package.json) environment, or vice-versa, when the library is exclusively CommonJS.
  fix For CommonJS-only libraries, ensure your project's `package.json` does NOT have `"type": "module"` if you are using `require()`. If your project is ESM-native, you might need to use dynamic `import('matchmediaquery')` or resort to a bundler to handle CJS modules.

• TypeError: (0 , matchmediaquery_1.matchMediaQuery) is not a function

  cause This typically occurs when trying to destructure a CommonJS default export as a named export in an ES module environment, or if a bundler incorrectly transpiles the module.
  fix Import the library as a default CommonJS export: `const matchMediaQuery = require('matchmediaquery');` if in a CJS context. If using a bundler with ESM, ensure it correctly handles CJS default exports.

• TS2307: Cannot find module 'matchmediaquery' or its corresponding type declarations.

  cause The TypeScript compiler cannot locate type definitions for the `matchmediaquery` package.
  fix Create a manual type declaration file (e.g., `global.d.ts` or `matchmediaquery.d.ts`) in your project. Add `declare module 'matchmediaquery' { function matchMediaQuery(query: string, options?: object): boolean; export = matchMediaQuery; }` to define its interface.

Warnings

• breaking The library is considered abandoned. Its last update was in 2015, meaning it does not support modern JavaScript features, module systems (ESM), or contemporary CSS media query specifications (e.g., `prefers-color-scheme`, `dynamic-range`). Using it in a modern project will likely lead to compatibility issues and missing functionality.
  Fix: Migrate to a modern, actively maintained library for isomorphic media queries or use client-side `window.matchMedia` directly for browser contexts. Consider libraries like `react-responsive` (for React) or custom solutions.
• gotcha The library is exclusively CommonJS. Attempting to use `import` statements directly in an ESM-native Node.js project or without a bundler configured for CJS interop will result in a module resolution error.
  Fix: Ensure your environment supports CommonJS `require()` or configure your bundler (e.g., Webpack, Rollup) to correctly transpile CJS modules. In Node.js, use `const matchMediaQuery = require('matchmediaquery');`
• gotcha There are no official TypeScript type definitions available for `matchmediaquery`. Developers using TypeScript will encounter 'Could not find a declaration file for module' errors or have to manually declare types.
  Fix: Create a custom declaration file (e.g., `matchmediaquery.d.ts`) to provide type information. Example: `declare module 'matchmediaquery' { function matchMediaQuery(query: string, options?: object): boolean; export = matchMediaQuery; }`
• gotcha The library's server-side simulation relies on specific options (e.g., `width`, `height`, `devicePixelRatio`) being passed to accurately evaluate media queries. Without these, it may make incorrect assumptions or return unexpected results.
  Fix: Always provide a comprehensive set of viewport and device-specific options (e.g., `width`, `height`, `type`, `devicePixelRatio`) when using `matchMediaQuery` in a server-side context to ensure accurate simulation of the target environment.

Install

• npm install matchmediaquery npm
• yarn add matchmediaquery yarn
• pnpm add matchmediaquery pnpm

Imports

• matchMediaQueryFunction
  wrong:

  import matchMediaQuery from 'matchmediaquery';

  correct:

  const matchMediaQuery = require('matchmediaquery');

  The library primarily uses CommonJS module exports. Direct ESM 'import' syntax is not supported without a transpiler or bundler setup that explicitly handles CommonJS modules.
• matchMediaQueryFunction (named)
  wrong:

  const { matchMediaQuery } = require('matchmediaquery');

  correct:

  const matchMediaQuery = require('matchmediaquery');

  The library exports a single function as its default (module.exports), not a named property. Destructuring will result in `undefined`.
• Type Definition
  wrong:

  import type { MatchMediaQuery } from 'matchmediaquery';

  correct:

  /// <reference types="matchmediaquery" />

  No official TypeScript type definitions are shipped with the package, nor are they available on DefinitelyTyped. Type declarations would need to be created manually if used in a TypeScript project.

Quickstart

Demonstrates how to import and use `matchmediaquery` to evaluate media queries, including server-side simulation of viewport properties.

const matchMediaQuery = require('matchmediaquery');

// Example 1: Basic media query check (client-side/browser context)
// In a browser, this will use window.matchMedia. On the server,
// it simulates based on provided or default properties.
const isSmallScreen = matchMediaQuery('(max-width: 600px)');
console.log(`Is small screen (browser context): ${isSmallScreen}`);

// Example 2: Server-side simulation with specific viewport properties
// This allows you to test media queries on the server without a DOM.
const simulateMobile = matchMediaQuery('(min-width: 320px) and (max-width: 768px)', {
  type: 'screen',
  width: 375, // Simulate iPhone width
  height: 667,
  devicePixelRatio: 2
});
console.log(`Is mobile (server simulated): ${simulateMobile}`);

// Example 3: Another server-side check for a larger desktop screen
const simulateDesktop = matchMediaQuery('(min-width: 1024px)', {
  type: 'screen',
  width: 1280,
  height: 800,
  devicePixelRatio: 1
});
console.log(`Is desktop (server simulated): ${simulateDesktop}`);