Installation
Install the Gland packages you need, configure TypeScript, and verify the toolchain.
Requirements
Section titled “Requirements”| Node.js | >= 20 |
| TypeScript | >= 5.0 |
| Package manager | pnpm (recommended), npm or Yarn |
Gland relies on reflect-metadata for decorator metadata, and on experimentalDecorators
plus emitDecoratorMetadata from TypeScript. Both are set up for you below.
Create a project
Section titled “Create a project”-
Scaffold a TypeScript project.
Terminal window mkdir my-app && cd my-apppnpm init -
Install the runtime packages.
For an HTTP application. Swap
@glandjs/expressfor whichever transport you want —@glandjs/fastify,@glandjs/koa,@glandjs/honoor@glandjs/node. Only one of them is ever needed:Terminal window pnpm add @glandjs/core @glandjs/common @glandjs/events @glandjs/http @glandjs/node reflect-metadataTerminal window npm install @glandjs/core @glandjs/common @glandjs/events @glandjs/http @glandjs/node reflect-metadataTerminal window yarn add @glandjs/core @glandjs/common @glandjs/events @glandjs/http @glandjs/node reflect-metadata -
Install the toolchain and
reflect-metadata.reflect-metadatais a peer dependency of@glandjs/coreand@glandjs/common:Terminal window pnpm add -D typescript @types/nodepnpm add reflect-metadataTerminal window npm install -D typescript @types/nodenpm install reflect-metadataTerminal window yarn add -D typescript @types/nodeyarn add reflect-metadata -
Configure
tsconfig.json.The three options below are required.
useDefineForClassFieldsmust befalse, or decorator metadata is lost.tsconfig.json {"compilerOptions": {"target": "ES2022","module": "NodeNext","moduleResolution": "NodeNext","strict": true,"experimentalDecorators": true,"emitDecoratorMetadata": true,"useDefineForClassFields": false,"skipLibCheck": true,"outDir": "dist"},"include": ["src"]} -
Verify the installation.
src/main.ts import 'reflect-metadata'import { EventBroker } from '@glandjs/events'const broker = new EventBroker({ name: 'smoke-test' })broker.on('ping', (payload) => console.log(payload))broker.emit('ping', { ok: true })Terminal window npx tsc && node dist/main.js# { ok: true }
Package reference
Section titled “Package reference”| Package | What it gives you | Install it if |
|---|---|---|
@glandjs/core |
DI container, module bootstrap, lifecycle hooks, Context |
always |
@glandjs/common |
@Module, @Controller, @Channel, @On, @Inject |
always |
@glandjs/events |
EventBroker, channels, mesh networking, IOEvent |
always |
@glandjs/emitter |
Standalone zero-dependency event emitter | you want a pub/sub primitive without the framework |
@glandjs/http |
Route decorators, HttpContext, the middleware onion, HttpCore, HttpBroker |
you serve HTTP |
@glandjs/express |
The Express 5 adapter | you use Express |
@glandjs/fastify |
The Fastify 5 adapter | you use Fastify |
@glandjs/koa |
The Koa 3 adapter | you use Koa |
@glandjs/hono |
The Hono 4 adapter, on Node and the edge | you want Fetch or an edge runtime |
@glandjs/node |
The node:http adapter, zero dependencies |
you want no framework at all |
Pick one adapter. They are interchangeable: the same controller runs unchanged on
any of them, and only the connectTo() line differs. The
adapter matrix is the honest comparison.
Optional extras
Section titled “Optional extras”@glandjs/http has no runtime dependencies beyond the toolkit. A few adapter features
are peer dependencies marked optional, and each one throws a message naming the package
rather than failing with undefined is not a function.
| Adapter | Install for | Package |
|---|---|---|
@glandjs/express |
multipart | multer |
@glandjs/fastify |
cookies, forms, static, multipart | @fastify/cookie, @fastify/formbody, @fastify/static, @fastify/multipart |
@glandjs/koa |
body parsing, static, multipart | koa-bodyparser, koa-static, @koa/multer |
@glandjs/hono |
listening on Node | @hono/node-server |
@glandjs/node |
nothing | — |
CORS, cookies, problem details and SSE are implemented inside @glandjs/http and
need nothing installed.
First steps walks through building a working API.