Install CLI

Heron CLI can help you scaffold a project and speed up local development.

npm i -g @heronjs/cli

pnpm add -g @heronjs/cli

yarn global add @heronjs/cli

bun add --global @heronjs/cli

Create a project

Start with an empty directory and initialize a Node.js project.

mkdir example
cd example
npm init -y
 
echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" > .npmrc

The NPM_TOKEN is required to install the HeronJS packages from npm.

npm install @heronjs/core @heronjs/common @heronjs/express

pnpm add @heronjs/core @heronjs/common @heronjs/express

yarn add @heronjs/core @heronjs/common @heronjs/express

bun add @heronjs/core @heronjs/common @heronjs/express

Create your root module

The root module is the entry point of your application. It declares the modules and platform features that HeronJS should load when the app starts.

@Module({
    imports: [TodosModule],
})
@GateKeeper(AuthContext)
@DataSources([MYSQLDatabase, PostgresDatabase])
@Stores([MemoryCacheConfig])
export class AppModule {}

In this example:

• @Module() registers the application module and its imports.
• @GateKeeper() applies the application-level authentication or authorization context.
• @DataSources() registers the database connections used by the app.
• @Stores() configures the storage or caching layer.

Bootstrap the application

After defining the root module, create the server entry file and start HeronJS with that module.

import 'reflect-metadata';
import { AppModule } from './app';
import { HeronJS } from '@heronjs/core';
 
const main = async () => {
    const app = await HeronJS.create({ module: AppModule });
    await app.listen({
        port: 3000,
    });
};
 
(async () => main())();

This does two things:

• HeronJS.create() builds the application from your root module.
• app.listen() starts the HTTP server on port 3000.

Start the application

Run your start script to launch the server.

npm run start

pnpm run start

yarn run start

bun run start

Once the app is running, your server will be available at http://localhost:3000.