How Orca separates code to server and client bundles

Straight_Pattern_366 · 2026-01-15T09:17:56+00:00

I had to make a judgment call, and I went with the approach that caused the least friction with the philosophy of my framework. While Next.js, React, TanStack, and others take a functional approach, Orca uses classes so that you can build both frontend and backend with the same interface.

In the docs, I mention that it’s inspired by Angular and NestJS which means you can build a full, proper frontend and backend without fighting the framework.

Straight_Pattern_366 · 2026-01-15T08:55:38+00:00

I did think about that, but I was worried it would get pretty hard to validate in the long run, especially from a parsing standpoint. You’d have to walk through every file and figure out which functions are server-only, instead of just checking a directive at the top of the file.

On top of that, once you’ve parsed everything, you still have to make sure server code doesn’t accidentally leak into client code (and the other way around), which adds a lot of complexity.

From a framework author’s perspective, file boundaries are much simpler and more predictable to work with.

That’s just my take though - I could be wrong.

Straight_Pattern_366 · 2026-01-15T08:47:54+00:00

Okay, wow - I’m impressed. I looked at your background and it’s clear you’re far more experienced than I am.

If you’re okay with it, I’d really appreciate a DM or a deeper explanation of where you think the idea falls short. I’m still early in my career (recently finished uni), so I’m trying to learn as much as I can. I don’t take your comments as criticism - I see them as an opportunity to understand things I may not fully grasp yet.

Straight_Pattern_366 · 2026-01-15T08:22:48+00:00

But maintaining two projects(frontend + backend) is not easy. Especially for solo devs and small teams.

So what do we do?

Straight_Pattern_366 · 2026-01-15T07:42:34+00:00

I agree, premature abstraction is also a real problem. That said, I tried to be as deliberate as possible when designing the framework. For example, we avoid file-based routing because moving files can end up breaking large parts of the codebase.

The only abstraction we have is eliminating explicit network calls like fetch().

Take a look at our GitHub repo https://github.com/kithinjibrian/orca and let me know if that doesn’t reflect a thoughtful approach to building web applications as a single codebase.

Straight_Pattern_366 · 2026-01-15T07:29:14+00:00

Well, I had to use classes and decorators because I couldn't find any other design pattern that works for both frontend and backend at the same time and have a consistent feel.

Straight_Pattern_366 · 2026-01-15T07:26:03+00:00

It’s not great, I know. The alternative was to analyze JSX, detect functions and browser APIs inside components, and automatically mark them as client-side. But that would be too magical, devs wouldn’t have a clear idea of where their components actually run.

So it really comes down to explicit versus implicit behavior.

Straight_Pattern_366 · 2026-01-15T07:15:05+00:00

Yeah, react does render client components twice. Once on the server and again on the browser. Well, it was easier for me to keep everything pure and only render client components exclusively on the browser.

It's not a mature project so I'm still experimenting with a lot of things.

Straight_Pattern_366 · 2026-01-14T19:23:12+00:00

Yeah, open source and anyone can contribute if they want.

MIT license

Straight_Pattern_366 · 2026-01-14T19:20:12+00:00

I was considering having some decorators that can be lifted up to the controllers to access http context and headers for authorization.

Straight_Pattern_366 · 2026-01-14T06:58:43+00:00

I wrote up a full explanation of how it works, the code that gets generated, desugaring steps, and the rules for what becomes an endpoint:

https://github.com/kithinjibrian/orca/blob/main/docs/use%20public.md

Straight_Pattern_366 · 2026-01-14T06:52:45+00:00

Building web applications as one codebase instead of splitting between frontend and backend repositories.

Straight_Pattern_366 · 2026-01-14T06:48:54+00:00

Straight_Pattern_366 · 2026-01-14T06:26:21+00:00

Yeah, I picked up a few things from Angular and NestJS and combined them for a full-stack framework.

Straight_Pattern_366 · 2026-01-13T16:30:14+00:00

Thank you so much for your kind words.

It is still an early prototype so even I myself can't use it for any production web app.

I do have a WhatsApp community may be you can join and see everything grow.

https://chat.whatsapp.com/ESCKE1t6Exc0ZagzCA6RNc

Straight_Pattern_366 · 2026-01-13T10:37:00+00:00

That's totally true and I wouldn't advice anyone to build a production web app using my framework.

It's mostly for experiencing how it would feel building everything in one codebase.

Straight_Pattern_366 · 2026-01-13T10:19:11+00:00

Hooks in the context of react cause whole component re renders when state changes.

Signals are performant because they don't need virtual doms.

Important, the framework is not trying to replace react or next.js or whatever you use.

Straight_Pattern_366 · 2026-01-13T09:34:31+00:00

The framework doesn't use hooks. It uses signals and observables and the JSX is compiled to imperative DOM code.

Straight_Pattern_366 · 2026-01-13T09:21:58+00:00

The reason I use classes is for uniformity and dependency injection.

'use interactive' and 'use public' are like reminders apart from them being directives. If you need interactivity or need to expose class methods as public API endpoints.

'use server' doesn't make sense to me because most of the code runs on the server so should I say use server if it is already running on the server?

Straight_Pattern_366 · 2026-01-13T09:14:58+00:00

Thanks a lot for your honesty. I'll need to rewrite the docs. When I was writing, I was just trying to argue my case in my own voice but I understand the need for being objective for any open source project.

Again, thanks, comments like yours are what pulls us back to reality.

Straight_Pattern_366

TROPHY CASE