{"id":24764110,"url":"https://github.com/stillat/blade-parser-typescript","last_synced_at":"2025-05-08T23:44:08.086Z","repository":{"id":45911538,"uuid":"512236271","full_name":"Stillat/blade-parser-typescript","owner":"Stillat","description":"A Laravel Blade parser, compiler, and static analyzer written in TypeScript.","archived":false,"fork":false,"pushed_at":"2025-02-25T00:26:28.000Z","size":16438,"stargazers_count":94,"open_issues_count":17,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-08T23:44:02.180Z","etag":null,"topics":["blade","laravel"],"latest_commit_sha":null,"homepage":"https://stillat.com","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/Stillat.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":".github/FUNDING.yml","license":"license.md","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},"funding":{"github":"JohnathonKoster"}},"created_at":"2022-07-09T16:41:37.000Z","updated_at":"2025-05-02T14:26:24.000Z","dependencies_parsed_at":"2024-06-02T21:20:02.350Z","dependency_job_id":"e1a171d6-72e0-458b-ad95-2e54acfb4229","html_url":"https://github.com/Stillat/blade-parser-typescript","commit_stats":{"total_commits":34,"total_committers":1,"mean_commits":34.0,"dds":0.0,"last_synced_commit":"0073e2db43a38eb0dd490325aa96f73e704bb740"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-parser-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-parser-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-parser-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fblade-parser-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stillat","download_url":"https://codeload.github.com/Stillat/blade-parser-typescript/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253166474,"owners_count":21864467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["blade","laravel"],"created_at":"2025-01-28T21:32:51.118Z","updated_at":"2025-05-08T23:44:08.055Z","avatar_url":"https://github.com/Stillat.png","language":"TypeScript","funding_links":["https://github.com/sponsors/JohnathonKoster"],"categories":[],"sub_categories":[],"readme":"# Blade Parser\n\nThis library provides a Laravel Blade parser written in TypeScript. In addition to being able to parse Blade template files, this library also provides utilities and libraries that make it simpler to perform static analysis on Blade documents.\n\nWhat this project is:\n\n* A standalone Blade parser written in TypeScript/JavaScript\n* A standalone Blade compiler written in TypeScript/JavaScript\n* A Blade static analysis library\n* A Blade error/diagnostics library\n* An advanced Blade document transformation library\n* A Blade Formatter for Prettier (more info here)\n\nWhat this project is not:\n\n* A view engine. It will not be able to actually render your Blade templates\n\n## Installing\n\nThis package can be installed in your project using the following command:\n\n```bash\nnpm install --save stillat-blade-parser\n```\n\n## Basic Usage\n\nThe simplest way to get started using this library is to use the `BladeDocument.fromText` static helper method:\n\n```ts\nimport { BladeDocument } from \"stillat-blade-parser/out/document/bladeDocument\";\n\nconst document = BladeDocument.fromText(`\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003e{{ $title }}\u003c/title\u003e\n    \u003c/head\u003e\n\u003c/html\u003e`);\n```\n\nThis method will return an instance of `BladeDocument`, which provides many useful features and helpers.\n\nAs an example, we can ask the document for a list of all parsed nodes and do something special with any directives we find:\n\n```ts\nimport { BladeDocument } from \"stillat-blade-parser/out/document/bladeDocument\";\nimport { DirectiveNode } from 'stillat-blade-parser/out/nodes/nodes';\n\nconst document = BladeDocument.fromText(`\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003e{{ $title }}\u003c/title\u003e\n    \u003c/head\u003e\n\u003c/html\u003e`);\n\ndocument.getAllNodes().forEach((node) =\u003e {\n    if (node instanceof DirectiveNode) {\n        console.log(node.directiveName);\n    }\n});\n```\n\n## Parsing Options\n\nThe Blade parser can be configured with a few options to help guide the parser. These configurable options are:\n\n* `customIfs`: A list of custom `if` directives\n* `directives`: A list of directives that can be parsed\n* `ignoreDirectives`: A list of directive names that should be ignored\n\nAll provided option values are case-insensitive. Do not include the `@` when supplying directive names to the `directives` or `ignoreDirectives` lists.\n\n### Supplying Options to the Parser\n\nTo supply parser options, you must have an instance of `BladeDocument` *before* you parse the template contents. Each `BladeDocument` also contains a parser instance. We can use the `getParser()` method to retrieve the internal parser instance, which will allow us to set our options:\n\n```ts\nimport { BladeDocument } from \"stillat-blade-parser/out/document/bladeDocument\";\nimport { ParserOptions } from 'stillat-blade-parser/out/parser/parserOptions';\n\nconst document = new BladeDocument(),\n    options:ParserOptions = {\n        customIfs: [],\n        directives: [],\n        ignoreDirectives: []\n    };\n\n// Set the parser options.\ndocument.getParser().withParserOptions(options);\n\ndocument.loadString(`Template content`);\n```\n\n### The `directives` and `ignoreDirectives` Options\n\nThe `directives` and `ignoreDirectives` options are mutually exclusive, and only one will be used at a time. If values are provided for the `directives` configuration option, it will take precedence over the `ignoreDirectives` option.\n\nThe `ignoreDirectives` option is the default configuration setup, and allows developers to supply a list of directive names that *should not be parsed*. Because this parser library does not have any runtime access to your project's specific directives, it will attempt to parse everything that *could* be a valid directive.\n\nBy default, the `ignoreDirectives` option is set to the following:\n\n```ts\nconst options:ParserOptions = {\n    customIfs: [],\n    directives: [],\n    ignoreDirectives: [\n        'media',\n        'charset',\n        'import',\n        'namespace',\n        'supports',\n        'document',\n        'page',\n        'font-face',\n        'keyframes',\n        'viewport',\n        'counter-style',\n        'font-feature-values',\n        'swash',\n        'ornaments',\n        'annotation',\n        'stylistic',\n        'styleset',\n        'character-variant',\n        'font-variant-alternates',\n        'property',\n        'color-profile',\n        'click',\n        'submit', \n        'scroll',\n        'keydown',\n        'keypress',\n        'keyup',\n        'blur', \n        'change',\n        'contextmenu',\n        'copy',\n        'cut',\n        'paste',\n        'dblclick',\n        'drag',\n        'dragend',\n        'dragenter',\n        'dragleave',\n        'dragover',\n        'dragstart',\n        'drop',\n        'focus',\n        'focusin',\n        'focusout',\n        'input',\n        'mousedown',\n        'mouseenter',\n        'mouseleave',\n        'mousemove',\n        'mouseover',\n        'mouseout',\n        'mouseup',\n        'mousewheel',\n        'resize',\n        'select',\n        'touchcancel',\n        'touchend',\n        'touchmove',\n        'touchstart',\n        'wheel'\n    ]\n};\n```\n\nWhenever a potential directive is encountered and is present in the `ignoreDirectives` list, that section of the template is skipped over and that potential directive becomes part of the document's literal text.\n\nIn contrast, the `directives` configuration option can be used to supply a list of directive names that *can be parsed*. If a potential directive is encountered that is *not* in this list, that potential directive is skipped and becomes part of the document's literal text.\n\n### The `customIfs` Configuration Option\n\nThe `customIfs` configuration option is the parser's counterpart to Laravel's [Custom If Statements](https://laravel.com/docs/9.x/blade#custom-if-statements) feature. An important thing to note is this configuration option simply hints to the parser what will become an `if` statement internally.\n\nThis option can be set like so:\n\n```ts\nconst options:ParserOptions = {\n    customIfs: [\n        'disk',\n    ],\n    directives: [],\n    ignoreDirectives: []\n};\n```\n\nIn most situations you do *not* need to supply any value for this configuration option. The parser is capable of analyzing your Blade templates and detecting custom if statements automatically.\n\n## Formatting Conditional Element Open/Close Tags\n\nBecause of the formatter works internally, you will need to take a few steps if you need to format templates containing Blade code similar to the following:\n\n```blade\n@if ($someCondition)\n    \u003cx-slot:the_slot\u003e\n@endif\n\n    \u003c!-- More content here. --\u003e\n\n@if ($someCondition)\n    \u003c/x-slot\u003e\n@endif\n```\n\nThe above template will result in a Prettier error stating it encountered an unexpected closing tag. This can be resolved by wrapping the fragmented open/close tags with ignore comments:\n\n```blade\n@if ($someCondition)\n    {{-- format-ignore-start --}}\u003cx-slot:the_slot\u003e{{-- format-ignore-end --}}\n@endif\n\n    \u003c!-- More content here. --\u003e\n\n@if ($someCondition)\n    {{-- format-ignore-start --}}\u003c/x-slot\u003e{{-- format-ignore-end --}}\n@endif\n```\n\n## Reporting Issues\n\nPlease use the issues feature on GitHub to report bugs/issues. For general questions on how to use this library, please use the Discussions feature. Be considerate when interacting with others :)\n\nDue to the complexity and scope of this project, when reporting bugs/issues please include *all* required information to reproduce the bug or issue. You are encouraged to attach any problematic templates to the issue as a file in addition to being included in the issue description (this helps to eliminate any formatting/adjustments that the GitHub UI may apply).\n\n[https://github.com/stillat/blade-parser-typescript](https://github.com/stillat/blade-parser-typescript)\n\n## Contributing Changes\n\nThank you for considering contributing changes to this project!\n\n### Building from Source\n\nTo build this project from source, issue the following commands:\n\n```bash\nnpm install\nnpm run compile\n```\n\nIf you introduce changes that break existing tests with un-important whitespace changes, it is fine to simply update those tests to account for the new whitespace changes. An example of these types of changes would be the `transformer_` tests. Breaking whitespace inside literal/node content (unless its a bug fix) is not acceptable, however.\n\n### Running the Tests\n\nBefore opening a pull request, do try and ensure that new features/changes have corresponding tests created. In addition, make sure to correct any failing tests.\n\nTo run the test suite issue the following command:\n\n```bash\nnpm run test:parser\n```\n\n### Debugging the Parser Library\n\nThe easiest method to debug the parser library is to use VS Code and select the `Blade Parser` Run and Debug configuration. This debug configuration will launch the `/out/parser.ts` file in debug mode, allowing you to run and debug code from within that file right within VS Code.\n\n## License\n\nThis library is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n\nIf you find this project useful, or are using it in a commercial setting, please consider funding the project to ensure it's continued development.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fblade-parser-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstillat%2Fblade-parser-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fblade-parser-typescript/lists"}