{"id":13582367,"url":"https://github.com/webrpc/webrpc","last_synced_at":"2026-02-02T01:19:37.154Z","repository":{"id":34150896,"uuid":"168755538","full_name":"webrpc/webrpc","owner":"webrpc","description":"webrpc is a schema-driven approach to writing backend services for modern Web apps and networks","archived":false,"fork":false,"pushed_at":"2025-05-12T11:53:46.000Z","size":12789,"stargazers_count":774,"open_issues_count":25,"forks_count":49,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-12T12:23:58.933Z","etag":null,"topics":["api","code-generation","golang","json","rest","rpc","typescript","webapps","webrpc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webrpc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2019-02-01T20:22:28.000Z","updated_at":"2025-05-12T11:31:37.000Z","dependencies_parsed_at":"2023-01-15T04:56:01.208Z","dependency_job_id":"46bfcc5c-54ed-4d83-8a01-a7a0bc60e2b9","html_url":"https://github.com/webrpc/webrpc","commit_stats":null,"previous_names":["webrpc/webrpc-go"],"tags_count":87,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrpc%2Fwebrpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrpc%2Fwebrpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrpc%2Fwebrpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrpc%2Fwebrpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webrpc","download_url":"https://codeload.github.com/webrpc/webrpc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254041,"owners_count":22039792,"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":["api","code-generation","golang","json","rest","rpc","typescript","webapps","webrpc"],"created_at":"2024-08-01T15:02:39.026Z","updated_at":"2026-02-02T01:19:37.140Z","avatar_url":"https://github.com/webrpc.png","language":"Go","readme":"\u003cimg alt=\"webrpc\" src=\"https://github.com/webrpc/webrpc/raw/master/webrpc.png\" width=\"1024\" /\u003e\n\nwebrpc is a schema-driven approach to writing backend servers for the Web. Write your server's\nAPI interface in a schema format of [RIDL](./_examples/golang-basics/example.ridl) or [JSON](./_examples/golang-basics/example.webrpc.json),\nand then run `webrpc-gen` to generate the networking source code for your server and client apps. From the schema,\n`webrpc-gen` will generate application base class types/interfaces, JSON encoders, and networking code. In doing\nso, it's able to generate fully functioning and typed client libraries to communicate with your server. Enjoy\nstrongly-typed Web services and never having to write an API client library again.\n\nUnder the hood, webrpc is a Web service meta-protocol, schema and code-generator tool for\nsimplifying the development of backend services for modern Web applications.\n\n- [Getting started](#getting-started)\n- [Code generators](#code-generators)\n- [Quick example](#quick-example)\n  - [Example apps](#example-apps)\n- [Why](#why)\n- [Design / architecture](#design--architecture)\n- [Schema](#schema)\n- [Development](#development)\n  - [Building from source](#building-from-source)\n  - [Writing your own code-generator](#writing-your-own-code-generator)\n  - [Format ridl](#format-ridl)\n- [Authors](#authors)\n- [Credits](#credits)\n- [License](#license)\n\n# Getting started\n\n1. Install [webrpc-gen](https://github.com/webrpc/webrpc/releases)\n2. Write+design a [webrpc schema file](./_examples/golang-basics/example.ridl) for your Web service\n3. Run the code-generator to create your server interface and client, ie.\n   - `webrpc-gen -schema=example.ridl -target=golang -pkg=service -server -client -out=./service/proto.gen.go`\n   - `webrpc-gen -schema=example.ridl -target=typescript -client -out=./web/client.ts`\n4. Implement the handlers for your server -- of course, it can't guess the server logic :)\n\nanother option is to copy the [hello-webrpc](./_examples/hello-webrpc) example, and adapt for your own webapp and server.\n\nBtw, check out https://marketplace.visualstudio.com/items?itemName=XanderAppWorks.vscode-webrpc-ridl-syntax for VSCode\nplugin for RIDL synx highlighting.\n\n# Code generators\n\n| Generator                                              | Description                       | Schema | Client | Server |\n|--------------------------------------------------------|-----------------------------------|--------|--------|--------|\n| [golang](https://github.com/webrpc/gen-golang)         | Go 1.22+                          | v1     | ✅     | ✅     |\n| [typescript](https://github.com/webrpc/gen-typescript) | TypeScript (ES2022+)              | v1     | ✅     | ✅     |\n| [javascript](https://github.com/webrpc/gen-javascript) | JavaScript (ES6)                  | v1     | ✅     | ✅     |\n| [kotlin](https://github.com/webrpc/gen-kotlin)         | Kotlin (coroutines, moshi, ktor)  | v1     | ✅     |        |\n| [dart](https://github.com/webrpc/gen-dart)             | Dart 3.1+                         | v1     | ✅     |        |\n| [openapi](https://github.com/webrpc/gen-openapi)       | OpenAPI 3.0.0 (Swagger)           | v1     | ✅ [*](https://github.com/swagger-api/swagger-codegen#overview) | ✅ [*](https://github.com/swagger-api/swagger-codegen#overview)  |\n\n..contribute more! [webrpc generators](./gen/) are just Go templates (similar to [Hugo](https://gohugo.io/templates/) or [Helm](https://helm.sh/docs/chart_best_practices/templates/)).\n\n# Quick example\n\nHere is an example webrpc schema in RIDL format (a new documentation-like format introduced by webrpc)\n\n```\nwebrpc = v1\n\nname = your-app\nversion = v0.1.0\n\nstruct User\n  - id: uint64\n  - username: string\n  - createdAt?: timestamp\n\nstruct UsersQueryFilter\n  - page?: uint32\n  - name?: string\n  - location?: string\n\nservice ExampleService\n  - Ping()\n  - Status() =\u003e (status: bool)\n  - GetUserByID(userID: uint64) =\u003e (user: User)\n  - IsOnline(user: User) =\u003e (online: bool)\n  - ListUsers(q?: UsersQueryFilter) =\u003e (page: uint32, users: []User)\n\nerror 100 RateLimited     \"too many requests\"   HTTP 429\nerror 101 DatabaseDown    \"service outage\"      HTTP 503\n```\n\nGenerate webrpc Go server+client code:\n\n```\nwebrpc-gen -schema=example.ridl -target=golang -pkg=main -server -client -out=./example.gen.go\n```\n\nand see the generated `./example.gen.go` file of types, server and client in Go. This is essentially\nhow the [golang-basics](./_examples/golang-basics) example was built.\n\n\n## Example apps\n\n| Example                                        | Description                                   |\n|------------------------------------------------|-----------------------------------------------|\n| [hello-webrpc](./_examples/hello-webrpc)       | Go server \u003c=\u003e Javascript webapp               |\n| [hello-webrpc-ts](./_examples/hello-webrpc-ts) | Go server \u003c=\u003e Typescript webapp               |\n| [golang-basics](./_examples/golang-basics)     | Go server \u003c=\u003e Go client                       |\n| [golang-nodejs](./_examples/golang-nodejs)     | Go server \u003c=\u003e Node.js (Javascript ES6) client |\n| [node-ts](./_examples/node-ts)                 | Node.js server \u003c=\u003e Typescript webapp client   |\n\n# Why\n\n**TLDR;** it's much simpler + faster to write and consume a webrpc service than traditional approaches\nlike a REST API or gRPC service.\n\n  1. Code-generate your client libraries in full -- never write another API client again\n  2. Compatible with the Web. A Webrpc server is just a HTTP/HTTPS server that speaks JSON, and thus\n     all existing browsers, http clients, load balancers, proxies, caches, and tools work\n     out of the box (versus gRPC). cURL \"just works\".\n  3. Be more productive, write more correct systems.\n\n---\n\nWriting a Web service / microservice takes a lot of work and time. REST is making me tired.\nThere are many pieces to build -- designing the routes of your service, agreeing on conventions\nfor the routes with your team, the request payloads, the response payloads, writing the actual server\nlogic, routing the methods and requests to the server handlers, implementing the handlers, and\nthen writing a client library for your desired language so it can speak to your Web\nservice. Yikes, it's a lot of work. Want to add an additional field or handler? yea, you\nhave to go through the entire cycle. And what about type-safety across the wire?\n\nwebrpc automates a lot the work for you. Now from a single [webrpc schema file](./schema/README.md),\nyou can use the `webrpc-gen` cli to generate source code for:\n* Strongly-typed request / response data payloads for your target language\n* Strongly-typed server interface and methods on the service, aka the RPC methods\n* Complete client library to communicate with the web service\n\n\n# Design / architecture\n\nwebrpc services speak JSON, as our goals are to build services that communicate with webapps.\nWe optimize for developer experience, ease of use and productivity when building backends\nfor modern webapps. However, webrpc also works great for service\u003c-\u003eservice communication,\nbut it won't be as fast as gRPC in that scenario, but I'd be surprised to hear if for the majority\nof cases that this would be a bottleneck or costly tradeoff.\n\nwebrpc is heavily inspired by gRPC and Twirp. It is architecturally the same and has a similar\nworkflow, but simpler. In fact, the webrpc schema is similar in design to protobuf, as\nin we have messages (structs) and RPC methods, but the type system is arguably more flexible and\ncode-gen tooling is simpler. The [webrpc schema](./schema/README.md) is a documentation-like\nlanguage for describing a server's api interface and the type system within is inspired by Go,\nTypescript and WASM.\n\nWe've been thinking about webrpc's design for years, and were happy to see gRPC and Twirp\ncome onto the scene and pave the way with some great patterns. Over the years and after writing\ndozens of backends for Javascript-based Webapps and native mobile apps, and even built prior\nlibraries like [chi](https://github.com/go-chi/chi), a HTTP router for Go -- we asked ourselves: \n\nWhy have \"Rails\" and \"Django\" been such productive frameworks for writing webapps? And the answer\nwe came to is that its productive because the server and client are the same program,\nrunning in the same process on the same computer. Rails/Django/others like it, when rendering\nclient-state can just call a function in the same program, the client and the server\nare within the same domain and same state -- everything is a function-call away. Compare this to\nmodern app development such as writing a React.js SPA or a native iOS mobile app, where the app\nspeaks to an external API server with now the huge added effort to bridge data/runtime from\none namespace (the app) to an entirely other namespace (the server). It's too much work and\ntakes too much time, and is too brittle. There is a better way! instead of writing the code..\njust generate it. If we generate all of the code to native objects in both app/server,\nsuddenly, we can make a remote service once again feel like calling a method on the same\nprogram running on the same computer/process. Remote-Procedure-Call works!\n\nFinally, we'd like to compare generated RPC services (gRPC/Twirp/webrpc/other) to the most\ncommon pattern to writing services by \"making a RESTful API\", where the machinery is similar\nto RPC services. Picture the flow of data when a client calls out to a server -- from a client\nruntime proxy-object, we encode that object, send it over the wire, the server decodes it into\na server runtime proxy-object, the server handler queries the db, returns a proxy object,\nencodes it, and sends the function return data over the wire again. That is a ton of work,\nespecially if you have to write it by hand and then maintain robust code in both the client and\nthe server. Ahh, I just want to call a function on my server from my app! Save yourself the work\nand time, and code-generate it instead - Enter gRPC / Twirp .. and now, webrpc :) \n\n\n# Schema\n\nThe webrpc schema type system is inspired by Go and TypeScript, and is simple and flexible enough\nto cover the wide variety of language targets, designed to target RPC communication with Web\napplications and other Web services.\n\nHigh-level features:\n\n  * RIDL, aka RPC IDL, aka \"RPC interface design language\", format - a documentation-like schema\n  format for describing a server application.\n  * JSON schema format is also supported if you prefer to write tools to target webrpc's code-gen tools\n  * Type system inspired by Go + Typescript\n    * integers, floats, byte, bool, any, null, date/time\n    * lists (multi-dimensional arrays supported too)\n    * maps (with nesting / complex structures)\n    * structs / objects\n      * optional fields, default values, and pluggable code-generation for a language target\n    * enums\n\nFor more information please see the [schema readme](./schema/README.md).\n\n\n# Development\n\n## Building from source\n\n1. Install Go 1.16+\n2. $ `make build`\n3. $ `make test`\n4. $ `make install`\n\n\n## Writing your own code-generator\n\nSee [webrpc-gen documentation](./gen).\n\n## Format ridl\n- Use [Ridlfmt](https://github.com/webrpc/ridlfmt)\n- Supports same arguments as `gofmt` \n- See: [Example](https://github.com/webrpc/webrpc/blob/master/_examples/golang-basics/Makefile#L4)\n\n# Authors\n\n* [Peter Kieltyka](https://github.com/pkieltyka)\n* [José Carlos Nieto](https://github.com/xiam)\n* [Vojtech Vitek](https://github.com/VojtechVitek)\n* ..and full list of [contributors](https://github.com/webrpc/webrpc/graphs/contributors)!\n\n\n# Credits\n\n* [Twirp authors](https://github.com/twitchtv/twirp) for making twirp. Much of the webrpc-go\nlibrary comes from the twirp project.\n* [gRPC authors](https://grpc.io), for coming up with the overall architecture and patterns\nfor code-generating the bindings between client and server from a common IDL.\n\n\n# License\n\nMIT\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebrpc%2Fwebrpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebrpc%2Fwebrpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebrpc%2Fwebrpc/lists"}