VS Code TextMate Grammar Updater

1.1.0 · maintenance · verified Sun Apr 19

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.

Common errors

```
'vscode-grammar-updater' command not found
```
cause The package is installed locally as a `devDependency` and not globally, or `npm`'s `bin` path is not in the system's PATH.

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`.
```
Failed to fetch grammar from 'https://github.com/...' (or similar network error)
```
cause Network connectivity issues, proxy problems, or rate limiting from the remote Git host.

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).

Warnings

gotcha 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.
Fix: Prioritize `npm run` scripts for usage and inspect the source code or `dist` files for programmatic entry points if direct import is necessary.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

npm install vscode-grammar-updater npm
yarn add vscode-grammar-updater yarn
pnpm add vscode-grammar-updater pnpm

Imports

updateGrammars
wrong:
```
const { updateGrammars } = require('vscode-grammar-updater');
```
correct:
```
import { updateGrammars } from 'vscode-grammar-updater';
```
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.
GrammarUpdateOptions
```
import type { GrammarUpdateOptions } from 'vscode-grammar-updater';
```
TypeScript types are included, suggesting an interface for configuration options when using the programmatic API, if available.

Quickstart

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.

{
  "name": "my-vscode-extension",
  "version": "0.0.1",
  "description": "My VS Code language extension with a custom grammar.",
  "scripts": {
    "update-grammar": "vscode-grammar-updater --sourceRepoUrl https://github.com/my-org/my-lang-grammar --targetFilePath ./syntaxes/mylang.tmLanguage.json --cacheDir ./.grammar-cache"
  },
  "devDependencies": {
    "vscode-grammar-updater": "^1.1.0"
  }
}

// To run this, first save the above as `package.json` in your extension root,
// then install dependencies:
// npm install

// Then execute the update script:
// npm run update-grammar

// This script attempts to fetch and update the grammar from 'my-org/my-lang-grammar'
// and place it in './syntaxes/mylang.tmLanguage.json', using '.grammar-cache'
// for temporary files. Specific arguments might vary based on the grammar source.

view raw JSON →