From API Routes and Server Actions to oRPC in Next.js

oRPC offers everything that API routes, Server Actions (Server Functions), and tRPC provide, but goes further by adding more capabilities in a more coherent way—without introducing any magic and instead relying on well-established standards (like OpenAPI, for example).

However, there were several reasons why I hadn’t used it earlier.

Migration from Go and HTML/CSS to Next.js

The first version of the ScreenshotOne dashboard was built with pure Go, HTML, and CSS. No frameworks, except Bootstrap for UI. I was most experienced with this stack, and it allowed me to build and launch the product quickly.

But once the product started to grow, the dashboard required more and more features, and the stack quickly became a bottleneck. I wasn’t experienced enough with client-side development. However, I already saw that React could be a good fit for the dashboard UI. The mental model of reasoning about state and how it is reflected in the UI resonated with me. However, I didn’t know how to approach it, and refactoring seemed like a big investment at that moment.

Later, about two or three years ago, I discovered Next.js and started experimenting with it. It included all the tooling around React, and I realized that by relying on it, I could focus purely on shipping features. So, I went ahead and refactored the entire dashboard to use Next.js. This indeed helped me scale the dashboard to a complex UI and ship a ton of features.

However, on the server side, the journey was less smooth, and it took me some time to find an approach that would be a good fit for ScreenshotOne in the long term.

API routes

There were different versions of them, but I followed the suggested approach by the Next.js documentation and went with their API routes for the server-side logic.

Familiarity and convenience

A typical component code looked like:

1
import React, { useState } from "react";
2

3
function ChangeRoleButton({ memberId }) {
4
    const [processing, setProcessing] = useState(false);
5
    const [newRole, setNewRole] = useState("developer");
6

7
    async function handleChangeRole() {
8
        setProcessing(true);
9
        const response = await fetch("/api/organization/change-role", {
10
            method: "POST",
11
            headers: { "Content-Type": "application/json" },
12
            body: JSON.stringify({
13
                memberId,
14
                newRole,
15
            }),
16
        });
17
        setProcessing(false);
18

19
        // handle response...
20
    }
21

22
    return (
23
        <div>
24
            <select
25
                value={newRole}
26
                onChange={(e) => setNewRole(e.target.value)}
27
                disabled={processing}
28
            >
29
                <option value="admin">Admin</option>
30
                <option value="developer">Developer</option>
31
            </select>
32
            <button onClick={handleChangeRole} disabled={processing}>
33
                {processing ? "Changing..." : "Change Role"}
34
            </button>
35
        </div>
36
    );
37
}

And in addition to that, I needed to implement the server-side logic in a separate file:

1
export const POST = withVerifiedUser(async (request) => {
2
    await connection();
3

4
    const user = request.user;
5
    if (!user || !canChangeRoles(user.organizationRole)) {
6
        return NextResponse.json({ message: "Unauthorized" }, { status: 403 });
7
    }
8

9
    const body = await request.json();
10
    const parseResult = changeRoleSchema.safeParse(body);
11
    if (!parseResult.success) {
12
        return NextResponse.json({ userErrorMessage: "Invalid request data" }, { status: 400 });
13
    }
14

15
    const { memberId, newRole } = parseResult.data;
16

17
    // change role logic...
18

19
    return NextResponse.json(result);
20
});

The main advantage of API routes was that I didn’t need any external dependencies and could write all the code in a familiar way. However, that way had a few critical downsides.

Downsides

1. A lot of boilerplate glue code. Parsing input, validating payloads, handling errors, processing responses, and describing types is repeated in every route.

2. Weak end-to-end type safety. Unless you manually share schemas, it’s easy to lose track of all types. It takes a lot of discipline to avoid descending into chaos.

3. Manual contracts. The entire API surface (routes, options, response types) is implicit and scattered everywhere instead of being defined in one place.

4. Harder refactoring. API routes are string-based and loosely coupled, so renaming and refactoring them is easy to break.

There are many more reasons, but even just these made it clear I needed a better alternative to API routes.

Server Actions

Next.js introduced the concept of Server Actions (now called Server Functions), which allows you to write server-side code like this:

1
"use server";
2

3
import { z } from "zod";
4

5
const ChangeRoleSchema = z.object({
6
    memberId: z.string(),
7
    newRole: z.enum(["admin", "developer"]),
8
});
9

