buffrs 0.12.0

Modern protobuf package management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

# Workspaces

Since version 0.12, buffrs supports workspaces for managing multiple related packages in a single repository.

## What is a Workspace?

A workspace is a collection of buffrs packages that share a common root directory. This is useful when maintaining multiple API versions, splitting functionality across packages, or managing shared libraries alongside consuming packages.

## Creating a Workspace

To create a workspace, add a `[workspace]` section to your root `Proto.toml`:

```toml
edition = "0.12"

[workspace]
members = [
  "packages/common",
  "packages/api-one",
  "packages/api-two",
]
```

Each member is a separate buffrs package with its own `Proto.toml` manifest. The workspace root `Proto.toml` should **not** contain a `[package]` section - it only defines the workspace structure.

## Directory Structure

A typical workspace structure:

```
my-workspace/
├── Proto.toml              # Workspace root manifest
└── packages/
    ├── common/
    │   ├── Proto.toml      # Package manifest
    │   └── proto/
    │       └── common.proto
    ├── api-one/
    │   ├── Proto.toml
    │   └── proto/
    │       └── api.proto
    └── api-two/
        ├── Proto.toml
        └── proto/
            └── api.proto
```

## Workspace Commands

### Installing Dependencies

From the workspace root:

```bash
buffrs install
```

This installs dependencies for all workspace members, handling inter-workspace dependencies automatically.

### Publishing

From the workspace root:

```bash
buffrs publish --registry http://... --repository my-repo
```

Buffrs automatically:
- Resolves dependencies across all workspace members
- Publishes packages in topological order (dependencies first)
- Handles local dependencies within the workspace
- Ensures each package is published only once, even if multiple members depend on it

### Uninstalling

From the workspace root:

```bash
buffrs uninstall
```

Clears vendor directories for all workspace members.

## Inter-workspace Dependencies

Workspace members can depend on each other using local path references:

```toml
# packages/api-two/Proto.toml
edition = "0.12"

[package]
type = "api"
name = "my-api-two"
version = "2.0.0"

[dependencies]
"my-common" = { path = "../common" }
```

When publishing the workspace, buffrs automatically publishes `my-common` first, then publishes `my-api-two` with the dependency reference updated to point to the registry.

## Package-only Commands

Some commands are designed for package-level operations and cannot run from a workspace root:

- `buffrs add`
- `buffrs remove`
- `buffrs package`
- `buffrs lint`
- `buffrs list`

These commands will provide a clear error message directing you to run them from a package directory within the workspace.

## Benefits

Workspaces provide:

- **Single-command publishing**: No need to manually navigate directories or worry about dependency order
- **Automatic deduplication**: Shared dependencies are published once
- **Development efficiency**: Develop and test changes across multiple packages simultaneously
- **Monorepo support**: Natural fit for monorepo setups with multiple API packages