node-useref

library0.3.15jsnpmunverified

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.

devops

npm install node-useref

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-USEREF

node-useref

devopsjavascriptv0.3.15

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useref

✓ const useref = require('node-useref');

✗ import useref from 'node-useref';

This package is CommonJS-only and has not been updated since 2016. ESM imports are not supported natively.

useref function call

✓ const [transformedHtml, assetMap] = useref(inputHtml);

✗ const transformedHtml = useref(inputHtml);

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.

Custom Block Handler

✓ useref(inputHtml, { customBlockType: (content, target, options, alternateSearchPath) => { /*...*/ } });

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').

Demonstrates how to parse an HTML string with build blocks, transforming asset references and capturing the map of original assets for further build processing.

const useref = require('node-useref'); const sampleHtml = ` <html> <head>  <link href="css/one.css" rel="stylesheet"> <link href="css/two.css" rel="stylesheet">  </head> <body>  <script type="text/javascript" src="scripts/one.js"></script> <script type="text/javascript" src="scripts/two.js"></script>   <script type="text/javascript" src="scripts/three.js"></script> <script type="text/javascript" src="scripts/four.js"></script>   <p>This content will be removed.</p>  </body> </html>`; const [transformedHtml, assetMap] = useref(sampleHtml); console.log('--- Transformed HTML ---'); console.log(transformedHtml); console.log('\n--- Asset Map ---'); console.log(JSON.stringify(assetMap, null, 2)); /* Example Expected Output for transformedHtml: <html> <head> <link rel="stylesheet" href="css/combined.css"/> </head> <body> <script src="scripts/combined.js"></script> <script src="scripts/async.js" async data-foo="bar" ></script> </body> </html> */

Debug

Known issues

breakingThe package is effectively abandoned, with its last commit and release in June 2016. There will be no further updates, bug fixes, or security patches.

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.

affects: 0.3.15

gotchanode-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.

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.

affects: >=0.1.0

gotchaThe `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).

fix

Use array destructuring for clarity: `const [html, assets] = useref(inputHtml);`

affects: >=0.1.0

gotchaGiven 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.

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.

affects: >=0.3.15

Errors

Common errors & fixes

TypeError: useref is not a function

Attempting to use `node-useref` with an ES module `import` statement or assuming a named export.

fix

Use the CommonJS `require` syntax: `const useref = require('node-useref');`

ReferenceError: useref is not defined

The `useref` variable was used without being correctly imported/required first.

fix

Add `const useref = require('node-useref');` at the top of your file before using the function.

Asset files referenced in the `assetMap` are not found by subsequent build steps.

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.

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`.

Upgrade

Version history

0.3.15latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/manuelcabral/useref ↗

packagehttps://www.npmjs.com/package/node-useref ↗