Skip to content

Quick Start ​

There are two ways to design your application: Controller based and Route method based. They can be mixed in the same app.

Using a controller ​

Controllers group related routes and can take dependencies through the constructor. This is the approach the CLI scaffolds.

ts
import { Megh } from '@meghjs/core';
import { WelcomeController } from './controllers/welcome.controller';

const app = Megh.createApplication();
app.useControllers([ WelcomeController ]);

app.run();
ts
import { ApiController, Get } from '@meghjs/core';

@ApiController
export class WelcomeController {

    @Get()
    sayHello(){
        return 'Hello world!.';
    }
}

See Controller for parameters, REST resources and error handling.

Using inline routes ​

For small apps, register handlers directly on the app with mapGet, mapPost, mapPut, mapPatch and mapDelete:

ts
import { Megh } from '@meghjs/core';

const app = Megh.createApplication();

app.mapGet('/', () => 'Welcome to Megh.');

app.run(); // PORT from the environment, else :4000

Handlers receive the request and response, and returning an object sends JSON:

ts
app.mapGet('/users/:id', (req) => ({ id: req.params.id }));

app.mapPost('/users', (req) => {
  return { created: req.body };
});

Inline routes return a chainable object for middleware, authorization and OpenAPI metadata:

ts
app.mapGet('/secret', handler)
  .useMiddleware([ApiKeyMiddleware])  // classes (resolved through DI) or instances
  .authorized()                       // like @Authorized(); .authorized('jwt') picks a handler
  .useOpenApi({ tags: ['internal'] });

They run the same pipeline as controller routes: middleware, then the authentication handler (request.user), then .authorized(). Return Results.* to set the status code; thrown errors go through the error handler.

Returning responses ​

Returning an object or array sends JSON; returning a string sends it as-is.

Set the status code with @HttpCode, or return a result that carries one:

ts
import { Post, Get, HttpCode, Results, HttpResponse } from '@meghjs/core';

@Post('/')
@HttpCode(201)
create(@Body() dto: CreateUserDto) {
  return this.users.create(dto);          // 201 with the user as JSON
}

@Get('/:id')
async findOne(@Param('id') id: number) {
  const user = await this.users.find(id);
  return user ? Results.Ok(user)          // 200 { data: user }
              : Results.NotFound('nope'); // 404 { code, status, message }
}
ResultStatusBody
Results.Ok(x)200{ data: x }
Results.Created(x)201{ data: x }
Results.NoContent()204empty
Results.NotFound(msg)404{ code, status, message }
Results.OkStream(stream, { contentType, filename })200the stream
HttpResponse.Created(x)201{ message, data }
HttpResponse.NoContent()204empty
Results.Redirect(url, status?)302 (or 301, 303, 307, 308)empty, Location: url

A returned result's status wins over @HttpCode.

Redirects and headers ​

@Redirect(url, status?) redirects instead of sending the return value. The handler can pick another target by returning { url, statusCode }:

ts
import { Get, Redirect, ResponseHeader, Results } from '@meghjs/core';

@Get('/docs')
@Redirect('https://docs.example.com', 301)
docs() {}

@Get('/latest')
@Redirect('/releases')
latest() {
  return { url: `/releases/${this.releases.latestId()}` }; // 302 there
}

@Get('/me')
me(@AuthUser() user?: User) {
  return user ?? Results.Redirect('/login');
}

@ResponseHeader(name, value) sets a header on every response from the route. Stack it for several; a header a returned Results.* sets wins:

ts
@Get('/report')
@ResponseHeader('Cache-Control', 'no-store')
report() { ... }

@Header() is the parameter decorator that reads a request header.

To send an error status, throw an HTTP exception:

ts
import { HttpExceptions } from '@meghjs/core';

throw HttpExceptions.notFound('User not found');

Error responses have the shape { code, status: "Error", message, data? }. Outside development, 5xx responses hide the message and data. See Error Handling.

Inline routes don't validate DTOs; use a controller when you need that.

Running the app ​

run takes an optional port. Without one it uses the PORT environment variable, else 4000:

ts
app.run();      // PORT, else :4000
app.run(3000);  // :3000
app.run(3000, { host: '127.0.0.1' });

Set NODE_ENV=development locally to get detailed errors and pretty logs. An unset NODE_ENV counts as production.

See Application for the app options, the use* methods, what run() does, lifecycle hooks and shutdown.

Next steps ​

Released under the MIT License.