{"id":40448343,"url":"https://github.com/connerohnesorge/bufrnix","last_synced_at":"2026-01-20T17:08:38.413Z","repository":{"id":290864638,"uuid":"926831398","full_name":"connerohnesorge/bufrnix","owner":"connerohnesorge","description":"Nix powered Protocol Buffers with declarative, reproducible code generation and comprehensive developer tooling.","archived":false,"fork":false,"pushed_at":"2025-12-24T20:51:10.000Z","size":4996,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-26T10:39:47.787Z","etag":null,"topics":["buf","code-generation","code-generator","flake","flake-parts","grpc","grpc-go","nix","nix-flake","protobuf"],"latest_commit_sha":null,"homepage":"https://connerohnesorge.github.io/bufrnix/","language":"Nix","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/connerohnesorge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-02-03T23:41:23.000Z","updated_at":"2025-12-24T20:51:11.000Z","dependencies_parsed_at":"2025-05-01T01:30:56.380Z","dependency_job_id":"c4b0f436-1fa5-44de-b536-d2daaa075099","html_url":"https://github.com/connerohnesorge/bufrnix","commit_stats":null,"previous_names":["conneroisu/bufrnix","connerohnesorge/bufrnix"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/connerohnesorge/bufrnix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connerohnesorge%2Fbufrnix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connerohnesorge%2Fbufrnix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connerohnesorge%2Fbufrnix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connerohnesorge%2Fbufrnix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/connerohnesorge","download_url":"https://codeload.github.com/connerohnesorge/bufrnix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/connerohnesorge%2Fbufrnix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["buf","code-generation","code-generator","flake","flake-parts","grpc","grpc-go","nix","nix-flake","protobuf"],"created_at":"2026-01-20T17:08:37.511Z","updated_at":"2026-01-20T17:08:38.395Z","avatar_url":"https://github.com/connerohnesorge.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bufrnix\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/bufrnix.png\" alt=\"Bufrnix Logo\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eNix-powered Protocol Buffers with declarative code generation and comprehensive developer tooling\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/conneroisu/bufr.nix/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://nixos.org\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Built%20with-Nix-5277C3.svg?logo=nixos\u0026logoColor=white\" alt=\"Built with Nix\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://protobuf.dev/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Protocol-Buffers-00ADD8.svg?logo=google\" alt=\"Protocol Buffers\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://conneroisu.github.io/bufrnix/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/docs-available-brightgreen.svg\" alt=\"Documentation\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-key-features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#-language-support\"\u003eLanguages\u003c/a\u003e •\n  \u003ca href=\"#-examples\"\u003eExamples\u003c/a\u003e •\n  \u003ca href=\"https://conneroisu.github.io/bufrnix/\"\u003eDocumentation\u003c/a\u003e\n\u003c/p\u003e\n\n## 📋 Overview\n\nBufrnix provides a **declarative, reproducible way** to generate Protocol Buffer code for multiple languages through Nix flakes. It eliminates the complexity of managing protoc plugins, dependencies, and build environments by leveraging Nix's deterministic package management.\n\n\u003e 📚 See the [quick start guide](https://conneroisu.github.io/bufrnix/guides/getting-started/) for a quick introduction to Bufrnix.\n\n### Table of Contents\n\n- [🎯 Why Bufrnix?](#-why-bufrnix)\n  - [The Problems with Remote Plugin Systems](#the-problems-with-remote-plugin-systems)\n  - [How Bufrnix Solves These Problems](#how-bufrnix-solves-these-problems)\n- [✨ Key Features](#-key-features)\n- [🚀 Quick Start](#-quick-start)\n- [📖 Comprehensive Examples](#-comprehensive-examples)\n- [🌍 Language Support](#-language-support)\n- [💡 Examples](#-examples)\n- [🛠️ Development Environment](#️-development-environment)\n- [⚙️ Configuration Reference](#️-configuration-reference)\n- [🔧 Advanced Usage](#-advanced-usage)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n\n## 🎯 Why Bufrnix?\n\nProtocol Buffer tooling has traditionally suffered from **dependency hell**, **network dependencies**, and **non-reproducible builds**. While Buf's remote plugin system simplifies initial setup, it introduces critical limitations that become deal-breakers for production teams:\n\n### The Problems with Remote Plugin Systems\n\n**🌐 Network Dependency Friction**\n- Remote plugins require constant internet connectivity, breaking offline development\n- Corporate firewalls and air-gapped environments can't access remote plugin execution  \n- Network latency and rate limiting slow down development workflows\n- Timeout errors (`context deadline exceeded`) and service interruptions disrupt CI/CD pipelines\n- Geographic latency affects teams in regions distant from Buf's servers\n\n**🔒 Security and Compliance Concerns**\n- Proprietary Protocol Buffer schemas must be sent to external servers for processing\n- Financial services, healthcare, and government contractors can't share sensitive API definitions\n- Intellectual property concerns prevent many organizations from using remote execution\n- Compliance requirements (SOX, HIPAA, FedRAMP) demand local processing of technical specifications\n- Supply chain security policies prohibit external dependency on third-party infrastructure\n\n**⚡ Technical Limitations**\n- **64KB response size limits** cause silent failures with large generated outputs (affects protoc-gen-grpc-swift and other plugins)\n- Plugins requiring file system access or multi-stage generation cannot function remotely\n- **\"All\" strategy requirement** prevents efficient directory-based generation optimizations\n- Custom plugins require expensive Pro/Enterprise subscriptions\n- Plugin ecosystem growth is bottlenecked by centralized approval processes\n- Cross-plugin dependencies (like protoc-gen-gotag modifying generated Go code) are impossible\n\n**🔄 Reproducibility Challenges**\n- Network variability introduces non-determinism in generated code\n- Plugin version updates can break existing workflows without warning\n- Cache invalidation and remote infrastructure changes affect build consistency\n- Migration between plugin versions often requires extensive code modifications\n- Alpha-to-stable transitions have caused breaking changes requiring full codebase updates\n- Remote caching can mask non-deterministic plugin behavior until production\n\n### How Bufrnix Solves These Problems\n\n**🏠 Local, Deterministic Execution**\n```nix\n# All plugins execute locally with dependencies managed by Nix\nlanguages.go = {\n  enable = true;\n  grpc.enable = true;     # No network calls, no timeouts\n  validate.enable = true; # Full plugin ecosystem available\n  # Exact plugin versions cryptographically pinned\n  grpc.package = pkgs.protoc-gen-go-grpc; # v1.3.0 always\n};\n```\n\n**🔐 Complete Privacy and Control**\n- All processing happens on your machines - schemas never leave your environment\n- No external dependencies for code generation workflows\n- Full control over plugin versions, updates, and security patches\n- Compliance-friendly for regulated industries (SOX, HIPAA, FedRAMP)\n- Supply chain integrity through cryptographic verification\n\n**⚡ Performance and Flexibility**\n- **60x faster builds** in some cases (20 minutes → 20 seconds in CI)\n- No artificial size limits (64KB) or plugin capability restrictions\n- Support for custom plugins, multi-stage generation, and complex workflows\n- Plugin chaining and file system access work seamlessly\n- Directory-based generation strategies for optimal performance\n- Parallel execution across multiple languages and plugins\n\n**🎯 True Reproducibility**\n```nix\n# Same inputs = identical outputs, always\nconfig = {\n  languages.go.grpc.package = pkgs.protoc-gen-go-grpc; # Exact version pinned\n  # Cryptographic hashes ensure supply chain integrity\n  # Content-addressed storage prevents version drift\n  # Hermetic builds with no external state\n};\n```\n\n**🛠 Developer Experience**\n- **Offline-first**: Development continues without internet connectivity\n- **Zero setup**: `nix develop` provides complete toolchain in seconds\n- **Type-safe configuration**: Catch errors before generation runs\n- **Multi-language**: Generate for 8+ languages simultaneously from one config\n- **Plugin ecosystem**: Access to all community plugins, not just Buf-approved ones\n\n### Real-World Impact\n\nTeams using Bufrnix report:\n- **Eliminated \"works on my machine\" problems** with reproducible Nix environments\n- **Simplified CI/CD pipelines** with deterministic, cacheable builds\n- **Improved security posture** by keeping sensitive schemas internal\n- **Faster iteration** without network latency and rate limiting\n- **Better compliance** with local processing requirements\n- **Cost savings** by eliminating Pro/Enterprise subscriptions for custom plugins\n- **Increased developer productivity** with offline-capable workflows\n\n### The Broader Ecosystem: Buf vs. Bufrnix\n\nBufrnix doesn't compete with Buf - it **complements** the Protocol Buffer ecosystem by addressing different use cases:\n\n**Buf excels at:**\n- Schema management and breaking change detection\n- Collaborative protobuf development with buf.build registry\n- Getting started quickly with zero local setup\n- Managed plugin ecosystem with security guarantees\n- Remote code generation for simple workflows\n\n**Bufrnix excels at:**\n- Local, offline-first development workflows\n- Complex multi-language, multi-plugin scenarios\n- Regulated environments with compliance requirements\n- High-performance build pipelines at scale\n- Custom plugin development and integration\n- Supply chain security with cryptographic verification\n\n**The hybrid approach** many teams adopt:\n1. **Use Buf for** schema validation, breaking change detection, and collaboration\n2. **Use Bufrnix for** actual code generation in production environments\n3. **Combine both** for comprehensive Protocol Buffer development workflows\n\nThis pattern maximizes the benefits of both tools while avoiding their respective limitations.\n\n### When to Choose Bufrnix\n\n**Choose Bufrnix if you need:**\n- Offline development capabilities\n- Corporate firewall/air-gapped environment support\n- Sensitive schema privacy and compliance\n- Custom or community plugins not in Buf's registry\n- Reproducible builds with version pinning\n- High-performance local execution\n- Multi-language code generation workflows\n\n**Buf's remote plugins work well for:**\n- Quick experimentation and getting started\n- Simple, single-language projects\n- Teams comfortable with external processing\n- Workflows fitting within remote plugin limitations\n\nBufrnix doesn't replace Buf - it **extends** the Protocol Buffer ecosystem with local, reproducible alternatives for teams that need them.\n\n### ✨ Key Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e🚀 \u003cstrong\u003eMulti-language Support\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e13+ languages: Go, JS/TS, Python, Java, C++, C#, Kotlin, Scala, Dart, PHP, Swift, C, and documentation generation\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e🔧 \u003cstrong\u003eRich Plugin Ecosystem\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003egRPC, gRPC-Web, gRPC-Gateway, Twirp, and validation\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e📦 \u003cstrong\u003eZero Setup\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003eAll dependencies managed through Nix\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e🎯 \u003cstrong\u003eDeclarative Configuration\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003eType-safe configuration with clear error messages\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e🔄 \u003cstrong\u003eReproducible Builds\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003eSame output across all machines and CI/CD\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e⚡ \u003cstrong\u003eDeveloper Experience\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003eComprehensive tooling, formatting, linting, and language servers included\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- [Nix](https://nixos.org/download.html) with [flakes enabled](https://nixos.wiki/wiki/Flakes)\n- That's it! All other dependencies are managed by Nix\n\n### 1. Basic Usage\n\nCreate a `flake.nix` in your project root:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    bufrnix.url = \"github:conneroisu/bufr.nix\";\n    bufrnix.inputs.nixpkgs.follows = \"nixpkgs\";\n  };\n\n  outputs = { nixpkgs, bufrnix, ... }: \n  let\n    system = \"x86_64-linux\";  # or your system\n    pkgs = nixpkgs.legacyPackages.${system};\n  in {\n    packages.default = bufrnix.lib.mkBufrnixPackage {\n      inherit (pkgs) lib;\n      inherit pkgs;\n      config = {\n        root = ./.;\n        protoc = {\n          files = [\"./proto/user/v1/user.proto\"];\n        };\n        languages.go = {\n          enable = true;\n          outputPath = \"gen/go\";\n          grpc.enable = true;\n        };\n      };\n    };\n  };\n}\n```\n\n### 2. Create Your Proto Files\n\n```protobuf\n// proto/user/v1/user.proto\nsyntax = \"proto3\";\n\npackage user.v1;\n\noption go_package = \"example.com/user/v1;userv1\";\n\nservice UserService {\n  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);\n  rpc GetUser(GetUserRequest) returns (GetUserResponse);\n}\n\nmessage CreateUserRequest {\n  string name = 1;\n  string email = 2;\n}\n\nmessage CreateUserResponse {\n  User user = 1;\n}\n\nmessage GetUserRequest {\n  string id = 1;\n}\n\nmessage GetUserResponse {\n  User user = 1;\n}\n\nmessage User {\n  string id = 1;\n  string name = 2;\n  string email = 3;\n  int64 created_at = 4;\n}\n```\n\n### 3. Generate Code\n\n```bash\nnix run\n```\n\nGenerated code will appear in `gen/go/user/v1/`:\n- `user.pb.go` - Protocol Buffer messages\n- `user_grpc.pb.go` - gRPC service definitions\n\n## 📖 Comprehensive Examples\n\n### Multi-Language Project\n\nGenerate code for multiple languages simultaneously:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n    bufrnix.url = \"github:conneroisu/bufr.nix\";\n    bufrnix.inputs.nixpkgs.follows = \"nixpkgs\";\n  };\n\n  outputs = { nixpkgs, bufrnix, ... }: {\n    packages.default = bufrnix.lib.mkBufrnixPackage {\n      inherit (nixpkgs.legacyPackages.x86_64-linux) lib pkgs;\n      config = {\n        root = ./.;\n        protoc = {\n          sourceDirectories = [\"./proto\"];\n          includeDirectories = [\"./proto\"];\n          files = [\n            \"./proto/user/v1/user.proto\"\n            \"./proto/product/v1/product.proto\"\n          ];\n        };\n        \n        # Go with full gRPC ecosystem\n        languages.go = {\n          enable = true;\n          outputPath = \"gen/go\";\n          options = [\"paths=source_relative\"];\n          grpc.enable = true;\n          gateway.enable = true;      # HTTP/JSON transcoding\n          validate.enable = true;     # Message validation\n        };\n        \n        # Dart for Flutter applications\n        languages.dart = {\n          enable = true;\n          outputPath = \"lib/proto\";\n          packageName = \"my_app_proto\";\n          grpc.enable = true;\n        };\n        \n        # JavaScript for web and Node.js\n        languages.js = {\n          enable = true;\n          outputPath = \"src/proto\";\n          packageName = \"my-proto\";\n          es.enable = true;           # Modern ECMAScript modules\n          grpcWeb.enable = true;      # Browser-compatible gRPC\n          twirp.enable = true;        # Twirp RPC framework\n        };\n        \n        # PHP with Twirp support\n        languages.php = {\n          enable = true;\n          outputPath = \"gen/php\";\n          namespace = \"MyApp\\\\Proto\";\n          twirp.enable = true;\n        };\n        \n        # Swift for iOS/macOS applications\n        languages.swift = {\n          enable = true;\n          outputPath = \"Sources/Generated\";\n          packageName = \"MyAppProto\";\n        };\n      };\n    };\n  };\n}\n```\n\n### Advanced Go Configuration\n\nFor Go projects requiring the full ecosystem:\n\n```nix\nlanguages.go = {\n  enable = true;\n  outputPath = \"internal/proto\";\n  packagePrefix = \"github.com/myorg/myproject\";\n  options = [\n    \"paths=source_relative\"\n    \"require_unimplemented_servers=false\"\n  ];\n  \n  # Core gRPC support\n  grpc = {\n    enable = true;\n    options = [\n      \"paths=source_relative\"\n      \"require_unimplemented_servers=false\"\n    ];\n  };\n  \n  # HTTP/JSON gateway for REST APIs\n  gateway = {\n    enable = true;\n    options = [\n      \"paths=source_relative\"\n      \"generate_unbound_methods=true\"\n    ];\n  };\n  \n  # Message validation\n  validate = {\n    enable = true;\n    options = [\"lang=go\"];\n  };\n};\n```\n\n### Modern JavaScript/TypeScript Setup\n\nFor modern web applications:\n\n```nix\nlanguages.js = {\n  enable = true;\n  outputPath = \"src/generated\";\n  packageName = \"@myorg/proto\";\n  \n  # Modern ECMAScript modules\n  es = {\n    enable = true;\n    options = [\n      \"target=ts\"                    # Generate TypeScript\n      \"import_extension=.js\"         # ES module extensions\n    ];\n  };\n\n  # gRPC-Web for browser compatibility\n  grpcWeb = {\n    enable = true;\n    options = [\n      \"import_style=typescript\"\n      \"mode=grpcwebtext\"\n    ];\n  };\n};\n```\n\n## 🌍 Language Support\n\n| Language | Status | Plugins \u0026 Features | Output |\n|----------|---------|-------------------|--------|\n| **Go** | ✅ Full | `protoc-gen-go`, gRPC, Gateway, Validation, VTProtobuf, Struct Transformer | Standard Go packages with comprehensive ecosystem |\n| **JavaScript/TypeScript** | ✅ Full | ES modules, gRPC-Web, Twirp, ts-proto, Protovalidate | Modern JS/TS with type definitions |\n| **Python** | ✅ Full | Standard protoc, gRPC, mypy, betterproto, type stubs | Python packages with optional typing |\n| **Dart** | ✅ Full | `protoc-gen-dart`, gRPC support | Flutter/server Dart classes with type safety |\n| **PHP** | ✅ Full | Standard protoc, Twirp, Async, Laravel, Symfony, gRPC, RoadRunner | PSR-4 compatible classes with framework integration |\n| **Java** | ✅ Full | `protoc-gen-java`, gRPC, Protovalidate | Standard Java classes with build system integration |\n| **C++** | ✅ Full | `protoc-gen-cpp`, gRPC, CMake helpers | Native C++ classes with CMake integration |\n| **Swift** | ✅ Full | `protoc-gen-swift` | iOS/macOS Swift classes with SwiftProtobuf |\n| **C#** | ✅ Full | `protoc-gen-csharp`, gRPC | .NET compatible classes with gRPC support |\n| **Kotlin** | ✅ Full | `protoc-gen-kotlin`, gRPC | JVM Kotlin classes with modern RPC support |\n| **Scala** | ✅ Full | `protoc-gen-scala`, gRPC | Scala classes with functional programming patterns |\n| **C** | ✅ Full | protobuf-c, nanopb | Embedded-friendly C implementations |\n| **Documentation** | ✅ Full | HTML/SVG generation, MDX templates | Rich documentation output formats |\n\n## 💡 Examples\n\nExplore complete working examples in the [`examples/`](examples/) directory:\n\n### 🟦 [Simple Go gRPC Example](examples/simple-flake/)\n```bash\ncd examples/simple-flake\nnix develop\ngo run main.go\n```\n- Basic gRPC server and client\n- User management service\n- Error handling and validation\n\n### 🎯 [Comprehensive Dart Example](examples/dart-example/) \n```bash\ncd examples/dart-example\nnix develop\ndart pub get\ndart run lib/main.dart\ndart test\n```\n- Complex protobuf messages with all field types\n- Complete gRPC client implementation \n- Comprehensive test suite\n\n### 🟨 [Modern JavaScript Example](examples/js-example/)\n```bash\ncd examples/js-example\nnix develop\nnpm install \u0026\u0026 npm run build \u0026\u0026 npm start\n```\n- Multiple JavaScript output formats\n- gRPC-Web and Twirp clients\n- TypeScript integration\n\n### 🐘 [PHP Twirp Example](examples/php-twirp/)\n```bash\ncd examples/php-twirp\nnix develop\ncomposer install\nphp -S localhost:8080 -t src/\n```\n- Twirp RPC server and client\n- PSR-4 autoloading\n- JSON-over-HTTP communication\n\n### 🍎 [Swift Example](examples/swift-example/)\n```bash\ncd examples/swift-example\nnix develop\nbufrnix_init\nbufrnix\nswift build \u0026\u0026 swift run\n```\n- Protocol Buffer messages for iOS/macOS\n- Type-safe Swift code generation\n- SwiftProtobuf integration\n\n## 🛠️ Development Environment\n\n### Prerequisites\n\n- [Nix](https://nixos.org/download.html) with [flakes enabled](https://nixos.wiki/wiki/Flakes)\n- That's it! All other dependencies are managed by Nix\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/conneroisu/bufr.nix.git\ncd bufrnix\n\n# Enter development environment  \nnix develop\n\n# Available commands:\ndx        # Edit flake.nix\nlint      # Run Nix linting (statix + deadnix)\nnix fmt   # Format all files (Nix, Markdown, TypeScript, YAML)\n```\n\n### Documentation Development\n\nThe documentation is built with Astro and uses MDX format for enhanced content capabilities:\n\n```bash\ncd doc\nnix develop\nbun install\nbun run dev     # http://localhost:4321\nbun run build   # Build static site\n```\n\n## ⚙️ Configuration Reference\n\n### Root Configuration\n\n```nix\nconfig = {\n  # Required: Root directory containing proto files\n  root = \"./proto\";\n  \n  # Protoc configuration\n  protoc = {\n    sourceDirectories = [\"./proto\"];      # Where to find .proto files\n    includeDirectories = [\"./proto\"];     # Include path for imports\n    files = [                             # Optional: specific files to compile\n      \"./proto/user/v1/user.proto\"      # If empty, compiles all .proto files\n    ];\n  };\n  \n  # Debug configuration\n  debug = {\n    enable = false;                       # Enable debug output\n    verbosity = 1;                        # 1-3, higher = more verbose\n    logFile = \"\";                         # Empty = stdout, or path to file\n  };\n  \n  # Language configurations (see language-specific docs)\n  languages = { ... };\n};\n```\n\n### Language-Specific Options\n\nEach language module supports:\n\n- `enable`: Boolean to enable/disable the language\n- `outputPath`: Where to place generated files (relative to root)\n- `options`: Array of options passed to the base protoc plugin\n- Plugin-specific configuration (e.g., `grpc.enable`, `validate.enable`)\n\nSee the [Language Modules Documentation](src/languages/README.md) for complete details.\n\n## 🔧 Advanced Usage\n\n### Custom Proto Dependencies\n\n```nix\nprotoc = {\n  includeDirectories = [\n    \"./proto\"\n    \"${pkgs.protobuf}/include\"           # Include well-known types\n    \"${googleapis}/google/api\"           # Google API protos\n  ];\n};\n```\n\n### CI/CD Integration\n\n```yaml\n# .github/workflows/protobuf.yml\nname: Generate Protobuf Code\non: [push, pull_request]\njobs:\n  generate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: cachix/install-nix-action@v22\n        with:\n          extra_nix_config: |\n            experimental-features = nix-command flakes\n      - run: nix build\n      - run: git diff --exit-code  # Ensure generated code is up-to-date\n```\n\n### Multiple Output Configurations\n\nGenerate different outputs for different environments:\n\n```nix\n{\n  packages = {\n    # Production build with optimizations\n    prod = bufrnix.lib.mkBufrnixPackage {\n      inherit (pkgs) lib;\n      inherit pkgs;\n      config = {\n        languages.go = {\n          enable = true;\n          options = [\"paths=source_relative\" \"Mgrpc/service_config/service_config.proto=google.golang.org/grpc/serviceconfig\"];\n        };\n      };\n    };\n    \n    # Development build with validation and debugging\n    dev = bufrnix.lib.mkBufrnixPackage {\n      inherit (pkgs) lib;  \n      inherit pkgs;\n      config = {\n        debug.enable = true;\n        languages.go = {\n          enable = true;\n          validate.enable = true;\n          gateway.enable = true;\n        };\n      };\n    };\n  };\n}\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n1. **Fork and clone** the repository\n2. **Make changes** to language modules or core functionality\n3. **Test** with the example projects\n4. **Update documentation** as needed\n5. **Submit a pull request**\n\n### Adding Language Support\n\n1. Create a new module in `src/languages/`\n2. Add configuration options to `src/lib/bufrnix-options.nix`\n3. Create a working example in `examples/`\n4. Update documentation\n\nSee the [Language Modules README](src/languages/README.md) for details.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Related Projects\n\n- [Protocol Buffers](https://developers.google.com/protocol-buffers) - Google's language-neutral data serialization\n- [Nix](https://nixos.org/) - Reproducible package management and builds\n- [gRPC](https://grpc.io/) - High-performance RPC framework\n- [Twirp](https://github.com/twitchtv/twirp) - Simple RPC framework for service-to-service communication\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eQuestions?\u003c/strong\u003e Check out the \u003ca href=\"https://conneroisu.github.io/bufrnix/\"\u003edocumentation\u003c/a\u003e, browse the \u003ca href=\"examples/\"\u003eexamples\u003c/a\u003e, or \u003ca href=\"https://github.com/conneroisu/bufr.nix/issues/new\"\u003eopen an issue\u003c/a\u003e!\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by the Bufrnix community\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnerohnesorge%2Fbufrnix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconnerohnesorge%2Fbufrnix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconnerohnesorge%2Fbufrnix/lists"}