{"record":{"id":"4705529eb0b651ab","repo":"feathericons/feather","slug":"feather-replace-only-works-in-a-browser-enviro","errorCode":null,"errorMessage":"`feather.replace()` only works in a browser environment.","messagePattern":"`feather\\.replace\\(\\)` only works in a browser environment\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/replace.js","lineNumber":13,"sourceCode":"/* eslint-env browser */\nimport classnames from 'classnames/dedupe';\n\nimport icons from './icons';\n\n/**\n * Replace all HTML elements that have a `data-feather` attribute with SVG markup\n * corresponding to the element's `data-feather` attribute value.\n * @param {Object} attrs\n */\nfunction replace(attrs = {}) {\n  if (typeof document === 'undefined') {\n    throw new Error('`feather.replace()` only works in a browser environment.');\n  }\n\n  const elementsToReplace = document.querySelectorAll('[data-feather]');\n\n  Array.from(elementsToReplace).forEach(element =>\n    replaceElement(element, attrs),\n  );\n}\n\n/**\n * Replace a single HTML element with SVG markup\n * corresponding to the element's `data-feather` attribute value.\n * @param {HTMLElement} element\n * @param {Object} attrs\n */\nfunction replaceElement(element, attrs = {}) {\n  const elementAttrs = getAttrs(element);\n  const name = elementAttrs['data-feather'];","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/feathericons/feather/blob/3dc050d97405062eba78aa57115c0a15c63abdaa/src/replace.js#L1-L31","documentation":"feather.replace() is a browser-only convenience API: it scans the DOM for elements with a `data-feather` attribute and replaces them with the corresponding SVG markup. It calls `document.querySelectorAll`, which only exists in a browser (or a DOM-emulating environment). The library throws this error immediately when `typeof document === 'undefined'` so you get a clear message instead of an opaque ReferenceError.","triggerScenarios":"Calling feather.replace() in Node.js (no DOM), in a server-side rendering pass (Next.js/Nuxt/Rails SSR), inside a Web Worker, or in a test runner (Jest node environment) where `document` is not defined.","commonSituations":"Importing feather-icons in a Node script to pre-render icons; calling replace() in a component's server-side render function; running unit tests with testEnvironment:'node'; using the package in an Electron main process.","solutions":["Call feather.replace() only after the DOM is available, e.g. in a browser entry point or a useEffect/componentDidMount-style hook with a browser check.","Guard the call: only invoke it when typeof document !== 'undefined'.","In SSR frameworks, move the call into client-side lifecycle code or a 'use client' / mounted-only block.","In Jest, set testEnvironment to 'jsdom' if you need to test replace().","If rendering outside a browser, use the string-returning APIs instead: feather.icons[name].toSvg(attrs) and inject the markup yourself."],"exampleFix":"// before\nimport feather from 'feather-icons';\nfeather.replace(); // throws in Node/SSR\n\n// after\nimport feather from 'feather-icons';\nif (typeof document !== 'undefined') {\n  feather.replace();\n}","handlingStrategy":"fallback","validationCode":"if (typeof document === 'undefined') { /* skip replace, use toSvg strings instead */ }","typeGuard":"const canUseFeatherReplace = (): boolean => typeof document !== 'undefined' && typeof document.querySelectorAll === 'function';","tryCatchPattern":"try {\n  feather.replace();\n} catch (e) {\n  if (e.message.includes('browser environment')) {\n    // SSR/Node path: render icons via feather.icons[name].toSvg() instead\n  } else {\n    throw e;\n  }\n}","preventionTips":["Only call replace() in client-side lifecycle code (useEffect, mounted hooks)","Guard with typeof document !== 'undefined' in isomorphic code","Use jsdom test environment when testing DOM replacement","Prefer feather.icons[name].toSvg() when you control rendering"],"tags":["browser-only","dom","ssr","environment"],"backgroundTag":"browser-environment-required","analyzedSha":"3dc050d97405062eba78aa57115c0a15c63abdaa","analyzedAt":"2026-08-30T12:01:49.665Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}