10
export async function changeRole(formData: FormData) {
11
    const parsed = ChangeRoleSchema.safeParse({
12
        memberId: formData.get("memberId"),
13
        newRole: formData.get("newRole"),
14
    });
15

16
    if (!parsed.success) {
17
        throw new Error("Invalid input");
18
    }
19

20
    const user = await requireAuthenticatedUser();
21

22
    if (!canChangeRoles(user.organizationRole)) {
23
        throw new Error("Unauthorized");
24
    }
25

26
    const { memberId, newRole } = parsed.data;
27

28
    // change role logic...
29

30
    return { success: true };
31
}

And use it directly in the client as:

1
"use client";
2

3
import { changeRole } from "@/actions/change-role";
4

5
export function ChangeRoleButton({ memberId }) {
6
    async function handleSubmit(formData: FormData) {
7
        formData.set("memberId", memberId);
8
        await changeRole(formData);
9
    }
10

11
    return (
12
        <form action={handleSubmit}>
13
            <select name="newRole">
14
                <option value="admin">Admin</option>
15
                <option value="developer">Developer</option>
16
            </select>
17

18
            <button type="submit">Change role</button>
19
        </form>
20
    );
21
}

Safe Server Actions

When Server Actions became production-ready, I migrated all the API calls to them. I also used the next-safe-action library to reduce the boilerplate code even more.

1
"use server";
2

3
const action = actionClient
4
    .use(authMiddleware)
5
    .inputSchema(
6
        z.object({
7
            name: z.string().min(1),
8
        })
9
    )
10
    .action(async ({ ctx, parsedInput }) => {
11
        return { greeting: `Hello, ${parsedInput.name}!` };
12
    });

Safe Actions solved a lot of issues:

1. Type-safety and input validation.
2. Middleware for authentication and authorization.
3. Consistent error handling.

And many more.

They removed a lot of pitfalls of raw Server Actions and improved our Next.js codebase by far.

But that doesn’t change the underlying architecture. The application boundary remains implicit and tightly coupled to a framework feature. Because Safe Server Actions are still a thin wrapper around Server Actions.

Security concerns

Another aspect that made me uncomfortable with Server Actions was security issues.

At a conceptual level, Server Actions are not just local function calls. Under the hood they are public HTTP endpoints implemented through the React Server Components runtime and the React Flight protocol. Every action exposed in your codebase becomes an addressable server entrypoint.

Actions should always be treated like public APIs and must perform authentication, authorization, and validation on the server side. Relying on the client or assuming an action is “internal” can easily lead to vulnerabilities. And if the boundaries are not handled carefully, this creates a surprisingly large attack surface.

Remote Code Execution (RCE)

A vulnerability tracked demonstrated that maliciously crafted serialized payloads could manipulate the deserialization process used by the React Flight protocol. By exploiting JavaScript internals and prototype access during deserialization, attackers could potentially execute arbitrary code on the server. This type of vulnerability is particularly dangerous because it happens at the framework transport layer, not inside your application code.

Exposing source code

Another reported issue showed that specially crafted requests could sometimes bypass safeguards and expose compiled Server Action source code. If that happens, attackers may gain access to internal business logic, implementation details, or references to sensitive infrastructure. Even if secrets are not directly leaked, revealing internal code paths can significantly help attackers craft more targeted exploits.

DoS

One more issue demonstrated that malformed payloads could trigger expensive deserialization paths or infinite loops, causing high CPU usage and hanging server processes. Because Server Actions sit inside the application runtime rather than a clearly defined API gateway, these kinds of issues can be harder to isolate operationally.

Input validation, SSRF, and authorization vulnerabilities

Server Actions can appear deceptively similar to local function calls within React components, which makes it easy to overlook the fact that they are exposed as public endpoints. Without rigorous server-side input validation and explicit authorization checks, these actions may inadvertently allow attackers to perform unauthorized operations or introduce security risks such as SSRF or broken access control.

Always update the framework

Of course, you must always keep the Next.js updated, apply security patches quickly, and treat every Server Action as a fully exposed server endpoint with strict validation and authorization.

And of course, with enough discipline and following the best practices a lot of issues can be avoided, but that doesn’t make it a nice experience to use Server Actions.

Unnecessary errors in logs

And even if there were no issues anymore, there was a certain kind of errors (“Failed to find Server Action”) that appeared in the ScreenshotOne dashboard logs and frustrated me:

After applying all the possible fixes, the errors didn’t disappear. Since even if you fix everything, there might be automated vulnerabilirity testers checking periodically for vulnerabilities in your codebase. And it creates a lot of noise in the logs.

