---

name: javascript-development description: JavaScript development patterns for Metalsmith plugins, browser scripts, and Node.js tooling. Triggers when writing JavaScript code, creating Metalsmith plugins, browser functionality, Nunjucks templates, or Node.js build scripts. Enforces functional programming patterns, ES6+ features, JSDoc documentation, dual ESM/CJS module support, and Mocha testing. No TypeScript.

JavaScript Development Skill

Prescriptive guidance for modern JavaScript development following functional patterns, ES6+ features, clean architecture, and modern tooling without TypeScript.

Core Principles

1. Functional over imperative - Use pure functions, avoid mutation, prefer composition
2. Immutability by default - Use const unless reassignment is required, then let
3. Explicit over implicit - Return values explicitly, no side effects, clear data flow
4. Single responsibility - Each function does one thing well
5. DRY (Don't Repeat Yourself) - Encapsulate repetitive logic in functions
6. Native first - Use Node.js and browser APIs before reaching for npm packages
7. No TypeScript - Use JSDoc for type hints that IDEs understand

ES6+ Features

Variable Declarations

Copy// Always use const by default
const options = { pattern: '**/*.html' };
const files = Object.keys(metalsmith.files);

// Use let only when reassignment is needed
let count = 0;
for (const file of files) {
  if (matchesPattern(file)) {
    count += 1;
  }
}

// Never use var

Destructuring

Copy// Object destructuring in function parameters
function processFile({ contents, mode, stats }, options) {
  const { pattern, ignore } = options;
  // ...
}

// Array destructuring
const [first, second, ...rest] = items;

// Destructuring with defaults
const { pattern = '**/*.html', ignore = [] } = options;

// Nested destructuring
const { fuseOptions: { threshold = 0.3 } } = config;

Template Literals

Copy// Use template literals for string interpolation
const message = `Processing ${files.length} files with pattern: ${pattern}`;

// Multi-line strings
const html = `
  <div class="card">
    <h2>${title}</h2>
    <p>${description}</p>
  </div>
`;

// Tagged templates for complex cases
const query = sql`SELECT * FROM users WHERE id = ${userId}`;

Arrow Functions

Copy// Use arrow functions for short callbacks and pure functions
const doubled = numbers.map((n) => n * 2);

// Use regular functions for methods that need 'this' or for named exports
export function processFiles(files, options) {
  // ...
}

// Arrow function for inline handlers
input.addEventListener('input', (event) => {
  handleInput(event.target.value);
});

Default Parameters

Copy// Use default parameters instead of conditional checks
function createIndex(files, options = {}) {
  const { pattern = '**/*.html', threshold = 0.3 } = options;
  // ...
}

// Avoid this pattern
function createIndex(files, options) {
  options = options || {};  // Don't do this
  const pattern = options.pattern || '**/*.html';  // Or this
}

Spread and Rest Operators

Copy// Spread for immutable updates
const updated = { ...original, newProp: value };
const combined = [...array1, ...array2];

// Rest for gathering remaining arguments
function log(message, ...args) {
  console.log(message, ...args);
}

// Rest in destructuring
const { pattern, ...otherOptions } = options;

Strict Equality and Defensive Coding

Always Use Strict Equality

Copy// Always use === and !==
if (value === null) { }
if (type !== 'undefined') { }
if (count === 0) { }

// Never use == or != (type coercion causes bugs)
if (value == null) { }  // Don't do this
if (count == '0') { }   // Or this

Optional Chaining (?.)

Copy// Safe property access
const title = file?.metadata?.title;
const firstTag = post?.tags?.[0];
const result = processor?.process?.(data);

// Instead of
const title = file && file.metadata && file.metadata.title;

Nullish Coalescing (??)

Copy// Use ?? for defaults when null/undefined (not falsy)
const port = config.port ?? 3000;        // Only if null/undefined
const name = user.name ?? 'Anonymous';

// Use || only when you want to replace all falsy values
const count = input || 0;  // Replaces '', 0, false, null, undefined

// Important difference:
const value1 = 0 ?? 10;    // Returns 0 (0 is not null/undefined)
const value2 = 0 || 10;    // Returns 10 (0 is falsy)
const value3 = '' ?? 'default';  // Returns '' (empty string is not null/undefined)
const value4 = '' || 'default';  // Returns 'default' (empty string is falsy)

Defensive Type Checks

Copy// Check types explicitly when needed
function processFile(file, options) {
  if (typeof file !== 'object' || file === null) {
    throw new Error('metalsmith-plugin: file must be an object');
  }
  
  if (!Array.isArray(options.patterns)) {
    throw new Error('metalsmith-plugin: patterns must be an array');
  }
}

Async/Await Patterns

Basic Async Functions

Copy/**
 * Read and parse a JSON file
 * @param {string} filePath - Path to JSON file
 * @returns {Promise<Object>} Parsed JSON content
 */
async function readJsonFile(filePath) {
  const content = await readFile(filePath, 'utf8');
  return JSON.parse(content);
}

Error Handling with Async/Await

Only catch at boundaries - external calls where you can add context or recover:

Copy/**
 * Fetch data from external API
 * This is a boundary - external call can fail for reasons outside our control
 * @param {string} url - URL to fetch
 * @returns {Promise<Object>} Response data
 */
async function fetchData(url) {
  const response = await fetch(url);
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status} from ${url}: ${response.statusText}`);
  }
  
  return response.json();
}

// No try/catch in trusted async code - let errors bubble
async function processAllEntries(entries, options) {
  const results = await Promise.all(
    entries.map((entry) => processEntry(entry, options))
  );
  return results.filter(Boolean);
}

Parallel Async Operations

Copy// Process multiple items in parallel
async function processAllFiles(files, options) {
  const results = await Promise.all(
    files.map((file) => processFile(file, options))
  );
  return results.filter(Boolean);
}

// With error handling for individual items
async function processAllFilesSafe(files, options) {
  const results = await Promise.allSettled(
    files.map((file) => processFile(file, options))
  );
  
  return results
    .filter((result) => result.status === 'fulfilled')
    .map((result) => result.value);
}

Sequential Async Operations

Copy// When order matters or you need to avoid overwhelming a resource
async function processSequentially(items, processor) {
  const results = [];
  
  for (const item of items) {
    const result = await processor(item);
    results.push(result);
  }
  
  return results;
}

// Using reduce for sequential async
async function processSequentiallyAlt(items, processor) {
  return items.reduce(async (accPromise, item) => {
    const acc = await accPromise;
    const result = await processor(item);
    return [...acc, result];
  }, Promise.resolve([]));
}

Async in Metalsmith Plugins

Copy/**
 * Async-aware Metalsmith plugin
 * @param {Options} options - Plugin options
 * @returns {import('metalsmith').Plugin} Metalsmith plugin function
 */
export default function asyncPlugin(options = {}) {
  const config = deepMerge(defaultOptions, options);

  return async function (files, metalsmith) {
    const debug = metalsmith.debug('metalsmith-async-plugin');
    debug('Starting async processing');

    const filesToProcess = metalsmith.match(config.pattern, Object.keys(files));
    
    // Process files in parallel
    await Promise.all(
      filesToProcess.map(async (filename) => {
        const file = files[filename];
        const result = await processFileAsync(file, config);
        files[filename] = { ...file, ...result };
      })
    );

    debug('Async processing complete');
  };
}

Native Methods Over Dependencies

Always prefer built-in APIs. Every dependency is a liability.

Node.js Native Modules

Browser Native APIs

When Dependencies Are Appropriate

Add a dependency only when:

• Native equivalent doesn't exist or is significantly worse
• The package solves a complex, well-tested problem (e.g., cheerio for HTML parsing, fuse.js for fuzzy search)
• Writing it yourself would be error-prone or time-consuming
• The package is well-maintained with minimal transitive dependencies

Metalsmith Plugin Pattern

Every Metalsmith plugin uses the two-phase factory pattern:

Copy/**
 * Plugin options
 * @typedef {Object} Options
 * @property {string|string[]} [pattern] - Files to process
 * @property {string} [outputPath] - Output destination
 */

/**
 * Brief description of what the plugin does.
 *
 * @param {Options} options - Plugin options
 * @returns {import('metalsmith').Plugin} Metalsmith plugin function
 */
export default function pluginName(options = {}) {
  const config = deepMerge(defaultOptions, options);

  const metalsmithPlugin = function (files, metalsmith, done) {
    const debug = metalsmith.debug('metalsmith-plugin-name');
    debug('Starting with options:', config);

    try {
      // Plugin logic here
      done();
    } catch (error) {
      debug('Plugin failed:', error);
      done(error);
    }
  };

  Object.defineProperty(metalsmithPlugin, 'name', {
    value: 'pluginNamePlugin',
    configurable: true,
  });

  return metalsmithPlugin;
}

Metalsmith Native Methods

Always use Metalsmith's built-in methods over external packages:

Configuration Pattern

Separate configuration into its own module with deep merge and normalization:

Copy/**
 * Default plugin options
 * @type {Object}
 */
export const defaultOptions = {
  pattern: '**/*.html',
  ignore: [],
  outputPath: 'output.json',
};

/**
 * Deep merge configuration objects without mutation
 * @param {Object} target - Base configuration
 * @param {Object} source - Override configuration
 * @returns {Object} Merged configuration
 */
export const deepMerge = (target, source) =>
  Object.keys(source).reduce(
    (acc, key) => ({
      ...acc,
      [key]:
        source[key]?.constructor === Object
          ? deepMerge(target[key] ?? {}, source[key])
          : source[key],
    }),
    { ...target }
  );

/**
 * Convert value to array
 * @param {*} value - Value to normalize
 * @returns {Array} Array version of value
 */
export function normalizeToArray(value) {
  if (typeof value === 'string') {
    return [value];
  }
  if (Array.isArray(value)) {
    return value;
  }
  return [];
}

JSDoc Style

Use JSDoc for all exported functions and complex types:

Copy/**
 * @typedef {Object} SearchEntry
 * @property {string} id - Unique identifier
 * @property {string} url - Page URL
 * @property {string} title - Page title
 * @property {string} content - Text content
 */

/**
 * Process a single file and extract search data.
 * Uses Cheerio for HTML parsing to ensure accurate content extraction.
 *
 * @param {string} filename - Path to file being processed
 * @param {Object} fileData - Metalsmith file object with contents and metadata
 * @param {Object} options - Normalized plugin options
 * @returns {SearchEntry|null} Search entry or null if file should be skipped
 */
export function processFile(filename, fileData, options) {
  // Implementation
}

JSDoc Rules

• @typedef for complex option objects and data structures
• @param with type, name, and description for every parameter
• @returns with type and description
• Brief description as first line, details after blank line
• Use {import('metalsmith').Plugin} for Metalsmith types
• No abbreviations: use error not err, options not opts

Functional Patterns

Prefer Pure Functions

Copy// Good: Pure function, no side effects
function filterIgnoredFiles(matchedFiles, ignoredFiles) {
  return matchedFiles.filter((filename) => !ignoredFiles.includes(filename));
}

// Bad: Mutates input
function filterIgnoredFiles(matchedFiles, ignoredFiles) {
  ignoredFiles.forEach((file) => {
    const index = matchedFiles.indexOf(file);
    if (index > -1) matchedFiles.splice(index, 1);
  });
  return matchedFiles;
}

Use Reduce for Transformations

Copy// Good: Functional transformation with immutable accumulator
const result = items.reduce(
  (acc, item) => ({
    ...acc,
    [item.id]: processItem(item),
  }),
  {}
);

// Alternative with Map for better performance on large datasets
const result = new Map(
  items.map((item) => [item.id, processItem(item)])
);

Single-Purpose Functions (DRY)

Copy// Good: Each function does one thing, logic is not repeated
function hasIgnorePatterns(ignore) {
  return ignore.length > 0;
}

function getMatchedFiles(pattern, files, metalsmith) {
  return metalsmith.match(pattern, Object.keys(files));
}

function filterIgnored(matched, ignored) {
  return matched.filter((file) => !ignored.includes(file));
}

// Compose single-purpose functions
function getFilesToProcess(files, options, metalsmith) {
  const matched = getMatchedFiles(options.pattern, files, metalsmith);
  
  if (!hasIgnorePatterns(options.ignore)) {
    return matched;
  }
  
  const ignored = getMatchedFiles(options.ignore, files, metalsmith);
  return filterIgnored(matched, ignored);
}

Early Returns Over Nested Conditionals

Copy// Good: Early returns
function processFile(file, options) {
  if (!file) {
    return null;
  }
  
  if (!matchesPattern(file, options.pattern)) {
    return null;
  }
  
  return extractContent(file);
}

// Bad: Deep nesting
function processFile(file, options) {
  if (file) {
    if (matchesPattern(file, options.pattern)) {
      return extractContent(file);
    }
  }
  return null;
}

Linting and Formatting

Use ESLint and Prettier to enforce consistent style and catch errors.

ESLint Configuration (eslint.config.js)

Copyimport eslintPluginPrettier from 'eslint-plugin-prettier';
import eslintConfigPrettier from 'eslint-config-prettier';

export default [
  {
    ignores: ['lib/**', 'node_modules/**', 'coverage/**'],
  },
  {
    files: ['**/*.js'],
    languageOptions: {
      ecmaVersion: 2022,
      sourceType: 'module',
    },
    plugins: {
      prettier: eslintPluginPrettier,
    },
    rules: {
      ...eslintConfigPrettier.rules,
      'prettier/prettier': 'error',
      'no-var': 'error',
      'prefer-const': 'error',
      'eqeqeq': ['error', 'always'],
      'no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    },
  },
];

Prettier Configuration (prettier.config.js)

Copyexport default {
  semi: true,
  singleQuote: true,
  trailingComma: 'es5',
  printWidth: 100,
  tabWidth: 2,
};

Key Rules Enforced

• no-var - Prevents use of var
• prefer-const - Requires const when variable isn't reassigned
• eqeqeq - Requires === and !==
• no-unused-vars - Catches dead code

Module Structure

Directory Layout

Copyplugin-name/
├── src/
│   ├── index.js           # Main entry, exports plugin factory
│   ├── utils/
│   │   └── config.js      # Configuration, defaults, deep merge
│   └── processors/
│       └── file-processor.js  # Core processing logic
├── test/
│   ├── index.test.js      # ESM tests
│   ├── cjs.test.cjs       # CJS compatibility tests
│   └── fixtures/          # Test fixtures
├── lib/                   # Built output (generated)
├── package.json
├── eslint.config.js
└── prettier.config.js

Dual ESM/CJS Support

Use microbundle for building both module formats:

package.json:

Copy{
  "type": "module",
  "main": "./lib/index.cjs",
  "module": "./lib/index.js",
  "exports": {
    "import": "./lib/index.js",
    "require": "./lib/index.cjs",
    "default": "./lib/index.js"
  },
  "scripts": {
    "build": "microbundle --entry src/index.js --output lib/index.js --target node -f esm,cjs --strict --generateTypes=false",
    "lint": "eslint --fix .",
    "lint:check": "eslint .",
    "format": "prettier --write \"**/*.{js,json,md}\"",
    "format:check": "prettier --check \"**/*.{js,json,md}\""
  },
  "engines": {
    "node": ">= 18.0.0"
  }
}

Error Handling

Catch at boundaries, let errors bubble in trusted code.

Over-defensive code with nested try/catch blocks obscures the real error source, hides bugs that should crash, and adds noise. If a trusted internal function fails, the stack trace is your best debugging tool.

Where to Catch

Entry points and boundaries:

Copy// Plugin entry point - this IS a boundary
const metalsmithPlugin = function (files, metalsmith, done) {
  const debug = metalsmith.debug('metalsmith-plugin-name');

  try {
    const result = processFiles(files, config);
    done();
  } catch (error) {
    debug('Plugin failed:', error);
    done(error);  // Propagate to Metalsmith
  }
};

External calls (network, file system, user input):

Copy// External call - can fail for reasons outside your control
async function fetchConfig(url) {
  const response = await fetch(url);
  
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  
  return response.json();
}

When you can actually recover:

Copy// Recovery is possible - try cache on network failure
async function getDataWithFallback(url, cacheKey) {
  try {
    return await fetchData(url);
  } catch (error) {
    const cached = await cache.get(cacheKey);
    if (cached) {
      return cached;
    }
    throw error;  // Re-throw if no recovery possible
  }
}

Where NOT to Catch

Trusted internal functions - let them fail:

Copy// Good: No try/catch, errors bubble up naturally
function deepMerge(target, source) {
  return Object.keys(source).reduce(
    (acc, key) => ({
      ...acc,
      [key]:
        source[key]?.constructor === Object
          ? deepMerge(target[key] ?? {}, source[key])
          : source[key],
    }),
    { ...target }
  );
}

// Good: Validation throws, caller decides how to handle
function validateOptions(options) {
  if (!options.pattern) {
    throw new Error('metalsmith-plugin-name: pattern option is required');
  }
}

// Good: Pure transformation, no catching needed
function filterIgnoredFiles(matchedFiles, ignoredFiles) {
  return matchedFiles.filter((filename) => !ignoredFiles.includes(filename));
}

Bad: Over-defensive internal code:

Copy// Bad: Catching in trusted code obscures bugs
function deepMerge(target, source) {
  try {
    return Object.keys(source).reduce(/* ... */);
  } catch (error) {
    console.error('Merge failed:', error);  // Now you've hidden the real problem
    return target;  // Silent failure - bugs will surface elsewhere
  }
}

// Bad: Wrapping every call
function processFiles(files, options) {
  try {
    const validated = validateOptions(options);  // Unnecessary
    try {
      const merged = deepMerge(defaults, validated);  // Unnecessary
      try {
        return transform(files, merged);  // Unnecessary
      } catch (e) { /* ... */ }
    } catch (e) { /* ... */ }
  } catch (e) { /* ... */ }
}

The Rule

Ask: "Can I recover here, or am I just re-throwing with less information?"

If the answer is "just re-throwing," remove the try/catch and let the error bubble to a boundary that can handle it properly.

Testing with Mocha

Unit Tests

Copyimport assert from 'node:assert';
import { describe, it } from 'mocha';
import { deepMerge, normalizeToArray } from '../src/utils/config.js';

describe('config utilities', function () {
  describe('deepMerge', function () {
    it('should merge nested objects immutably', function () {
      const target = { a: { b: 1 } };
      const source = { a: { c: 2 } };
      const result = deepMerge(target, source);
      
      assert.deepStrictEqual(result, { a: { b: 1, c: 2 } });
      assert.deepStrictEqual(target, { a: { b: 1 } }); // Original unchanged
    });
  });

  describe('normalizeToArray', function () {
    it('should wrap string in array', function () {
      assert.deepStrictEqual(normalizeToArray('*.html'), ['*.html']);
    });

    it('should return array as-is', function () {
      const input = ['*.html', '*.md'];
      assert.strictEqual(normalizeToArray(input), input);
    });

    it('should return empty array for invalid input', function () {
      assert.deepStrictEqual(normalizeToArray(null), []);
      assert.deepStrictEqual(normalizeToArray(undefined), []);
    });
  });
});

Integration Tests

Copyimport assert from 'node:assert';
import { describe, it } from 'mocha';
import Metalsmith from 'metalsmith';
import plugin from '../lib/index.js';

describe('metalsmith-plugin integration', function () {
  it('should process files matching pattern', function (done) {
    Metalsmith('test/fixtures/basic')
      .use(plugin({ pattern: '**/*.html' }))
      .build(function (error, files) {
        assert.strictEqual(error, null);
        assert.ok(files['output.json']);
        done();
      });
  });

  it('should handle empty file set', function (done) {
    Metalsmith('test/fixtures/empty')
      .use(plugin())
      .build(function (error) {
        assert.strictEqual(error, null);
        done();
      });
  });
});

Test Both Module Formats

Copy// test/cjs.test.cjs - CommonJS compatibility
const assert = require('node:assert');
const { describe, it } = require('mocha');
const plugin = require('../lib/index.cjs');

describe('CommonJS compatibility', function () {
  it('should export plugin function', function () {
    assert.strictEqual(typeof plugin, 'function');
  });

  it('should accept options', function () {
    const instance = plugin({ pattern: '**/*.md' });
    assert.strictEqual(typeof instance, 'function');
  });
});

Browser JavaScript

For browser scripts, use vanilla JS with ES modules:

Copy/**
 * Initialize search functionality
 * @param {Object} options - Configuration options
 * @param {string} options.inputSelector - Search input selector
 * @param {string} options.resultsSelector - Results container selector
 */
export function initSearch(options) {
  const input = document.querySelector(options.inputSelector);
  const results = document.querySelector(options.resultsSelector);

  if (!input || !results) {
    console.warn('Search elements not found');
    return;
  }

  input.addEventListener('input', handleSearchInput(results));
}

/**
 * Create search input handler (curried function)
 * @param {HTMLElement} resultsContainer - Results container element
 * @returns {Function} Event handler function
 */
function handleSearchInput(resultsContainer) {
  return (event) => {
    const query = event.target.value.trim();
    
    if (query.length < 2) {
      resultsContainer.innerHTML = '';
      return;
    }

    performSearch(query).then((results) => {
      renderResults(results, resultsContainer);
    });
  };
}

Nunjucks Patterns

Macro for Reusable Components

Copy{# components/button.njk #}
{% macro button(text, url, variant = 'primary') %}
<a href="{{ url }}" class="button button--{{ variant }}">
  {{ text }}
</a>
{% endmacro %}

Custom Filters

Copy// In Metalsmith build - register filters in layouts config
.use(layouts({
  engineOptions: {
    filters: {
      /**
       * Format date for display
       * @param {string} dateString - ISO date string
       * @returns {string} Formatted date
       */
      formatDate(dateString) {
        return new Date(dateString).toLocaleDateString('en-US', {
          year: 'numeric',
          month: 'long',
          day: 'numeric',
        });
      },
    },
  },
}))

Naming Conventions

No abbreviations: error not err, options not opts, config not cfg, result not res

Code Style

Imports

Copy// Node built-ins first (with node: prefix)
import { readFile, writeFile } from 'node:fs/promises';
import path from 'node:path';

// External dependencies
import Metalsmith from 'metalsmith';

// Internal modules (relative)
import { deepMerge, defaultOptions } from './utils/config.js';
import { processFile } from './processors/file-processor.js';

Exports

Copy// Named exports for utilities
export { deepMerge, normalizeToArray, validateOptions };

// Default export for main plugin function
export default function pluginName(options = {}) {
  // ...
}