{"id":13676,"library":"node-useref","title":"HTML Build Block Reference Replacement","description":"node-useref is a utility package designed to parse HTML files for special 'build blocks' defined by HTML comments (e.g., ``). Its primary function is to replace multiple script or link tags within these blocks with a single consolidated tag, or to remove the block entirely based on the specified type (`js`, `css`, `remove`). It outputs the modified HTML string along with a comprehensive map detailing the original assets that were part of each consolidated block, enabling subsequent build tools (like concatenators or minifiers) to process the actual files. The current stable version is 0.3.15, released in 2016. The package is effectively abandoned, with no active development or maintenance. Its key differentiator is its focused role as a HTML parser and rewritter for asset references, leaving the actual file manipulation to external tools, and its support for IE conditional comments and custom block types.","status":"abandoned","version":"0.3.15","language":"javascript","source_language":"en","source_url":"git://github.com/manuelcabral/useref","tags":["javascript","build","blocks","comments","replace","scripts","link","ref"],"install":[{"cmd":"npm install node-useref","lang":"bash","label":"npm"},{"cmd":"yarn add node-useref","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-useref","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only and has not been updated since 2016. ESM imports are not supported natively.","wrong":"import useref from 'node-useref';","symbol":"useref","correct":"const useref = require('node-useref');"},{"note":"The `useref` function returns a two-element array: the modified HTML string and an object mapping the consolidated assets to their original source files. Destructuring is recommended.","wrong":"const transformedHtml = useref(inputHtml);","symbol":"useref function call","correct":"const [transformedHtml, assetMap] = useref(inputHtml);"},{"note":"Custom build blocks are defined by adding an object as the second argument to the `useref` function, where keys match the custom block type (e.g., 'build:mytype').","symbol":"Custom Block Handler","correct":"useref(inputHtml, { customBlockType: (content, target, options, alternateSearchPath) => { /*...*/ } });"}],"quickstart":{"code":"const useref = require('node-useref');\n\nconst sampleHtml = `\n\n\n \n \n \n \n\n\n \n \n \n \n\n \n \n \n \n\n \n

This content will be removed.

\n \n\n`;\n\nconst [transformedHtml, assetMap] = useref(sampleHtml);\n\nconsole.log('--- Transformed HTML ---');\nconsole.log(transformedHtml);\nconsole.log('\\n--- Asset Map ---');\nconsole.log(JSON.stringify(assetMap, null, 2));\n\n/*\nExample Expected Output for transformedHtml:\n\n\n \n\n\n \n \n\n\n\n\n*/","lang":"javascript","description":"Demonstrates how to parse an HTML string with build blocks, transforming asset references and capturing the map of original assets for further build processing."},"warnings":[{"fix":"Consider migrating to a more actively maintained build tool or a modern module bundler (e.g., Webpack, Rollup, Vite) that offers similar asset optimization features natively.","message":"The package is effectively abandoned, with its last commit and release in June 2016. There will be no further updates, bug fixes, or security patches.","severity":"breaking","affected_versions":"0.3.15"},{"fix":"Ensure your project uses CommonJS (`const useref = require('node-useref');`) or configure your bundler (e.g., Webpack) to correctly handle CJS modules in an ESM context.","message":"node-useref is a CommonJS-only package. Attempting to use `import useref from 'node-useref'` will result in errors in an ESM environment without specific transpilation or bundler configuration.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use array destructuring for clarity: `const [html, assets] = useref(inputHtml);`","message":"The `useref` function returns an array `[transformedHtml, assetMap]`. Developers must correctly destructure or access both elements if they intend to use the asset map for subsequent build steps (like concatenation and minification).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Test thoroughly with your specific Node.js version. If issues arise, consider containerizing your build environment with an older Node.js version or migrating to a modern alternative.","message":"Given its age, `node-useref` may have compatibility issues with newer Node.js versions, particularly regarding internal APIs or dependencies that have changed or been removed over time.","severity":"gotcha","affected_versions":">=0.3.15"}],"env_vars":null,"search_vec":"'0.3.15':100 '2016':103 'abandon':108 'activ':111 'actual':93,133 'along':66 'asset':74,129 'base':52 'block':3,21,40,50,81,148,152 'build':2,20,84,151 'comment':25,145,153 'comprehens':69 'concaten':87 'condit':144 'consolid':44,80 'css':58 'current':96 'custom':147 'defin':22 'design':13 'detail':71 'develop':112 'differenti':117 'e.g':26 'effect':107 'enabl':82 'entir':51 'extern':137 'file':17,94,134 'focus':120 'function':29 'html':1,16,24,64,124 'ie':143 'javascript':150 'js':57 'key':116 'leav':131 'like':86 'link':36,156 'mainten':114 'manipul':135 'map':70 'minifi':89 'modifi':63 'multipl':33 'node':7 'node-useref':6 'origin':73 'output':61 'packag':12,105 'pars':15 'parser':125 'part':77 'primari':28 'process':91 'ref':157 'refer':4,130 'releas':101 'remov':48,59 'replac':5,32,154 'rewritt':127 'role':121 'script':34,155 'singl':43 'special':19 'specifi':55 'stabl':97 'string':65 'subsequ':83 'support':141 'tag':37,45 'tool':85,138 'type':56,149 'useref':8 'util':11 'version':98 'within':38","created_at":"2026-04-20T01:55:44.327511+00:00","updated_at":"2026-04-20T01:55:44.327511+00:00","problems":[{"fix":"Use the CommonJS `require` syntax: `const useref = require('node-useref');`","cause":"Attempting to use `node-useref` with an ES module `import` statement or assuming a named export.","error":"TypeError: useref is not a function"},{"fix":"Add `const useref = require('node-useref');` at the top of your file before using the function.","cause":"The `useref` variable was used without being correctly imported/required first.","error":"ReferenceError: useref is not defined"},{"fix":"Carefully review the 'alternate search path' option in your HTML build blocks and ensure that the root path provided to your subsequent asset processing tools (e.g., for minification, concatenation) correctly aligns with the paths generated in the `assetMap`.","cause":"The `alternate search path` parameter in the build block or the root path for asset resolution is incorrectly configured, leading to relative paths in the `assetMap` that don't match the actual file system structure during build.","error":"Asset files referenced in the `assetMap` are not found by subsequent build steps."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/manuelcabral/useref","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/node-useref","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}