Introducing Harpy.js: A Modern Full-Stack Framework for Building Type-Safe, SEO-Friendly Web Applications

🤔 WHAT IS HARPY.JS?

Harpy.js is a full-stack TypeScript framework that enables you to build server-side rendered (SSR) React applications using NestJS as the foundation.

Think of it as NestJS meeting React with first-class support for SSR, hydration, SEO, internationalization, and modern deployment patterns. You get the best of both worlds: the architectural patterns and dependency injection of NestJS combined with the component-driven approach of React.

📦 THE HARPY.JS ECOSYSTEM

Why I built it instead of using Next.js and why it might (or might not) make sense for you.

👉 Harpy.js: https://www.harpyjs.org

👉 GitHub: https://github.com/Makhloufhleli/harpy.js

👉 npm: https://www.npmjs.com/package/@harpy-js/core

I built it because my mental model as a NestJS developer didn’t fit Next.js, and after building multiple SEO-critical apps, I realized I wanted a different kind of full-stack framework.

One where:

• NestJS is the core, not just an API folder


• Dependency Injection is first-class everywhere


• Backend architecture drives rendering


• SEO is treated as backend infrastructure


• Frontend and backend truly share one architecture

🔍 KEY FEATURES

Server-Side Rendering (SSR) with Automatic client Hydration for interactive react components

Harpy.js provides built-in SSR capabilities that work out of the box. Your React components render on the server for fast initial page loads and excellent SEO, then automatically hydrate on the client for full interactivity. The framework handles the complexity of SSR for you, including proper script injection, state serialization, and hydration boundary detection.

You can mark specific components for client-side only rendering using the 'use client' directive when you need browser APIs, event handlers, or stateful interactions. This gives you fine-grained control over what renders where, optimizing both performance and developer experience.

NestJS Dependency Injection Everywhere

Harpy.js is built on NestJS, which means you have access to its powerful dependency injection system, modular architecture, decorators, and entire ecosystem of libraries. Create services, inject them into controllers, use guards and interceptors, and leverage all the patterns you know from NestJS. Your React components can seamlessly access data from NestJS services through controllers, maintaining clean separation of concerns.

🚀 GETTING STARTED

Getting started with Harpy.js is straightforward.

Install the CLI globally with npm install -g @harpy-js/cli, then create a new project using harpy create my-app. The CLI will guide you through the setup process with interactive prompts. Navigate to your project directory and start the development server with npm run dev.

Your application will be running with hot reload enabled for both server and client code. The generated project includes example components, layouts, routing setup, i18n configuration, and SEO services ready to customize.

When you're ready to deploy, build your application with npm run build and start the production server with npm run start. The same build works for both standalone server deployment and serverless platforms.

Follow the documentation on https://www.harpyjs.org for more details

💡 Why I’m Sharing This Early

Harpy.js is actively developed.

I’m sharing it now because:

• I want honest feedback


• I want to know what feels wrong


• I want to learn how others solve these problems

If you’ve ever thought:

"I wish NestJS could just render my app"

I’d genuinely love your thoughts.

💬 REACH OUT

If you’d like to discuss Harpy.js, share feedback, ask questions, or just connect:

📧 Email: [email protected]

🔗 LinkedIn: https://www.linkedin.com/in/makhlouf-helali-84461b110

I’m always happy to changewith you.