Skip to content

Installation

Install the Gland packages you need, configure TypeScript, and verify the toolchain.

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.

  1. Scaffold a TypeScript project.

    Terminal window
    mkdir my-app && cd my-app
    pnpm init
  2. Install the runtime packages.

    For an HTTP application. Swap @glandjs/express for whichever transport you want — @glandjs/fastify, @glandjs/koa, @glandjs/hono or @glandjs/node. Only one of them is ever needed:

    Terminal window
    pnpm add @glandjs/core @glandjs/common @glandjs/events @glandjs/http @glandjs/node reflect-metadata
  3. Install the toolchain and reflect-metadata.

    reflect-metadata is a peer dependency of @glandjs/core and @glandjs/common:

    Terminal window
    pnpm add -D typescript @types/node
    pnpm add reflect-metadata
  4. Configure tsconfig.json.

    The three options below are required. useDefineForClassFields must be false, 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"]
    }
  5. 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 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.

@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.