Skip to content

Commit 905e81c

Browse files
dinwwwhdinwwwh
authored
docs: update README for all packages (#168)
* docs: update README for all packages * improve font weight and size * improve
1 parent 30f4fa7 commit 905e81c

File tree

10 files changed

+960
-70
lines changed

10 files changed

+960
-70
lines changed

‎README.md‎

Lines changed: 45 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -5,75 +5,59 @@
55
<h1></h1>
66

77
<div align="center">
8-
9-
![NPM Downloads](https://img.shields.io/npm/dm/%40orpc/server?logo=npm)
10-
![GitHub Release](https://img.shields.io/github/v/release/unnoq/orpc?logo=github)
11-
![GitHub commit activity](https://img.shields.io/github/commit-activity/m/unnoq/orpc?logo=git&logoColor=%23fff)
12-
![GitHub License](https://img.shields.io/github/license/unnoq/orpc)
13-
8+
<a href="https://codecov.io/gh/unnoq/orpc">
9+
<img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
10+
</a>
11+
<a href="https://www.npmjs.com/package/@orpc/client">
12+
<img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fclient?logo=npm" />
13+
</a>
14+
<a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
15+
<img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
16+
</a>
17+
<a href="https://discord.gg/TXEbwRBvQn">
18+
<img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
19+
</a>
1420
</div>
1521

16-
<p align="center">End-to-end typesafe APIs built quicker & easier</p>
17-
18-
> [!NOTE]
19-
> This project is still in heavy development, please be mindful of breaking changes.
20-
21-
**oRPC is a powerful combination of RPC and OpenAPI, offering an exceptional developer experience powered by TypeScript. It's designed to be simple and straightforward to use.**
22-
23-
---
24-
25-
## Features
22+
<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
2623

27-
- **Type-safe 🔒**: oRPC is built on top of TypeScript, which means you get full type safety out of the box.
28-
- **Easy to use ✍️**: oRPC is designed to be simple and straightforward to use.
29-
- **Contract first 📝**: Take advantage of a "contract first" approach to developing your API.
30-
- **Built-in plugins 🔌**: Easily implement into your favourite frameworks.
24+
**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards, ensuring a smooth and enjoyable developer experience.
3125

3226
---
3327

34-
## Documentation & Examples
35-
36-
You can find the full documentation & examples [here](https://orpc.unnoq.com).
37-
38-
---
28+
## Highlights
29+
30+
- **End-to-End Type Safety 🔒**: Ensure complete type safety from inputs to outputs and errors, bridging server and client seamlessly.
31+
- **First-Class OpenAPI 📄**: Adheres to the OpenAPI standard out of the box, ensuring seamless integration and comprehensive API documentation.
32+
- **Contract-First Development 📜**: (Optional) Define your API contract upfront and implement it with confidence.
33+
- **Exceptional Developer Experience ✨**: Enjoy a streamlined workflow with robust typing and clear, in-code documentation.
34+
- **Multi-Runtime Support 🌍**: Run your code seamlessly on Cloudflare, Deno, Bun, Node.js, and more.
35+
- **Framework Integrations 🧩**: Supports Tanstack Query (React, Vue), Pinia Colada, and more.
36+
- **Server Actions ⚡️**: Fully compatible with React Server Actions on Next.js, TanStack Start, and more.
37+
- **Standard Schema Support 🗂️**: Effortlessly work with Zod, Valibot, ArkType, and others right out of the box.
38+
- **Fast & Lightweight 💨**: Built on native APIs across all runtimes – optimized for speed and efficiency.
39+
- **Native Types 📦**: Enjoy built-in support for Date, File, Blob, BigInt, URL and more with no extra setup.
40+
- **Lazy Router ⏱️**: Improve cold start times with our lazy routing feature.
41+
- **SSE & Streaming 📡**: Provides SSE and streaming features – perfect for real-time notifications and AI-powered streaming responses.
42+
- **Reusability 🔄**: Write once and reuse your code across multiple purposes effortlessly.
43+
- **Extendability 🔌**: Easily enhance oRPC with plugins, middleware, and interceptors.
44+
- **Reliability 🛡️**: Well-tested, fully TypeScript, production-ready, and MIT licensed for peace of mind.
45+
- **Simplicity 💡**: Enjoy straightforward, clean code with no hidden magic.
46+
47+
## Documentation
48+
49+
You can find the full documentation [here](https://orpc.unnoq.com).
3950

4051
## Packages
4152

42-
- `@orpc/contract`: Build your API contract.
43-
- `@orpc/server`: Build your API or implement API contract.
44-
- `@orpc/client`: Consume your API on the client with type-safety.
45-
- `@orpc/react-query`: Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
46-
- `@orpc/vue-query`: Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
47-
- `@orpc/vue-colada`: Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
48-
- `@orpc/openapi`: Generate OpenAPI specs and provide OpenAPI handler for `@orpc/server`.
49-
- `@orpc/next`: Helpers and hooks for [Next.JS](https://nextjs.org/).
50-
- `@orpc/zod`: More schemas that [Zod](https://zod.dev/) doesn't support yet.
51-
52-
---
53-
54-
## Comparison
55-
56-
This comparison table helps you understand how oRPC differs from other popular TypeScript RPC and REST solutions.
57-
58-
- ✅ First-class, built-in support.
59-
- 🟡 Lacks features, or requires third-party integrations.
60-
- 🛑 Not supported or not documented.
61-
62-
| Feature | oRPC | tRPC | ts-rest | Description |
63-
| ------------------------ | ---- | ---- | ------- | ------------------------------------------------------------------ |
64-
| End-to-end Type Safety | ✅ | ✅ | ✅ | Full TypeScript type inference from backend to frontend. |
65-
| End-to-end Type Error | ✅ | 🛑 | ✅ | Full TYpeScript type inference for Error from backend to frontend. |
66-
| React Query Integration | ✅ | ✅ | 🟡 | Native support for React Query/TanStack Query. |
67-
| Vue Query Integration | ✅ | 🛑 | 🟡 | Native support for Vue Query/TanStack Query. |
68-
| Pinia Colada Integration | ✅ | 🛑 | 🛑 | Native support for VPinia Colada. |
69-
| With Contract-First | ✅ | 🛑 | ✅ | API definitions before implementation. |
70-
| Without Contract-First | ✅ | ✅ | 🛑 | API definitions and implementation are combined in same place |
71-
| File Operations | ✅ | 🟡 | 🟡 | Built-in support for file uploads/downloads. |
72-
| OpenAPI Support | ✅ | 🟡 | 🟡 | Generation and consumption of OpenAPI specs. |
73-
| Server Actions Support | ✅ | ✅ | 🛑 | React/Next.js Actions compatibility. |
74-
| Server-Sent Event (SSE) | ✅ | ✅ | 🛑 | Server-Sent Event (SSE) support. |
75-
| WebSockets | 🛑 | ✅ | 🛑 | WebSockets support. |
76-
| Nest.js integration | 🛑 | 🟡 | ✅ | Integration with Nest.js. |
53+
- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
54+
- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
55+
- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
56+
- [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
57+
- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
58+
- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
59+
- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
60+
- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
7761

7862
## References
7963

@@ -84,4 +68,4 @@ oRPC is inspired by existing solutions that prioritize type safety and developer
8468

8569
## License
8670

87-
Distributed under the MIT License. See [LICENSE](LICENSE) for more information.
71+
Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

‎packages/client/README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎packages/client/README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
<div align="center">
2+
<image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 />
3+
</div>
4+
5+
<h1></h1>
6+
7+
<div align="center">
8+
<a href="https://codecov.io/gh/unnoq/orpc">
9+
<img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
10+
</a>
11+
<a href="https://www.npmjs.com/package/@orpc/client">
12+
<img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fclient?logo=npm" />
13+
</a>
14+
<a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
15+
<img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
16+
</a>
17+
<a href="https://discord.gg/TXEbwRBvQn">
18+
<img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
19+
</a>
20+
</div>
21+
22+
<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
23+
24+
**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards, ensuring a smooth and enjoyable developer experience.
25+
26+
---
27+
28+
## Highlights
29+
30+
- **End-to-End Type Safety 🔒**: Ensure complete type safety from inputs to outputs and errors, bridging server and client seamlessly.
31+
- **First-Class OpenAPI 📄**: Adheres to the OpenAPI standard out of the box, ensuring seamless integration and comprehensive API documentation.
32+
- **Contract-First Development 📜**: (Optional) Define your API contract upfront and implement it with confidence.
33+
- **Exceptional Developer Experience ✨**: Enjoy a streamlined workflow with robust typing and clear, in-code documentation.
34+
- **Multi-Runtime Support 🌍**: Run your code seamlessly on Cloudflare, Deno, Bun, Node.js, and more.
35+
- **Framework Integrations 🧩**: Supports Tanstack Query (React, Vue), Pinia Colada, and more.
36+
- **Server Actions ⚡️**: Fully compatible with React Server Actions on Next.js, TanStack Start, and more.
37+
- **Standard Schema Support 🗂️**: Effortlessly work with Zod, Valibot, ArkType, and others right out of the box.
38+
- **Fast & Lightweight 💨**: Built on native APIs across all runtimes – optimized for speed and efficiency.
39+
- **Native Types 📦**: Enjoy built-in support for Date, File, Blob, BigInt, URL and more with no extra setup.
40+
- **Lazy Router ⏱️**: Improve cold start times with our lazy routing feature.
41+
- **SSE & Streaming 📡**: Provides SSE and streaming features – perfect for real-time notifications and AI-powered streaming responses.
42+
- **Reusability 🔄**: Write once and reuse your code across multiple purposes effortlessly.
43+
- **Extendability 🔌**: Easily enhance oRPC with plugins, middleware, and interceptors.
44+
- **Reliability 🛡️**: Well-tested, fully TypeScript, production-ready, and MIT licensed for peace of mind.
45+
- **Simplicity 💡**: Enjoy straightforward, clean code with no hidden magic.
46+
47+
## Documentation
48+
49+
You can find the full documentation [here](https://orpc.unnoq.com).
50+
51+
## Packages
52+
53+
- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
54+
- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
55+
- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
56+
- [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
57+
- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
58+
- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
59+
- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
60+
- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
61+
62+
## `@orpc/client`
63+
64+
Consume your API on the client with type-safety. Read the [documentation](https://orpc.unnoq.com/docs/client/client-side) for more information.
65+
66+
```ts
67+
import { createORPCClient } from '@orpc/client'
68+
import { RPCLink } from '@orpc/client/fetch'
69+
import { ContractRouterClient } from '@orpc/contract'
70+
import { RouterClient } from '@orpc/server'
71+
72+
const link = new RPCLink({
73+
url: 'http://localhost:3000/rpc',
74+
headers: () => ({
75+
authorization: 'Bearer token',
76+
}),
77+
// fetch: <-- provide fetch polyfill fetch if needed
78+
})
79+
80+
// Create a client for your router
81+
const client: RouterClient<typeof router> = createORPCClient(link)
82+
// Or, create a client using a contract
83+
const client: ContractRouterClient<typeof contract> = createORPCClient(link)
84+
```
85+
86+
## License
87+
88+
Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

‎packages/contract/README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎packages/contract/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<div align="center">
2+
<image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 />
3+
</div>
4+
5+
<h1></h1>
6+
7+
<div align="center">
8+
<a href="https://codecov.io/gh/unnoq/orpc">
9+
<img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
10+
</a>
11+
<a href="https://www.npmjs.com/package/@orpc/contract">
12+
<img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fcontract?logo=npm" />
13+
</a>
14+
<a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
15+
<img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
16+
</a>
17+
<a href="https://discord.gg/TXEbwRBvQn">
18+
<img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
19+
</a>
20+
</div>
21+
22+
<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
23+
24+
**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards, ensuring a smooth and enjoyable developer experience.
25+
26+
---
27+
28+
## Highlights
29+
30+
- **End-to-End Type Safety 🔒**: Ensure complete type safety from inputs to outputs and errors, bridging server and client seamlessly.
31+
- **First-Class OpenAPI 📄**: Adheres to the OpenAPI standard out of the box, ensuring seamless integration and comprehensive API documentation.
32+
- **Contract-First Development 📜**: (Optional) Define your API contract upfront and implement it with confidence.
33+
- **Exceptional Developer Experience ✨**: Enjoy a streamlined workflow with robust typing and clear, in-code documentation.
34+
- **Multi-Runtime Support 🌍**: Run your code seamlessly on Cloudflare, Deno, Bun, Node.js, and more.
35+
- **Framework Integrations 🧩**: Supports Tanstack Query (React, Vue), Pinia Colada, and more.
36+
- **Server Actions ⚡️**: Fully compatible with React Server Actions on Next.js, TanStack Start, and more.
37+
- **Standard Schema Support 🗂️**: Effortlessly work with Zod, Valibot, ArkType, and others right out of the box.
38+
- **Fast & Lightweight 💨**: Built on native APIs across all runtimes – optimized for speed and efficiency.
39+
- **Native Types 📦**: Enjoy built-in support for Date, File, Blob, BigInt, URL and more with no extra setup.
40+
- **Lazy Router ⏱️**: Improve cold start times with our lazy routing feature.
41+
- **SSE & Streaming 📡**: Provides SSE and streaming features – perfect for real-time notifications and AI-powered streaming responses.
42+
- **Reusability 🔄**: Write once and reuse your code across multiple purposes effortlessly.
43+
- **Extendability 🔌**: Easily enhance oRPC with plugins, middleware, and interceptors.
44+
- **Reliability 🛡️**: Well-tested, fully TypeScript, production-ready, and MIT licensed for peace of mind.
45+
- **Simplicity 💡**: Enjoy straightforward, clean code with no hidden magic.
46+
47+
## Documentation
48+
49+
You can find the full documentation [here](https://orpc.unnoq.com).
50+
51+
## Packages
52+
53+
- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
54+
- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
55+
- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
56+
- [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
57+
- [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).
58+
- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
59+
- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
60+
- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
61+
62+
## `@orpc/contract`
63+
64+
Build your API contract. Read the [documentation](https://orpc.unnoq.com/docs/contract-first/define-contract) for more information.
65+
66+
```ts
67+
export const PlanetSchema = z.object({
68+
id: z.number().int().min(1),
69+
name: z.string(),
70+
description: z.string().optional(),
71+
})
72+
73+
export const listPlanetContract = oc
74+
.input(
75+
z.object({
76+
limit: z.number().int().min(1).max(100).optional(),
77+
cursor: z.number().int().min(0).default(0),
78+
}),
79+
)
80+
.output(z.array(PlanetSchema))
81+
82+
export const findPlanetContract = oc
83+
.input(PlanetSchema.pick({ id: true }))
84+
.output(PlanetSchema)
85+
86+
export const createPlanetContract = oc
87+
.input(PlanetSchema.omit({ id: true }))
88+
.output(PlanetSchema)
89+
90+
export const contract = {
91+
planet: {
92+
list: listPlanetContract,
93+
find: findPlanetContract,
94+
create: createPlanetContract,
95+
},
96+
}
97+
```
98+
99+
## License
100+
101+
Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

‎packages/openapi/README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)