Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 16 additions & 14 deletions doc/src/content/docs/guides/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -193,24 +193,26 @@ languages.go = {
Cannot find module '@myorg/proto'
```

**Solutions:**
**Solution:**

1. **Check package.json generation:**
Bufrnix no longer generates package.json files. You need to manage imports manually in your project. Either:

```nix
languages.js = {
enable = true;
es = {
enable = true;
generatePackageJson = true;
packageName = "@myorg/proto";
};
};
1. **Use relative imports:**

```typescript
import { User } from "./gen/js/user_pb.js";
```

2. **Install generated packages:**
```bash
npm install ./gen/js # If package.json was generated
2. **Configure TypeScript path aliases in tsconfig.json:**

```json
{
"compilerOptions": {
"paths": {
"@myorg/proto/*": ["./gen/js/*"]
}
}
}
```

**Error: TypeScript type errors**
Expand Down
103 changes: 55 additions & 48 deletions doc/src/content/docs/reference/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,17 @@ title: Configuration Reference
description: Complete reference for all Bufrnix configuration options and settings with examples.
---

import { Card, CardGrid, Tabs, TabItem, Code, Badge, LinkCard, FileTree, Aside } from "@astrojs/starlight/components";
import {
Card,
CardGrid,
Tabs,
TabItem,
Code,
Badge,
LinkCard,
FileTree,
Aside,
} from "@astrojs/starlight/components";

# Configuration Reference

Expand All @@ -15,10 +25,12 @@ Bufrnix configuration prioritizes **explicitness over magic** and **reproducibil

<CardGrid>
<Card title="Type-safe" icon="check">
All options are validated at evaluation time, catching errors before generation runs
All options are validated at evaluation time, catching errors before
generation runs
</Card>
<Card title="Reproducible" icon="rocket">
Same configuration = identical outputs across all environments and team members
Same configuration = identical outputs across all environments and team
members
</Card>
<Card title="Explicit dependencies" icon="shield">
No hidden network calls or surprise downloads - everything declared upfront
Expand All @@ -29,7 +41,9 @@ Bufrnix configuration prioritizes **explicitness over magic** and **reproducibil
</CardGrid>

<Aside type="tip" title="Production Ready">
This approach trades some initial setup time for long-term reliability, making Bufrnix ideal for production systems where consistency matters more than convenience.
This approach trades some initial setup time for long-term reliability, making
Bufrnix ideal for production systems where consistency matters more than
convenience.
</Aside>

## Basic Configuration Structure
Expand Down Expand Up @@ -86,29 +100,21 @@ This approach trades some initial setup time for long-term reliability, making B
python = { enable = true; outputPath = "gen/python"; };
# ... other languages
};
};

};
}`}
lang="nix"
title="Complete configuration structure"
lang="nix"
title="Complete configuration structure"
/>

</TabItem>
</Tabs>

<FileTree>
- project/
- flake.nix ← Bufrnix configuration here
- proto/
- user/v1/
- user.proto
- gen/ ← Generated code output
- go/
- python/
- js/
- project/ - flake.nix ← Bufrnix configuration here - proto/ - user/v1/ -
user.proto - gen/ ← Generated code output - go/ - python/ - js/
</FileTree>
};
}
```
}; } ```

## Root Configuration

Expand Down Expand Up @@ -218,7 +224,7 @@ languages = {
];
grpc.enable = true;
};

