feat(cli): add openapi suppport in orpc (#563)

AmanVarshney01 · web-flow · commit a276addef874 · 2025-09-04T15:08:44.000+05:30
diff --git a/apps/cli/src/constants.ts b/apps/cli/src/constants.ts
@@ -112,6 +112,8 @@ export const dependencyVersionMap = {
 
 	"@orpc/server": "^1.8.6",
 	"@orpc/client": "^1.8.6",
+	"@orpc/openapi": "^1.8.6",
+	"@orpc/zod": "^1.8.6",
 	"@orpc/tanstack-query": "^1.8.6",
 
 	"@trpc/tanstack-react-query": "^11.5.0",
diff --git a/apps/cli/src/helpers/core/api-setup.ts b/apps/cli/src/helpers/core/api-setup.ts
@@ -54,7 +54,14 @@ function getApiDependencies(
 	> = {};
 
 	if (api === "orpc") {
-		deps.server = { dependencies: ["@orpc/server", "@orpc/client"] };
+		deps.server = {
+			dependencies: [
+				"@orpc/server",
+				"@orpc/client",
+				"@orpc/openapi",
+				"@orpc/zod",
+			],
+		};
 	} else if (api === "trpc") {
 		deps.server = { dependencies: ["@trpc/server", "@trpc/client"] };
 	}
diff --git a/apps/cli/src/helpers/core/post-installation.ts b/apps/cli/src/helpers/core/post-installation.ts
@@ -14,6 +14,7 @@ export async function displayPostInstallInstructions(
 	config: ProjectConfig & { depsInstalled: boolean },
 ) {
 	const {
+		api,
 		database,
 		relativePath,
 		packageManager,
@@ -158,6 +159,14 @@ export async function displayPostInstallInstructions(
 
 	if (!isConvex) {
 		output += `${pc.cyan("•")} Backend API: http://localhost:3000\n`;
+
+		if (api === "orpc") {
+			if (backend === "next") {
+				output += `${pc.cyan("•")} OpenAPI (Scalar UI): http://localhost:3000/rpc/api\n`;
+			} else {
+				output += `${pc.cyan("•")} OpenAPI (Scalar UI): http://localhost:3000/api\n`;
+			}
+		}
 	}
 
 	if (addons?.includes("starlight")) {
diff --git a/apps/cli/src/helpers/deployment/alchemy/alchemy-next-setup.ts b/apps/cli/src/helpers/deployment/alchemy/alchemy-next-setup.ts
@@ -25,7 +25,6 @@ export async function setupNextAlchemyDeploy(
 				...pkg.scripts,
 				deploy: "alchemy deploy",
 				destroy: "alchemy destroy",
-				dev: "alchemy dev",
 			};
 		}
 		await fs.writeJson(pkgPath, pkg, { spaces: 2 });
diff --git a/apps/cli/src/helpers/deployment/alchemy/alchemy-nuxt-setup.ts b/apps/cli/src/helpers/deployment/alchemy/alchemy-nuxt-setup.ts
@@ -26,7 +26,6 @@ export async function setupNuxtAlchemyDeploy(
 				...pkg.scripts,
 				deploy: "alchemy deploy",
 				destroy: "alchemy destroy",
-				dev: "alchemy dev",
 			};
 		}
 		await fs.writeJson(pkgPath, pkg, { spaces: 2 });
diff --git a/apps/cli/src/helpers/deployment/alchemy/alchemy-react-router-setup.ts b/apps/cli/src/helpers/deployment/alchemy/alchemy-react-router-setup.ts
@@ -25,7 +25,6 @@ export async function setupReactRouterAlchemyDeploy(
 				...pkg.scripts,
 				deploy: "alchemy deploy",
 				destroy: "alchemy destroy",
-				dev: "alchemy dev",
 			};
 		}
 		await fs.writeJson(pkgPath, pkg, { spaces: 2 });
diff --git a/apps/cli/src/helpers/deployment/alchemy/alchemy-solid-setup.ts b/apps/cli/src/helpers/deployment/alchemy/alchemy-solid-setup.ts
@@ -25,7 +25,6 @@ export async function setupSolidAlchemyDeploy(
 				...pkg.scripts,
 				deploy: "alchemy deploy",
 				destroy: "alchemy destroy",
-				dev: "alchemy dev",
 			};
 		}
 		await fs.writeJson(pkgPath, pkg, { spaces: 2 });
diff --git a/apps/cli/src/helpers/deployment/alchemy/alchemy-svelte-setup.ts b/apps/cli/src/helpers/deployment/alchemy/alchemy-svelte-setup.ts
@@ -26,7 +26,6 @@ export async function setupSvelteAlchemyDeploy(
 				...pkg.scripts,
 				deploy: "alchemy deploy",
 				destroy: "alchemy destroy",
-				dev: "alchemy dev",
 			};
 		}
 
diff --git a/apps/cli/src/helpers/deployment/alchemy/alchemy-tanstack-router-setup.ts b/apps/cli/src/helpers/deployment/alchemy/alchemy-tanstack-router-setup.ts
@@ -25,7 +25,6 @@ export async function setupTanStackRouterAlchemyDeploy(
 				...pkg.scripts,
 				deploy: "alchemy deploy",
 				destroy: "alchemy destroy",
-				dev: "alchemy dev",
 			};
 		}
 
diff --git a/apps/cli/src/helpers/deployment/alchemy/alchemy-tanstack-start-setup.ts b/apps/cli/src/helpers/deployment/alchemy/alchemy-tanstack-start-setup.ts
@@ -26,7 +26,6 @@ export async function setupTanStackStartAlchemyDeploy(
 				...pkg.scripts,
 				deploy: "alchemy deploy",
 				destroy: "alchemy destroy",
-				dev: "alchemy dev",
 			};
 		}
 
