Organize Protobuf files into modules

To create and push to the BSR, your module must build successfully. This means that you are able to run buf build successfully on your module and your module has no dependencies pinned to a non-main commit. Before you can push a module into the BSR, a repository must exist, and you must own or have access to that repository. A repository can be created either through the UI or from the command line with the Buf CLI. If you want to collaborate with other users on a module, select an organization as the owner of the repository.

1. Log into the BSR

We recommend following the "Getting Started with the Buf Schema Registry" guide, if you haven't already done this.

2. Create a repository for your module

Through the UI: Log in at https://buf.build/login, navigate to Your repositories, click Create Repository, select an owner, give it a repository name, and choose visibility (public or private).

Or use the CLI:

$ buf beta registry repository create buf.build/<USERNAME>/push-a-module --visibility public

3. Add a Protobuf file

Add some Protobuf code, in this example the package name is going to be acme/units/v1 so the code is going to be in the acme/units/v1/unit.proto file with the acme.units.v1 package name to mirror the import path.

syntax = "proto3";
package acme.units.v1;

message Unit {
  int32 number = 1;
  string name = 2;
}

4. Initialize a module

Run buf mod init buf.build/<USERNAME>/push-a-module which will add the following buf.yaml file:

version: v1
name: buf.build/<USERNAME>/push-a-module
breaking:
  use:
    - FILE
lint:
  use:
    - DEFAULT

If you already have a buf.yaml file, ensure that the name field is populated with the BSR module name.

5. Push to the BSR

buf push will push the local module state to the BSR and print out the commit

$ buf push
65740666fd6340898d10f1eb9c91448f

6. Depend on the module in another project

To use your module as a dependency in another project, add it to the deps key in the buf.yaml file of that project:

version: v1
name: buf.build/<USERNAME>/push-a-module-2
deps:
  - buf.build/<USERNAME>/push-a-module

7. Update the dependencies in the new project

Running buf mod update will pull the dependencies from the BSR

$ buf mod update

This will add the following to the buf.lock:

# Generated by buf. DO NOT EDIT.
version: v1
deps:
  - remote: buf.build
    owner: <USERNAME>
    repository: push-a-module
    commit: 65740666fd6340898d10f1eb9c91448f # this commit might be different

8. Import the Protobuf files into the new project

Because the buf.build/<USERNAME>/push-a-module supplies the file acme/units/v1/unit.proto we can now import it in our second project:

syntax = "proto3";
import "acme/units/v1/unit.proto";

message Day {
  acme.units.v1.Unit Temperature = 1;
}

Now you can run any buf command; buf build, buf generate, buf curl, buf push and buf will resolve the reference of acme.units.v1.unit.

To learn how to iterate on modules, see A guide to iterating on modules.