can-use-dom: Browser DOM Detection Utility

0.1.0 · abandoned · verified Sun Apr 19

This package provides a very minimalist utility to determine if the current JavaScript environment has access to the Document Object Model (DOM), primarily used for writing isomorphic (universal) JavaScript applications that need to behave differently client-side versus server-side. It exports a simple boolean value, `true` if `window`, `window.document`, and `window.document.createElement` are all defined, and `false` otherwise. The package is extremely lightweight with no dependencies. First released as version `0.1.0` and last updated over nine years ago, its development is considered abandoned. Due to its age, it primarily uses CommonJS module syntax, meaning direct native ESM imports may not function without a bundler or transpilation layer. Modern alternatives often include more sophisticated environment detection or rely on frameworks to abstract these differences. Its main differentiator is its absolute simplicity and singular focus, though its lack of maintenance makes it a less reliable choice for new projects.

Common errors

```
SyntaxError: Named export 'canUseDOM' not found (module 'can-use-dom' does not have an export named 'canUseDOM')
```
cause Attempting to use ES Module named import syntax (`import { canUseDOM } from 'can-use-dom';`) for a package that only exports via CommonJS `module.exports = ...`.

fix Change the import statement to `const canUseDOM = require('can-use-dom');`.
```
TypeError: Cannot read properties of undefined (reading 'document')
```
cause Executing code that accesses `document` or `window` APIs in a non-browser environment (e.g., Node.js) where `canUseDOM` returned `false`, but the conditional check was missed or misconfigured.

fix Ensure all browser-specific code paths are strictly guarded by `if (canUseDOM) { ... }` or equivalent environment checks, especially when developing isomorphic applications.

Warnings

breaking The package exclusively uses CommonJS (`module.exports`). Attempting to use native ES Module `import` syntax will likely result in a runtime error or `undefined` due to a lack of named or default exports, unless your build process specifically transpiles or bundles it.
Fix: Always use `const canUseDOM = require('can-use-dom');` for direct usage. For projects targeting modern ESM, ensure your bundler (e.g., Webpack, Rollup, Vite) is configured to handle CommonJS modules.
gotcha This package has not been updated in over nine years (since its initial 0.1.0 release). Its lack of maintenance means it may not address modern browser environments, server-side rendering (SSR) complexities (e.g., JSDOM contexts), or security best practices.
Fix: For new projects, consider more actively maintained alternatives or implement your own robust environment detection tailored to your specific needs. For existing projects, be aware of potential compatibility issues with newer environments.
gotcha The DOM detection logic is very basic (`window`, `document`, `createElement` existence). It might not differentiate between a full browser environment and a mocked DOM environment (like JSDOM used in testing or some SSR setups) which could lead to unexpected behavior if specific browser-only APIs are invoked.
Fix: If running in a mocked DOM environment, you might need additional checks to distinguish it from a real browser. For more granular control, extend the check with specific API detections or rely on framework-level environment variables.

Install

npm install can-use-dom npm
yarn add can-use-dom yarn
pnpm add can-use-dom pnpm

Imports

canUseDOM
wrong:
```
import canUseDOM from 'can-use-dom';
// or
import { canUseDOM } from 'can-use-dom';
```
correct:
```
const canUseDOM = require('can-use-dom');
```
This package exports a raw boolean value directly via CommonJS's `module.exports`. Direct native ESM imports may fail or result in `undefined` without bundler transformation, as there are no named or default exports.

Quickstart

Demonstrates how to import and use the `can-use-dom` boolean to conditionally execute browser-specific code.

const canUseDOM = require('can-use-dom');

if (canUseDOM) {
  console.log('Current environment supports DOM operations.');
  // Example: Manipulate the DOM if available
  const rootElement = document.getElementById('root');
  if (rootElement) {
    rootElement.innerHTML = '<h1>Hello from the browser!</h1>';
    console.log('DOM updated successfully.');
  }
} else {
  console.log('Current environment does NOT support DOM operations (e.g., Node.js server).');
  // Example: Server-side rendering logic or other non-DOM operations
  console.log('Performing server-side specific tasks...');
}

// To run this in Node.js, simply execute the file.
// To run this in a browser, embed it in an HTML script tag or use a bundler.

view raw JSON →