js = {
# Frontend: Public APIs + Google annotations
additionalFiles = [
Expand All @@ -236,40 +242,41 @@ languages = {

**Configuration Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `languages.*.files` | list of strings or null | `null` | Proto files for this language only. Overrides global `protoc.files` |
| `languages.*.additionalFiles` | list of strings | `[]` | Additional files to add to global `protoc.files` for this language |
| Option | Type | Default | Description |
| ----------------------------- | ----------------------- | ------- | ------------------------------------------------------------------- |
| `languages.*.files` | list of strings or null | `null` | Proto files for this language only. Overrides global `protoc.files` |
| `languages.*.additionalFiles` | list of strings | `[]` | Additional files to add to global `protoc.files` for this language |

**Use Cases:**

<CardGrid>
<Card title="Backend + Frontend Separation" icon="split">
**Problem**: Different services for different tiers
**Solution**: `go.files` for internal services, `js.additionalFiles` for public APIs
**Problem**: Different services for different tiers **Solution**: `go.files`
for internal services, `js.additionalFiles` for public APIs
</Card>
<Card title="Google Annotations Linting" icon="shield">
**Problem**: Go + Google annotations = linting errors
**Solution**: Exclude Google annotations from Go, include in JavaScript
**Problem**: Go + Google annotations = linting errors **Solution**: Exclude
Google annotations from Go, include in JavaScript
</Card>
<Card title="Security Boundaries" icon="lock">
**Problem**: Frontend accessing internal services
**Solution**: Use `files` to enforce strict separation at build time
**Problem**: Frontend accessing internal services **Solution**: Use `files`
to enforce strict separation at build time
</Card>
<Card title="Build Performance" icon="rocket">
**Problem**: All languages process all files
**Solution**: Each language processes only relevant files
**Problem**: All languages process all files **Solution**: Each language
processes only relevant files
</Card>
</CardGrid>

<Aside type="tip" title="Migration from Global Files">
**Backward Compatible**: Existing configurations work unchanged. Per-language files are opt-in enhancements.

**Migration Path**:

1. Start with global `protoc.files` (current behavior)
2. Add `additionalFiles` for language-specific extensions
2. Add `additionalFiles` for language-specific extensions
3. Use `files` for complete per-language control
</Aside>
</Aside>

## Language Support

Expand Down Expand Up @@ -364,22 +371,19 @@ Modern JavaScript/TypeScript support with multiple output formats and RPC framew
languages.js = {
enable = true;
outputPath = "src/proto";
packageName = "@myorg/proto";

# Modern ECMAScript modules with TypeScript (recommended)
es = {
enable = true;
target = "ts"; # Generate TypeScript
options = ["import_extension=.js"]; # ES module extensions
generatePackageJson = true;
packageName = "@myorg/proto-es";
# Note: Manage your package.json file manually in your project
};

# Connect-ES for modern RPC
connect = {
enable = true;
generatePackageJson = true;
packageName = "@myorg/proto-connect";
# Note: Manage your package.json file manually in your project
};

# gRPC-Web for browser compatibility
Expand All @@ -404,20 +408,25 @@ languages.js = {
tsProto = {
enable = true;
options = ["esModuleInterop=true" "useOptionals=messages"];
generatePackageJson = true;
generateTsConfig = true;
# Note: Manage your package.json file manually in your project
};
};
```

#### JavaScript Configuration Options

| Option | Type | Default | Description |
| ------------- | --------------- | ---------- | -------------------------------------------- |
| `enable` | boolean | `false` | Enable JavaScript/TypeScript code generation |
| `outputPath` | string | `"gen/js"` | Output directory for generated code |
| `packageName` | string | `""` | JavaScript package name |
| `options` | list of strings | `[]` | Options to pass to protoc JS plugins |
| Option | Type | Default | Description |
| ------------ | --------------- | ---------- | -------------------------------------------- |
| `enable` | boolean | `false` | Enable JavaScript/TypeScript code generation |
| `outputPath` | string | `"gen/js"` | Output directory for generated code |
| `options` | list of strings | `[]` | Options to pass to protoc JS plugins |

<Aside type="note">
**Package Management**: Bufrnix focuses on protobuf generation. Manage your
`package.json` file manually in your project to define dependencies and
metadata.
</Aside>

### Dart Configuration

Expand Down Expand Up @@ -796,12 +805,10 @@ Here's a comprehensive example showing multiple languages configured together:
js = {
enable = true;
outputPath = "web/src/proto";
packageName = "@myorg/proto";

es = {
enable = true;
target = "ts";
generatePackageJson = true;
};

connect.enable = true;
Expand Down
8 changes: 3 additions & 5 deletions doc/src/content/docs/reference/languages.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -595,16 +595,12 @@ languages = {
es = {
enable = true; # Enabled by default
target = "ts"; # Options: "js", "ts", "dts"
generatePackageJson = true;
packageName = "@myproject/proto";
importExtension = ".js"; # For Node.js ES modules
};

# Connect-ES - Modern RPC framework
connect = {
enable = true; # Integrated with protoc-gen-es v2
generatePackageJson = true;
packageName = "@myproject/connect";
};

# Runtime validation support
Expand All @@ -616,7 +612,6 @@ languages = {
# Alternative: ts-proto for different style
tsProto = {
enable = false; # Set to true for interface-style TypeScript
generatePackageJson = true;
generateTsConfig = true;
options = [
"esModuleInterop=true"
Expand All @@ -631,6 +626,9 @@ languages = {
};
};
};

# Note: Bufrnix no longer generates package.json files. You should manage your
# package.json manually in your project.
```

### Generated Code Features
Expand Down
36 changes: 21 additions & 15 deletions doc/src/content/docs/reference/languages/javascript.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,13 @@ title: JavaScript/TypeScript Language Support
description: Modern Protocol Buffer support for JavaScript and TypeScript with ES modules, Connect-ES, gRPC-Web, and Twirp.
---

import { Tabs, TabItem, Badge, CardGrid, Card } from "@astrojs/starlight/components";
import {
Tabs,
TabItem,
Badge,
CardGrid,
Card,
} from "@astrojs/starlight/components";
import { Code } from "astro:components";
import basicConfig from "./javascript.x-basic-configuration.nix?raw";

Expand All @@ -16,12 +22,12 @@ JavaScript/TypeScript support provides multiple output formats and RPC options f

## Available Plugins

| Plugin | Description | Generated Files |
| --------------------------- | ----------------- | ---------------------- |
| **`protoc-gen-js`** | CommonJS messages | `*_pb.js`, `*_pb.d.ts` |
| **`protoc-gen-es`** | ES modules | `*.js`, `*.d.ts` |
| **`protoc-gen-grpc-web`** | gRPC-Web client | `*_grpc_web_pb.js` |
| **`protoc-gen-twirp_js`** | Twirp RPC | `*_twirp.js` |
| Plugin | Description | Generated Files |
| ------------------------- | ----------------- | ---------------------- |
| **`protoc-gen-js`** | CommonJS messages | `*_pb.js`, `*_pb.d.ts` |
| **`protoc-gen-es`** | ES modules | `*.js`, `*.d.ts` |
| **`protoc-gen-grpc-web`** | gRPC-Web client | `*_grpc_web_pb.js` |
| **`protoc-gen-twirp_js`** | Twirp RPC | `*_twirp.js` |

## Configuration

Expand All @@ -40,7 +46,6 @@ languages.js = {
languages.js = {
enable = true;
outputPath = "src/proto";
packageName = "@myorg/proto";
options = [
"import_style=commonjs"
"binary"
Expand Down Expand Up @@ -72,6 +77,9 @@ languages.js = {
options = ["lang=typescript"];
};
};

# Note: Bufrnix no longer generates package.json files. You should manage your
# package.json manually in your project.
```

## Per-Language Files
Expand Down Expand Up @@ -164,10 +172,10 @@ languages.js = {

### Configuration Options

| Option | Type | Description | Example |
|--------|------|-------------|---------|
| `files` | `list` | Override global files completely | Web client APIs only |
| `additionalFiles` | `list` | Extend global files | Add Google annotations |
| Option | Type | Description | Example |
| ----------------- | ------ | -------------------------------- | ---------------------- |
| `files` | `list` | Override global files completely | Web client APIs only |
| `additionalFiles` | `list` | Extend global files | Add Google annotations |

### Common JavaScript Use Cases

Expand Down Expand Up @@ -512,9 +520,7 @@ message StreamUsersRequest {
// vite.config.ts
export default {
optimizeDeps: {
include: [
"@bufbuild/protobuf",
],
include: ["@bufbuild/protobuf"],
},
};
```
Expand Down
Loading