npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ikscodes/browser-env

v1.0.0

Published

Simulates a global browser environment using JSDOM.

Downloads

662

Readme

@ikscodes/browser-env

Simulates a global browser environment using jsdom.

This is a drop-in replacement for browser-env with built-in TypeScript typings and simple stubbing features.

This allows you to run browser modules in Node.js 6 or newer with minimal or no effort. Can also be used to test browser modules with any Node.js test framework. Please note, only the DOM is simulated, if you want to run a module that requires more advanced browser features (like localStorage), you'll need to polyfill that seperately.

❗️Important note

This module adds properties from the jsdom window namespace to the Node.js global namespace. This is explicitly recommended against by jsdom. There may be scenarios where this is ok for your use case but please read through the linked wiki page and make sure you understand the caveats. If you don't need the browser environment enabled globally, window may be a better solution.

Install

npm install --save @ikscodes/browser-env

Or if you're just using for testing you'll probably want:

npm install --save-dev @ikscodes/browser-env

Usage

// Init
import browserEnv from '@ikscodes/browser-env';
browserEnv();

// Now you have access to a browser like environment in Node.js:

typeof window;
// => 'object'

typeof document;
// => 'object'

var div = document.createElement('div');
// => HTMLDivElement

div instanceof HTMLElement
// => true

By default everything in the jsdom window namespace is tacked on to the Node.js global namespace (excluding existing Node.js properties e.g console, setTimout). If you want to trim this down you can pass an array of required properties:

// Init
import browserEnv from '@ikscodes/browser-env';
browserEnv(['window']);

typeof window;
// => 'object'

typeof document;
// => 'undefined'

You can also pass a config object straight through to jsdom. This can be done with or without specifying required properties.

import browserEnv from '@ikscodes/browser-env';
browserEnv(['window'], { userAgent: 'My User Agent' });

// or

import browserEnv from '@ikscodes/browser-env';
browserEnv({ userAgent: 'My User Agent' });

// or (it doesn't matter which order you provide the arguments).

import browserEnv from '@ikscodes/browser-env';
browserEnv({ userAgent: 'My User Agent' }, ['window']);

browser-env can also be preloaded at node startup as:

node -r @ikscodes/browser-env/register test.js

Sometimes, especially during tests, it can be useful to stub parts of Window behavior:

import browserEnv from '@ikscodes/browser-env';
import sinon from 'sinon';
browserEnv();

// Pathing argument is identical to `Lodash.get`
// (accepts an array of property identfiers or a string representation)
browserEnv.stub('document.createElement', sinon.stub());

document.createElement('iframe');
document.createElement.calledOnce // => true

// Remove all stubs
// (note: this rebuilds the window with the
//  same arguments passed to `browserEnv`).
browserEnv.restore();
document.createElement.calledOnce // => undefined

Rationale

I love browser-env, but I required just a few more features to be productive:

  1. I work mostly in TypeScript, so compatible typings are a must!
  2. I often found myself stubbing Window properties during unit tests, which also means stubbing NodeJs.Global if the property exists in the NodeJS context. This presented a challenge while trying to keep unit tests DRY.

So @ikscodes/browser-env was born. I strive to keep feature parity and drop-in compatibility with the original package.