Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parseToString
✓ import { parseToString } from 'hcl2-json-parser'
✗ 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
✓ import { parseToObject } from 'hcl2-json-parser'
✗ 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
✓ const hcl = require('hcl2-json-parser')
✗ import hcl from '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`.
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();
Debug
Known issues
breakingMigration 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.fixEnsure `await` calls for `parseToString` and `parseToObject` are wrapped in `try-catch` blocks to handle potential parsing errors returned as rejected Promises.
affects: <1.0.0 (for the original `hcl2-parser`)
gotchaThe 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.fixProfile 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.
affects: >=1.0.0
gotchaError messages originate from the underlying `tmccombs/hcl2json` Go library, which may have a different format or level of detail than typical JavaScript parsing errors.fixWhen 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error parsing HCL: Failed to parse HCL: <stdin>:1,1-1: Keywords are not allowed as attributes.
The input string is not valid HCL syntax (e.g., trying to parse arbitrary text like 'invalid hcl!!!').
fixEnsure 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.
A closing brace `}` is missing or misplaced, leading to an incomplete HCL block or file.
fixCarefully review the HCL configuration for missing closing curly braces, brackets, or unclosed string literals that prevent correct parsing of blocks.
Audit
Dependencies
No dependency data recorded yet.