{"id":15024,"library":"vscode-grammar-updater","title":"VS Code TextMate Grammar Updater","description":"The `vscode-grammar-updater` package is a specialized utility designed by Microsoft to manage and synchronize TextMate grammars within Visual Studio Code language extensions. Its primary function is to update grammar definitions from their source repositories, ensuring that syntax highlighting and other language features in VS Code extensions remain current. The current stable version is 1.1.0, published approximately four years ago, indicating a maintenance-focused development cycle tied closely to VS Code's internal needs rather than an independent, rapid release schedule. This tool is a key differentiator for VS Code extension developers, providing a built-in mechanism for integrating external TextMate grammar updates directly into the extension ecosystem, which might otherwise require manual, error-prone synchronization processes.","status":"maintenance","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/microsoft/vscode-grammar-updater","tags":["javascript","typescript"],"install":[{"cmd":"npm install vscode-grammar-updater","lang":"bash","label":"npm"},{"cmd":"yarn add vscode-grammar-updater","lang":"bash","label":"yarn"},{"cmd":"pnpm add vscode-grammar-updater","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for parsing YAML grammar definitions, which can be more human-readable than JSON.","package":"js-yaml","optional":false},{"reason":"Used for parsing command-line arguments for CLI usage.","package":"minimist","optional":false}],"imports":[{"note":"While TypeScript types are provided, this package is primarily used via CLI scripts within VS Code's internal build processes. Programmatic API details are sparsely documented, but a named export for the core update logic is a common pattern for such utilities.","wrong":"const { updateGrammars } = require('vscode-grammar-updater');","symbol":"updateGrammars","correct":"import { updateGrammars } from 'vscode-grammar-updater';"},{"note":"TypeScript types are included, suggesting an interface for configuration options when using the programmatic API, if available.","symbol":"GrammarUpdateOptions","correct":"import type { GrammarUpdateOptions } from 'vscode-grammar-updater';"}],"quickstart":{"code":"{\n  \"name\": \"my-vscode-extension\",\n  \"version\": \"0.0.1\",\n  \"description\": \"My VS Code language extension with a custom grammar.\",\n  \"scripts\": {\n    \"update-grammar\": \"vscode-grammar-updater --sourceRepoUrl https://github.com/my-org/my-lang-grammar --targetFilePath ./syntaxes/mylang.tmLanguage.json --cacheDir ./.grammar-cache\"\n  },\n  \"devDependencies\": {\n    \"vscode-grammar-updater\": \"^1.1.0\"\n  }\n}\n\n// To run this, first save the above as `package.json` in your extension root,\n// then install dependencies:\n// npm install\n\n// Then execute the update script:\n// npm run update-grammar\n\n// This script attempts to fetch and update the grammar from 'my-org/my-lang-grammar'\n// and place it in './syntaxes/mylang.tmLanguage.json', using '.grammar-cache'\n// for temporary files. Specific arguments might vary based on the grammar source.","lang":"json","description":"Demonstrates typical usage via an `npm` script in `package.json`, which is the most common way this utility is invoked for updating TextMate grammars within a VS Code extension project."},"warnings":[{"fix":"Prioritize `npm run` scripts for usage and inspect the source code or `dist` files for programmatic entry points if direct import is necessary.","message":"The package's primary mode of operation appears to be CLI-driven, often integrated into `npm` scripts, rather than direct programmatic import. Comprehensive API documentation for programmatic use is limited.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly check the GitHub repository for activity and ensure it meets your project's security and maintenance requirements. Consider pinning the version to avoid unexpected changes if it were to receive a breaking update.","message":"The package was last published over four years ago (May 18, 2022). While it's maintained by Microsoft for internal VS Code processes, external consumers should be aware of the infrequent updates and potential for outdated internal dependencies.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify network connectivity and proxy settings if updates fail with network-related errors. Corporate firewalls or restricted build environments might block access to external Git repositories.","message":"This utility requires network access to fetch grammars from their source repositories (e.g., GitHub). Ensure the execution environment has appropriate network connectivity and permissions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult example usage in other Microsoft/VS Code repositories (e.g., `vscode-typescript-next` build scripts) for common argument patterns, or review the source code for parameter parsing logic.","message":"The exact command-line arguments and their behavior might not be fully documented for external users. Inspection of the source code or usage in other VS Code repositories might be necessary to understand all available options.","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":"If used in an `npm` script (e.g., `\"update\": \"vscode-grammar-updater ...\"`), ensure the `npm install` command has been run. If trying to execute directly from the terminal, use `npx vscode-grammar-updater ...` or install globally via `npm install -g vscode-grammar-updater`.","cause":"The package is installed locally as a `devDependency` and not globally, or `npm`'s `bin` path is not in the system's PATH.","error":"'vscode-grammar-updater' command not found"},{"fix":"Check your internet connection, verify proxy settings if applicable (e.g., `HTTP_PROXY`, `HTTPS_PROXY` environment variables), and ensure you're not hitting API rate limits on the source repository's hosting platform (e.g., GitHub).","cause":"Network connectivity issues, proxy problems, or rate limiting from the remote Git host.","error":"Failed to fetch grammar from 'https://github.com/...' (or similar network error)"}],"ecosystem":"npm"}