You can’t do it if you use them in the codebase, but one of the ways to fix that is to block Server Actions entirely. And that’s what I did eventually once migrated to oRPC.

oRPC

But the most profound reason to migrate to oRPC isn’t just the downsides of Server Actions—many of those are avoidable. It’s the upsides and new opportunities I saw by migrating to oRPC:

1. Explicit boundaries between client and server. With oRPC, every server-side operation is defined as a clear, isolated procedure—no more implicit or “magical” boundaries controlled by framework conventions.

2. Better control over request and error handling. oRPC encourages me to design the flow of requests, authentication, and error handling on my own. And keep all that consistent.

3. A structure that is easier to reuse outside of React if I ever need to. Procedures and routers in oRPC are not tightly coupled to any particular runtime or UI framework. If I ever need to scale the dashboard or extract the server and make it standalone, it is an easy move.

4. And less dependence on one specific Next.js mechanism and magic. When coding with AI you need less magic, not more.

5. Plus OpenAPI and public API support if I need to adjust the dashboard for agents to use. Built-in support for OpenAPI in oRPC means the API can be automatically documented and exposed publicly if needed. This is invaluable if I want to allow third-party integrations, create self-service developer experiences, or make the dashboard itself agent-friendly—all without duplicating logic or maintaining a separate API surface.

Once I refactored all the Server Actions to oRPC, it made me envy AI coding agents writing code. The ergonomics is so nice it makes me want to code manually again:

1
import "server-only";
2
import { z } from "zod";
3
import { os } from "@orpc/server";
4

5
const StorageConfigurationSchema = z.object({
6
    credentials: z.object({
7
        endpoint: z.string().url(),
8
        accessKeyId: z.string(),
9
        secretKey: z.string(),
10
        defaultBucket: z.string(),
11
    }),
12
});
13

14
export const storageRouter = {
15
    testConfiguration: os.input(StorageConfigurationSchema).handler(async ({ input }) => {
16
        await requireAuthenticatedUser();
17

18
        try {
19
            return await testStorageConnection(input.credentials);
20
        } catch {
21
            return {
22
                valid: false,
23
                errorMessage: "Failed to test storage configuration.",
24
            };
25
        }
26
    }),
27
    updateConfiguration: os.input(StorageConfigurationSchema).handler(async ({ input }) => {
28
        const user = await requireAuthenticatedUser();
29

30
        const updated = await saveStorageConfiguration(user.organizationId, input.credentials);
31

32
        return { success: true, updated };
33
    }),
34
};

oRPC versus tRPC

This was an important question because tRPC is the more established choice and it is also very good.

But why choose tRPC if oRPC has everything that tRPC provides, and more, right out of the box? OpenAPI support is built in, contract-first development is supported, and it works with standard schema libraries such as Zod. That combination mattered a lot to me.

Check out oRPC comparison for details on the differences between oRPC and tRPC.

Blocking Server Actions entirely

Once the migration was successful, tested and I felt I can keep going with the new solution, I went one step further: I blocked Server Actions in the codebase and added a check to prevent introducing them again—the build will fail if Server Actions are used.

In case if more developers work in the codebase in the future, I did not want the architecture to drift back into a mixed model where some mutations use oRPC and others quietly reintroduce Server Actions because they look convenient in the moment.

Also, it removed the issues with unnecessary errors in the logs.

Check out this guide on how to block Server Actions (now Server Functions) entirely if you ever need to.

Sponsor oRPC

At the time of writing this article, oRPC is developed by a single developer. Sponsoring the project, even for just one month, is the least ScreenshotOne can do to support it.

If you are using oRPC or find it to be an interesting project, consider sponsoring it as well. Every dollar counts, whether it’s $5, $50, or $500.

Check out other open-source projects that ScreenshotOne has sponsored.

Thoughts

Every approach has its upsides and downsides:

1. API routes are the original Next.js way to create HTTP-based endpoints using file-based routing, letting you handle requests and responses directly with minimal setup.
2. Server Functions (previously Server Actions) let you write server-side logic and call it directly from the client, enabling data updates without separate API endpoints.
3. tRPC provides typesafe, contract-based API calls where your input/output types are shared between server and client, removing the need for manual type definitions.

But oRPC offered me the most upsides of all approaches combined (along with additional capabilities) while leaving me with the least downsides.

If your product is growing, your logs are getting noisy, and your server boundary feels increasingly implicit, it may be worth asking whether your current approach is still worth the tradeoff, and maybe give a try to oRPC.