protobuf_generator 1.0.9

A flutter generator package for generating code for protobuf, without installing protoc and protoc_plugin manually

protobuf_generator

A flutter generator package to compile Protocol Buffer files to Dart source code using build_runner (i.e. the Dart build pipline) without needing to manually install the protoc compiler or the Dart Protobuf plugin protoc_plugin.

The protobuf_generator package downloads the necessary Protobuf dependencies and googleapis for your platform to a temporary local directory.

Installation

Add the necessary dependencies to your pubspec.yaml file:

dependencies:
  protobuf: <latest>
  protoc_plugin: <latest>

dev_dependencies:
  build_runner: <latest>
  protobuf_generator: <latest>

Configuration

You must add your .proto files to a build.yaml file next to the pubspec.yaml:

targets:
  $default:
    sources:
      - $package$
      - lib/**
      - proto/** # Your .proto directory

This will use the default configuration for the protobuf_generator.

You may also configure custom options:

targets:
  $default:
    sources:
      - $package$
      - lib/$lib$
      - proto/**
    builders:
      protobuf_generator:
        options:
          # The version of the Protobuf compiler to use.
          # (Default: "27.2", make sure to use quotation marks)
          protobuf_version: "27.2"
          
          # The version of the Dart protoc_plugin package to use.
          # (Default: "21.1.2", make sure to use quotation marks)
          protoc_plugin_version: "21.1.2"

          # Directory which is treated as the root of all Protobuf files.
          # (Default: "proto/")
          proto_root_dir: "proto/"

          # Include paths given to the Protobuf compiler during compilation.
          # (Default: ["proto/"])
          proto_paths:
            - "proto/"

          # The root directory for generated Dart output files.
          # (Default: "lib/src/proto")
          dart_out_dir: "lib/src/generated"

          # Use the "protoc" command that's available on the PATH instead of downloading one
          # (Default: false)
          use_installed_protoc: false

          # Whether or not the protoc_plugin Dart scripts should be precompiled for better performance.
          # (Default: true)
          precompile_protoc_plugin: true

          # Whether or not to generate the descriptor file for the proto files
          # (Default: false)
          generate_descriptor_file: false

          # Whether or not to generate gRPC service stubs (.pbgrpc.dart files)
          # (Default: false)
          generate_grpc: false
          # GitHub repositories configuration
          # GitHub repositories containing proto files to include
          github_repos:
            # Simple format - just the repository URL (uses 'main' branch and repository root)
            - "https://github.com/owner/proto-definitions"
            
            # Full format with branch and single subdirectory
            - url: "https://github.com/grpc/grpc-proto"
              branch: "master"
              paths:
                - "grpc"
              
            # Another example with a specific tag/branch
            - url: "https://github.com/envoyproxy/protoc-gen-validate"
              branch: "v0.10.1"
              paths:
                - "api/v1"
              
            # SSH format also supported
            - url: "[e-mail]:company/internal-protos.git"
              branch: "main"
              paths:
                - "api/v1"
                - "api/v2"
              
            # Custom GitHub domain (GitHub Enterprise) examples
            - url: "[e-mail]:dreamplug-tech/protorepo.git"
              branch: "master"
            - url: "https://enterprise.github.com/company/repo"
              branch: "main"

Using Only GitHub Repositories

If you want to use only GitHub repositories without any local proto files, you can:

1. Create a dummy trigger file (e.g., github_trigger.proto) with basic proto content
2. Configure github_repos in your build.yaml as shown above
3. Include the dummy trigger file in the sources list
4. Run dart run build_runner build to generate code from the GitHub repositories

Step 1: Create dummy trigger file (github_trigger.proto):

syntax = "proto3";

package trigger;

// This is a dummy file to trigger build_runner for GitHub-only repositories
message GithubTrigger {
  string dummy = 1;
}

Step 2: Configure build.yaml for GitHub-only setup:

targets:
  $default:
    builders:
      protobuf_generator:
        options:
          dart_path: "lib/src/generated"
          proto_paths: []  # No local proto files
          github_repos:
            - url: "https://github.com/grpc/grpc-proto"
              branch: "master"
              paths:
                - "grpc"
        sources:
          - github_trigger.proto  # Include the dummy trigger file

The dummy trigger file is required because build_runner needs actual source files to execute. The generator will detect this special file and process only the GitHub repositories, ignoring the trigger file itself during protobuf generation.

Running

Once everything is set up, you may simply run the build_runner package:

dart run build_runner build

The build_runner sometimes caches results longer than it should, so in some cases, it may be necessary to delete the .dart_tool/build directory.

Contributing

If you have read up till here, then 🎉🎉🎉. There are couple of ways in which you can contribute to the growing community of protobuf_generator.dart.

• Pick up any issue marked with "good first issue"
• Propose any feature, enhancement
• Report a bug
• Fix a bug
• Write and improve some documentation. Documentation is super critical and its importance cannot be overstated!
• Send in a Pull Request 😊