Node.js-style HMACs for Browsers

Common errors

• ReferenceError: Buffer is not defined

  cause In browser environments, the `Buffer` global object, which is native to Node.js, is not automatically available. `create-hmac` expects `Buffer` instances for keys and input.
  fix You need to explicitly polyfill `Buffer` in your browser environment. This is commonly done by installing and importing the `buffer` package from npm: `npm install buffer` and then `const { Buffer } = require('buffer');` at the top of your files, or configuring your bundler (e.g., Webpack's `fallback` option) to provide it.

• Error: Not a string, buffer, or ArrayBuffer

  cause The `hmac.update()` method expects its input to be a string, a Node.js `Buffer`, or an `ArrayBuffer`. Passing other types (e.g., plain JavaScript objects or numbers) will result in this error.
  fix Ensure all data passed to `hmac.update()` is converted to a string, Buffer, or ArrayBuffer first. For example, `hmac.update(JSON.stringify(myObject))` or `hmac.update(Buffer.from(myArray))`.

Warnings

• gotcha The `create-hmac` package is part of the `crypto-browserify` project, which aims to polyfill Node.js's `crypto` module for browser environments. While functional, modern browser applications are encouraged to use the native Web Crypto API for better performance, security, and integration with the browser's cryptographic primitives.
  Fix: For new browser-only projects or sections of code, consider migrating to the native `window.crypto.subtle` API. For isomorphic code, consider conditional imports or wrappers that use `create-hmac` in Node.js/legacy browsers and Web Crypto in modern browsers.
• gotcha This package has seen very limited maintenance and updates since 2019. While the underlying cryptographic algorithms are stable, the lack of active development means that it may not address new browser-specific quirks, performance optimizations, or potential future vulnerabilities promptly. Relying on unmaintained dependencies, especially in security-sensitive areas, carries inherent risks.
  Fix: Regularly audit dependencies for maintenance status. For critical applications, consider alternative, actively maintained cryptographic libraries or prioritize migration to Web Crypto API for browser environments. If continued use is necessary, ensure thorough testing.

Install

• npm install create-hmac npm
• yarn add create-hmac yarn
• pnpm add create-hmac pnpm

Imports

• createHmac
  wrong:

  import { createHmac } from 'create-hmac'

  correct:

  const createHmac = require('create-hmac')

  This package is primarily a CommonJS module. While modern bundlers (e.g., Webpack, Rollup) can process `require()` calls and make it available in ESM projects, direct `import` syntax might not work out-of-the-box in pure ESM environments without specific import resolution configuration.
• createHmac (with types)
  wrong:

  import { createHmac } from 'create-hmac';

  correct:

  import createHmac from 'create-hmac';

  While primarily CJS, if using TypeScript or an ESM-compatible bundler, a default import might be inferred. However, `create-hmac` does not ship with its own TypeScript types, so `@types/create-hmac` would be required for full type safety.

Quickstart

This quickstart demonstrates both synchronous and streaming usage of `createHmac` with SHA-256 and SHA-512 algorithms, showcasing how to generate a digest and how to process data as a stream, similar to Node.js's native crypto module.

const createHmac = require('create-hmac');
const { Buffer } = require('buffer'); // Polyfill for browser environments

// Example 1: Synchronous HMAC generation
const secretKeySync = Buffer.from('supersecret', 'utf8');
const hmacSync = createHmac('sha256', secretKeySync);
hmacSync.update('This is the message to sign.');
const digestSync = hmacSync.digest('hex');
console.log('Synchronous HMAC (SHA256, hex):', digestSync);

// Example 2: HMAC as a stream
const secretKeyStream = Buffer.from('another-secret', 'utf8');
const hmacStream = createHmac('sha512', secretKeyStream);

hmacStream.on('data', chunk => {
  console.log('Stream chunk:', chunk.toString('hex'));
});

hmacStream.on('end', () => {
  console.log('Stream HMAC generation complete.');
});

hmacStream.write('Part one of the streamed data.');
hmacStream.write('Part two of the streamed data.');
hmacStream.end();