oRPCv1

Beta Leave feedback · Contribute

About

oRPC combines RPC with OpenAPI, allowing you to define and call remote or local procedures through a type-safe API while adhering to the OpenAPI specification.

The oRPC plugin for Hey API generates contracts from your OpenAPI spec, fully compatible with all core features.

Collaborators

• Stephen Zhou

Features

• oRPC v1 support
• seamless integration with @hey-api/openapi-ts ecosystem
• generated contracts
• minimal learning curve thanks to extending the underlying technology

Installation

In your configuration, add orpc to your plugins and you’ll be ready to generate oRPC artifacts. 🎉

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    'orpc',
  ],
};

Output

The oRPC plugin will generate the following artifacts, depending on the input specification.

Contracts

Contracts are generated from all endpoints.

example

orpc.gen.ts

import { oc } from '@orpc/contract';

const addPet = oc.route({
  description: 'Add a new pet to the store.',
  inputStructure: 'detailed',
  method: 'POST',
  operationId: 'addPet',
  path: '/pet',
  summary: 'Add a new pet to the store.',
  tags: ['pet'],
});

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    'orpc',
  ],
};

Validators

To enable schema validation, set validator to zod or one of the available validator plugins. This will implicitly add the selected plugin with default values.

For a more granular approach, manually add a validator plugin and set validator to the plugin name or true to automatically select a compatible plugin. Until you customize the validator plugin, both approaches will produce the same default output.

example

orpc.gen.ts

import { oc } from '@orpc/contract';

import { vAddPetBody, vAddPetResponse } from './valibot.gen';

const addPet = oc
  .route({
    description: 'Add a new pet to the store.',
    inputStructure: 'detailed',
    method: 'POST',
    operationId: 'addPet',
    path: '/pet',
    summary: 'Add a new pet to the store.',
    tags: ['pet'],
  })
  .input(v.object({ body: vAddPetBody }))
  .output(vAddPetResponse);

config

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'orpc',
      validator: true, // or 'valibot'
    },
    {
      name: 'valibot', // customize (optional)
      // other options
    },
  ],
};

You can choose to validate only inputs or outputs.

inputs

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'orpc',
      validator: {
        input: 'zod',
      },
    },
  ],
};

outputs

openapi-ts.config.ts

export default {
  input: 'hey-api/backend', // sign up at app.heyapi.dev
  output: 'src/client',
  plugins: [
    // ...other plugins
    {
      name: 'orpc',
      validator: {
        output: 'zod',
      },
    },
  ],
};

Learn more about available validators on the Validators page.

API

You can view the complete list of options in the UserConfig interface.

Examples

You can view live examples on StackBlitz or on GitHub.