diff --git a/apps/cli/templates/api/orpc/server/next/src/app/rpc/[...all]/route.ts.hbs b/apps/cli/templates/api/orpc/server/next/src/app/rpc/[...all]/route.ts.hbs
@@ -2,18 +2,47 @@
 import { createContext } from '@/lib/context'
 {{/if}}
 import { appRouter } from '@/routers'
+import { OpenAPIHandler } from '@orpc/openapi/fetch'
+import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
+import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
 import { RPCHandler } from '@orpc/server/fetch'
+import { onError } from '@orpc/server'
 import { NextRequest } from 'next/server'
 
-const handler = new RPCHandler(appRouter)
+const rpcHandler = new RPCHandler(appRouter, {
+  interceptors: [
+    onError((error) => {
+      console.error(error)
+    }),
+  ],
+})
+const apiHandler = new OpenAPIHandler(appRouter, {
+  plugins: [
+    new OpenAPIReferencePlugin({
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+    }),
+  ],
+  interceptors: [
+    onError((error) => {
+      console.error(error)
+    }),
+  ],
+})
 
 async function handleRequest(req: NextRequest) {
-  const { response } = await handler.handle(req, {
+  const rpcResult = await rpcHandler.handle(req, {
     prefix: '/rpc',
     context: {{#if (eq auth "better-auth")}}await createContext(req){{else}}{}{{/if}},
   })
+  if (rpcResult.response) return rpcResult.response
 
-  return response ?? new Response('Not found', { status: 404 })
+  const apiResult = await apiHandler.handle(req, {
+    prefix: '/rpc/api',
+    context: {{#if (eq auth "better-auth")}}await createContext(req){{else}}{}{{/if}},
+  })
+  if (apiResult.response) return apiResult.response
+
+  return new Response('Not found', { status: 404 })
 }
 
 export const GET = handleRequest
diff --git a/apps/cli/templates/backend/server/elysia/src/index.ts.hbs b/apps/cli/templates/backend/server/elysia/src/index.ts.hbs
@@ -10,7 +10,11 @@ import { appRouter } from "./routers/index";
 import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
 {{/if}}
 {{#if (eq api "orpc")}}
+import { OpenAPIHandler } from "@orpc/openapi/fetch";
+import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
 import { RPCHandler } from "@orpc/server/fetch";
+import { onError } from "@orpc/server";
 import { appRouter } from "./routers";
 import { createContext } from "./lib/context";
 {{/if}}
@@ -19,7 +23,25 @@ import { auth } from "./lib/auth";
 {{/if}}
 
 {{#if (eq api "orpc")}}
-const handler = new RPCHandler(appRouter);
+const rpcHandler = new RPCHandler(appRouter, {
+  interceptors: [
+    onError((error) => {
+      console.error(error);
+    }),
+  ],
+});
+const apiHandler = new OpenAPIHandler(appRouter, {
+  plugins: [
+    new OpenAPIReferencePlugin({
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+    }),
+  ],
+  interceptors: [
+    onError((error) => {
+      console.error(error);
+    }),
+  ],
+});
 {{/if}}
 
 {{#if (eq runtime "node")}}
@@ -48,12 +70,19 @@ const app = new Elysia()
   {{/if}}
 {{#if (eq api "orpc")}}
   .all('/rpc*', async (context) => {
-    const { response } = await handler.handle(context.request, {
+    const { response } = await rpcHandler.handle(context.request, {
       prefix: '/rpc',
       context: await createContext({ context })
     })
     return response ?? new Response('Not Found', { status: 404 })
   })
+  .all('/api*', async (context) => {
+    const { response } = await apiHandler.handle(context.request, {
+      prefix: '/api',
+      context: await createContext({ context })
+    })
+    return response ?? new Response('Not Found', { status: 404 })
+  })
 {{/if}}
 {{#if (eq api "trpc")}}
   .all("/trpc/*", async (context) => {
diff --git a/apps/cli/templates/backend/server/express/src/index.ts.hbs b/apps/cli/templates/backend/server/express/src/index.ts.hbs
@@ -5,7 +5,11 @@ import { createContext } from "./lib/context";
 import { appRouter } from "./routers/index";
 {{/if}}
 {{#if (eq api "orpc")}}
+import { OpenAPIHandler } from "@orpc/openapi/node";
+import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
 import { RPCHandler } from "@orpc/server/node";
+import { onError } from "@orpc/server";
 import { appRouter } from "./routers";
 {{#if (eq auth "better-auth")}}
 import { createContext } from "./lib/context";
@@ -50,17 +54,47 @@ app.use(
 {{/if}}
 
 {{#if (eq api "orpc")}}
-const handler = new RPCHandler(appRouter);
-app.use("/rpc{*path}", async (req, res, next) => {
-  const { matched } = await handler.handle(req, res, {
+const rpcHandler = new RPCHandler(appRouter, {
+  interceptors: [
+    onError((error) => {
+      console.error(error);
+    }),
+  ],
+});
+const apiHandler = new OpenAPIHandler(appRouter, {
+  plugins: [
+    new OpenAPIReferencePlugin({
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+    }),
+  ],
+  interceptors: [
+    onError((error) => {
+      console.error(error);
+    }),
+  ],
+});
+
+app.use(async (req, res, next) => {
+  const rpcResult = await rpcHandler.handle(req, res, {
     prefix: "/rpc",
     {{#if (eq auth "better-auth")}}
     context: await createContext({ req }),
     {{else}}
     context: {},
     {{/if}}
   });
-  if (matched) return;
+  if (rpcResult.matched) return;
+
+  const apiResult = await apiHandler.handle(req, res, {
+    prefix: "/api",
+    {{#if (eq auth "better-auth")}}
+    context: await createContext({ req }),
+    {{else}}
+    context: {},
+    {{/if}}
+  });
+  if (apiResult.matched) return;
+
   next();
 });
 {{/if}}
diff --git a/apps/cli/templates/backend/server/fastify/src/index.ts.hbs b/apps/cli/templates/backend/server/fastify/src/index.ts.hbs
@@ -9,8 +9,12 @@ import { appRouter, type AppRouter } from "./routers/index";
 {{/if}}
 
 {{#if (eq api "orpc")}}
+import { OpenAPIHandler } from "@orpc/openapi/node";
+import { OpenAPIReferencePlugin } from "@orpc/openapi/plugins";
+import { ZodToJsonSchemaConverter } from "@orpc/zod/zod4";
 import { RPCHandler } from "@orpc/server/node";
 import { CORSPlugin } from "@orpc/server/plugins";
+import { onError } from "@orpc/server";
 import { appRouter } from "./routers/index";
 import { createServer } from "node:http";
 {{#if (eq auth "better-auth")}}
@@ -40,21 +44,39 @@ const baseCorsConfig = {
 };
 
 {{#if (eq api "orpc")}}
-const handler = new RPCHandler(appRouter, {
+const rpcHandler = new RPCHandler(appRouter, {
   plugins: [
     new CORSPlugin({
       origin: process.env.CORS_ORIGIN,
       credentials: true,
       allowHeaders: ["Content-Type", "Authorization"],
     }),
   ],
+  interceptors: [
+    onError((error) => {
+      console.error(error);
+    }),
+  ],
+});
+
+const apiHandler = new OpenAPIHandler(appRouter, {
+  plugins: [
+    new OpenAPIReferencePlugin({
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+    }),
+  ],
+  interceptors: [
+    onError((error) => {
+      console.error(error);
+    }),
+  ],
 });
 
 const fastify = Fastify({
   logger: true,
   serverFactory: (fastifyHandler) => {
     const server = createServer(async (req, res) => {
-      const { matched } = await handler.handle(req, res, {
+      const { matched } = await rpcHandler.handle(req, res, {
         context: await createContext(req.headers),
         prefix: "/rpc",
       });
@@ -63,6 +85,15 @@ const fastify = Fastify({
         return;
       }
 
+      const apiResult = await apiHandler.handle(req, res, {
+        context: await createContext(req.headers),
+        prefix: "/api",
+      });
+
+      if (apiResult.matched) {
+        return;
+      }
+
       fastifyHandler(req, res);
     });
 
diff --git a/apps/cli/templates/backend/server/hono/src/index.ts.hbs b/apps/cli/templates/backend/server/hono/src/index.ts.hbs

Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,6 @@ export async function setupNextAlchemyDeploy(`
`25`	`25`	`...pkg.scripts,`
`26`	`26`	`deploy: "alchemy deploy",`
`27`	`27`	`destroy: "alchemy destroy",`
`28`		`- dev: "alchemy dev",`
`29`	`28`	`};`
`30`	`29`	`}`
`31`	`30`	`await fs.writeJson(pkgPath, pkg, { spaces: 2 });`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,6 @@ export async function setupNuxtAlchemyDeploy(`
`26`	`26`	`...pkg.scripts,`
`27`	`27`	`deploy: "alchemy deploy",`
`28`	`28`	`destroy: "alchemy destroy",`
`29`		`- dev: "alchemy dev",`
`30`	`29`	`};`
`31`	`30`	`}`
`32`	`31`	`await fs.writeJson(pkgPath, pkg, { spaces: 2 });`