HCL v2 Parser for JavaScript

1.0.1 · active · verified Tue Apr 21

This library provides a JavaScript parser for HCL (HashiCorp Configuration Language) version 2 syntax. It is currently at version 1.0.1 and appears to be actively maintained, being an updated fork of an unmaintained predecessor (`hcl2-parser`). Its key differentiator is robust support for HCL v2, which many other JavaScript parsers lack. It achieves this by wrapping the Go-based `tmccombs/hcl2json` library, transpiling the Go code to JavaScript using GopherJS. Unlike its unmaintained predecessor, this version correctly returns parsing errors to the user by rejecting a Promise, making it more reliable for production use cases like parsing Terraform configurations.

Common errors

```
Error parsing HCL: Failed to parse HCL: <stdin>:1,1-1: Keywords are not allowed as attributes.
```
cause The input string is not valid HCL syntax (e.g., trying to parse arbitrary text like 'invalid hcl!!!').

fix Ensure the HCL input string strictly adheres to the HCL v2 specification. Check for typos, incorrect keywords, or malformed blocks.
```
Error parsing HCL: Failed to parse HCL: <stdin>:5,3-4: Expected a new line or a comment character at the end of the line, but got '}' at the end of input.
```
cause A closing brace `}` is missing or misplaced, leading to an incomplete HCL block or file.

fix Carefully review the HCL configuration for missing closing curly braces, brackets, or unclosed string literals that prevent correct parsing of blocks.

Warnings

breaking Migration from the unmaintained `hcl2-parser` to `hcl2-json-parser` requires updating error handling. The original library silently failed, while this version robustly rejects Promises with parsing errors.
Fix: Ensure `await` calls for `parseToString` and `parseToObject` are wrapped in `try-catch` blocks to handle potential parsing errors returned as rejected Promises.
gotcha The library internally uses GopherJS to transpile a Go HCL parser. This can impact bundle size in client-side applications and might introduce unique debugging characteristics.
Fix: Profile client-side bundle size and parsing performance for large HCL inputs. Consider server-side parsing for performance-critical scenarios or very large HCL configurations to offload work.
gotcha Error messages originate from the underlying `tmccombs/hcl2json` Go library, which may have a different format or level of detail than typical JavaScript parsing errors.
Fix: When handling parsing errors, be prepared to parse or display error messages that reflect the Go library's output, which might require specific logic for user-friendly presentation.

Install

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

Imports

parseToString
wrong:
```
import parseToString from 'hcl2-json-parser'
```
correct:
```
import { parseToString } from 'hcl2-json-parser'
```
This function returns a Promise that resolves with the parsed HCL as a JSON string. It can also be accessed via CommonJS destructuring (e.g., `const { parseToString } = require('hcl2-json-parser')`) or a namespace import (e.g., `import * as hcl from 'hcl2-json-parser'; hcl.parseToString(...)`).
parseToObject
wrong:
```
import parseToObject from 'hcl2-json-parser'
```
correct:
```
import { parseToObject } from 'hcl2-json-parser'
```
This function returns a Promise that resolves with the parsed HCL as a JavaScript object. It can also be accessed via CommonJS destructuring (e.g., `const { parseToObject } = require('hcl2-json-parser')`) or a namespace import (e.g., `import * as hcl from 'hcl2-json-parser'; hcl.parseToObject(...)`).
Entire module object
wrong:
```
import hcl from 'hcl2-json-parser'
```
correct:
```
const hcl = require('hcl2-json-parser')
```
This CommonJS `require` pattern loads the entire module object. For ES Modules, use `import * as hcl from 'hcl2-json-parser'` to achieve similar access to `hcl.parseToObject` and `hcl.parseToString`.

Quickstart

Demonstrates how to parse an HCL string into both a JSON string and a JavaScript object, including basic error handling for invalid HCL syntax.

import { parseToObject, parseToString } from 'hcl2-json-parser';

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

async function parseHCL() {
  try {
    // Parse into a JSON string
    const stringResult = await parseToString(hclString);
    console.log("Parsed JSON String:\n", stringResult);

    // Parse into an object
    const objectResult: any = await parseToObject(hclString);
    console.log("\nResource Group Name:", objectResult.resource.azurerm_resource_group.example.name);
    console.log("Resource Group Location:", objectResult.resource.azurerm_resource_group.example.location);

    // Demonstrate error handling for invalid HCL
    await parseToObject("invalid hcl!!!");
  } catch (e: any) {
    console.error("\nError parsing HCL (expected for 'invalid hcl!!!'):", e.message);
  }
}

parseHCL();

view raw JSON →