Protobuf VSC

A comprehensive Protocol Buffers (protobuf) extension for Visual Studio Code providing syntax highlighting, IntelliSense, diagnostics, formatting, protoc compilation, breaking change detection, and more.

Author: Julian Bensch (@DrBlury)

Features

Syntax Highlighting

• Full syntax highlighting for .proto files
• Support for proto2, proto3, and 2023 edition syntax
• Text Proto Support: Syntax highlighting for .textproto, .pbtxt, .prototxt files
• Customizable via VS Code themes

Code Navigation

• Go to Definition: Navigate to message, enum, service, and RPC definitions
• Go to Definition on Imports: Navigate to imported .proto files
• Find All References: Find all usages of messages, enums, and fields
• Document Symbols: Outline view with all messages, enums, services, and RPCs
• Workspace Symbols: Search symbols across all .proto files

IntelliSense & Completions

• Auto-complete for keywords and built-in types
• Message and enum name completions from current file and imports
• Context-aware suggestions
• Import path completions including Google well-known types

Hover Information

• Display type information on hover
• Documentation for built-in types
• Symbol information for custom types

Diagnostics & Error Checking

• Syntax errors: Invalid protobuf syntax detection
• Naming conventions: Check PascalCase for messages/enums, snake_case for fields
• Reference errors: Undefined message or enum references
• Import errors: Missing or invalid import paths
• Field tag issues:
  • Duplicate field numbers
  • Reserved field number usage
  • Field numbers out of valid range
• Duplicate field names: Fields with same name in a message
• Discouraged constructs: Warnings about deprecated patterns

Code Formatting

• Built-in formatter with configurable settings
• clang-format Integration: Use clang-format for formatting (optional)
• Configurable indent size
• Tab vs spaces support
• Format on save support
• Format selection support

Protoc Compilation

• Compile Single File: Compile the current proto file with protoc
• Compile All: Batch compile all proto files in workspace
• Configurable Options: Pass custom protoc options and output paths
• Compile on Save: Optionally compile files automatically on save
• Variable Expansion: Support for ${workspaceRoot} and ${env.*} variables

Breaking Change Detection

• Detect API-breaking changes against a git baseline
• Configurable Rules:
  • Field number changes/deletions
  • Type changes
  • Message/enum deletions
  • RPC signature changes
  • Enum value changes
• Compare against any git reference (branch, tag, commit)
• Detailed violation reports with line locations

External Linter Integration

• Buf Lint: Integrate with buf CLI for linting
• Protolint: Integrate with protolint for additional lint rules
• Run on save or on demand
• View available lint rules
• Configure via buf.yaml or .protolint.yaml

Code Actions & Quick Fixes

• Fix Naming Conventions: Convert message/enum/field names to proper conventions
• Add Import: Automatically add import for unknown types
• Fix Duplicate Field Numbers: Suggest next available field number
• Convert 'required' to 'optional': Update deprecated proto2 required fields

Rename Symbol

• Rename messages, enums, fields, and services across workspace
• Safely updates all references
• Preview changes before applying

Code Snippets

• proto3 syntax declaration
• proto2 syntax declaration
• Edition 2023 declaration
• Message, enum, service declarations
• RPC methods
• Field declarations
• Import and package statements

Editor Features

• Folding: Support for messages, enums, services, and multi-line comments
• Bracket Matching: Match braces, brackets, and angle brackets
• Comment Toggling: Toggle line and block comments

Commands

Configuration

General Settings

Diagnostics Settings

Protoc Compilation Settings

Example protoc options:

{
  "protobuf.protoc.options": [
    "--proto_path=${workspaceRoot}/protos",
    "--java_out=${workspaceRoot}/gen/java",
    "--go_out=${workspaceRoot}/gen/go"
  ]
}

Breaking Change Detection Settings

External Linter Settings

clang-format Settings

Installation

From VS Code Marketplace

Search for "Protobuf VSC" in the VS Code Extensions view.

From Source

1. Clone this repository
2. Run npm install
3. Run npm run compile
4. Press F5 to launch the Extension Development Host

Prerequisites for Optional Features

Protoc Compilation

Install the Protocol Buffers compiler:

• macOS: brew install protobuf
• Ubuntu: apt-get install protobuf-compiler
• Windows: Download from protobuf releases

Buf Linter

Install the Buf CLI:

# macOS/Linux
brew install bufbuild/buf/buf

# npm
npm install -g @bufbuild/buf

Protolint

Install protolint:

# macOS
brew install protolint

# Go
go install github.com/yoheimuta/protolint/cmd/protolint@latest

clang-format

Install clang-format:

• macOS: brew install clang-format
• Ubuntu: apt-get install clang-format
• Windows: Included with LLVM/Clang installation

Development

Prerequisites

• Node.js 18+
• npm 9+
• VS Code 1.85+

Building

npm install
npm run compile

Testing

npm run test

Debugging

1. Open this project in VS Code
2. Press F5 to launch the Extension Development Host
3. Open a .proto file to test the extension

Supported Protobuf Versions

• proto2
• proto3
• Edition 2023

Supported File Types

• .proto - Protocol Buffers definition files
• .textproto, .pbtxt, .prototxt, .txtpb, .textpb, .pb.txt - Text Proto format files

License

MIT License - Copyright (c) 2025 Julian Bensch

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.