{"id":15077721,"url":"https://github.com/armortal/protobuffed","last_synced_at":"2026-01-18T22:33:37.146Z","repository":{"id":65496216,"uuid":"590339208","full_name":"armortal/protobuffed","owner":"armortal","description":"Protocol buffers buffed up :muscle: A lightweight tool for managing your protobuf projects.","archived":false,"fork":false,"pushed_at":"2025-03-14T22:10:53.000Z","size":142,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-14T23:19:52.047Z","etag":null,"topics":["grpc","protobuf","protocol-buffers"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/armortal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2023-01-18T07:20:39.000Z","updated_at":"2025-03-14T22:07:35.000Z","dependencies_parsed_at":"2024-06-21T01:06:20.050Z","dependency_job_id":"51c1b07e-667b-4710-b63d-f7444de7b59a","html_url":"https://github.com/armortal/protobuffed","commit_stats":{"total_commits":68,"total_committers":1,"mean_commits":68.0,"dds":0.0,"last_synced_commit":"bfda2951e2dfb888ce5b94e9152541d4728d09a1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armortal%2Fprotobuffed","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armortal%2Fprotobuffed/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armortal%2Fprotobuffed/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/armortal%2Fprotobuffed/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/armortal","download_url":"https://codeload.github.com/armortal/protobuffed/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305945,"owners_count":20917208,"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":["grpc","protobuf","protocol-buffers"],"created_at":"2024-09-25T04:30:45.144Z","updated_at":"2025-04-05T08:12:41.251Z","avatar_url":"https://github.com/armortal.png","language":"Go","readme":"# protobuffed [![test](https://github.com/armortal/protobuffed/actions/workflows/test.yml/badge.svg)](https://github.com/armortal/protobuffed/actions/workflows/test.yml)\n\nProtocol buffers buffed up :muscle: A lightweight tool for managing your protobuf projects.\n\nProtobuffed was originally developed to ease the workload on developers when working with projects that utilize protocol buffers. The process involved in setting up protobuf and plugin binaries can be overwhelming and time consuming particularly when working in teams and ensuring each developer have the same binary versions. Protobuffed aims to solve this issue by using a single configuration file that sits in your project's repository and does the heavy lifting so that developers don't have to.\n\n\u003e :warning: This project is currently in active development and we may make changes (potentially breaking) as we gather feedback from early adopters until we get to the first major release.\n\n## Contents\n\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n\t- [Initializing a new project](#initializing-a-new-project)\n    - [Creating your proto](#creating-your-proto)\n\t- [Adding your configuration](#adding-your-configuration)\n\t- [Generating code](#generating-code)\n- [Dependencies](#dependencies)\n    - [Registered](#registered)\n    - [Custom](#custom)\n- [Configuration](#configuration)\n- [Commands](#commands)\n\t- [init](#init)\n\t- [install](#install)\n  - [run](#run)\n  - [generate](#generate)\n- [Cache](#cache)\n- [Contributing](#contributing)\n\n## Installation\n\nInstall with `go`:\n\n`go install github.com/armortal/protobuffed`\n\n## Getting Started\n\nThis getting started guide is based off our example which you can find in the [examples directory](./examples).\n\n### Initializing a new project\n\nProtobuffed uses a [configuration](#configuration) file that describes the project's dependencies, plugins and its associated configuration. You can initialize a new project by running `protobuffed init` (generally in the root folder of your project). You will see a newly created file named `protobuffed.json` (can be changed with the `-f` or `--file` flag).\n\nThe below example was created with `protobuffed init --name example`\n\n```json\n{\n  \"name\": \"example\",\n  \"dependencies\": {\n    \"protoc\": \"v30.1\"\n  },\n  \"imports\": [],\n  \"inputs\": [],\n  \"plugins\": [],\n  \"scripts\" : {}\n}\n```\n\n### Creating your proto\n\nEach one of your projects will have at least one `.proto` file which will have service and message definitions. Let's create service and message definitions for an *Auth* service in a file named `example.proto`. In our example, we are using the third\nparty [Google APIs](https://github.com/googleapis/googleapis) options for generating our gRPC Gateway stub.\n\n```proto\nsyntax = \"proto3\";\n\noption go_package = \"github.com/armortal/protobuffed/examples\";\n\nimport \"google/api/annotations.proto\";\n\npackage armortal.protobuffed.example;\n\nservice Auth {\n    rpc SignIn(SignInRequest) returns (SignInResponse) {\n        option (google.api.http) = {\n            post: \"/signin\"\n            body: \"*\"\n        };\n    };\n\n    rpc SignUp(SignUpRequest) returns (SignUpResponse) {\n        option (google.api.http) = {\n            post: \"/signup\"\n            body: \"*\"\n        };\n    };\n}\n\nmessage SignInRequest {\n    string email = 1;\n    string password = 2;\n}\n\nmessage SignInResponse {\n    string token = 1;\n}\n\nmessage SignUpRequest {\n    string email = 1;\n    string password = 2;\n}\n\nmessage SignUpResponse {\n    string token = 1;\n}\n```\n\nWe now need to add the following to our configuration:\n- The name of the proto file in the **inputs** array.\n- The plugins and their associated dependencies.\n- The Google APIs **dependency** so we can import the third party proto definitions.\n- The imports of both the Google APIs dependency and the location of our protos (we need to add this if specifying an import).\n\n```json\n{\n  \"name\": \"example\",\n  \"dependencies\": {\n    \"protoc\": \"v30.1\",\n    \"protoc-gen-go\": \"v1.36.5\",\n    \"protoc-gen-go-grpc\": \"v1.71.0\",\n    \"protoc-gen-grpc-gateway\": \"v2.26.1\",\n    \"protoc-gen-grpc-web\": \"v1.5.0\",\n    \"protoc-gen-js\": \"v3.21.4\",\n    \"googleapis\": \"git://github.com/googleapis/googleapis\"\n  },\n  \"imports\": [\n    \".\",\n    \".protobuffed/googleapis\"\n  ],\n  \"inputs\": [\n    \"example.proto\"\n  ],\n  \"plugins\": [\n    {\n      \"name\": \"go\",\n      \"options\": \"paths=source_relative\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"go-grpc\",\n      \"options\": \"paths=source_relative\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"grpc-gateway\",\n      \"options\": \"paths=source_relative\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"grpc-web\",\n      \"options\": \"import_style=commonjs+dts,mode=grpcwebtext\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"js\",\n      \"options\": \"import_style=commonjs,binary\",\n      \"output\": \"./\"\n    }\n  ]\n}\n```\n\n### Install dependencies\n\nIn order to generate our code, we need to first run `protobuffed install` to download and install our dependencies. If your\nconfiguration file location is different to the default (`protobuffed.json`), you can specify this with the `--file` of `-f` option.\n\nAfter running the command, you will see a newly created folder named `.protobuffed` which contains all your dependencies. \nYou should update your `.gitignore` to include `.protobuffed/` so that the dependencies aren't committed to Git. With the binaries installed and the code generated, your project should now look like:\n\n```\n├── .protobuffed/\n|   ├── protoc/\n|   ├── protoc-gen-go/\n|   ├── protoc-gen-go-grpc/\n|   ├── protoc-gen-grpc-gateway/\n|   ├── protoc-gen-grpc-web/\n|   ├── protoc-gen-js/\n|   ├── googleapis\n├── .gitignore\n├── example.proto\n├── protobuffed.json\n```\n\n### Generating code\n\nNow that our configuration file is defined and our dependencies installed, we can now generate source code with `protobuffed generate`. Below is an example of your directory after executing the command.\n\n\u003e :information_source: By default, each dependencies' **bin** folder is added to the path before executing **protoc**.\n\n```\n├── .protobuffed/\n|   ├── protoc/\n|   ├── protoc-gen-go/\n|   ├── protoc/\n|   ├── protoc-gen-go/\n|   ├── protoc-gen-go-grpc/\n|   ├── protoc-gen-grpc-gateway/\n|   ├── protoc-gen-grpc-web/\n|   ├── protoc-gen-js/\n|   ├── googleapis\n├── example.pb.go\n├── example_grpc.pb.go\n├── example_grpc_web_pb.d.ts\n├── example_grpc_web_pb.js\n├── example_pb.d.ts\n├── example_pb.js\n├── .gitignore\n├── example.proto\n├── protobuffed.json\n```\n\n## Dependencies\n\nAll projects will have at least one dependency. There are both [registered](#registered) and [custom](#custom) dependencies which can be included.\n\n### Registered\n\nThe following dependencies are registered and implemented in this project. They can be used directly with semantic versions (e.g. v0.1.0)\n\n| Name | Source |\n| :--- | :--------- |\n| **protoc** | [https://github.com/protocolbuffers/protobuf](https://github.com/protocolbuffers/protobuf) |\n| **protoc-gen-go** | [https://github.com/protocolbuffers/protobuf-go](https://github.com/protocolbuffers/protobuf-go) |\n| **protoc-gen-go-grpc** | [https://github.com/grpc/grpc-go](https://github.com/grpc/grpc-go) |\n| **protoc-gen-grpc-gateway** | [https://github.com/grpc-ecosystem/grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) |\n| **protoc-gen-grpc-web** | [https://github.com/grpc/grpc-web](https://github.com/grpc/grpc-web) |\n| **protoc-gen-js** | [https://github.com/protocolbuffers/protobuf-javascript](https://github.com/protocolbuffers/protobuf-javascript) |\n\n### Custom\n\nIf you require a dependency that is not registered, you can include them using a URL with the following schemes:\n\n| Scheme | Description |\n| :----- | :---------- |\n| `git` | Clone a git repository using `git clone`. You must have `git` installed. |\n| `http` | Download via http. |\n| `https` | Download via https. |\n\nIf you need to add some further logic than just simply downloading a custom dependency (e.g. build a binary, unzip a file), you can add\nit to the `scripts` section of your configuration file and execute it with the `run` command prior to generating your files.\n\nFor example, to continue from our example above, if we need to download this repository's contents and unzip it we can add an inline script or call one like the following:\n\n```json\n{\n  \"name\": \"example\",\n  \"dependencies\": {\n    \"protoc\": \"v30.1\",\n    \"protoc-gen-go\": \"v1.36.5\",\n    \"protoc-gen-go-grpc\": \"v1.71.0\",\n    \"protoc-gen-grpc-gateway\": \"v2.26.1\",\n    \"protoc-gen-grpc-web\": \"v1.5.0\",\n    \"protoc-gen-js\": \"v3.21.4\",\n    \"googleapis\": \"git://github.com/googleapis/googleapis\",\n    \"armortal\": \"https://github.com/armortal/protobuffed/archive/refs/heads/main.zip\"\n  },\n  \"imports\": [\n    \".\",\n    \".protobuffed/googleapis\"\n  ],\n  \"inputs\": [\n    \"example.proto\"\n  ],\n  \"plugins\": [\n    {\n      \"name\": \"go\",\n      \"options\": \"paths=source_relative\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"go-grpc\",\n      \"options\": \"paths=source_relative\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"grpc-gateway\",\n      \"options\": \"paths=source_relative\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"grpc-web\",\n      \"options\": \"import_style=commonjs+dts,mode=grpcwebtext\",\n      \"output\": \"./\"\n    },\n    {\n      \"name\": \"js\",\n      \"options\": \"import_style=commonjs,binary\",\n      \"output\": \"./\"\n    }\n  ],\n  \"scripts\": {\n    \"unzipInline\": \"unzip -o .protobuffed/armortal/main.zip -d .protobuffed/armortal \u0026\u0026 mv .protobuffed/armortal/protobuffed-main/* .protobuffed/armortal \u0026\u0026 rm -rf .protobuffed/armortal/protobuffed-main .protobuffed/armortal/main.zip\",\n    \"unzip\": \"scripts/unzip.sh\"\n  }\n}\n```\n\n## Configuration\n\nA configuration file represents your project's configuration.\n\n| Name | Type | Description |\n| :--- | :--- | :---------- |\n| `dependencies` | **map[string]string** | The dependency configuration. If dependency value is a semantic version (e.g. v1.0.0), this must be a registered dependency defined in this project. If not, you must use a `http(s)` or `git` URL. |\n| `imports` | **[]string** | Imports to include. |\n| `inputs` | **[]string** | Proto files to generate source for. |\n| `plugins` | **[][Plugin](#plugin)** | Plugins to include. |\n| `scripts` | **map[string]string** | A map of scripts to define that can be executed via the `run` command. |\n\n### Plugin\n\n| Name | Type | Description |\n| :--- | :--- | :---------- |\n| `name` | **string** | The plugin name. This must be the full binary name and must be found in a dependencies' **bin** folder or environment **PATH**. |\n| `options` | **string** | A comma separated string of plugin options in the form of KEY=VALUE (e.g. `KEY1=VALUE1,KEY2=VALUE2`)\n| `output` | **string** | The output path. |\n\n## Commands\n\nExecute commands with `protobuffed \u003cCOMMAND\u003e \u003cOPTIONS\u003e`\n\n| Name | Description |\n| :--- | :---------- |\n| [init](#init) | Initializes a new configuration file. |\n| [install](#install) | Install all dependencies. |\n| [run](#run) | Run a script in the configuration. |\n| [generate](#generate) | Run the protoc compiler and generate source files. |\n\n### init\n\nInitializes a new configuration file.\n\n| Options | Short | Description |\n| :------ | :---- | :---------- |\n| `file` | `f` | The path of the configuration file to write (default is `protobuffed.json`) |\n| `name` | `n` | The name of the project. |\n\n### install\n\nInstall all dependencies.\n\n| Options | Short | Description |\n| :------ | :---- | :---------- |\n| `file` | `f` | The path of the configuration file to read (default is `protobuffed.json`) |\n\n\n### run\n\nRun a script defined in the configuration file. The command is `protobuffed run \u003cSCRIPT_NAME\u003e` where **SCRIPT_NAME** is\none that is defined in the `scripts` section of the configuration file.\n\n| Options | Short | Description |\n| :------ | :---- | :---------- |\n| `file` | `f` | The path of the configuration file to read (default is `protobuffed.json`) |\n\n### generate\n\nRun the protoc compiler and generate source files.\n\n| Options | Short | Description |\n| :------ | :---- | :---------- |\n| `file` | `f` | The path of the configuration file to read (default is `protobuffed.json`) |\n\n## Cache\n\nAll dependencies are stored in a `.protobuffed` directory in the folder where Protobuffed is executed.\n\nEach subfolder named after the key name in your dependencies' configuration.\n\nFor custom dependencies, if you want binaries to be included in the execution path, they must be located in\na `bin` folder within the dependency folder (e.g. `.protobuffed/\u003cYOUR_DEPENDENCY\u003e/bin`)\n\n## Contributing\n\nSee [Contributing](./CONTRIBUTING.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmortal%2Fprotobuffed","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmortal%2Fprotobuffed","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmortal%2Fprotobuffed/lists"}