CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ssr-window

Better handling for window and document objects in SSR environment

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

SSR Window

SSR Window provides safe handling for window and document objects in server-side rendering (SSR) environments. Unlike full DOM implementations like JSDOM, it provides minimal patches to prevent SSR applications from throwing errors when accessing browser-specific APIs. This lightweight approach ensures compatibility without the overhead of complete DOM simulation.

Package Information

  • Package Name: ssr-window
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install ssr-window

Core Imports

import { getWindow, getDocument, ssrWindow, ssrDocument, extend } from "ssr-window";

For CommonJS:

const { getWindow, getDocument, ssrWindow, ssrDocument, extend } = require("ssr-window");

Basic Usage

import { getWindow, getDocument } from "ssr-window";

// Get safe window and document objects
const window = getWindow();
const document = getDocument();

// Use them safely in SSR environment
window.addEventListener('resize', () => {
  console.log('Resize event (safe in SSR)');
});

const div = document.createElement('div');
div.setAttribute('class', 'container');

// Query DOM safely (returns null/empty arrays in SSR)
const elements = document.querySelectorAll('.item');

Architecture

SSR Window is built around two core concepts:

  • Safe Object Patching: Extends existing browser objects with SSR-safe fallbacks when properties are missing
  • Pre-configured Objects: Provides ssrWindow and ssrDocument objects with safe default implementations
  • Extensibility: Allows customization through the extend utility for adding application-specific properties

Capabilities

Window Management

Safe window object handling that works in both browser and SSR environments.

/**
 * Returns a patched Window object that works in both browser and SSR environments
 * @returns Window object extended with SSR-safe properties
 */
function getWindow(): Window;

/**
 * Pre-configured window-like object with SSR-safe properties and methods
 */
declare const ssrWindow: {
  document: typeof ssrDocument;
  navigator: {
    userAgent: string;
  };
  location: {
    hash: string;
    host: string;
    hostname: string;
    href: string;
    origin: string;
    pathname: string;
    protocol: string;
    search: string;
  };
  history: {
    replaceState(): void;
    pushState(): void;
    go(): void;
    back(): void;
  };
  CustomEvent: () => any;
  addEventListener(): void;
  removeEventListener(): void;
  getComputedStyle(): {
    getPropertyValue(): string;
  };
  Image(): void;
  Date(): void;
  screen: {};
  setTimeout(): void;
  clearTimeout(): void;
  matchMedia(): {};
  requestAnimationFrame(callback: any): NodeJS.Timeout | null;
  cancelAnimationFrame(id: any): void;
};

Usage Examples:

import { getWindow, ssrWindow } from "ssr-window";

// Get patched window object (browser window + SSR fallbacks)
const window = getWindow();
window.requestAnimationFrame(() => {
  // Safe in both browser and SSR
});

// Access pre-configured SSR window directly
console.log(ssrWindow.navigator.userAgent); // Returns empty string in SSR

Document Management

Safe document object handling for DOM operations in SSR environments.

/**
 * Returns a patched Document object that works in both browser and SSR environments
 * @returns Document object extended with SSR-safe properties
 */
function getDocument(): Document;

/**
 * Pre-configured document-like object with SSR-safe properties and methods
 */
declare const ssrDocument: {
  body: {};
  addEventListener(): void;
  removeEventListener(): void;
  activeElement: {
    blur(): void;
    nodeName: string;
  };
  querySelector(): null;
  querySelectorAll(): any[];
  getElementById(): null;
  createEvent(): {
    initEvent(): void;
  };
  createElement(): {
    children: any[];
    childNodes: any[];
    style: {};
    setAttribute(): void;
    getElementsByTagName(): any[];
  };
  createElementNS(): {};
  importNode(): null;
  location: {
    hash: string;
    host: string;
    hostname: string;
    href: string;
    origin: string;
    pathname: string;
    protocol: string;
    search: string;
  };
};

Usage Examples:

import { getDocument, ssrDocument } from "ssr-window";

// Get patched document object (browser document + SSR fallbacks)
const document = getDocument();
const element = document.createElement('div'); // Safe in SSR
element.setAttribute('class', 'container');

// Access pre-configured SSR document directly
const results = ssrDocument.querySelectorAll('.items'); // Returns [] in SSR

Object Extension

Utility for safely extending objects with additional properties, used internally and available for custom extensions.

/**
 * Safely extends target object with source object properties
 * Recursively merges objects while avoiding prototype pollution
 * @param target - Target object to extend (defaults to empty object)
 * @param src - Source object to copy properties from (defaults to empty object)
 */
function extend(target?: any, src?: any): void;

Usage Examples:

import { ssrWindow, ssrDocument, extend } from "ssr-window";

// Extend ssrWindow with custom properties
extend(ssrWindow, {
  navigator: {
    language: 'en-US',
    platform: 'linux',
  },
  customProperty: 'custom value',
});

// Extend ssrDocument with custom properties
extend(ssrDocument, {
  body: {
    classList: {
      add: () => {},
      remove: () => {},
    },
  },
  title: 'SSR Page Title',
});

// Use extended objects
console.log(ssrWindow.navigator.language); // 'en-US'
console.log(ssrDocument.title); // 'SSR Page Title'

Error Handling

SSR Window is designed to prevent errors rather than throw them:

  • DOM Query Methods: Return null or empty arrays instead of throwing
  • Event Methods: Provide no-op implementations that safely do nothing
  • Timing Functions: Offer safe fallbacks using setTimeout/clearTimeout
  • Object Extension: Protects against prototype pollution and handles undefined inputs

All methods are designed to fail silently in SSR environments while working normally in browser environments.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ssr-window@5.0.x
Publish Source
CLI
Badge
tessl/npm-ssr-window badge