Upgrading to 0.6
0.6.0 removes APIs that did nothing, makes app.run() read PORT, and sends framework messages through the logger. Most apps only need to delete a call or two. Read Breaking in 0.6.0 before upgrading.
0.6.1 and 0.6.3 add features and fixes with no breaking changes. See New in 0.6.3 and New in 0.6.1. 0.6.2 was tagged but never published to npm; its changes ship in 0.6.3.
0.6.5 adds features and fixes, and changes some CLI generator flags (make:model writes a plain class unless you pass --orm). Apps don't need code changes. See New in 0.6.5.
A 0.x minor release can contain breaking changes; patch releases such as 0.6.1 don't. See the versioning policy.
npm i @meghjs/core@^0.6.5
npm i -D @meghjs/cli@^0.6.5New in 0.6.5
There is no 0.6.4: the changes on main after 0.6.3 ship in 0.6.5.
Changes to the CLI generators
0.6.5 changes what some generator flags mean. Your app's code is not affected, only what the make:* commands write from now on. Check any scripts that run them:
make:modelwrites a plain class by default. For a Megh ORM model (columns read from its migration), add--orm:megh make:model user --orm.--templateand--fieldsstill build a Megh ORM model without it.--ormnow means Megh ORM; TypeORM is--typeorm. Onmake:model,make:controller -mandmake:service -m, replace--ormwith--typeormwhere you generate TypeORM entities or repository services. With-m, Megh ORM stays the default.- A resource can't be built on a plain class.
make:resource,make:controller -mandmake:factorystop with a message if the model file is a plain class; regenerate it withmake:model <name> --orm --force. megh -vprints the logo, thenMegh v<version>, instead of the bare version. A script that reads it should matchv(\d+\.\d+\.\d+)on the last line, or usenpm ls @meghjs/cli.megh --helpandmegh newno longer print the logo.
New
- Generators write unit tests.
make:service useralso writessrc/services/user.service.spec.ts, and so do the other generators exceptmake:modeland the database ones.make:resourcetests every service method and route without a database. Pass--notest(or-nt) to skip them. See CLI: Tests. make:test(m:t) writes a test for a file you already have:megh make:test user.service.make:class(m:cls) writes a plain class insrc/classes/.megh --infoprints the CLI, Node.js and OS versions and the project's Megh packages, for bug reports. See Version and info.- Compression.
app.useCompression(), over@fastify/compress. See Compression. - Global prefix and versioning.
app.setGlobalPrefix('api', { exclude })andapp.useVersioning({ type: 'uri' | 'header' })with@Version(). See Global prefix and versioning. - Redirects and response headers.
@Redirect(url, status),Results.Redirect(url, status)and@ResponseHeader(name, value). See Redirects and headers. - Validated environment and config.
app.useEnvSchema(EnvDto)and@AppConfig({ schema })check values at boot and list every problem in aConfigValidationError. See Validating at boot. - Socket.IO authentication. The
useAuthenticationhandler runs on the handshake and setssocket.data.user. See WebSocket: Authentication. megh migrate --compiled(anddb:seed --compiled) runs the built.jsmigrations, for production images withoutsrc/. It is picked automatically when there is nosrc/folder. See Database Commands.
Fixes
- The CLI's generated files load when a name matches a Megh decorator:
make:config app(AppConfig) and aPost,GetorQuerymodel inmake:resource. MeghTest.getController/getProviderstand-ins are no longer written to the shared container, and requests wait for the routes to be mapped. See Testing.PartialType,PickTypeandOmitTypecopy class-validator, class-transformer, Megh and OpenAPI metadata.MEGH_DOTENV=falsestopsEnvironmentfrom reading.env;GetConfigpasses on errors fromconfig()and caches untilEnvironment.reload().- Controller auto-discovery reads the tsconfig
rootDir/outDir, detects tsx and other TypeScript runtimes, and fails on a file it can't import. - Scheduler: tasks stop when startup fails,
close()waits for running jobs, anduseScheduler({})scanssrc/tasks. useControllers()adds to earlier lists; a clear boot error for@Body()/@Query()without decorator metadata; Scalar serves the generated spec;FileStorageconfines saves after following symlinks; the error logger logs the path without the query string.megh doctorrequires Node.js 22, like the packages.
New in 0.6.3
Generators for events, queues and scheduled tasks.
make:event,make:listener(--eventto type it),make:queue,make:workerandmake:task(--cron,--interval). See Events, Queue and Scheduler.make:*puts the module folder first.megh make:model users/usernow writessrc/users/models/user.model.ts, notsrc/models/users/user.model.ts. The same goes for controllers, services, DTOs, middleware, config and mail. Existing files stay where they are, andmake:resource,make:factoryandsync:modelstill find models in the old place. See Folders.Auto-discovered controllers.
useControllers({ auto: true })without apathnow scans everycontrollers/folder undersrc/, so module controllers are found. With apath, nothing changes.megh newoffers OpenAPI, CORS and MeghORM only. Mail, Scalar UI, TypeORM and Knex are no longer set up bymegh new; asking for them with--featuresprints how to add them. Existing projects are not affected. See Mail: Setting it up.Generated models put each decorator on its own line, with a blank line between columns.
sync:modelstill reads models in the one-line style, and keeps hand-written fields as they are.update:modelis nowsync:model(aliass:m). The old name andu:mstill work.Generators review changes to existing files.
sync:modeland anymake:*run with-fshow a diff of each file they would change, the files that import it and the lines that use removed or retyped members, then ask before writing. Declining puts everything back. Pass-yto skip the question; scripts and CI aren't asked. See Reviewing changes.A smaller Megh logo above
megh --help.
New in 0.6.1
No code changes needed. Everything here is opt-in.
- Mail. Inject
Mailerand sendMailableclasses over SMTP, or over SendGrid, Mailgun, Postmark or Resend's HTTP APIs. A failover mailer tries each in turn.queue()andlater()send through the queue. Turn it on withapp.useMail(), configured fromMEGH_MAIL_*in.env; options passed touseMail()override them. See Mail. - Security headers.
app.useSecurityHeaders()sends a Content Security Policy, HSTS,X-Frame-Options,nosniffand the other usual headers. It is built in, so@fastify/helmetis no longer needed. See Security Hardening. - Rate limiting.
app.useRateLimit()limits requests per client and answers 429.@RateLimit()gives a route its own limit, andRedisRateLimitStoreshares counts between replicas. It is built in, so@fastify/rate-limitis no longer needed. See Security Hardening. - CLI:
megh make:mail <Name>creates a Mailable.megh newoffers a Mail feature.megh newrunsgit init(skip it with--skip-gitorMEGH_SKIP_GIT=1).- Generated resource services have JSDoc.
- Fixes:
megh newnow installs the OpenAPI packages when you pick OpenAPI or Scalar, so the generated app starts.- The "No mailer is set" error lists every configured mailer.
If you registered @fastify/helmet or @fastify/rate-limit yourself in an onInit hook, as the 0.6.0 docs suggested, that keeps working. To switch, remove the app.app.register(...) calls, uninstall the two packages, and call app.useSecurityHeaders() and app.useRateLimit() instead.
Breaking in 0.6.0
Removed APIs
These did nothing, or were a second name for another API. Delete the calls, or switch to the replacement:
| Removed | Use instead |
|---|---|
app.useHttps() | Nothing: it was a no-op. For HTTPS, pass server: { https: { key, cert } } to Megh.createApplication(), or terminate TLS at a proxy |
app.useSerialization() | Nothing: it was a no-op |
app.mapFeatures() | Nothing: it was a no-op |
MeghSocketIo | Get the server with MeghContainer.get(SocketIoServer). See WebSocket |
DuplicateRouteException | Nothing. Fastify already refuses duplicate routes at startup |
MeghRouter.mapRoute(), MeghRouter.registerMiddleware() | app.mapGet() and the other map* methods, and app.useMiddlewares() |
CreateSwaggerObjectSchema, GetObjectSchema | generateClassSchema |
Your type checker finds every call that needs changing.
app.run() reads PORT
app.run() without a port now listens on the PORT environment variable, like it already read HOST, and falls back to 4000. A port passed to run() still wins:
app.run(); // PORT, else 4000
app.run(3000); // 3000, whatever PORT saysAn app that calls app.run() without a port and has PORT set to something else, for example by the hosting platform, now listens on PORT. That's usually what you want. To keep the old behaviour, pass the port explicitly.
An invalid PORT, such as abc, now stops startup with an error.
Apps created by the CLI read PORT themselves in serve.ts and keep working. You can simplify serve.ts to app.run().
Framework logs go through the logger
Framework messages that went to console now go through the logger. That includes the startup line Application running on <address>, and warnings such as a route using @Authorized with no authorization handler registered. In production they're JSON lines like every other log entry.
If a test spied on console.warn or console.error to check one of these messages, spy on the logger instead. See Testing.
Other changes
- New projects leave
NODE_ENVout of.env.megh servealready runs the app in development andmegh startin production. The old line turned on development mode, with error details in responses, when a project's.envwas deployed and the app started withnode dist/serve.js. In an existing project, removeNODE_ENV=developmentfrom.envif you deploy that file. See Deployment. MeghScheduleris exported, for running scheduled tasks in a process without the HTTP app. See Scheduler.- New docs: Application, Configuration, Scheduler, Testing, Deployment, Security Hardening, API Reference, Versioning Policy and FAQ.
- Doc fixes:
useStaticFilestakesroot, notpath.useMultipartlimits files to 10 MB unless you passlimits, on top ofFileStorage's 50 MB.
Coming from older versions
On 0.5.0 to 0.5.4, read Upgrading to 0.5.5 first.