Registry / http-networking / netjet

netjet

JSON →
library1.4.0jsnpmunverified

Netjet is an Express.js middleware designed to automatically inject `<link rel="preload">` headers into HTML responses. These headers enable web browsers to perform early resource fetching, which can significantly improve page load performance by fetching critical assets like scripts, styles, and images before the browser's main parsing engine discovers them. The package is currently at version 1.4.0 and appears to be in an active maintenance state, with recent updates focusing on bug fixes and additional preload attributes. It differentiates itself by offering automatic, configurable scanning of HTML responses for subresources to preload, and leverages an `lru-cache` for efficient caching of resource analysis. Its primary use case is optimizing web application delivery for HTTP/2 and modern browsers.

http-networkingweb-framework
npm install netjet
github ↗package ↗
INSTALL
IMPORT
SIG · NETJET
N
netjet
http-networkingjavascriptv1.4.0
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.

netjet
✓ const netjet = require('netjet');
✗ import netjet from 'netjet';
Netjet is primarily a CommonJS module. Attempting a direct ESM import (e.g., in a `type: module` project) will likely result in a `TypeError: require is not a function` or similar unless transpiled or configured for interoperability.
NetjetOptions
✓ /** @typedef {import('netjet').NetjetOptions} NetjetOptions */
While Netjet does not explicitly ship TypeScript types in its `package.json`, this JSDoc pattern provides type hinting for the options object in JavaScript projects. If a `@types/netjet` package were available, `import type { NetjetOptions } from 'netjet'` would be the TypeScript equivalent.
netjet() middleware
✓ app.use(netjet({ directives: ['nopush'] }));
✗ app.use(netjet);
The `netjet` function must be called (e.g., `netjet()`) to return the actual Express middleware. Passing `netjet` directly without invoking it will lead to an error or unexpected behavior as `app.use` expects a function returning the middleware.

Demonstrates how to integrate Netjet middleware into an Express.js application to automatically generate `Link` preload headers for static assets like CSS, images, and JavaScript files, including custom attributes and cache configuration.

const express = require('express'); const netjet = require('netjet'); const path = require('path'); const fs = require('fs'); const app = express(); const port = 1337; const root = path.join(__dirname, 'public'); // Assuming a 'public' folder // Create a 'public' directory and dummy files if they don't exist if (!fs.existsSync(root)) { fs.mkdirSync(root); } fs.writeFileSync(path.join(root, 'style.css'), 'body { color: blue; }'); fs.writeFileSync(path.join(root, 'image.png'), '/* dummy image content */'); fs.writeFileSync(path.join(root, 'script.js'), 'console.log("Script loaded!");'); app .use(netjet({ // Enable parsing for images, scripts, styles (often true by default, but explicit for clarity) images: true, scripts: true, styles: true, // Example option from v1.3.0 notes to add custom attributes directives: ['nopush'], // Recommended: configure an LRU cache to prevent unbounded memory usage cache: { max: 500 } })) .use(express.static(root)) // Serve static files after Netjet has a chance to process responses .get('/', (req, res) => { res.send(` <!DOCTYPE html> <html> <head> <title>Netjet Demo</title> <link rel="stylesheet" href="/style.css"> </head> <body> <h1>Hello from Netjet!</h1> <img src="/image.png" alt="demo image"> <script src="/script.js"></script> </body> </html> `); }) .listen(port, () => { console.log(`Netjet demo app listening on http://localhost:${port}`); console.log(`Open http://localhost:${port} in your browser and inspect network/headers for preload links.`); });
Debug
Known issues
gotchaThe package is marked as 'stability-experimental' in its README badge. While actively maintained, this suggests the API might evolve, and future versions could introduce breaking changes or significant behavioral shifts without strict adherence to semantic versioning for major increments.
fix
Regularly review release notes for updates and thoroughly test against new versions before deploying to production. Consider pinning to specific patch versions (`~1.x.x`) to mitigate unexpected changes.
affects: >=1.0.0
breakingPrior to version 1.1.3, URLs included in generated `Link` preload headers were not consistently or correctly encoded. This could lead to malformed headers, HTTP/2 push failures, or browsers failing to fetch preloaded resources, especially for URLs containing special characters.
fix
Upgrade to `netjet@1.1.3` or higher to ensure proper URL encoding in `Link` headers.
affects: <1.1.3
gotchaNetjet relies on intercepting and modifying the HTML response to inject preload headers. It must be placed *before* any middleware that serves the HTML content (e.g., `express.static`, templating engines, or routes sending HTML). If placed after, it will not be able to process the response and add headers.
fix
Ensure `app.use(netjet(options))` is invoked early in your Express middleware chain, preceding any middleware responsible for serving the HTML content it needs to analyze.
affects: >=1.0.0
gotchaThe `cache` option, which uses `lru-cache` internally, can lead to uncontrolled memory growth if `cache.max` is not configured. Without a maximum number of items, the cache will continuously store resource analysis results, potentially consuming excessive memory over time.
fix
Always configure a `cache.max` option with an appropriate integer value (e.g., `netjet({ cache: { max: 500 } })`) to prevent unbounded cache growth and potential out-of-memory errors in long-running applications.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: app.use() requires middleware functions but got a [object Undefined]
The `netjet` package exports a function that *returns* the middleware, not the middleware function directly.
fix
You must invoke `netjet()` to obtain the middleware function, even if you don't pass any options. Correct usage is `app.use(netjet())` or `app.use(netjet({ /* options */ }))`.
No preload headers are generated, despite serving HTML with assets.
This typically occurs if the `netjet` middleware is positioned incorrectly in the Express middleware chain (after content has been served) or if the asset-specific options (`images`, `scripts`, `styles`) are disabled.
fix
Verify that `netjet` is placed *before* your static file server (`express.static`) and other HTML-serving routes. Also, check the `netjet` options; ensure that `images: true`, `scripts: true`, and `styles: true` are explicitly set if you want those resources to be preloaded.
ERR_HTTP_HEADERS_SENT: Cannot set headers after they are sent to the client
While Netjet uses response hijacking to mitigate this, incorrect placement or interaction with other middleware that eagerly sends headers can still cause this error if Netjet attempts to modify headers after the response stream has begun.
fix
Ensure `netjet` is placed early in the middleware chain, specifically before any middleware or route handlers that might explicitly call `res.send()`, `res.end()`, or `res.setHeaders()` in a way that bypasses Netjet's interception mechanism.
Upgrade
Version history
1.4.0latest on npm
Audit
Dependencies
expressrequiredCore dependency as Netjet functions as an Express.js middleware.
lru-cacherequiredUsed internally for caching resource analysis; configurable via Netjet's options.
Agent activity
8 hits · last 30 days
node
8
Resources
githubhttps://github.com/cloudflare/netjet ↗
packagehttps://www.npmjs.com/package/netjet ↗