{"id":15490,"library":"useref","title":"useref HTML Build Block Parser","description":"useref is a JavaScript library designed to parse HTML files and replace special \"build blocks\" with optimized references. Extracted from the `grunt-useref` plugin, it provides a standalone utility for integrating into web build processes. The current stable version is 1.4.4, with releases appearing to be on an as-needed basis, focusing on stability and bug fixes as indicated by the versioning. Its primary differentiator is its ability to identify and process `...` comments, consolidating multiple script or link tags into a single optimized reference, and supporting custom block types for advanced processing. It also preserves IE conditional comments. This functionality is crucial for web performance optimization workflows where assets are concatenated and minified.","status":"active","version":"1.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/jonkemp/useref","tags":["javascript","build","blocks","comments","replace","scripts","link","ref"],"install":[{"cmd":"npm install useref","lang":"bash","label":"npm"},{"cmd":"yarn add useref","lang":"bash","label":"yarn"},{"cmd":"pnpm add useref","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is primarily designed for CommonJS usage. For modern ES Module projects, ensure your build setup correctly handles CommonJS interop, or consider using dynamic import if necessary.","wrong":"import useref from 'useref';","symbol":"useref","correct":"const useref = require('useref');"}],"quickstart":{"code":"const useref = require('useref');\n\nconst sampleHtml = `\n\n\n \n \n \n \n\n\n \n \n \n \n\n \n \n \n \n\n\n`;\n\nconst [resultHtml, assetsMap] = useref(sampleHtml);\n\nconsole.log(\"Transformed HTML:\");\nconsole.log(resultHtml);\nconsole.log(\"\\nIdentified Assets:\");\nconsole.log(JSON.stringify(assetsMap, null, 2));\n\n/*\nExample resultHtml output:\n\n\n \n\n\n \n \n\n\n*/\n\n/*\nExample assetsMap output:\n{\n \"css\": {\n \"css/combined.css\": {\n \"assets\": [\n \"css/one.css\",\n \"css/two.css\"\n ]\n }\n },\n \"js\": {\n \"scripts/combined.js\": {\n \"assets\": [\n \"scripts/one.js\",\n \"scripts/two.js\"\n ]\n },\n \"scripts/async.js\": {\n \"assets\": [\n \"scripts/three.js\",\n \"scripts/four.js\"\n ]\n }\n }\n}\n*/","lang":"javascript","description":"Demonstrates how to parse an HTML string, transform build blocks into consolidated references, and retrieve the map of original assets to their optimized targets."},"warnings":[{"fix":"Thoroughly test custom block handlers with various inputs and ensure the returned string is valid and correctly represents the desired replacement for the block.","message":"Implementing custom block handlers requires careful attention to the returned HTML. The function must return a valid HTML string that will replace the entire build block content. Incorrectly formatted HTML or unexpected values can lead to malformed output.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always explicitly define and test the alternate search path to ensure it correctly resolves the asset paths relative to the treated HTML file.","message":"The 'alternate search path' in build blocks specifies a base path for input files within that block. Misunderstanding its scope or how it interacts with relative paths can lead to incorrect asset resolution in the `assetsMap`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that any custom parameters or overwritten defaults (e.g., `rel` attribute) on the generated tags behave as expected in target browsers and environments.","message":"Parameters specified in build blocks (e.g., `async data-foo='bar'`) are directly applied to the generated tag. Overwriting default attributes like `rel` for CSS links should be done carefully to avoid unexpected styling or loading behavior.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using `const useref = require('useref');` for CommonJS environments, or configure your build system for proper CommonJS interop if using ES modules.","cause":"Attempting to use `useref` as an ES module default import in a CommonJS context, or vice-versa, or incorrect `require` syntax.","error":"useref is not a function"},{"fix":"Verify that your HTML contains correctly formatted `` and `` blocks, and that the `type` (js, css, remove, or custom) is recognized by `useref`.","cause":"Occurs when trying to access the second element of the array returned by `useref` (the assets map), but `useref` failed to parse any blocks or the block types were not recognized, leading to an empty or malformed assets object.","error":"TypeError: Cannot read property 'assets' of undefined"},{"fix":"Ensure the input to `useref()` is a valid HTML string. Check for unclosed tags, invalid comments, or non-string inputs.","cause":"Passing malformed or non-string HTML content to `useref`, or an issue with internal HTML parsing.","error":"SyntaxError: Unexpected token '<'"}],"ecosystem":"npm"}