Comment-Preserving JSON/JSON5 Writer

Common errors

• Error: Cannot find module 'jscodeshift'

  cause The `jscodeshift` package is a peer dependency or a required runtime dependency for `json5-writer`'s core functionality and must be installed separately.
  fix Install `jscodeshift` as a dependency: `npm install jscodeshift` or `yarn add jscodeshift`.

• TypeError: writer.load is not a function

  cause Incorrect import of `json5-writer`. The library exports a default object, and `load` is a method on that object.
  fix For CommonJS, use `const json5Writer = require('json5-writer');` then `json5Writer.load()`. For ESM, use `import json5Writer from 'json5-writer';` then `json5Writer.load()`.

• SyntaxError: Unexpected token / in JSON at position X

  cause Attempting to parse a JSON5 string (which allows comments) with the native `JSON.parse()` method before passing it to `json5-writer`, or when `.toJSON()` is expected but comments are still present.
  fix Ensure you are passing the raw JSON5 string directly to `json5Writer.load()`. If outputting JSON, use `.toJSON()` and verify comments are stripped, or ensure no comments are added if the target system only accepts strict JSON.

Warnings

• gotcha When using the `.write(value)` method, any property or field present in the original document but not in the `value` object passed to `.write()` will be removed. To explicitly preserve an existing value while updating other fields, you must set its corresponding property in the `value` object to `undefined`.
  Fix: Pass `undefined` for properties you wish to retain from the original document but not modify with the current `.write()` call. For example, `writer.write({ propertyToKeep: undefined, otherProperty: 'newValue' })`.
• gotcha The default output options for `.toSource()` (which outputs JSON5) and `.toJSON()` (which outputs standard JSON) differ. `.toSource()` by default uses single quotes, trailing commas, and infers key quoting, whereas `.toJSON()` defaults to double quotes, no trailing commas, and quotes all keys.
  Fix: Always explicitly specify options for `quote`, `trailingComma`, and `quoteKeys` in both `.toSource()` and `.toJSON()` if you require a consistent or specific output format across different calls or when converting between JSON5 and JSON.
• gotcha Advanced manipulation of the parsed document requires direct interaction with the underlying jscodeshift AST via the `.ast` property. This necessitates familiarity with jscodeshift's API and AST structures, which can have a learning curve.
  Fix: Consult the `jscodeshift` documentation for AST node types and traversal methods. Start with simple `find` and `forEach` operations to understand the AST structure before attempting complex transformations.

Install

• npm install json5-writer npm
• yarn add json5-writer yarn
• pnpm add json5-writer pnpm

Imports

• json5Writer
  wrong:

  const json5Writer = require('json5-writer').default;

  correct:

  import json5Writer from 'json5-writer';

  While the README uses `require('json5-writer')` for CommonJS, modern Node.js and bundlers often resolve this to a default import. For direct CommonJS usage, `const json5Writer = require('json5-writer');` is correct. The import shown here is for ESM.
• json5Writer.load
  wrong:

  import { load } from 'json5-writer';

  correct:

  import json5Writer from 'json5-writer'; const writer = json5Writer.load(jsonStr);

  `load` is a method on the default export object, not a named export itself.
• j
  wrong:

  const j = require('jscodeshift').j;

  correct:

  import j from 'jscodeshift';

  jscodeshift's main export is often referred to as `j` by convention in its examples for AST traversal. This is a default import for jscodeshift itself, used for direct AST manipulation.

Quickstart

This quickstart demonstrates loading, modifying, and saving a JSON5 configuration file, preserving comments and formatting. It shows how to update existing properties, add new ones, and use `undefined` to explicitly retain a property's value when writing a new object, using environment variables for dynamic values.

import * as fs from 'node:fs/promises';
import * as path from 'node:path';
import json5Writer from 'json5-writer';

async function updateConfigFile() {
  const configPath = path.join(process.cwd(), 'config.json5');
  const initialConfig = `{
  // Main application settings
  'app-name': 'My Awesome App',
  // Database connection details
  db: {
    host: 'localhost',
    port: 5432,
    user: 'admin'
  },
  // Feature flags
  features: {
    beta: true,
    analytics: false
  }
}`;

  // Ensure config file exists for demonstration
  await fs.writeFile(configPath, initialConfig, 'utf-8');

  try {
    const configContent = await fs.readFile(configPath, 'utf-8');
    const writer = json5Writer.load(configContent);

    writer.write({
      'app-name': 'New App Name',
      db: {
        host: process.env.DB_HOST ?? 'prod.database.com', // Use env var or default
        // 'port' will be preserved if not explicitly overwritten with undefined or a new value
        user: 'deploy_user' // Update user
      },
      features: {
        beta: undefined, // Preserve existing 'beta' value
        analytics: true, // Update analytics flag
        'new-feature': true // Add a new feature
      }
    });

    const updatedConfigContent = writer.toSource({
      quote: 'single',
      trailingComma: true,
      quoteKeys: undefined
    });
    console.log('Updated config.json5 content:\n', updatedConfigContent);

    await fs.writeFile(configPath, updatedConfigContent, 'utf-8');
    console.log(`Successfully updated ${configPath}`);
  } catch (error) {
    console.error(`Failed to update config file: ${error.message}`);
  }
}

updateConfigFile();