{"id":48600775,"url":"https://github.com/matronator/mtrgen-js","last_synced_at":"2026-04-08T22:02:05.741Z","repository":{"id":345488655,"uuid":"1179791586","full_name":"matronator/mtrgen-js","owner":"matronator","description":"MTRGen port in TypeScript","archived":false,"fork":false,"pushed_at":"2026-03-26T20:29:35.000Z","size":990,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T02:55:15.920Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matronator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T11:39:03.000Z","updated_at":"2026-03-26T20:29:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/matronator/mtrgen-js","commit_stats":null,"previous_names":["matronator/mtrgen-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/matronator/mtrgen-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fmtrgen-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fmtrgen-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fmtrgen-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fmtrgen-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matronator","download_url":"https://codeload.github.com/matronator/mtrgen-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matronator%2Fmtrgen-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31575755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-08T22:02:02.350Z","updated_at":"2026-04-08T22:02:05.735Z","avatar_url":"https://github.com/matronator.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MTRGen.js\n\n![MTRGen Logo](.github/logo.png)\n\n![Latest version](https://badgen.net/npm/v/mtrgen-js)\n![License](https://badgen.net/npm/license/mtrgen-js)\n![Dependencies](https://badgen.net/bundlephobia/dependency-count/mtrgen-js)\n![Weekly downloads](https://badgen.net/npm/dw/mtrgen-js)\n\n#### [Official Website](https://mtrgen.matronator.cz) | [Documentation](https://mtrgen.matronator.cz/public/docs/) | [Template Repository](https://mtrgen.matronator.cz/repository) | [PHP version](https://github.com/matronator/MTRGen)\n\n`mtrgen` is a template-driven file generator for Node.js and browser. It ships both as a TypeScript library and as a CLI so you can generate files from `.mtr` templates in code or directly from the terminal.\n\nThis is a port of the original PHP libraries [MTRGen](https://github.com/matronator/MTRGen) and [Pars'Em](https://github.com/matronator/parsem).\n\nNode.js 20 or newer is recommended for development, releases, and CLI usage.\n\n## Table of Contents\n\n- [MTRGen.js](#mtrgenjs)\n    - [Install](#install)\n    - [CLI](#cli)\n        - [Generate](#generate)\n        - [Template Store](#template-store)\n        - [Online Registry](#online-registry)\n    - [Template Format](#template-format)\n        - [Variables](#variables)\n            - [Default Value Precedence](#default-value-precedence)\n            - [Literals](#literals)\n            - [Filters](#filters)\n        - [Conditions](#conditions)\n        - [Loops](#loops)\n        - [Comments](#comments)\n    - [Library Usage](#library-usage)\n    - [Development](#development)\n\n## Install\n\nLibrary:\n\n```sh\n# NPM:\nnpm i mtrgen-js\n# PNPM:\npnpm i mtrgen-js\n# Bun:\nbun i mtrgen-js\n```\n\nCLI:\n\n```sh\n# NPM:\nnpm i -g mtrgen-js\n# PNPM:\npnpm i -g mtrgen-js\n# Bun:\nbun i -g mtrgen-js\n```\n\nOr run it without a global install:\n\n```sh\n# NPM:\nnpx mtrgen generate ./templates/component.ts.mtr --arg name=Button\n# PNPM:\npnpx mtrgen generate ./templates/component.ts.mtr --arg name=Button\n# Bun:\nbunx mtrgen generate ./templates/component.ts.mtr --arg name=Button\n```\n\n## CLI\n\nThe package exposes the `mtrgen` command:\n\n```sh\nmtrgen \u003ccommand\u003e [options]\n```\n\nAvailable commands:\n\n- `generate`, `gen`: generate from a saved template name or from `--path \u003cfile\u003e`.\n- `save`, `s`: save a local `.mtr` template into the local store.\n- `saved`, `ls`: list templates in the local store.\n- `remove`, `rm`: remove a template from the local store.\n- `repair`, `r`: remove broken entries from the local store.\n- `add`, `a`: download a template from the online registry into the local store.\n- `use`, `u`: generate directly from an online registry template.\n- `login`, `in`: log into the online registry and save the access token locally.\n- `signup`, `sign`: create a registry account.\n- `publish`, `pub`: publish a local or saved template to the online registry.\n- `help [command]`: show global help or command help.\n- `list`: list the available commands.\n- `-v`, `--version`: print the package version.\n\nThe local template store and login profile are saved under `~/.mtrgen`.\n\n### Generate\n\n```sh\nmtrgen generate [name] [key=value ...]\nmtrgen generate --path \u003ctemplate-path\u003e [options]\n```\n\nSupported options for `generate` and `use`:\n\n- `-o, --out-dir \u003cdir\u003e`: output root directory. Defaults to the current working directory.\n- `-d, --data \u003cfile\u003e`: path to a JSON file with template arguments.\n- `-a, --arg \u003ckey=value\u003e`: inline template argument. Repeat this flag to pass multiple values.\n- `--dry-run`: print the target file paths without writing anything.\n- `-h, --help`: show command help.\n\nExamples:\n\n```sh\nmtrgen generate --path ./templates/component.ts.mtr --arg name=Button --arg folder=components\n\nmtrgen generate ButtonTemplate name=Button folder=components\n\nmtrgen generate ButtonTemplate --data ./component.json --out-dir ./src\n\nmtrgen use vendor/component name=Button --out-dir ./src\n```\n\nInline CLI argument values use the same literal parser as template defaults when possible:\n\n- strings: `name=Button`\n- quoted strings: `title=\"Hello world\"`\n- booleans: `enabled=true`\n- numbers: `count=3`\n- `null`: `value=null`\n- arrays: `items=[\"one\", \"two\"]`\n- objects: `meta={folder: \"ui\", nested: {enabled: true}}`\n\nNested keys are supported in CLI arguments:\n\n```sh\nmtrgen generate ./template.mtr --arg meta.folder=components --arg items[0]=Button\n```\n\n### Template Store\n\n```sh\nmtrgen save ./templates/component.ts.mtr --alias ButtonTemplate\nmtrgen saved\nmtrgen remove ButtonTemplate\nmtrgen repair\n```\n\n### Online Registry\n\nThe registry-backed commands use `https://mtrgen.matronator.cz/api`.\n\n```sh\nmtrgen signup my-user Password123\nmtrgen login my-user Password123\nmtrgen add vendor/component\nmtrgen use vendor/component name=Button\nmtrgen publish ButtonTemplate\nmtrgen publish --path ./templates/component.ts.mtr\n```\n\n## Template Format\n\nFor the full language reference, see [docs/mtrgen-spec.md](./docs/mtrgen-spec.md).\n\nEvery generator template starts with an `MTRGEN` header:\n\n```txt\n--- MTRGEN ---\nname: component\nfilename: \u003c% $name|pascalCase %\u003e.tsx\npath: src/\u003c% $folder=\"components\" %\u003e\ndefaults:\n    title: \"Hello\"\n    enabled: true\n--- /MTRGEN ---\n\nexport const title = \"\u003c% $title %\u003e\";\n```\n\nRequired header fields:\n\n- `name`: template name.\n- `filename`: output filename template.\n- `path`: output directory template.\n\nOptional header fields:\n\n- `defaults`: global default values available to the filename, path, and template body.\n- `syntax`: template syntax version. Defaults to `2`.\n\n### Variables\n\nVariable tags use `\u003c% ... %\u003e`:\n\n```txt\nHello \u003c% $name %\u003e!\n```\n\nVariables support inline defaults:\n\n```txt\nHello \u003c% $name=\"world\" %\u003e!\n```\n\nLookup supports nested properties and array indexes:\n\n```txt\n\u003c% $user.name %\u003e\n\u003c% $user.profile.handle %\u003e\n\u003c% $items[0] %\u003e\n\u003c% $meta[\"folder\"] %\u003e\n\u003c% $meta[$field] %\u003e\n```\n\nAll variable lookups are `$`-prefixed by default. If you need the legacy bare-lookup behavior, you can opt a template into `syntax: 1` in its `MTRGEN` header.\n\nPlain objects are interpolated as JSON.\n\n#### Default Value Precedence\n\nWhen the same value exists in multiple places, precedence is:\n\n1. explicit runtime arguments\n2. inline variable defaults like `\u003c% $name=\"Button\" %\u003e`\n3. header defaults in the `defaults:` block\n\n#### Literals\n\nTemplate defaults and CLI values can use these literal forms:\n\n- strings: `\"hello\"` or `'hello'`\n- numbers: `1`, `3.14`, `-2`\n- booleans: `true`, `false`\n- null: `null`\n- arrays: `[1, \"two\", true, null]`\n- objects: `{folder: \"ui\", nested: {enabled: true}}`\n\nMultiline arrays and objects are supported inside the header `defaults:` block.\n\n#### Filters\n\nFilters are chained with `|`:\n\n```txt\n\u003c% $name|pascalCase %\u003e\n\u003c% $title|truncate:30,\"...\" %\u003e\n\u003c% $foo|truncate:3,\"\"|upper %\u003e\n```\n\nAvailable filters:\n\n- text casing: `upper`, `lower`, `upperFirst`, `lowerFirst`, `camelCase`, `snakeCase`, `kebabCase`, `pascalCase`, `titleCase`\n- collection helpers: `first`, `last`, `length`, `reverse`, `random`, `shuffle`\n- string shaping: `truncate`, `trim`, `substring`, `stripTags`, `nl2br`\n- encoding and escaping: `url`, `escape`, `unescape`, `hash`, `rot13`, `encode`, `decode`\n- math helpers: `pow`, `ceil`, `floor`, `round`\n\nExamples:\n\n```txt\n\u003c% $name|upper %\u003e\n\u003c% $componentName|pascalCase %\u003e\n\u003c% $body|truncate:120,\"...\" %\u003e\n\u003c% $url|encode:\"base64\" %\u003e\n\u003c% $count|pow:2 %\u003e\n```\n\n### Conditions\n\nConditional blocks use `if`, `elseif`, `else`, and `endif`:\n\n```txt\n\u003c% if $enabled %\u003e\n    enabled\n\u003c% else %\u003e\n    disabled\n\u003c% endif %\u003e\n```\n\nSupported comparison operators:\n\n- `===`\n- `!==`\n- `==`\n- `!=`\n- `\u003c`\n- `\u003c=`\n- `\u003e`\n- `\u003e=`\n\nConditions support:\n\n- variable lookups with `$name`\n- nested lookups like `$user.name` or `$items[0]`\n- grouped expressions with parentheses\n- boolean operators `\u0026\u0026` and `||`\n- literal comparisons\n- negation with `!`\n- nested condition blocks\n\nExample:\n\n```txt\n\u003c% if ($kind === \"service\" \u0026\u0026 $enabled) || !$fallback %\u003e\n    export class \u003c% $name|pascalCase %\u003eService {}\n\u003c% elseif !$enabled %\u003e\n    // disabled\n\u003c% else %\u003e\n    export const \u003c% $name %\u003e = true;\n\u003c% endif %\u003e\n```\n\n### Loops\n\nLoop blocks use `for` and `endfor`:\n\n```txt\n\u003c% for item of $items %\u003e\n    \u003c% $item %\u003e\n\u003c% endfor %\u003e\n```\n\nSupported forms:\n\n- `\u003c% for item of $array %\u003e`\n- `\u003c% for [item, index] of $array %\u003e`\n- `\u003c% for [item, key] of $object %\u003e`\n- `\u003c% for item of $object %\u003e`\n- `\u003c% for [_, index] of $array %\u003e`\n- `\u003c% for [_, key] of $object %\u003e`\n\nLoop position blocks are also available inside `for` bodies:\n\n```txt\n\u003c% for item of $items %\u003e\n    \u003c% first %\u003e[\u003c% endfirst %\u003e\n    \u003c% $item %\u003e\u003c% sep %\u003e, \u003c% endsep %\u003e\n    \u003c% last %\u003e]\u003c% endlast %\u003e\n\u003c% endfor %\u003e\n```\n\n`empty` renders only when the iterable has no entries:\n\n```txt\n\u003c% for item of $items %\u003e\n    \u003c% $item %\u003e\n    \u003c% empty %\u003eNo items\u003c% endempty %\u003e\n\u003c% endfor %\u003e\n```\n\n### Comments\n\nComments are removed from the final output:\n\n```txt\n\u003c# this will not be rendered #\u003e\n```\n\nMultiline comments are supported too.\n\n## Library Usage\n\n```ts\nimport { Generator, Parser } from \"mtrgen-js\";\n\nconst template = `--- MTRGEN ---\nname: component\nfilename: \u003c% $name|pascalCase %\u003e.ts\npath: src/components\n--- /MTRGEN ---\n\nexport const name = \"\u003c% $name %\u003e\";\n`;\n\nconst file = Generator.parseTemplate(template, { name: \"button\" });\nconsole.log(file.filePath);\nconsole.log(file.contents);\n\nconsole.log(Parser.parseString(\"Hello \u003c% $name %\u003e!\", { name: \"world\" }));\n```\n\nGenerate from a template file and write it to disk:\n\n```ts\nimport { Generator } from \"mtrgen-js\";\n\nconst files = Generator.parseAnyFile(\"./templates/component.ts.mtr\", {\n    name: \"button\",\n    folder: \"ui\",\n});\n\nGenerator.writeFiles(files, {\n    rootDir: process.cwd(),\n});\n```\n\n## Development\n\n```sh\nnpm run build\nnpm run test\n```\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatronator%2Fmtrgen-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatronator%2Fmtrgen-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatronator%2Fmtrgen-js/lists"}