A zero-dependency, fully featured, HTTP server micro-framework
npm install @byteshift/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.
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.
- 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.
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.
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
`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.
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('
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`.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.