Astring: Fast ESTree Code Generator

Common errors

• TypeError: generate is not a function

  cause Attempting to use `require('astring')` or `import generate from 'astring'` when `generate` is a named export.
  fix Use correct named import syntax: `import { generate } from 'astring';` for ESM or `const { generate } = require('astring');` for CommonJS.

• TypeError: Cannot read properties of undefined (reading 'type')

  cause The AST node being processed by `astring.generate` is either `undefined`, `null`, or does not conform to the expected ESTree structure (e.g., missing a `type` property).
  fix Inspect the input AST to ensure it's a valid ESTree-compliant object and that all its nodes have a `type` property. This often happens if the parsing failed or a transformation corrupted the AST.

Warnings

• gotcha Astring relies on `String.prototype.repeat` and `String.prototype.endsWith`. If targeting older JavaScript environments (e.g., IE) that lack these methods, you must include appropriate polyfills (e.g., `string.prototype.repeat`, `string.prototype.endsWith`, or `babel-polyfill`) for Astring to function correctly.
  Fix: For older environments, install and import polyfills like `npm install string.prototype.repeat string.prototype.endsWith` and `import 'string.prototype.repeat'; import 'string.prototype.endsWith';`
• gotcha Astring expects an ESTree-compliant AST. Feeding it a malformed or non-compliant AST, or one generated by a parser with significant deviations from the ESTree spec, may result in incorrect code generation or runtime errors.
  Fix: Ensure your AST is generated by a reputable, ESTree-compliant parser (e.g., Acorn, Meriyah, Espree) and matches the expected structure for Astring's handlers.
• gotcha Enabling comment generation (`comments: true`) or providing complex custom generators can impact performance. While Astring is designed for speed, these options add overhead and should be considered carefully in performance-critical applications.
  Fix: Only enable `comments: true` or use custom generators when necessary. For maximum performance in production, disable comment generation if comments are not required in the output.

Install

• npm install astring npm
• yarn add astring yarn
• pnpm add astring pnpm

Imports

• generate
  wrong:

  const generate = require('astring');

  correct:

  import { generate } from 'astring';

  Astring primarily uses named exports. For CommonJS, use `const { generate } = require('astring');` for named destructuring.
• GENERATOR
  wrong:

  const { GENERATOR } = require('astring');

  correct:

  import { GENERATOR } from 'astring';

  The base generator object, useful for extending Astring's code generation logic with custom handlers for specific AST node types. The CommonJS equivalent `require` also uses named destructuring.
• astring (global)
  wrong:

  import { generate } from './dist/astring.min.js';

  correct:

  // In HTML:
  <script src="astring.min.js"></script>
  // In JS:
  var generate = astring.generate;

  The `dist/astring.min.js` bundle exposes `astring` as a global variable in browser environments, not as an ESM module for direct import.

Quickstart

This quickstart demonstrates parsing a JavaScript string into an ESTree AST using Acorn, then generating formatted code from that AST using Astring, including comments and custom indentation. It also shows using environment variables for dynamic values.

import { generate } from 'astring';
import * as acorn from 'acorn'; // npm install acorn

const sourceCode = `
const add = (a, b) => {
  // This is a simple addition function
  return a + b;
};

function subtract(x, y) {
  return x - y;
}

const result = add(process.env.NUM_ONE ?? '5', process.env.NUM_TWO ?? '3');
console.log('Result:', result);
`;

// Parse the source code into an ESTree-compliant AST
const ast = acorn.parse(sourceCode, {
  ecmaVersion: 2024, // Use a recent ECMAScript version
  sourceType: 'module',
});

// Generate code from the AST with specific options
const generatedCode = generate(ast, {
  indent: '  ', // Use 2 spaces for indentation
  lineEnd: '\n', // Use newline for line endings
  comments: true, // Enable comment generation
});

console.log('--- Original Source ---\n' + sourceCode);
console.log('\n--- Generated Code ---\n' + generatedCode);