# @byteshift/harmony

> A zero-dependency, fully featured, HTTP server micro-framework

Latest version **1.5.8** (published 2025-12-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @byteshift/harmony
pnpm add @byteshift/harmony
yarn add @byteshift/harmony
bun add @byteshift/harmony
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; has provenance.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.5.8 |
| Published | 2025-12-13 |
| First published | 2021-02-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 262.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Harold Iedema |
| Maintainers | haroldiedema |
| Keywords | byteshift, http, https, http2, jsx, ssr, events, hackable, server, controller, cookie, cookies |

## Links

- npm: https://www.npmjs.com/package/@byteshift/harmony
- Repository: https://github.com/haroldiedema/byteshift-harmony
- Homepage: https://github.com/haroldiedema/byteshift-harmony/wiki
- Issues: https://github.com/haroldiedema/byteshift-harmony/issues
- npm.io page: https://npm.io/package/@byteshift/harmony

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 1.5.8 (latest) — 2025-12-13
- 1.5.7 — 2025-10-01
- 1.5.6 — 2025-10-01
- 1.5.5 — 2025-10-01
- 1.5.4 — 2025-09-22
- 1.5.3 — 2025-09-19
- 1.5.2 — 2025-08-27
- 1.5.1 — 2025-08-27
- 1.5.0 — 2025-08-27
- 1.4.1 — 2022-12-20
- 1.4.0 — 2022-07-26
- 1.3.2 — 2022-07-22
- 1.3.1 — 2022-07-21
- 1.3.0 — 2022-07-21
- 1.2.9 — 2021-09-29
- … 21 more at https://npm.io/package/@byteshift/harmony/versions

## README

![](./docs/harmony-header.png)

## What is Harmony?

Harmony is a semi-opinionated zero dependency HTTP library similar to the widely
used express library. The main difference is that Harmony follows the "Model
View Controller" (MVC) pattern and is designed for large scale structured
TypeScript applications that are hosted via a NodeJS server.

Harmony is fully extensible via "event interceptors" and can handle nearly any
templating engine you throw at it. It even supports the use of cookies and
sessions out of the box to allow you to focus on one thing: Building your
website.

### Why should I use Harmony?

The Node ecosystem is full of various sized npm packages that all do their own
thing. If you wish to build a web-server that supports cookies or sessions, a
templating engine, the use of authentication, firewalls, or any form of
dependency injection, you'll quickly realize that your project has over 100
dependencies, not to mention the size of your node_modules directory. If you
find yourself teaching yourself how to use all these different libraries and
basically "hacking" things together to make it work for you, and you're tired of
focusing on other things besides building your own website or application, then
Harmony would probably suit you best.

If you are familiar with one of the well known PHP frameworks like Symfony or
Laravel, then getting started with Harmony will be a literal walk in the park.

### What do I need to know before working with Harmony?

 - Harmony is fully written in TypeScript and will work the best if your project
   is also written in the same language.
 - Harmony makes use of decorators (also known as annotations) to configure
   routes and which template to render.
   
If you are unfamiliar with either TypeScript or the use of decorators, it is
recommended to read up on these topics before diving straight in.

## Quick start

Setting up your Harmony server is done in just a few easy steps.
To make things easier, please make sure you have TypeScript up and running in
your project.

### 1. Installing the package

Harmony is just another NPM package and can be installed as such.

Through NPM:
```shell
$ npm i @byteshift/harmony --save
```

Or through Yarn:
```shell
$ yarn add @byteshift/harmony
```

### 2. Configuring & starting Harmony

```typescript
// app.ts
import {Harmony} from '@byteshift/harmony';

const harmony = new Harmony({
   port: 8080,
   https: {
       enabled: false
   }
});

// Start listening for incoming connections.
harmony.start();
```

If you navigate to http://127.0.0.1:8080/ in your browser, you should be
presented with a 404 error page. This is because no routes have been set up yet.

### 3. Creating your first controller

A controller in Harmony is just another TypeScript class. Methods inside this
class can be annotated with the `@Route` decorator to automatically use them as
end-points of your server.

```typescript
// MyController.ts
import {Route} from './Route';

export class MyController
{
    @Route("/", {methods: ["GET"]})
    public indexAction(): HtmlResponse
    {
        return new HtmlResponse('<h1>Hello World!</h1>');
    }
}
```

Now that we have your first controller, we'll need to let Harmony know this
particular controller exists. Let's go back to our `app.ts` file and make a small
adjustment.

```typescript
// app.ts
import {Harmony}      from '@byteshift/harmony';
import {MyController} from "./MyController";

const harmony = new Harmony({
   port: 8080,
   https: {
       enabled: false
   },
   // You can define a list of controllers here.
   // Make sure each controller class has at least one @Route configured.
   controllers: [
       MyController
   ]
});

// Start listening for incoming connections.
harmony.start();
```

If you want to add controllers _after_ the setup of Harmony, you can do so by
calling the `registerController` method on the `Harmony`-instance like so:

```typescript
harmony.registerController(HomeController);
```

If you navigate to http://127.0.0.1:8080/ in your browser, you should see the
"Hello World!" message that was generated by `MyController.indexAction`.

## Diving in deeper

The examples shown in the Quick Start chapter barely scratch the surface of what
is possible with Harmony. Please refer to the GitHub wiki page for more in-depth
documentation about each feature of Harmony.

---
_Source: https://npm.io/package/@byteshift/harmony · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._