{"id":13101,"library":"edge-parser","title":"Edge Template Parser","description":"edge-parser is a JavaScript/TypeScript library designed to parse the syntax of the Edge template engine, converting template strings into executable JavaScript functions. It is currently stable at version 9.1.0 (published December 2025), with recent releases focusing on features like update expression support and dependency updates. The library provides a programmatic API for tokenizing template input, transforming its Abstract Syntax Tree (AST), and processing tokens into a final JavaScript output, which can then be invoked with template state. A key differentiator is its explicit handling of error tracing within compiled templates via `filename` and `lineNumber` parameters, and highly configurable options for managing template variables (`statePropertyName`) and helper function paths (`escapeCallPath`, `toAttributesCallPath`).","status":"active","version":"9.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/edge-js/parser","tags":["javascript","edge","template","template-engine","typescript"],"install":[{"cmd":"npm install edge-parser","lang":"bash","label":"npm"},{"cmd":"yarn add edge-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add edge-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package became ESM-only in v9.0.0. Use `import` syntax. `Parser` is the main class for parsing Edge templates.","wrong":"const Parser = require('edge-parser')","symbol":"Parser","correct":"import { Parser } from 'edge-parser'"},{"note":"Part of the core toolkit for buffering the generated JavaScript output. ESM-only since v9.0.0.","wrong":"const EdgeBuffer = require('edge-parser').EdgeBuffer","symbol":"EdgeBuffer","correct":"import { EdgeBuffer } from 'edge-parser'"},{"note":"A utility class often used internally by the Parser to manage parsing context. ESM-only since v9.0.0.","wrong":"const Stack = require('edge-parser').Stack","symbol":"Stack","correct":"import { Stack } from 'edge-parser'"},{"note":"Since v9.0.0, TypeScript types are exported from the `edge-parser/types` subpath, not directly from the main package entrypoint.","wrong":"import type { ParserConfig } from 'edge-parser'","symbol":"types","correct":"import type { ParserConfig } from 'edge-parser/types'"}],"quickstart":{"code":"import { Parser, EdgeBuffer, Stack } from 'edge-parser';\n\nconst filename = 'eval.edge';\n\nconst parser = new Parser({}, new Stack(), {\n  statePropertyName: 'state',\n  escapeCallPath: 'escape',\n  toAttributesCallPath: 'toAttributes',\n});\n\nconst buffer = new EdgeBuffer(filename, {\n  outputVar: 'out',\n  rethrowCallPath: 'reThrow'\n});\n\nconst templateString = 'Hello {{ username ?? 'Guest' }}! Today is {{ new Date().toLocaleDateString() }}.';\n\nparser\n  .tokenize(templateString, { filename })\n  .forEach((token) => parser.processToken(token, buffer));\n\nconst output = buffer.flush();\n\nconsole.log('--- Compiled JavaScript Output ---');\nconsole.log(output);\n\n// To run the compiled template:\nconst fn = new Function('state, escape, reThrow', output);\n\nconst state = { username: 'Alice' };\nconst escape = (val) => String(val).replace(/[&<>'\"/]/g, c => `&#${c.charCodeAt(0)};`);\nconst reThrow = (err, filename, lineNumber) => {\n  console.error(`Error in ${filename} at line ${lineNumber}:`, err.message);\n  throw err;\n};\n\ntry {\n  const result = fn(state, escape, reThrow);\n  console.log('\\n--- Template Render Result ---');\n  console.log(result);\n} catch (e) {\n  console.error('\\n--- Template Execution Error ---');\n  console.error(e);\n}\n","lang":"typescript","description":"This code demonstrates how to initialize the Edge Parser, tokenize a template string, process the tokens into a JavaScript function, and then execute that function with a given state and helper utilities, including basic error handling."},"warnings":[{"fix":"Migrate all imports from CommonJS `require()` to ES Modules `import` syntax. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","message":"Version 9.0.0 of `edge-parser` transitioned to an ESM-only package. Attempting to use `require()` for imports will result in an `ERR_REQUIRE_ESM` error.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Update type imports to use the `edge-parser/types` subpath, e.g., `import type { ParserConfig } from 'edge-parser/types';`","message":"Since version 9.0.0, TypeScript type definitions are no longer exported directly from the main `edge-parser` package entrypoint. They are now located under a subpath.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Always provide a descriptive `filename` string when calling `parser.tokenize(template, { filename })` and initializing `new EdgeBuffer(filename, ...)`. This `filename` is embedded in the compiled output for error reporting.","message":"The `filename` option passed to `Parser.tokenize` and `EdgeBuffer` is crucial for generating meaningful stack traces in case of template execution errors. Without it, debugging runtime issues in compiled templates becomes significantly harder.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Carefully review the documentation for each configuration option and ensure the provided values correctly map to the expected global variables or helper functions available at the time the compiled template function is executed. For example, `escapeCallPath: 'escape'` implies an `escape` function will be available in the template's execution scope.","message":"The `Parser` and `EdgeBuffer` constructors require specific configuration objects (`statePropertyName`, `escapeCallPath`, `toAttributesCallPath`, `outputVar`, `rethrowCallPath`). Incorrectly configured paths or variable names will lead to runtime errors in the generated template function.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { Parser } = require('edge-parser');` to `import { Parser } from 'edge-parser';`. Ensure your `package.json` has `\"type\": \"module\"` or use a `.mjs` file extension for your script.","cause":"Attempting to import `edge-parser` using CommonJS `require()` syntax in a Node.js environment after the package transitioned to ESM-only in v9.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module C:\\path\\to\\node_modules\\edge-parser\\dist\\index.js from C:\\path\\to\\your_file.js not supported."},{"fix":"For versions `>=9.0.0`, ensure you use `import { Parser } from 'edge-parser';`. For versions `<9.0.0`, ensure you are correctly importing named exports (if using `require`, it might be `const { Parser } = require('edge-parser');` or `const Parser = require('edge-parser').Parser;` depending on exact package structure).","cause":"This error typically occurs if `edge-parser` is imported incorrectly (e.g., using `require()` in an ESM context, or attempting a default import when only named exports exist, or mismatching ESM/CJS in older Node versions).","error":"TypeError: Parser is not a constructor"},{"fix":"If using `edge-parser@<9.0.0`, types were likely directly from `edge-parser`. Update your import to `import type { ParserConfig } from 'edge-parser';`. If on `edge-parser@>=9.0.0`, double-check the exact subpath spelling: `import type { ParserConfig } from 'edge-parser/types';`","cause":"Attempting to import types from `edge-parser/types` in a version older than v9.0.0, or a typo in the import path.","error":"Cannot find module 'edge-parser/types'"},{"fix":"When creating `new Parser()`, ensure `statePropertyName` matches the variable name you intend to pass to the compiled function. When invoking the `new Function(...)` output, pass the state object as the first argument, e.g., `fn(myState, escape, reThrow)`.","cause":"The compiled template function expects a `state` variable (or whatever `statePropertyName` is configured to) in its scope, but it was not provided or was named differently during function invocation.","error":"ReferenceError: state is not defined (when executing the compiled template function)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}