HCL v2 Parser for JavaScript

1.0.3 · active · verified Sun Apr 19

hcl2-parser is a JavaScript library designed for parsing HashiCorp Configuration Language (HCL) version 2 strings, providing crucial utility for developers working with Terraform configurations or other systems that utilize HCLv2. It offers functions to convert HCL input into either a JSON string or a JavaScript object. A key differentiator for this package is its support for the newer HCL v2 syntax, which includes features like for-expressions, dynamic blocks, and null values, an capability often lacking in other JavaScript-based HCL parsers. The library achieves this by wrapping the Go-based `tmccombs/hcl2json` tool and transpiling the necessary Go code to JavaScript using GopherJS, resulting in a self-contained npm package. As of its initial stable release, version 1.0.3, the package includes TypeScript definitions and is primarily intended for use within Node.js environments. Its release cadence is currently nascent.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'resource')
```
cause Attempting to access properties directly on the array returned by `parseToObject` instead of its first element.

fix Access the parsed object at index 0, e.g., `hcl.parseToObject(hclString)[0].resource`.
```
SyntaxError: Unexpected token 'export' or ReferenceError: require is not defined
```
cause Incorrectly mixing ES module `import`/`export` syntax with CommonJS `require()` in the same file or environment without proper configuration/transpilation.

fix Ensure your project uses consistent module syntax (either CommonJS or ES Modules) or configure your build tool (e.g., Webpack, Rollup, Babel, TypeScript) to transpile modules correctly for your target environment. For Node.js, use `.mjs` or `type: module` in `package.json` for ESM.

Warnings

gotcha The `parseToObject` function always returns an array, even when parsing a single HCL document. Developers must access the first element of this array (`result[0]`) to get the actual parsed object.
Fix: Always access the parsed object via `hcl.parseToObject(input)[0]`.

Install

npm install hcl2-parser npm
yarn add hcl2-parser yarn
pnpm add hcl2-parser pnpm

Imports

parseToString

wrong:

import hcl from 'hcl2-parser'; const result = hcl.parseToString(...);

correct:

import { parseToString } from 'hcl2-parser';

For named ESM imports of specific parser functions.

parseToObject
```
import { parseToObject } from 'hcl2-parser';
```
For named ESM imports of specific parser functions.
hcl (namespace)
wrong:
```
import * as hcl = from 'hcl2-parser';
```
correct:
```
import * as hcl from 'hcl2-parser';
```
Correct ESM namespace import syntax. The 'hcl = from' syntax in some examples is incorrect.
hcl (CommonJS)
wrong:
```
import hcl from 'hcl2-parser';
```
correct:
```
const hcl = require('hcl2-parser');
```
Standard CommonJS `require` for Node.js environments. ESM `import` will not work directly in CJS modules without transpilation.

Quickstart

Demonstrates parsing an HCL string into both a JSON string and a JavaScript object using ESM imports, highlighting how to access specific elements.

import * as hcl from 'hcl2-parser';

const hclString = `
# Create a resource group
variable "azureRegion" {
  type = string
  default = "uksouth"
}
resource "azurerm_resource_group" "example" {
  name     = "example-resources"
  location = var.azureRegion
}
`;

// Parse into a JSON string
const stringResult = hcl.parseToString(hclString);
console.log('JSON String Result:', stringResult);

// Parse into an object, accessing the actual result in array index 0
const objectResult = hcl.parseToObject(hclString);
console.log('Parsed Object Resource:', objectResult[0].resource.azurerm_resource_group);
console.log('Name:', objectResult[0].resource.azurerm_resource_group.example.name);
console.log('Location:', objectResult[0].resource.azurerm_resource_group.example.location);

view raw JSON →