{"id":15638,"library":"hcl2-json-parser","title":"HCL v2 Parser for JavaScript","description":"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.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/tyleraldrich/hcl2-parser","tags":["javascript","terraform","hcl","json","typescript"],"install":[{"cmd":"npm install hcl2-json-parser","lang":"bash","label":"npm"},{"cmd":"yarn add hcl2-json-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add hcl2-json-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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(...)`).","wrong":"import parseToString from 'hcl2-json-parser'","symbol":"parseToString","correct":"import { parseToString } from 'hcl2-json-parser'"},{"note":"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(...)`).","wrong":"import parseToObject from 'hcl2-json-parser'","symbol":"parseToObject","correct":"import { parseToObject } from 'hcl2-json-parser'"},{"note":"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`.","wrong":"import hcl from 'hcl2-json-parser'","symbol":"Entire module object","correct":"const hcl = require('hcl2-json-parser')"}],"quickstart":{"code":"import { parseToObject, parseToString } from 'hcl2-json-parser';\n\nconst hclString = `\n# Create a resource group\nvariable \"azureRegion\" {\n  type = string\n  default = \"uksouth\"\n}\nresource \"azurerm_resource_group\" \"example\" {\n  name     = \"example-resources\"\n  location = var.azureRegion\n}\n`;\n\nasync function parseHCL() {\n  try {\n    // Parse into a JSON string\n    const stringResult = await parseToString(hclString);\n    console.log(\"Parsed JSON String:\\n\", stringResult);\n\n    // Parse into an object\n    const objectResult: any = await parseToObject(hclString);\n    console.log(\"\\nResource Group Name:\", objectResult.resource.azurerm_resource_group.example.name);\n    console.log(\"Resource Group Location:\", objectResult.resource.azurerm_resource_group.example.location);\n\n    // Demonstrate error handling for invalid HCL\n    await parseToObject(\"invalid hcl!!!\");\n  } catch (e: any) {\n    console.error(\"\\nError parsing HCL (expected for 'invalid hcl!!!'):\", e.message);\n  }\n}\n\nparseHCL();","lang":"typescript","description":"Demonstrates how to parse an HCL string into both a JSON string and a JavaScript object, including basic error handling for invalid HCL syntax."},"warnings":[{"fix":"Ensure `await` calls for `parseToString` and `parseToObject` are wrapped in `try-catch` blocks to handle potential parsing errors returned as rejected Promises.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 (for the original `hcl2-parser`)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure the HCL input string strictly adheres to the HCL v2 specification. Check for typos, incorrect keywords, or malformed blocks.","cause":"The input string is not valid HCL syntax (e.g., trying to parse arbitrary text like 'invalid hcl!!!').","error":"Error parsing HCL: Failed to parse HCL: <stdin>:1,1-1: Keywords are not allowed as attributes."},{"fix":"Carefully review the HCL configuration for missing closing curly braces, brackets, or unclosed string literals that prevent correct parsing of blocks.","cause":"A closing brace `}` is missing or misplaced, leading to an incomplete HCL block or file.","error":"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."}],"ecosystem":"npm"}