Getting Started

Use Node.js 24.11+ on the 24.x line, or a compatible newer release. These examples target 4.0.0. Both 4.0.0 and 3.7.11 are LTS versions. For applications using 3.7.11, use the 3.7.11 guide.

Create a project

Configure npm authentication for your package access if required, then install matching versions:


mkdir heron-example
cd heron-example
npm init -y
npm pkg set type=module
npm install @heronjs/core@4.0.0 @heronjs/common@4.0.0 @heronjs/express@4.0.0 reflect-metadata rxjs
npm install --save-dev typescript @types/node
npm pkg set 'scripts.build=tsc' 'scripts.start=node dist/main.js'

Create tsconfig.json. HeronJS requires legacy TypeScript decorators and emitted decorator metadata:


{
  "compilerOptions": {
    "target": "ES2023",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*.ts"]
}

Define a controller and root module

Create src/main.ts:


import 'reflect-metadata';
import {Module} from '@heronjs/common';
import {HeronJS} from '@heronjs/core';
import {Rest, Get} from '@heronjs/express';
 
@Rest('/api')
class HealthController {
  @Get({uri: '/health'})
  health() {
    return {ok: true};
  }
}
 
@Module({controllers: [HealthController]})
class AppModule {}
 
const app = await HeronJS.create({module: AppModule});
await app.listen({port: 3000, host: '127.0.0.1'});
 
const shutdown = () => {
  app.close().catch(() => {
    process.exitCode = 1;
  });
};
process.once('SIGINT', shutdown);
process.once('SIGTERM', shutdown);

@Module registers the controller with this application. The @heronjs/express package provides the native Fastify HTTP adapter. Load reflect-metadata before decorated application modules.

Build and run


npm run build
npm start

From another terminal:


curl http://127.0.0.1:3000/api/health
# {"ok":true}

app.address() reports the bound address. await app.close() stops owned protocols, services and workers and disposes application resources. Always await cleanup in tests and scripts.

Add providers, configure HTTP hooks, or register another protocol using its guide. Pin additional @heronjs/* packages to 4.0.0 to keep framework versions aligned.