Forem: Orinda Felix Ochieng

Building Production-Grade Authentication with kickjs Every Mistake You'll Make

Orinda Felix Ochieng — Tue, 14 Apr 2026 09:40:24 +0000

Build auth with kickjs

I spent a week building 20 authentication test applications for KickJS — a decorator-driven Node.js framework on Express 5 and TypeScript. The goal: stress-test every auth pattern the framework supports and document every pitfall along the way.

Here's what I learned, what broke, and how to fix it.

What We Built

A pnpm monorepo with 20 standalone apps, each testing a different authentication strategy:

Core auth patterns (11 apps):
JWT, API keys, OAuth (Google/GitHub/Discord/Microsoft), Passport.js bridge, RBAC, multi-strategy fallback, decorator precedence, guard middleware, session-based auth, SAML 2.0, API gateway

Multi-tenant auth (8 apps):
Header/subdomain tenant resolution, database-per-tenant isolation, schema-per-tenant, shared-table discriminator, tenant-scoped RBAC, per-tenant JWT secrets, cross-tenant adversarial testing

Identity provider (1 app):
Keycloak integration with realm/client role mapping, RS256 validation

222 tests. Zero failures. Here's what went wrong getting there.

Mistake 1: Accessing the User Wrong

Every framework has a way to get the authenticated user. Django has request.user. Laravel has Auth::user(). Spring Boot has @AuthenticationPrincipal.

In KickJS, the auth adapter sets req.user on the raw Express request during the middleware phase. But the framework's RequestContext (the ctx object your controllers receive) has its own metadata store with ctx.set() / ctx.get().

What you'll write first:

@Get('/me')
@Authenticated()
me(ctx: RequestContext) {
  const user = (ctx.req as any).user  // ugly, untyped, breaks abstraction
  ctx.json({ user })
}

Why this is wrong:

The as any cast bypasses TypeScript. You're reaching through the framework's abstraction into the raw Express request. If the framework changes how it stores the user, your code breaks silently.

The fix (coming in a future release):

// RequestContext gains a .user getter
get user(): AuthUser | undefined {
  return (this.req as any).user ?? this.metadata.get('user')
}

Until then, the workaround is what every app in our test suite uses. It works. It's just not pretty.

Takeaway: If your framework wraps the request object, make sure auth data is accessible through the wrapper, not just the raw object underneath.

Mistake 2: @public Routes Returning 401

We upgraded from auth v2 to v3 and suddenly every @Public() route started returning 401.

@Controller()
@Authenticated()       // class-level: all routes need auth
export class UserController {
  @Get('/me')
  me(ctx) { ... }      // protected - correct

  @Get('/health')
  @Public()             // should bypass auth
  health(ctx) { ... }   // was returning 401!
}

Root cause: The v3 package was a fresh publish where the Symbol('auth:public') identity changed. Symbols are runtime-unique — if the decorator and the adapter resolve from different module instances, the metadata keys don't match.

How we caught it: 6 of 11 apps broke simultaneously with the same pattern. That's the value of comprehensive test apps — one subtle framework change lights up failures everywhere.

The fix: The framework author patched it in v3.0.2. Our test suite confirmed the fix across all 11 apps in one command: pnpm test.

Takeaway: When you publish a package with Symbols as metadata keys, ensure there's exactly one copy in the dependency tree. pnpm ls is your friend.

Mistake 3: CSRF Blocking Your Login Endpoint

v3 added automatic CSRF protection. If you use session-based auth, it auto-enables. Smart, right?

Except it also blocks your POST /login endpoint — the one place users can't have a CSRF token yet because they haven't made a GET request to receive the cookie.

@Post('/login')
@Public()           // bypasses auth check
// but CSRF middleware still runs!
login(ctx) { ... }  // 403 "CSRF token mismatch"

Why it happens: CSRF middleware runs independently of auth middleware. @Public() exempts from authentication, not from CSRF. The login POST has no CSRF token because it's the first request.

The fix:

@Post('/login')
@Public()
@CsrfExempt()    // explicitly skip CSRF for this route
login(ctx) { ... }

The better fix (proposed to the framework): @Public() should auto-exempt from CSRF. If there's no session to protect, CSRF is meaningless. Django, Laravel, and Spring all handle this — public endpoints don't need CSRF because there's no cookie-based session to exploit.

Takeaway: CSRF protection + API-first design = friction. Login, logout, webhooks, and OAuth callbacks all need @CsrfExempt() or equivalent. Design your CSRF middleware to understand that pre-auth endpoints have nothing to protect.

Mistake 4: Roles in JWT Don't Match Roles in Your Decorator

Keycloak stores roles like this:

{
  "realm_access": {
    "roles": ["admin", "user"]
  },
  "resource_access": {
    "my-app": {
      "roles": ["editor", "viewer"]
    }
  }
}

But KickJS's @Roles('admin') checks a flat user.roles array. If your mapPayload only extracts realm_access.roles, you'll never match client-specific roles.

What goes wrong:

// Only gets realm roles — client roles silently lost
mapPayload: (payload) => ({
  id: payload.sub,
  roles: payload.realm_access?.roles ?? [],
})

@Roles('editor')  // never matches! 'editor' is in resource_access

The fix:

import { keycloakMapPayload } from '@forinda/kickjs-auth'

new JwtStrategy({
  jwksUri: 'https://keycloak.example.com/realms/my-realm/.../certs',
  mapPayload: keycloakMapPayload({ clientId: 'my-app' }),
  // Merges realm_access.roles + resource_access['my-app'].roles
})

Takeaway: Identity providers have their own claim structure. Don't assume roles are in a flat array. Map them explicitly and test with real-ish JWT payloads, not simplified mocks.

Mistake 5: Rate Limit State Leaking Between Tests

We wrote a custom rate-limit guard with an in-memory counter:

const counters = new Map<string, { count: number; resetAt: number }>()

export async function rateLimitGuard(ctx, next) {
  const key = ctx.req.ip || 'unknown'
  // ... increment counter, reject if over limit
}

Tests started failing randomly. The 6th test in the suite would get 429 even though it was the first request in that test.

Root cause: The Map is module-level. Test isolation resets the DI container (Container.reset()) but doesn't reset module-level state.

The fix:

export function resetRateLimitCounters() {
  counters.clear()
}

// In test:
beforeEach(() => {
  Container.reset()
  resetRateLimitCounters()  // don't forget this!
})

The v3 way: Use @RateLimit({ max: 5, windowMs: 60_000 }) decorator instead. The framework manages the counters per-route inside the adapter, and createTestApp with isolated: true gets a fresh adapter.

Takeaway: Module-level mutable state is the enemy of test isolation. Export a reset function or move state into the DI container.

Mistake 6: Multi-Tenant Role Leakage

This one's a security bug. In a multi-tenant app, the same user can have different roles in different tenants. Admin in Tenant A, viewer in Tenant B.

If you store roles in the JWT, they're global:

{ "sub": "user-123", "roles": ["admin"] }

Sending this JWT with X-Tenant-ID: tenant-b grants admin access in Tenant B even though the user is only a viewer there.

The fix — tenant-scoped role resolution:

new AuthAdapter({
  strategies: [new JwtStrategy({ ... })],
  roleResolver: async (user, tenantId) => {
    // Load roles from tenant's database, not from JWT
    return tenantRoleStore.getRoles(tenantId, user.id)
  },
})

The JWT carries identity (who you are). The tenant database carries authorization (what you can do here). Never trust JWT claims for tenant-scoped permissions.

How we tested it:

tenantRoleStore.setRoles('tenant-a', userId, ['admin'])
tenantRoleStore.setRoles('tenant-b', userId, ['viewer'])

// Same JWT, different tenant header
const resA = await request(app)
  .get('/admin-only')
  .set(withTenant('tenant-a'))
  .set(withBearer(token))
// 200 - admin in tenant A

const resB = await request(app)
  .get('/admin-only')
  .set(withTenant('tenant-b'))
  .set(withBearer(token))
// 403 - viewer in tenant B

Takeaway: In multi-tenant systems, separate authentication (identity) from authorization (permissions). JWTs prove who you are. The tenant's data store decides what you can do.

Mistake 7: Per-Tenant JWT Secrets — The Cross-Tenant Token Attack

Each tenant should have its own JWT signing secret. Otherwise, a token from Tenant A is valid in Tenant B.

new JwtStrategy({
  secret: 'one-secret-for-all',  // WRONG for multi-tenant
})

The attack: User in Tenant A copies their JWT. Sends it with X-Tenant-ID: tenant-b. Since the same secret validates both, Tenant B accepts it.

The fix:

const tenantSecrets = {
  'tenant-a': 'tenant-a-unique-secret-...',
  'tenant-b': 'tenant-b-unique-secret-...',
}

new JwtStrategy({
  secretResolver: async (tenantId) => {
    const secret = tenantSecrets[tenantId]
    if (!secret) throw new Error(`Unknown tenant: ${tenantId}`)
    return secret
  },
})

Now a Tenant A token fails verification against Tenant B's secret. Our adversarial test:

const tokenA = jwt.sign(payload, tenantSecrets['tenant-a'])

const res = await request(app)
  .get('/me')
  .set(withTenant('tenant-b'))   // wrong tenant
  .set(withBearer(tokenA))
// 401 - signature mismatch

Takeaway: Multi-tenant JWT = per-tenant secrets. No exceptions.

Mistake 8: Token Revocation That Un-Revokes

We found a bug in the framework's MemoryTokenStore.revokeAllForUser(). It was supposed to revoke all tokens for a user (for password change, account compromise). Instead, it deleted the revocation entries — making previously-revoked tokens valid again.

// What the code did:
async revokeAllForUser(userId: string): Promise<void> {
  for (const [key, entry] of this.revoked) {
    if (entry.userId === userId) {
      this.revoked.delete(key)  // REMOVES the blacklist entry!
    }
  }
}

After calling revokeAllForUser('user-123'), isRevoked('token-abc') returns false because the entry was deleted. The token works again.

How we caught it: The test expected isRevoked to return true after revokeAllForUser. It returned false. A simple naming confusion in the implementation — "revoke all" was implemented as "clean up tracking for".

Takeaway: Always test the negative path of security functions. "This token should NOT work after revocation" is more important than "this token should work before revocation."

Mistake 9: The Subdomain Tenant That Never Resolves

The TenantAdapter's subdomain strategy checks hostname.split('.').length >= 3. So:

Host	Parts	Resolves?
`tenant-a.api.example.com`	4	Yes: `tenant-a`
`tenant-a.localhost`	2	No
`localhost`	1	No

In development, localhost has no subdomain. You need at least 3 parts: tenant-a.api.localhost.

// This works:
.set('Host', 'tenant-a.api.localhost')  // 3 parts

// This doesn't:
.set('Host', 'tenant-a.localhost')  // only 2 parts

Takeaway: Test your tenant resolution with realistic hostnames. localhost is not the same as app.example.com. Your local dev setup needs a wildcard DNS or /etc/hosts entries.

Mistake 10: The Decorator Precedence Trap

Which wins — class-level @Authenticated() or method-level @Public()?

@Controller()
@Authenticated()           // class: everything needs auth
export class AuthController {
  @Get('/me')
  me(ctx) { ... }           // auth required (inherits from class)

  @Post('/login')
  @Public()                 // method overrides class
  login(ctx) { ... }        // public (method wins)

  @Delete('/:id')
  @Roles('admin')           // implies @Authenticated
  delete(ctx) { ... }       // needs auth + admin role
}

The resolution order:

Method @Public() — highest priority (skip auth)
Method @Authenticated() / @Roles() — require auth
Class @Authenticated() — require auth for all methods
defaultPolicy — fallback for unannotated routes

And defaultPolicy matters more than you think:

// defaultPolicy: 'protected' (default)
// Unannotated routes require auth — secure by default

// defaultPolicy: 'open'
// Unannotated routes are public — you must explicitly protect each one

We tested every combination. The one that catches people: @Roles('admin') without a token returns 401 (not 403). Auth is checked first, roles second. No token = unauthorized, not forbidden.

Takeaway: @Roles implies @Authenticated. The error code tells you which check failed: 401 = identity problem, 403 = permission problem.

The Architecture That Made This Possible

We used a pnpm workspace monorepo with one app per auth pattern:

kick-auth-implementations/
├── packages/shared/          # Test helpers, assertions, mock users
├── apps/
│   ├── jwt-auth/             # 33 tests
│   ├── api-key-auth/         # 16 tests
│   ├── oauth-auth/           # 12 tests
│   ├── session-auth/         # 11 tests (CSRF tests included)
│   ├── rbac-auth/            # 31 tests (policies + events)
│   ├── keycloak-auth/        # 8 tests
│   ├── mt-tenant-isolation/  # 7 adversarial tests
│   └── ... (20 apps total)
└── issues/                   # Framework bugs found along the way

Why this works:

Isolation: A bug in OAuth tests can't break JWT tests
Incremental: Add a new auth pattern without touching existing apps
CI-friendly: pnpm test runs all 222 tests in parallel
Documentation: Each app IS the documentation for that pattern

What We Filed

Building 20 apps against a framework surfaces real issues. We filed 22 framework issues:

Security gaps: CSRF auto-exempt for @Public(), token revocation semantics bug, security-by-default bootstrap

Missing features: JWKS key rotation (landed in v3.0.4), Keycloak claim mapping (landed in v3.0.4), token introspection strategy, back-channel logout, refresh token flow

Multi-tenant gaps: DI token is static singleton (needs AsyncLocalStorage), no database connection switching, auth + tenant adapter integration

DX improvements: ctx.user bridging, auth scaffold generator, password service (landed in v3)

TL;DR

Test the unhappy paths. 401 vs 403 matters. Expired tokens, wrong secrets, missing headers — test them all.
CSRF + API-first is tricky. Login endpoints need @CsrfExempt() until the framework auto-exempts @Public() routes.
Multi-tenant auth is a pipeline: Resolve tenant -> Switch context -> Authenticate -> Authorize with tenant-scoped roles. Each step depends on the previous one.
JWT carries identity, not authorization. In multi-tenant systems, load permissions from the tenant's data store, not from JWT claims.
Per-tenant JWT secrets are non-negotiable. One shared secret = cross-tenant token attacks.
Test with realistic data. Keycloak's nested role structure, subdomain hostname parts, Symbol identity across module boundaries — mocks hide these issues.

The entire test suite is open source. Every app, every test, every issue filed.

Built with KickJS — a decorator-driven Node.js framework on Express 5 and TypeScript.

The KickJS CLI: Scaffolding Production-Ready Node.js Backends in Seconds

Orinda Felix Ochieng — Fri, 10 Apr 2026 23:04:41 +0000

A deep dive into the code generation tool that makes KickJS feel like Rails — except it's TypeScript, it's Express 5, and the scaffolds are actually good.

Why a CLI Matters

Every backend framework eventually confronts the same problem: boilerplate. You know the shape of a new feature before you start typing — a controller, a service, a repository, DTOs, a module registration, maybe a test file. You've written it a hundred times. You're going to write it a hundred more. The code isn't hard; it's just tedious, and the tedium invites inconsistency.

The answer is code generation. Rails has rails g. Angular has ng g. NestJS has nest g. KickJS has kick g. But where NestJS generators feel like templates-with-string-substitution, KickJS generators are built to produce the same well-structured code your team would write by hand after a code review — wired up correctly, typed end-to-end, and ready to run without edits.

This article is the guided tour of the kick CLI. By the end, you'll know how to:

Scaffold a new project in one command
Generate full DDD modules with 16 files in about two seconds
Use the field-driven scaffold generator to create CRUD from a type description
Add KickJS packages with their peer dependencies resolved automatically
Define custom commands in kick.config.ts so your project-specific workflows become first-class CLI citizens
Inspect a running application's routes, middleware, and DI container
Generate fully-typed route handlers via the typegen system

Let's start from zero.

Installing the CLI

There are three ways to run kick, and each has its place.

1. Global install (recommended for daily use)

pnpm add -g @forinda/kickjs-cli
# or: npm install -g @forinda/kickjs-cli
# or: yarn global add @forinda/kickjs-cli

kick --version

With a global install, kick is on your $PATH and you can run it from anywhere. It'll pick up the project's local kick.config.ts automatically when you run it inside a project directory.

2. npx / pnpm dlx / yarn dlx (no install)

npx @forinda/kickjs-cli new my-api
# or: pnpm dlx @forinda/kickjs-cli new my-api
# or: yarn dlx @forinda/kickjs-cli new my-api

Good for one-off project creation or CI pipelines where you don't want a global install.

3. Project-local (inside the monorepo or a single project)

Once a KickJS project is created, @forinda/kickjs-cli is already in devDependencies. You can run it via:

pnpm kick dev
pnpm kick g module user

This is what most of the examples in this article use. It ensures you're running the exact CLI version pinned in the project's lockfile, which avoids the "works on my machine" problem when the CLI is upgraded.

Creating a Project: `kick new`

Here's the single command that creates a complete, runnable backend:

kick new my-api

Run that without any flags and the CLI walks you through five interactive prompts:

Project template — REST, GraphQL, DDD, CQRS, or Minimal
Package manager — pnpm, npm, or yarn
Default repository — Prisma, Drizzle, In-Memory, or a custom ORM
Git init — initialize a git repository and make the first commit
Install deps — run the selected package manager immediately

If you know what you want, skip the prompts entirely:

kick new my-api \
  --template rest \
  --repo drizzle \
  --pm pnpm \
  --git \
  --install

For CI pipelines or shell scripts where no TTY is available, this non-interactive form is essential. Every prompt has a corresponding flag, and the CLI errors out clearly if you leave a required field blank.

The Five Templates

The --template flag picks the shape of the generated project:

Template	What You Get	Packages Pre-installed
`rest` (default)	Express + Swagger + DevTools	`kickjs`, `kickjs-vite`, `kickjs-swagger`
`graphql`	GraphQLAdapter + GraphiQL	`kickjs`, `kickjs-vite`, `kickjs-graphql`
`ddd`	Full DDD layering for each module	`kickjs`, `kickjs-vite`, `kickjs-swagger`
`cqrs`	Commands, queries, events, WS, queue, OTel	`kickjs`, `kickjs-vite`, plus 4 more
`minimal`	Bare Express — no adapters	`kickjs`, `kickjs-vite`

The rest and ddd templates are 90% of what people want. rest gives you a flat structure where each module has its controller and service at the top level, which is perfect for small to medium APIs. ddd produces a layered structure with presentation/, application/, domain/, and infrastructure/ folders — the right choice when your domain logic deserves to be isolated from your HTTP plumbing.

Safety Nets

The scaffolder is careful about destructive operations. If the target directory already exists and isn't empty, it shows up to five entries from the directory and asks whether to clear them. Pass --force to skip the confirmation.

And — a small but meaningful fix we added recently — the CLI installs dependencies before running git init, so your lockfile and any files produced by kick typegen end up in the initial commit. You won't see a dangling "chore: add lockfile" commit as the second entry in your history.

The Dev Loop: `kick dev`, `kick build`, `kick start`

Once a project exists, three commands handle the entire lifecycle.

`kick dev`

kick dev
kick dev -e src/main.ts     # custom entry file
kick dev -p 4000            # custom port (overrides Vite default of 5173)

This starts the Vite development server in SSR mode. It's the secret sauce behind the framework's "instant reload without losing state" pitch. Edit a controller, save the file, and within 50 milliseconds the Express handler is swapped out — database connections, WebSocket state, and in-memory caches all survive intact. You can keep a Postgres connection pool open across hundreds of reloads.

The server listens on port 5173 by default (Vite's default). Override with -p or by setting PORT=3000 in your .env file.

`kick dev:debug`

Same as kick dev, but attaches a Node.js debugger. Point Chrome DevTools, VS Code, or your IDE's inspector at the debug port and you can set breakpoints that survive across HMR reloads. This is the one I use when I'm tracking down a bug that only appears after three requests.

`kick build`

kick build

Runs vite build with the framework's production defaults — ESM output, node20 target, proper externalization of native modules. The output lands in dist/. If your kick.config.ts lists copyDirs (for views, email templates, static assets), those get copied over as part of the build.

`kick start`

kick start
kick start -e dist/main.js
kick start -p 8080

Runs the built output with NODE_ENV=production. This is what you put in your Dockerfile or process manager. It doesn't use Vite at all — it's just node dist/index.js with some convenience wrappers for port and entry resolution.

Code Generation: `kick g`

This is the part you'll use most. The generate command (aliased to g) scaffolds code according to your project's pattern and conventions.

Run kick g --list to see every available generator in your terminal. Here's the shortlist:

Command	What It Generates
`kick g module <name>`	Full feature module (controller, DTOs, use-cases, repo)
`kick g scaffold <name> <fields...>`	Same as `module`, but with concrete fields
`kick g controller <name>`	Standalone `@Controller` class
`kick g service <name>`	Standalone `@Service` class
`kick g middleware <name>`	Express middleware function
`kick g guard <name>`	Route guard for auth/roles
`kick g dto <name>`	Zod DTO schema
`kick g adapter <name>`	`AppAdapter` with lifecycle hooks
`kick g test <name>`	Vitest test scaffold
`kick g resolver <name>`	GraphQL resolver
`kick g job <name>`	Queue job processor
`kick g config`	Generate `kick.config.ts`

Let's look at the important ones.

`kick g module` — Your New Best Friend

kick g module user

That one command creates the entire feature structure. With the default DDD pattern and the in-memory repo, you get 16 files organized into layers:

src/modules/users/
├── index.ts                                          # Module wiring
├── constants.ts                                      # Query config + DI tokens
├── presentation/
│   └── user.controller.ts                            # Full CRUD controller
├── application/
│   ├── dtos/
│   │   ├── create-user.dto.ts                        # Zod schema
│   │   ├── update-user.dto.ts
│   │   └── user-response.dto.ts
│   └── use-cases/
│       ├── create-user.use-case.ts
│       ├── get-user.use-case.ts
│       ├── list-users.use-case.ts
│       ├── update-user.use-case.ts
│       └── delete-user.use-case.ts
├── domain/
│   ├── entities/user.entity.ts
│   ├── value-objects/user-id.vo.ts
│   ├── repositories/user.repository.ts              # Interface + createToken
│   └── services/user-domain.service.ts
└── infrastructure/
    └── repositories/in-memory-user.repository.ts    # Working implementation

The generator also updates src/modules/index.ts to register the new module in the AppModuleClass[] array. No manual imports, no "forgot to register the module" bugs.

Pluralization is automatic. kick g module user produces src/modules/users/ (plural folder, plural route /users) but classes stay singular: UserController, UserService, UserEntity. The framework uses the battle-tested pluralize npm package, so irregular plurals work correctly: kick g module person produces src/modules/people/, kick g module status produces src/modules/statuses/, and kick g module category produces src/modules/categories/. Disable pluralization with --no-pluralize or set modules.pluralize: false in kick.config.ts.

Generate Multiple Modules at Once

kick g module user task project

Takes a list and creates all three modules in sequence. Each one is independently registered. This is nice when you're laying down the structure of a new feature area and already know the three modules you'll need.

Pattern Overrides

The default pattern comes from kick.config.ts, but you can override per-invocation:

kick g module user --pattern rest      # flat structure
kick g module user --pattern minimal   # just index.ts + controller
kick g module user --pattern cqrs      # commands, queries, events

The REST pattern is particularly nice for smaller modules — you get the module, controller, service, repository interface, in-memory implementation, DTOs, and tests, all at the top level of the module folder without the layered directory nesting.

`kick g scaffold` — CRUD From a Field Description

This is the generator that feels like magic. Instead of editing generated DTOs after the fact, you describe the fields up front and the scaffold generator produces working code with concrete types:

kick g scaffold post \
  title:string \
  body:text \
  published:boolean:optional \
  publishedAt:date:optional

The field syntax is name:type or name:type:optional. Here are the supported types:

Type	TypeScript	Zod	Example
`string`	`string`	`z.string()`	`title:string`
`text`	`string`	`z.string()`	`body:text`
`number`	`number`	`z.number()`	`price:number`
`int`	`number`	`z.number().int()`	`age:int`
`float`	`number`	`z.number()`	`rating:float`
`boolean`	`boolean`	`z.boolean()`	`active:boolean`
`date`	`string`	`z.string().datetime()`	`createdAt:date`
`email`	`string`	`z.string().email()`	`email:email`
`url`	`string`	`z.string().url()`	`website:url`
`uuid`	`string`	`z.string().uuid()`	`externalId:uuid`
`json`	`any`	`z.any()`	`metadata:json`
`enum:a,b,c`	`'a' \	'b' \	'c'`

And yes, you can combine them. A realistic scaffold command for a task management module might look like:

kick g scaffold task \
  title:string \
  description:text:optional \
  status:enum:todo,in_progress,done \
  priority:enum:low,medium,high \
  dueDate:date:optional \
  assigneeId:uuid:optional

Run that and you get DTOs, entities, a query config that knows about every field, a controller with five typed routes, five use-cases, and a working in-memory repository. The generated createTaskSchema ends up looking like this:

import { z } from 'zod'

export const createTaskSchema = z.object({
  title: z.string(),
  description: z.string().optional(),
  status: z.enum(['todo', 'in_progress', 'done']),
  priority: z.enum(['low', 'medium', 'high']),
  dueDate: z.string().datetime().optional(),
  assigneeId: z.string().uuid().optional(),
})

export type CreateTaskDTO = z.infer<typeof createTaskSchema>

No hand-written type annotations, no "I'll fix this later" TODO comments, just running code that matches the Zod contract.

About That `:optional` Suffix

You might have expected the optional marker to be ?, like in TypeScript: description?:text. That was the original design, and it still works — but only if you quote the argument, because ? is a shell glob character in bash and zsh. Without quotes, description?:text gets expanded to match any filename in the current directory starting with description and having one character before :text, which is almost never what you want and produces cryptic "no matches found" errors.

The :optional suffix is the shell-safe alternative. It works in any shell, without quoting, and it's unambiguous. You can still use ? if you quote the field ("description:text?" or "description?:text" both work), but :optional is what the docs recommend and what I'd use in scripts.

`kick g` Inside a Module: The `-m` Flag

Sometimes you don't want a whole new module — you want to add a single file to an existing one. The -m flag scopes standalone generators to a module:

kick g controller auth -m users       # → src/modules/users/presentation/auth.controller.ts
kick g service payment -m orders      # → src/modules/orders/domain/services/payment.service.ts
kick g dto create-user -m users       # → src/modules/users/application/dtos/create-user.dto.ts
kick g guard admin -m users           # → src/modules/users/presentation/guards/admin.guard.ts
kick g middleware cache -m products   # → src/modules/products/middleware/cache.middleware.ts

The CLI uses the project pattern (from kick.config.ts) to decide which subfolder inside the module to drop the file into. For the DDD pattern, controllers go to presentation/, services go to domain/services/, DTOs go to application/dtos/, and so on. For the flat REST pattern, everything goes to the module root.

If -m isn't given, standalone generators create files in app-level default directories: src/controllers/, src/services/, src/middleware/, etc.

Override the destination with -o, --out <dir>:

kick g controller health -o src/system
# → src/system/health.controller.ts

`kick g` With Dry Run

Before committing to a generator, you can preview the files it would create:

kick g module user --dry-run

Prints the list of files that would be generated but doesn't write anything. Useful when you're experimenting with generator flags and don't want to clean up afterwards.

`kick rm module`

The inverse of kick g module:

kick rm module user
kick rm module user task project   # delete multiple
kick rm module user --force        # skip confirmation

Deletes the module directory and removes its entry from src/modules/index.ts. Good for when you generated a module with the wrong name or pattern and want to start over.

Package Management: `kick list`, `kick add`

KickJS is a monorepo with 18+ published packages. Finding them and adding them with the right peer dependencies used to mean reading the docs. Now it's two commands.

`kick list`

kick list
# or: kick ls

Prints every available package with its description and peer dependencies:

  Available KickJS packages:

    kickjs           Unified framework: DI, decorators, routing, middleware (+ express)
    vite             Vite plugin: dev server, HMR, module discovery (+ vite)
    swagger          OpenAPI spec + Swagger UI + ReDoc
    graphql          GraphQL resolvers + GraphiQL (+ graphql)
    drizzle          Drizzle ORM adapter + query builder (+ drizzle-orm)
    prisma           Prisma adapter + query builder (+ @prisma/client)
    ws               WebSocket with @WsController decorators (+ socket.io)
    otel             OpenTelemetry tracing + metrics (+ @opentelemetry/api)
    devtools         Development dashboard — routes, DI, metrics, health
    auth             Authentication — JWT, API key, and custom strategies (+ jsonwebtoken)
    mailer           Email — SMTP, Resend, SES, or custom provider (+ nodemailer)
    cron             Cron job scheduling (production-grade with croner) (+ croner)
    queue            Queue adapter (BullMQ/RabbitMQ/Kafka)
    queue:bullmq     Queue with BullMQ + Redis (+ bullmq, ioredis)
    queue:rabbitmq   Queue with RabbitMQ (+ amqplib)
    queue:kafka      Queue with Kafka (+ kafkajs)
    multi-tenant     Tenant resolution middleware
    notifications    Multi-channel notifications — email, Slack, Discord, webhook
    testing          Test utilities and TestModule builder

`kick add`

kick add graphql           # adds @forinda/kickjs-graphql + graphql
kick add drizzle otel      # installs multiple packages at once
kick add queue:bullmq      # installs the queue package + bullmq + ioredis
kick add --list            # same as `kick list`

The important detail: kick add resolves peer dependencies for you. When you run kick add graphql, the CLI installs both @forinda/kickjs-graphql and graphql itself, because the GraphQL package has graphql as a peer. You don't have to read package.json or guess which peer version range to pin.

The package manager is auto-detected from your lockfile — if you have a pnpm-lock.yaml, it uses pnpm; if you have a package-lock.json, npm; and so on. Override with --pm <manager> if needed. Use -D, --dev to install as a dev dependency.

The queue: packages are a special case: they're meta-packages that install the queue abstraction plus a specific backend. queue:bullmq installs @forinda/kickjs-queue, bullmq, and ioredis in one go. That's the pattern to follow if you want "the queue system with a working backend" without thinking about it.

Environment Diagnostics: `kick info`

kick info

Prints your system information and the versions of KickJS packages in the current project:

  KickJS CLI

  System:
    OS:       linux 6.x.x (x64)
    Node:     v20.x.x

  Packages:
    @forinda/kickjs           2.2.4
    @forinda/kickjs-cli       2.2.4
    @forinda/kickjs-swagger   2.2.4

Paste the output into a GitHub issue when reporting a bug. It's the framework's equivalent of npx envinfo.

Inspecting a Running App: `kick inspect`

This one's more niche but genuinely useful when debugging. Start your dev server in one terminal, then in another terminal:

kick inspect
kick inspect --port 4000
kick inspect --watch      # re-inspect on every HMR reload
kick inspect --json       # raw JSON output for scripting

You get a live snapshot of the running application:

  KickJS Inspector — http://localhost:5173

  Routes (12):
    GET     /health
    GET     /api/v1/users
    POST    /api/v1/users
    GET     /api/v1/users/:id
    PUT     /api/v1/users/:id
    DELETE  /api/v1/users/:id
    GET     /api/v1/posts
    POST    /api/v1/posts
    GET     /graphql          [GraphQLAdapter]
    WS      /chat             [WsAdapter]

  Adapters (3):
    GraphQLAdapter     /graphql
    WsAdapter          /chat
    DevToolsAdapter    /_debug

  Middleware (5):
    cors, helmet, csrf, rateLimit, session

  DI Container:
    Services:    8
    Controllers: 4
    Resolvers:   2

This is faster than scrolling through startup logs and works in production too — you can run kick inspect --json > routes.json against a live app and commit the output as documentation.

The --watch flag is great during development. Keep the inspector in a split terminal pane and watch routes appear as you create controllers.

Custom Commands in `kick.config.ts`

Here's the feature that elevates the CLI from a scaffolding tool to a project runner: custom commands defined per-project. Open kick.config.ts at your project root:

import { defineConfig } from '@forinda/kickjs-cli'

export default defineConfig({
  pattern: 'rest',
  modules: {
    dir: 'src/modules',
    repo: 'drizzle',
    pluralize: true,
  },
  commands: [
    {
      name: 'db:migrate',
      description: 'Run Drizzle migrations against the dev database',
      steps: 'npx drizzle-kit migrate',
    },
    {
      name: 'db:seed',
      description: 'Seed the dev database with fixtures',
      steps: 'tsx scripts/seed.ts',
    },
    {
      name: 'db:reset',
      description: 'Drop, recreate, and reseed the dev database',
      steps: [
        'npx drizzle-kit drop',
        'npx drizzle-kit migrate',
        'tsx scripts/seed.ts',
      ],
      aliases: ['db:nuke'],
    },
  ],
})

Once defined, these show up as first-class commands alongside the built-in ones:

kick db:migrate
kick db:seed
kick db:reset     # runs the three steps sequentially
kick db:nuke      # alias for db:reset

Each command can run a single shell command or an array of commands that execute sequentially. The aliases field lets you define shorthand names.

The nice part is that the commands show up in kick --help, so a new developer on the team can run kick --help and immediately see every project-specific workflow — no separate README section to maintain, no Makefile to hunt through.

`kick g config`

If your project didn't have a kick.config.ts (older projects or minimal scaffolds), generate one with:

kick g config
kick g config --force                # overwrite existing
kick g config --modules-dir src/mods # custom modules path
kick g config --repo drizzle         # default repo

Typed Routes: `kick typegen`

This is the feature that makes KickJS handlers feel different from every other TypeScript backend I've worked with.

kick typegen

The typegen command scans your codebase for @Controller classes and their route decorators, reads the Zod schemas attached via @Post('/', { body: schema }), and produces a global KickRoutes namespace with one interface per controller. The result lands in .kickjs/types/routes.ts, and once it's there, your route handlers can reference the types directly:

import { Controller, Post, type Ctx } from '@forinda/kickjs'
import { z } from 'zod'

const createUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
})

@Controller('/users')
export class UserController {
  @Post('/', { body: createUserSchema, name: 'CreateUser' })
  create(ctx: Ctx<KickRoutes.UserController['create']>) {
    // ctx.body.email is inferred as string — from the Zod schema above
    // ctx.params is typed as {} because there are no route params
    // ctx.query is typed as whatever the query parser produces
    ctx.created({ id: '1', ...ctx.body })
  }
}

No manual z.infer<typeof createUserSchema>, no duplicated types between the controller and the service, no drift between what the decorator enforces at runtime and what TypeScript knows at compile time.

Typegen runs automatically on kick dev startup, and it re-runs every time you save a file that includes a controller. You don't run it manually except in three situations:

CI builds — before tsc --noEmit so the types are present when the typechecker runs
Fresh clones — so the first git clone + pnpm install + tsc sequence works
Manual regeneration — when you've changed something major and want to force a rebuild

Similarly, the typegen system produces a KickEnv interface from your src/config/index.ts schema. Once it runs, @Value('DATABASE_URL') becomes type-safe — TypeScript knows the return type is string, and autocompletes the available env keys. Add a new env variable to the schema, save the file, and the new key is immediately typed everywhere.

The One-Liner Shortcuts

Because I use these dozens of times per day, here are the incantations I have muscle memory for:

# Create a new project, fully non-interactive
kick new my-api -t rest -r drizzle --pm pnpm --git --install

# Scaffold a CRUD module with fields
kick g scaffold product \
  name:string price:number stock:int:optional \
  status:enum:draft,active,archived

# Start dev with a custom port
kick dev -p 4000

# Add GraphQL + WebSockets in one shot
kick add graphql ws

# Inspect the running app
kick inspect --watch

# Run a custom db:reset command
kick db:reset

None of these take more than a few seconds to type. All of them replace what would have been minutes of boilerplate.

What Makes a Good Generator

I want to end on the design philosophy, because I think it's what separates good code generators from bad ones, and it's worth understanding before you reach for any CLI tool.

A good generator produces code that you would actually write yourself. When I look at a file the scaffold created, I shouldn't cringe, and I shouldn't need to immediately reorganize the imports or rename the variables. The generator should have made the same choices a senior engineer on your team would make — conventional naming, idiomatic TypeScript, reasonable structure, no magic.

A good generator stays out of the way. Once a file is generated, the generator has no further opinion about it. You can edit the file freely, rename things, restructure it, and the generator won't complain the next time you run it against the same module name (you get an overwrite prompt, which is the correct behavior).

A good generator composes. Running kick g scaffold task doesn't prevent you from then running kick g guard admin -m tasks to add a guard. The generators know about the project pattern, so they cooperate on folder structure. You can iterate your way to a finished feature.

A good generator gives you an escape hatch. Every file the scaffold produces is editable, and you're never locked into the template. The scaffold is a starting point, not a cage. Swap the in-memory repository for a Drizzle one by replacing one file. Rewrite the controller by hand. The rest of the framework doesn't know or care.

The KickJS CLI tries to embody all four of these principles. It's not the most featureful CLI in the ecosystem, and it's not trying to be — but the code it produces is the code I want to see when I review a PR, and that's the bar I hold it to.

Closing Thoughts

If there's one thing I hope you take away from this article, it's this: the boring parts of backend development should be automated. The scaffolding, the wiring, the "create a file, add imports, register in the module" dance — that's not where you add value. The value is in the domain logic, the edge cases, the business rules, the test coverage. A good CLI frees you up to spend time on those things instead of typing the thousandth copy of an Express router.

KickJS isn't trying to hide what's underneath — it's Express 5, it's TypeScript, it's decorators, it's Zod. The CLI doesn't abstract those away; it just makes sure you spend less time typing the glue that holds them together.

Try it out:

npx @forinda/kickjs-cli new my-api
cd my-api
kick dev

Two commands and a cd. That's the pitch.

If you want to go deeper, the full docs cover every flag and every generator. The source is on GitHub — contributions welcome, especially new generator templates. And if this article saved you some typing, a star on the repo is the closest thing to a thank-you I can receive.

Happy scaffolding.

KickJS is an open-source Node.js framework built on Express 5 and TypeScript. The CLI is @forinda/kickjs-cli. Feedback and bug reports go to GitHub issues.

Build a Task Management API with KickJS — Categories, User Assignment, and Typed Everything

Orinda Felix Ochieng — Fri, 10 Apr 2026 22:54:56 +0000

A practical walkthrough of building a production-grade REST API in under an hour using decorators, dependency injection, and code generation.

Why KickJS?

If you've ever stared at an Express project and wished it had NestJS ergonomics without the learning curve, KickJS is the framework I built for exactly that itch. It's Express 5 underneath, so everything you already know still works. On top, it adds the stuff you end up writing anyway: a DI container, decorators, module system, Zod-powered validation, Vite HMR, and generators that scaffold a complete feature in about two seconds.

In this article, we're going to build a real task management API. Not a todo list with three endpoints — a proper backend with users, categories, and tasks that can be assigned to users. By the end, you'll have:

Typed end-to-end request handling (no any, no manual casts)
A clean DDD structure with controllers, services, repositories, and DTOs
User assignment with validation that the user actually exists
Category-based filtering with pagination, sorting, and search — for free
Auto-generated OpenAPI docs at /docs
Live-reloading dev server that preserves database connections

Total scaffolding time: ~5 seconds per module. Total writing time: the 20 minutes you spend reading this article.

Let's build it.

What We're Building

Here's the data model at a glance:

User
  id            uuid
  name          string
  email         string (unique)

Category
  id            uuid
  name          string
  color         string  (hex)
  description   string? (optional)

Task
  id            uuid
  title         string
  description   string? (optional)
  status        enum('todo' | 'in_progress' | 'done')
  priority      enum('low' | 'medium' | 'high')
  dueDate       string? (ISO date)
  categoryId    uuid    (FK to Category)
  assigneeId    uuid?   (FK to User, optional)

Endpoints we want:

Method	Route	Description
`GET`	`/api/v1/users`	List users (paginated, searchable)
`POST`	`/api/v1/users`	Create a user
`GET`	`/api/v1/users/:id`	Get one user
`GET`	`/api/v1/categories`	List categories
`POST`	`/api/v1/categories`	Create a category
`GET`	`/api/v1/tasks`	List tasks (filter by status, category, assignee)
`POST`	`/api/v1/tasks`	Create a task
`GET`	`/api/v1/tasks/:id`	Get one task
`PUT`	`/api/v1/tasks/:id`	Update a task
`PATCH`	`/api/v1/tasks/:id/assign`	Assign (or unassign) a task
`DELETE`	`/api/v1/tasks/:id`	Delete a task

Nothing you haven't seen before. The interesting part is how little code it takes to get there.

Step 1: Scaffold the Project

First, make sure you have Node 20 or newer. Then create the project with a single command:

npx @forinda/kickjs-cli new task-api \
  --template rest \
  --pm pnpm \
  --repo inmemory \
  --git --install

All flags are optional — leaving them off triggers interactive prompts — but passing them keeps the scaffold non-interactive, which is handy for scripts or if you just don't want to answer questions. Let me explain what each flag does:

--template rest — generates a REST API with Swagger and DevTools preconfigured. Other options are graphql, ddd, cqrs, and minimal.
--pm pnpm — uses pnpm. npm and yarn also work.
--repo inmemory — the generated repositories use an in-memory Map. For production you'd pick prisma or drizzle, but for a tutorial this gets us running without a database. (More on swapping repos later.)
--git --install — initializes a git repo and runs pnpm install. The CLI is smart enough to install dependencies before creating the initial commit, so your lockfile ends up in the first commit.

When it finishes, cd in:

cd task-api

Here's the project structure you get:

task-api/
├── src/
│   ├── config/
│   │   └── index.ts              # Env schema (Zod-validated)
│   ├── index.ts                  # Entry point — calls bootstrap()
│   └── modules/
│       ├── hello/                # Sample module (we'll delete this)
│       │   ├── hello.controller.ts
│       │   ├── hello.module.ts
│       │   └── hello.service.ts
│       └── index.ts              # Exports the modules array
├── .env / .env.example
├── AGENTS.md                     # AI agent guide
├── CLAUDE.md                     # AI development guide
├── README.md
├── kick.config.ts                # CLI configuration
├── package.json
├── tsconfig.json
├── vite.config.ts
└── vitest.config.ts

Take a quick look at src/index.ts. This is your whole entry point:

import 'reflect-metadata'
import './config' // registers env schema before bootstrap
import { bootstrap } from '@forinda/kickjs'
import { modules } from './modules'

// Export the app so the Vite plugin can pick it up in dev mode.
// In production, bootstrap() auto-starts the HTTP server.
export const app = await bootstrap({ modules })

That's it. No Express app construction, no manual middleware wiring, no app.listen — bootstrap() handles it. The import './config' is important: it's a side-effect import that registers your Zod env schema with the framework before any service resolves a config value. Keep it there.

Start the dev server to make sure everything works:

pnpm kick dev

You should see Server running on http://localhost:5173 — that's the Vite dev server default port. Hit http://localhost:5173/api/v1/hello and you'll get a cheerful greeting back. (If you want a different port, pass -p 3000 to kick dev or set PORT=3000 in your .env.) Delete the hello module — we'll replace it with real code.

pnpm kick rm module hello --force

The rm command deletes the module directory and un-registers it from src/modules/index.ts. The CLI cleans up after itself.

Step 2: Generate the User Module

Here's where KickJS starts earning its keep. Instead of hand-writing a controller, service, repository, DTOs, entities, and use-cases, you describe the fields and let the generator do it:

pnpm kick g scaffold user \
  name:string \
  email:email

That's one command. It creates 16 files across the DDD layers:

src/modules/users/
├── index.ts                                          # Module wiring
├── constants.ts                                      # Query config
├── presentation/
│   └── user.controller.ts                            # Full CRUD controller
├── application/
│   ├── dtos/
│   │   ├── create-user.dto.ts                        # Zod schema for POST
│   │   ├── update-user.dto.ts                        # Zod schema for PUT
│   │   └── user-response.dto.ts                      # Response shape
│   └── use-cases/
│       ├── create-user.use-case.ts
│       ├── get-user.use-case.ts
│       ├── list-users.use-case.ts
│       ├── update-user.use-case.ts
│       └── delete-user.use-case.ts
├── domain/
│   ├── entities/user.entity.ts                       # Domain entity
│   ├── value-objects/user-id.vo.ts                   # Typed ID
│   ├── repositories/user.repository.ts               # Interface + DI token
│   └── services/user-domain.service.ts               # Domain logic
└── infrastructure/
    └── repositories/in-memory-user.repository.ts     # Working implementation

Let me show you what the generated DTO looks like — this is the one place where the field definitions you gave the CLI actually show up:

// src/modules/users/application/dtos/create-user.dto.ts
import { z } from 'zod'

export const createUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
})

export type CreateUserDTO = z.infer<typeof createUserSchema>

The email:email field type tells the scaffold generator to use z.string().email() instead of the plain z.string() it would use for a string field. There are twelve built-in types — string, text, number, int, float, boolean, date, email, url, uuid, json, and enum:a,b,c — which cover the vast majority of what you need for HTTP APIs.

The generated controller is worth showing in full because it demonstrates something I think KickJS does really well:

// src/modules/users/presentation/user.controller.ts
import {
  Controller, Get, Post, Put, Delete,
  Autowired, ApiQueryParams, type Ctx,
} from '@forinda/kickjs'
import { ApiTags } from '@forinda/kickjs-swagger'
import { CreateUserUseCase } from '../application/use-cases/create-user.use-case'
import { GetUserUseCase } from '../application/use-cases/get-user.use-case'
import { ListUsersUseCase } from '../application/use-cases/list-users.use-case'
import { UpdateUserUseCase } from '../application/use-cases/update-user.use-case'
import { DeleteUserUseCase } from '../application/use-cases/delete-user.use-case'
import { createUserSchema } from '../application/dtos/create-user.dto'
import { updateUserSchema } from '../application/dtos/update-user.dto'
import { USER_QUERY_CONFIG } from '../constants'

@Controller()
export class UserController {
  @Autowired() private readonly createUserUseCase!: CreateUserUseCase
  @Autowired() private readonly getUserUseCase!: GetUserUseCase
  @Autowired() private readonly listUsersUseCase!: ListUsersUseCase
  @Autowired() private readonly updateUserUseCase!: UpdateUserUseCase
  @Autowired() private readonly deleteUserUseCase!: DeleteUserUseCase

  @Get('/')
  @ApiTags('User')
  @ApiQueryParams(USER_QUERY_CONFIG)
  async list(ctx: Ctx<KickRoutes.UserController['list']>) {
    return ctx.paginate(
      (parsed) => this.listUsersUseCase.execute(parsed),
      USER_QUERY_CONFIG,
    )
  }

  @Get('/:id')
  @ApiTags('User')
  async getById(ctx: Ctx<KickRoutes.UserController['getById']>) {
    const result = await this.getUserUseCase.execute(ctx.params.id)
    if (!result) return ctx.notFound('User not found')
    ctx.json(result)
  }

  @Post('/', { body: createUserSchema, name: 'CreateUser' })
  @ApiTags('User')
  async create(ctx: Ctx<KickRoutes.UserController['create']>) {
    const result = await this.createUserUseCase.execute(ctx.body)
    ctx.created(result)
  }

  @Put('/:id', { body: updateUserSchema, name: 'UpdateUser' })
  @ApiTags('User')
  async update(ctx: Ctx<KickRoutes.UserController['update']>) {
    const result = await this.updateUserUseCase.execute(ctx.params.id, ctx.body)
    ctx.json(result)
  }

  @Delete('/:id')
  @ApiTags('User')
  async remove(ctx: Ctx<KickRoutes.UserController['remove']>) {
    await this.deleteUserUseCase.execute(ctx.params.id)
    ctx.noContent()
  }
}

Notice the ctx: Ctx<KickRoutes.UserController['create']> signature. That type isn't written by hand — it's generated by kick typegen, which runs automatically when you start the dev server. It scans your controllers and produces a global KickRoutes namespace with one interface per controller, where each method has its own typed params, body, query, and response.

The upshot: inside create, when you type ctx.body., your editor autocompletes name and email because they came from the createUserSchema. If you add a field to the Zod schema, the type updates on the next save. If you rename createUserSchema to something else, TypeScript tells you where to fix it. No manual z.infer<>, no duplicated types between the DTO and the handler.

The Query Parsing You Didn't Write

Look at the list method:

@Get('/')
@ApiQueryParams(USER_QUERY_CONFIG)
async list(ctx: Ctx<KickRoutes.UserController['list']>) {
  return ctx.paginate(
    (parsed) => this.listUsersUseCase.execute(parsed),
    USER_QUERY_CONFIG,
  )
}

That ctx.paginate() call gives you pagination, filtering, sorting, and search — all from the query string — with zero additional code. The USER_QUERY_CONFIG constant was also generated:

// src/modules/users/constants.ts
import type { ApiQueryParamsConfig } from '@forinda/kickjs'

export const USER_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['name', 'email'],
  sortable: ['name', 'email', 'createdAt', 'updatedAt'],
  searchable: ['name', 'email'],
}

With this in place, a client can hit:

GET /api/v1/users?filter[name]=alice&sort=-createdAt&page=2&limit=10&search=example.com

...and get back a paginated response with the filters applied, results sorted, and text search hitting any field you marked as searchable. The response has the shape:

{
  "data": [/* ... */],
  "meta": {
    "page": 2,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

You didn't write any of that. It's all in ctx.paginate().

Step 3: Generate the Category Module

Same deal, different fields:

pnpm kick g scaffold category \
  name:string \
  color:string \
  description:text:optional

Two things worth noting here. First, description:text:optional uses the :optional suffix to mark the field as optional. You might be wondering why not description?:text, since ? is the TypeScript convention. The answer is shell glob expansion: ? is a single-character wildcard in bash and zsh, so description?:text without quotes would get expanded to match files in the current directory before the CLI ever sees it. The :optional suffix avoids that entirely and works in any shell without escaping.

Second, the text type is just an alias for string that hints at longer content. It's still z.string() and still a string in TypeScript — the distinction only matters if your repository uses it to pick a column type (Drizzle/Prisma generators use text for longer columns).

The generated DTO:

// src/modules/categories/application/dtos/create-category.dto.ts
import { z } from 'zod'

export const createCategorySchema = z.object({
  name: z.string(),
  color: z.string(),
  description: z.string().optional(),
})

export type CreateCategoryDTO = z.infer<typeof createCategorySchema>

No surprises. Run your dev server again (if you stopped it), and you'll see routes for /api/v1/users and /api/v1/categories already live.

Step 4: The Task Module — Where It Gets Interesting

Tasks have two foreign keys (category and assignee), and the scaffold generator can't enforce foreign-key validation for us — that's domain logic. So we'll scaffold the basic shape and then customize it.

pnpm kick g scaffold task \
  title:string \
  description:text:optional \
  status:enum:todo,in_progress,done \
  priority:enum:low,medium,high \
  dueDate:date:optional \
  categoryId:uuid \
  assigneeId:uuid:optional

The scaffold generator handles enum fields, optional fields, and UUID fields out of the box. Here's what the create DTO looks like:

// src/modules/tasks/application/dtos/create-task.dto.ts
import { z } from 'zod'

export const createTaskSchema = z.object({
  title: z.string(),
  description: z.string().optional(),
  status: z.enum(['todo', 'in_progress', 'done']),
  priority: z.enum(['low', 'medium', 'high']),
  dueDate: z.string().datetime().optional(),
  categoryId: z.string().uuid(),
  assigneeId: z.string().uuid().optional(),
})

export type CreateTaskDTO = z.infer<typeof createTaskSchema>

Now we need to teach the task service to validate foreign keys. This is where dependency injection starts paying off. The generated CreateTaskUseCase currently looks like this:

// src/modules/tasks/application/use-cases/create-task.use-case.ts
import { Service, Inject } from '@forinda/kickjs'
import { TASK_REPOSITORY, type ITaskRepository } from '../../domain/repositories/task.repository'
import type { CreateTaskDTO } from '../dtos/create-task.dto'

@Service()
export class CreateTaskUseCase {
  constructor(@Inject(TASK_REPOSITORY) private repo: ITaskRepository) {}

  async execute(dto: CreateTaskDTO) {
    return this.repo.create(dto)
  }
}

We want to check that the categoryId exists, and — if assigneeId is provided — that the user exists too. Update the use case:

import { Service, Inject, HttpException } from '@forinda/kickjs'
import { TASK_REPOSITORY, type ITaskRepository } from '../../domain/repositories/task.repository'
import { USER_REPOSITORY, type IUserRepository } from '../../../users/domain/repositories/user.repository'
import { CATEGORY_REPOSITORY, type ICategoryRepository } from '../../../categories/domain/repositories/category.repository'
import type { CreateTaskDTO } from '../dtos/create-task.dto'

@Service()
export class CreateTaskUseCase {
  constructor(
    @Inject(TASK_REPOSITORY) private readonly tasks: ITaskRepository,
    @Inject(USER_REPOSITORY) private readonly users: IUserRepository,
    @Inject(CATEGORY_REPOSITORY) private readonly categories: ICategoryRepository,
  ) {}

  async execute(dto: CreateTaskDTO) {
    // Verify the category exists
    const category = await this.categories.findById(dto.categoryId)
    if (!category) {
      throw new HttpException(400, `Category ${dto.categoryId} does not exist`)
    }

    // Verify the assignee exists, if one was provided
    if (dto.assigneeId) {
      const user = await this.users.findById(dto.assigneeId)
      if (!user) {
        throw new HttpException(400, `User ${dto.assigneeId} does not exist`)
      }
    }

    return this.tasks.create(dto)
  }
}

A few things are happening here that I want to call out:

createToken<T> — the repository tokens (USER_REPOSITORY, CATEGORY_REPOSITORY, TASK_REPOSITORY) are typed DI tokens, not plain symbols. When you @Inject(USER_REPOSITORY), TypeScript knows the result is IUserRepository — no casts, no generic parameter needed.
No manual wiring — you never instantiated UserRepository, CategoryRepository, or TaskRepository. The DI container resolved them automatically through the register() methods in each module's index.ts. This is one of the nicer payoffs of the module pattern.
HttpException — throwing this inside a use case gets caught by the framework's error handler and returned as a proper JSON error response with the status code you gave it. You don't need try/catch blocks in the controller.

Step 5: The Assignment Endpoint

Creating and updating tasks are already handled by the scaffold, but assignment is special enough that I want it on its own endpoint. We'll add a PATCH /tasks/:id/assign route that takes { assigneeId: string | null } and either assigns or unassigns.

First, a DTO:

// src/modules/tasks/application/dtos/assign-task.dto.ts
import { z } from 'zod'

export const assignTaskSchema = z.object({
  assigneeId: z.string().uuid().nullable(),
})

export type AssignTaskDTO = z.infer<typeof assignTaskSchema>

Notice the .nullable() — passing null explicitly is how the client says "unassign this task", which is different from omitting the field entirely.

Then a use case:

// src/modules/tasks/application/use-cases/assign-task.use-case.ts
import { Service, Inject, HttpException } from '@forinda/kickjs'
import { TASK_REPOSITORY, type ITaskRepository } from '../../domain/repositories/task.repository'
import { USER_REPOSITORY, type IUserRepository } from '../../../users/domain/repositories/user.repository'
import type { AssignTaskDTO } from '../dtos/assign-task.dto'

@Service()
export class AssignTaskUseCase {
  constructor(
    @Inject(TASK_REPOSITORY) private readonly tasks: ITaskRepository,
    @Inject(USER_REPOSITORY) private readonly users: IUserRepository,
  ) {}

  async execute(taskId: string, dto: AssignTaskDTO) {
    const task = await this.tasks.findById(taskId)
    if (!task) {
      throw new HttpException(404, `Task ${taskId} not found`)
    }

    // null = unassign
    if (dto.assigneeId === null) {
      return this.tasks.update(taskId, { assigneeId: null } as any)
    }

    // Otherwise, verify the user exists
    const user = await this.users.findById(dto.assigneeId)
    if (!user) {
      throw new HttpException(400, `User ${dto.assigneeId} does not exist`)
    }

    return this.tasks.update(taskId, { assigneeId: dto.assigneeId } as any)
  }
}

And finally, wire it into the task controller. Add an import, an @Autowired property, and a new @Patch method:

// src/modules/tasks/presentation/task.controller.ts
import { Controller, Get, Post, Put, Patch, Delete, Autowired, type Ctx } from '@forinda/kickjs'
// ...existing imports...
import { AssignTaskUseCase } from '../application/use-cases/assign-task.use-case'
import { assignTaskSchema } from '../application/dtos/assign-task.dto'

@Controller()
export class TaskController {
  // ...existing @Autowired properties...
  @Autowired() private readonly assignTaskUseCase!: AssignTaskUseCase

  // ...existing methods...

  @Patch('/:id/assign', { body: assignTaskSchema, name: 'AssignTask' })
  @ApiTags('Task')
  async assign(ctx: Ctx<KickRoutes.TaskController['assign']>) {
    const result = await this.assignTaskUseCase.execute(ctx.params.id, ctx.body)
    ctx.json(result)
  }
}

That's the entire assignment feature. 30 lines of code for validated FK checks, typed payloads, and proper error responses. The scaffold did the boring 90%.

Step 6: Filtering Tasks by Category and Assignee

Tasks have a categoryId and assigneeId, and we want clients to be able to filter tasks by either. Remember that USER_QUERY_CONFIG object the scaffold generated? It has the same structure for tasks, and it already knows about every field on the task entity. Open src/modules/tasks/constants.ts:

import type { ApiQueryParamsConfig } from '@forinda/kickjs'

export const TASK_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['title', 'description', 'status', 'priority', 'dueDate', 'categoryId', 'assigneeId'],
  sortable: ['title', 'status', 'priority', 'dueDate', 'createdAt', 'updatedAt'],
  searchable: ['title', 'description'],
}

Done. Clients can now hit:

GET /api/v1/tasks?filter[status]=in_progress&filter[assigneeId]=<uuid>&sort=-priority

...and get all in-progress tasks assigned to that user, sorted by priority descending. The in-memory repository already knows how to apply these filters because it implements findPaginated(parsed: ParsedQuery) and the scaffold gave it a working implementation. If you later switch to Prisma or Drizzle, the query config transfers unchanged — the adapters translate ParsedQuery into database queries automatically.

Step 7: Seeding Some Data

The in-memory repositories reset on every restart, which is great for testing but annoying for manual exploration. Let's add a tiny seeding helper that runs once at startup. Create src/seed.ts:

import { Container } from '@forinda/kickjs'
import { CreateUserUseCase } from './modules/users/application/use-cases/create-user.use-case'
import { CreateCategoryUseCase } from './modules/categories/application/use-cases/create-category.use-case'
import { CreateTaskUseCase } from './modules/tasks/application/use-cases/create-task.use-case'

export async function seed(): Promise<void> {
  const container = Container.getInstance()
  const createUser = container.resolve(CreateUserUseCase)
  const createCategory = container.resolve(CreateCategoryUseCase)
  const createTask = container.resolve(CreateTaskUseCase)

  const alice = await createUser.execute({ name: 'Alice', email: 'alice@example.com' })
  const bob = await createUser.execute({ name: 'Bob', email: 'bob@example.com' })

  const work = await createCategory.execute({
    name: 'Work',
    color: '#0ea5e9',
    description: 'Day job tasks',
  })
  const personal = await createCategory.execute({
    name: 'Personal',
    color: '#f59e0b',
  })

  await createTask.execute({
    title: 'Write the KickJS blog post',
    status: 'in_progress',
    priority: 'high',
    categoryId: work.id,
    assigneeId: alice.id,
  } as any)

  await createTask.execute({
    title: 'Buy groceries',
    status: 'todo',
    priority: 'low',
    categoryId: personal.id,
  } as any)
}

Then call it from src/index.ts, but only in development:

import 'reflect-metadata'
import './config'
import { bootstrap } from '@forinda/kickjs'
import { modules } from './modules'
import { seed } from './seed'

export const app = await bootstrap({ modules })

if (process.env.NODE_ENV !== 'production') {
  await seed()
}

Restart the server and hit GET /api/v1/tasks. You'll see the two seeded tasks. Hit GET /api/v1/tasks?filter[assigneeId]=<alice-id> and you'll see just Alice's task.

Step 8: Adding Swagger Docs (You Already Have Them)

The rest template installs @forinda/kickjs-swagger and pre-registers the SwaggerAdapter for you. If you open http://localhost:5173/docs in your browser, you'll see a fully populated Swagger UI with every endpoint grouped by the @ApiTags decorator on the controllers.

If you want to customize the metadata, open src/index.ts (or wherever the adapter is registered) and update the constructor options:

import { SwaggerAdapter } from '@forinda/kickjs-swagger'

export const app = await bootstrap({
  modules,
  adapters: [
    new SwaggerAdapter({
      info: {
        title: 'Task Management API',
        version: '1.0.0',
        description: 'REST API for managing tasks, categories, and user assignments',
      },
    }),
  ],
})

The schemas come directly from your Zod DTOs — no manual JSDoc annotations, no separate OpenAPI YAML file to keep in sync. Add a field to createTaskSchema, restart, and Swagger reflects it immediately.

Step 9: Writing a Test

KickJS ships with a testing helper that spins up a real app without needing an HTTP port. Here's a test for the assignment endpoint:

// src/modules/tasks/__tests__/assign-task.test.ts
import 'reflect-metadata'
import { describe, it, expect, beforeEach } from 'vitest'
import request from 'supertest'
import { Container } from '@forinda/kickjs'
import { createTestApp } from '@forinda/kickjs-testing'
import { modules } from '../../..//modules'

describe('PATCH /tasks/:id/assign', () => {
  beforeEach(() => Container.reset())

  it('assigns a task to an existing user', async () => {
    const { expressApp } = await createTestApp({ modules })

    // Create a user
    const userRes = await request(expressApp)
      .post('/api/v1/users')
      .send({ name: 'Alice', email: 'alice@example.com' })
    const user = userRes.body

    // Create a category
    const catRes = await request(expressApp)
      .post('/api/v1/categories')
      .send({ name: 'Work', color: '#0ea5e9' })
    const category = catRes.body

    // Create an unassigned task
    const taskRes = await request(expressApp)
      .post('/api/v1/tasks')
      .send({
        title: 'Write tests',
        status: 'todo',
        priority: 'high',
        categoryId: category.id,
      })
    const task = taskRes.body

    // Assign it
    const assignRes = await request(expressApp)
      .patch(`/api/v1/tasks/${task.id}/assign`)
      .send({ assigneeId: user.id })

    expect(assignRes.status).toBe(200)
    expect(assignRes.body.assigneeId).toBe(user.id)
  })

  it('rejects assignment to a non-existent user', async () => {
    const { expressApp } = await createTestApp({ modules })

    const catRes = await request(expressApp)
      .post('/api/v1/categories')
      .send({ name: 'Work', color: '#0ea5e9' })

    const taskRes = await request(expressApp)
      .post('/api/v1/tasks')
      .send({
        title: 'Write tests',
        status: 'todo',
        priority: 'high',
        categoryId: catRes.body.id,
      })

    const res = await request(expressApp)
      .patch(`/api/v1/tasks/${taskRes.body.id}/assign`)
      .send({ assigneeId: '00000000-0000-0000-0000-000000000000' })

    expect(res.status).toBe(400)
    expect(res.body.message).toMatch(/does not exist/)
  })
})

The Container.reset() call in beforeEach is important: KickJS decorators register classes on a global DI container at import time, so tests need to wipe it between runs to avoid leaking state. If you forget it, you'll get mysterious "already registered" errors when modules are re-imported.

Run the tests:

pnpm test

Both should pass. Green, green, ship it.

Swapping In a Real Database

The in-memory repository was perfect for getting the app running without configuration, but you probably want actual persistence. Switching is a two-step process, and — importantly — none of your controller, service, or use-case code has to change.

Option 1: Prisma

pnpm kick add prisma
npx prisma init
# Edit prisma/schema.prisma to define User, Category, Task models
npx prisma migrate dev --name init

Then regenerate the modules with --repo prisma:

pnpm kick g module user --repo prisma --force
pnpm kick g module category --repo prisma --force
pnpm kick g module task --repo prisma --force

(Or, more surgically, just replace the in-memory-*.repository.ts files with Prisma equivalents — the CLI has templates for both.)

Option 2: Drizzle

pnpm kick add drizzle

Then the same --repo drizzle flag on the generator. The repository interface stays the same, the implementation changes. Your use cases don't know or care which storage backend is in use.

What You Built

Let's take stock of what's running right now:

3 modules (users, categories, tasks) with full CRUD
Foreign-key validation between tasks and both users and categories
A dedicated assignment endpoint with null-aware unassignment
Filtering, sorting, pagination, and text search on every list endpoint — for free
Auto-generated OpenAPI docs at /docs
Typed request/response contracts, end-to-end
Vitest test suite with createTestApp integration helpers
HMR-enabled dev server that preserves in-memory state across file changes

Total lines of handwritten code, not counting what the generators produced: around 100. The generators produced another 1,500 lines or so, but that's code you'd write yourself anyway — the kind of structural boilerplate that every well-organized backend ends up with. The point isn't that the generators make the code disappear; the point is that they make the code appear without you having to type it, and they produce the same shape every time, so your whole team reads it the same way.

Where to Go Next

A few directions to take this further, depending on where your project needs to grow:

Authentication. Run pnpm kick add auth to install the JWT/OAuth package. Add @Roles('admin') and @Public() decorators to your controllers — auth is middleware-based and composes cleanly with existing routes.
Background jobs. If task assignments should trigger notifications, add pnpm kick add queue:bullmq and define a @Job processor. The queue adapter handles Redis wiring, retries, and dead-letter queues.
WebSockets. Run pnpm kick add ws for live task updates. The WS adapter shares the same DI container as HTTP, so your services stay the same — you just add a @WsController.
Multi-tenancy. Add pnpm kick add multi-tenant if tasks should be scoped per organization. Tenant resolution becomes request middleware, and your repositories automatically filter.

Each of these is one command and a few imports away. The framework is built to let you add capabilities incrementally, not pick them all at the start.

Closing Thoughts

I wrote KickJS because I kept reaching for the same Express patterns — DI containers, decorators, Zod validation, code generators — and stitching them together by hand in every new project. The surprise for me was how much better the developer experience gets when those pieces are designed to work together from day one. The scaffold generator doesn't just create files; it creates the right files, with the right imports, wired up to the right DI tokens, using the right naming conventions. The type system flows from Zod schemas through to controller handlers without you lifting a finger. And because everything is still Express underneath, you never get stuck when you need to drop down to raw middleware.

If you built along with this article, you now have a working task management API with user assignment. If you want to see more KickJS in action, check out the full documentation or the example apps in the monorepo — there's a Jira clone, a GraphQL API, a microservice template, and more.

Happy building.

KickJS is an open-source framework. Find it on GitHub and npm. If it saves you time, a star means a lot.

KickJS: Decorator-Driven APIs on Express 5 — NestJS Ergonomics, Zero Overhead

Orinda Felix Ochieng — Thu, 26 Mar 2026 15:57:16 +0000

I built a Node.js framework. Yes, another one. But hear me out.

TL;DR

KickJS gives you NestJS-style decorators on top of Express 5 without RxJS, without Angular-style modules, and without a 30-minute setup. One command scaffolds a full DDD module with working tests.

npx @forinda/kickjs-cli new my-api
cd my-api && pnpm dev
# API running at localhost:3000 with Swagger UI at /docs

GitHub: github.com/forinda/kick-js

Why Though

Every new API project, I'd copy-paste the same setup:

Express + TypeScript boilerplate
Some DI solution (Inversify, tsyringe, or hand-rolled)
Zod schemas for validation
Swagger generation from... somewhere
Pagination, filtering, sorting helpers
Error handling middleware
Test setup with supertest

That's 500+ lines before writing any business logic. NestJS solves this, but I didn't want to learn Angular patterns for a REST API.

Show Me the Code

A complete CRUD controller:

import { Controller, Get, Post, Put, Delete, Autowired } from '@forinda/kickjs-core'
import { RequestContext } from '@forinda/kickjs-http'

@Controller()
class UserController {
  @Autowired() private createUser!: CreateUserUseCase
  @Autowired() private listUsers!: ListUsersUseCase

  @Get('/')
  async list(ctx: RequestContext) {
    return ctx.paginate(
      (query) => this.listUsers.execute(query),
      { filterable: ['email', 'role'], sortable: ['name', 'createdAt'] },
    )
  }

  @Post('/', { body: createUserSchema })
  async create(ctx: RequestContext) {
    // ctx.body is validated by Zod, typed automatically
    const user = await this.createUser.execute(ctx.body)
    ctx.created(user)
  }
}

What happens here:

@Controller() registers in the DI container
@Autowired() injects dependencies (property injection)
@Get('/') defines the route
{ body: createUserSchema } validates with Zod, returns 422 on failure
ctx.paginate() handles query parsing, filtering, sorting, pagination
The same Zod schema generates the OpenAPI spec for Swagger

Zero configuration files for any of this.

The CLI Is the Star

kick g module product

Generates 18 files:

src/modules/products/
├── presentation/
│   └── product.controller.ts
├── application/
│   ├── use-cases/
│   │   ├── create-product.use-case.ts
│   │   ├── get-product.use-case.ts
│   │   ├── list-products.use-case.ts
│   │   ├── update-product.use-case.ts
│   │   └── delete-product.use-case.ts
│   └── dtos/
│       ├── create-product.dto.ts
│       ├── update-product.dto.ts
│       └── product-response.dto.ts
├── domain/
│   ├── repositories/product.repository.ts
│   ├── services/product-domain.service.ts
│   └── entities/product.entity.ts
├── infrastructure/repositories/
│   ├── drizzle-product.repository.ts
│   └── in-memory-product.repository.ts  ← test stub!
├── __tests__/
│   ├── product.controller.test.ts
│   └── product.repository.test.ts
└── index.ts

The key: it generates both the ORM repository and an in-memory test stub. Tests pass immediately — no database needed.

kick g module product --repo drizzle
npx vitest run  # ✅ all tests pass

Supports DDD, CQRS, REST, and minimal patterns. Works with Drizzle, Prisma, Mongoose, or custom ORMs.

Built-in Middleware (No Extra Installs)

import {
  helmet, cors, requestId, requestLogger,
  csrf, rateLimit,
} from '@forinda/kickjs-http'

bootstrap({
  modules: [UserModule, ProductModule],
  middleware: [
    helmet(),           // Security headers
    cors({ origin: ['https://myapp.com'] }),
    requestId(),        // X-Request-Id
    requestLogger(),    // Pino: method, URL, status, duration
    csrf(),             // Double-submit cookie
    rateLimit(),        // Sliding window
    express.json(),
  ],
})

Everything is optional. No middleware runs unless you declare it.

Vite 8 Powers Everything

No webpack. No tsup. No esbuild config. One tool:

What	How
Dev server	`kick dev` — Vite Environment Runner, HMR in ~200ms
Production build	`kick build` — Vite library mode
Tests	Vitest 4 + SWC for decorator support
Package builds	All 19 packages built with `vite build`

HMR preserves database connections and port bindings. Save a file, Express handler swaps instantly. No restart, no reconnect.

836+ Real Tests

Not expect(true).toBe(true) stubs. Real integration tests:

import { createTestApp } from '@forinda/kickjs-testing'
import request from 'supertest'

it('GET /api/v1/users returns paginated list', async () => {
  const { expressApp } = await createTestApp({
    modules: [UserModule],
  })

  const res = await request(expressApp)
    .get('/api/v1/users')
    .expect(200)

  expect(res.body.data).toHaveLength(2)
  expect(res.body.total).toBe(2)
})

Auth middleware tests:

it('rejects expired tokens', async () => {
  const token = jwt.sign({ sub: 'u1' }, SECRET, { expiresIn: '-1s' })

  await request(expressApp)
    .get('/api/v1/protected/me')
    .set('Authorization', `Bearer ${token}`)
    .expect(401)
})

10 example apps including 4 full task management APIs (Drizzle, Prisma, Mongoose) with 100+ tests each.

The 19 Packages

Package	What
`core`	DI container, 20+ decorators, Pino logger
`http`	Express 5 app, RequestContext, all middleware
`config`	Zod env validation, `@Value` decorator
`swagger`	Auto OpenAPI from decorators + Zod
`cli`	Scaffolding, generators, custom commands
`testing`	`createTestApp`, `createTestModule`
`auth`	JWT, API key, OAuth strategies
`prisma`	Prisma 5/6/7 adapter
`drizzle`	Drizzle query adapter
`ws`	WebSocket with `@WsController`
`graphql`	`@Resolver`, `@Query`, `@Mutation`
`queue`	BullMQ, RabbitMQ, Kafka
`cron`	`@Cron('0 * * * *')` scheduling
`mailer`	SMTP, Resend, SES
`otel`	OpenTelemetry tracing + metrics
`devtools`	Debug dashboard at `/_debug`
`multi-tenant`	Header/subdomain/path resolution
`notifications`	Email, Slack, Discord, webhook

All lockstep versioned. Install what you need.

What's Coming

Open issues on the project board:

Graceful request draining on shutdown
Kubernetes readiness/liveness probes
Circuit breaker for external services
Request-scoped DI for multi-tenant apps
Auto-wired OpenTelemetry trace propagation
Runtime compatibility: CI on Node 20/22/24 + Bun/Deno smoke tests

Get Started

npx @forinda/kickjs-cli new my-api
cd my-api && pnpm dev

Visit localhost:3000/docs for Swagger UI.

forinda / kick-js

A declarative progressive backend framework

KickJS

A production-grade, decorator-driven Node.js framework built on Express 5 and TypeScript.

KickJS gives you the DX of NestJS — decorators, dependency injection, module system, code generators — without the weight. No RxJS, no class-transformer, no class-validator. Just TypeScript, Zod, and decorators.

Highlights

Custom DI container — constructor and property injection, no external dependency
Decorator-driven — @Controller, @Get, @Post, @Service, @Autowired, @Middleware
Zod-native validation — schemas double as OpenAPI documentation
Vite HMR — zero-downtime hot reload in development, preserves DB/Redis/Socket connections
DDD generators — kick g module users scaffolds entity, repository, service, use-cases, DTOs, controller
Auto OpenAPI — Swagger UI and ReDoc generated from your decorators and Zod schemas
Pluggable — adapters for database, auth, cache, swagger; schema parsers for Zod/Yup/Joi; query builders for Drizzle/Prisma/Sequelize
Extensible CLI — register project-specific commands in kick.config.ts
ESM + TypeScript strict — modern stack, tree-shakeable packages

Install the CLI

…

View on GitHub

Star it, file issues, send PRs. The project board has tagged issues for all skill levels.

Docs: forinda.github.io/kick-js

Building a Jira Clone with KickJS and Prisma: Lessons from Supporting Prisma 5, 6, and 7

Orinda Felix Ochieng — Wed, 25 Mar 2026 14:36:27 +0000

How we built a decorator-driven Node.js framework adapter for Prisma ORM, what worked, and what didn't.

We recently shipped Prisma support for KickJS, our decorator-driven Node.js framework built on Express 5 and TypeScript. The goal was to make kick g module --repo prisma generate a fully working DDD module with Prisma repositories — no manual wiring needed.

Along the way, we built a full Jira-style project management API as a reference app, migrated it across Prisma 5/6 and Prisma 7, and ran into some interesting type safety challenges. Here's what we learned.

What We Built

The @forinda/kickjs-prisma adapter provides:

PrismaAdapter — lifecycle adapter that registers PrismaClient in the DI container
PrismaQueryAdapter — translates parsed query strings into Prisma findMany arguments
PrismaModelDelegate — typed interface for model CRUD operations (more on this below)
CLI integration — kick g module users --repo prisma generates a complete DDD module with working Prisma repositories

The reference app (jira-prisma-api) is a 14-module Jira clone with auth, workspaces, projects, tasks, labels, comments, attachments, channels, messages, notifications, activities, and stats — all backed by Prisma + PostgreSQL.

The Adapter: Simple by Design

The adapter itself is intentionally thin:

export class PrismaAdapter implements AppAdapter {
  name = 'PrismaAdapter'
  private client: any

  constructor(private options: PrismaAdapterOptions) {
    this.client = options.client
  }

  beforeStart(_app: any, container: Container): void {
    // Set up logging (Prisma 5/6 vs 7+ detection)
    if (this.options.logging) {
      if (typeof this.client.$on === 'function') {
        // Prisma 5/6: event-based logging
        this.client.$on('query', (event: any) => {
          log.debug(`Query: ${event.query} — ${event.duration}ms`)
        })
      } else if (typeof this.client.$extends === 'function') {
        // Prisma 7+: $on removed, use Client Extensions
        this.client = this.client.$extends({
          query: {
            $allOperations({ operation, model, args, query }: any) {
              const start = performance.now()
              return query(args).then((result: any) => {
                log.debug(`${model}.${operation} — ${Math.round(performance.now() - start)}ms`)
                return result
              })
            },
          },
        })
      }
    }

    container.registerFactory(PRISMA_CLIENT, () => this.client, Scope.SINGLETON)
  }

  async shutdown(): Promise<void> {
    if (typeof this.client.$disconnect === 'function') {
      await this.client.$disconnect()
    }
  }
}

Why client: any? Prisma's PrismaClient type is generated per-project — it includes your specific models, enums, and relations. The adapter can't import a concrete type without coupling to a specific schema. Using any keeps it version-agnostic across Prisma 5, 6, and 7.

Shortcoming #1: This means the adapter has zero compile-time knowledge of which models exist. You won't get a type error if you pass a misconfigured client. We considered using generics (PrismaAdapter<T extends PrismaClient>), but that would require the adapter package to depend on your specific generated client — defeating the purpose of a reusable package.

The Type Safety Problem

When we built the CLI template for kick g module --repo prisma, we hit a fundamental tension:

The template generates code at scaffold time, but the Prisma schema doesn't exist yet (or the model hasn't been added).

Our first attempt looked like this:

// Generated by: kick g module user --repo prisma
@Repository()
export class PrismaUserRepository {
  @Inject(PRISMA_CLIENT) private prisma!: PrismaClient

  async findById(id: string) {
    return (this.prisma.user as any).findUnique({ where: { id } })
    //     ^^^^^^^^^^^^^^^^^^^^
    //     as any because 'user' model may not exist on PrismaClient yet
  }
}

Every single Prisma call needed as any because:

The generated PrismaClient type only includes models defined in your schema
The CLI template can't know which models will exist when you run it
TypeScript can't verify this.prisma.user without the generated types

Shortcoming #2: We had as any on every model accessor call — 6+ casts per repository file. For a framework that emphasizes TypeScript-first development, this was embarrassing.

The PrismaModelDelegate Solution

We introduced PrismaModelDelegate — a typed interface that describes the common CRUD operations every Prisma model delegate supports:

export interface PrismaModelDelegate {
  findUnique(args: { where: Record<string, unknown>; include?: Record<string, unknown> }): Promise<unknown>
  findFirst?(args?: Record<string, unknown>): Promise<unknown>
  findMany(args?: Record<string, unknown>): Promise<unknown[]>
  create(args: { data: Record<string, unknown> }): Promise<unknown>
  update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<unknown>
  delete(args: { where: Record<string, unknown> }): Promise<unknown>
  deleteMany(args?: { where?: Record<string, unknown> }): Promise<{ count: number }>
  count(args?: { where?: Record<string, unknown> }): Promise<number>
}

Now the generated code type-narrows the injected client to just the model it needs:

@Repository()
export class PrismaUserRepository {
  @Inject(PRISMA_CLIENT) private prisma!: { user: PrismaModelDelegate }

  async findById(id: string) {
    return this.prisma.user.findUnique({ where: { id } }) as Promise<User | null>
  }

  async create(dto: CreateUserDTO) {
    return this.prisma.user.create({ data: dto as Record<string, unknown> }) as Promise<User>
  }
}

No as any on the model accessor. The { user: PrismaModelDelegate } type tells TypeScript that this.prisma.user exists and has CRUD methods with typed signatures.

Shortcoming #3: Methods return Promise<unknown> instead of Promise<User>. You still need as Promise<User> casts on return types. This is a safe downcast (narrowing unknown to a known type), not an unsafe any cast — but it's still a cast.

Shortcoming #4: The data parameter is typed as Record<string, unknown>, not Prisma.UserCreateInput. You lose field-level validation on writes. Passing { invalidField: true } compiles but fails at runtime.

The Upgrade Path

For production apps that need full type safety, we document a simple upgrade:

// Generated (works immediately, PrismaModelDelegate)
@Inject(PRISMA_CLIENT) private prisma!: { user: PrismaModelDelegate }

// Upgraded (full Prisma type safety)
import type { PrismaClient } from '@prisma/client'
@Inject(PRISMA_CLIENT) private prisma!: PrismaClient

One line change. After that, this.prisma.user.create({ data: dto }) validates dto against Prisma.UserCreateInput at compile time, returns User without casts, and gives you full autocomplete on where, include, select, etc.

Shortcoming #5: This upgrade requires knowing your Prisma client import path, which differs between Prisma 5/6 (@prisma/client) and Prisma 7 (@/generated/prisma/client). We added modules.prismaClientPath to the CLI config to address this, but the generated code always starts with PrismaModelDelegate regardless.

Prisma 7 Migration: What Changed

Prisma 7 introduced several breaking changes that affected our adapter:

1. No more `datasource.url` in schema

// Prisma 6
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// Prisma 7
datasource db {
  provider = "postgresql"
  // url moved to prisma.config.ts
}

2. Driver adapters required

// Prisma 6
const prisma = new PrismaClient()

// Prisma 7
import { PrismaPg } from '@prisma/adapter-pg'
import pg from 'pg'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter: new PrismaPg(pool) })

3. `$on` removed for logging

Our adapter detects this at runtime with typeof this.client.$on === 'function' and falls back to $extends. This is the one change that required code in the adapter itself.

4. Client generated to custom output

// Prisma 7
generator client {
  provider = "prisma-client"
  output   = "../src/generated/prisma"
}

All 47 import statements in our Jira example changed from @prisma/client to @/generated/prisma/client.

Shortcoming #6: The @prisma/client runtime package is still needed as a dependency even in Prisma 7 — the generated client imports from @prisma/client/runtime/client internally. This confused us initially when we tried to remove it.

The Query Adapter: Type-Safe Search Columns

Our PrismaQueryAdapter translates parsed URL query strings into Prisma findMany arguments:

GET /api/v1/users?page=2&limit=25&q=john&filter=role:eq:admin&sort=createdAt:desc

Becomes:

{
  where: {
    AND: [
      { role: { equals: 'admin' } },
      { OR: [
        { name: { contains: 'john', mode: 'insensitive' } },
        { email: { contains: 'john', mode: 'insensitive' } },
      ]}
    ]
  },
  orderBy: [{ createdAt: 'desc' }],
  skip: 25,
  take: 25,
}

We added a generic type parameter to validate searchColumns:

import type { User } from '@prisma/client'

const config: PrismaQueryConfig<User> = {
  searchColumns: ['name', 'email'],  // TypeScript validates these are User fields
  // searchColumns: ['invalid'],     // Compile error!
}

Shortcoming #7: This only validates searchColumns, not filterable or sortable fields. Those are validated at the controller layer via QueryParamsConfig from @forinda/kickjs-core, which uses plain string arrays. A unified type that validates across both layers would be better.

What We'd Do Differently

1. Start with the PrismaClient approach, not PrismaModelDelegate

PrismaModelDelegate was born from the constraint that the CLI generates code before the Prisma schema exists. In practice, most users add the model to their schema first, then generate the module. We should have made the full PrismaClient import the default and PrismaModelDelegate the fallback.

2. Generate a db/prisma.ts barrel file

Instead of importing PrismaClient in every repository, generate a single src/db/prisma.ts that re-exports the client and model types. Repositories import from there. When upgrading Prisma versions, you change one file.

3. Type-safe DTOs from Prisma schema

The generated DTOs use Zod schemas that duplicate what's already in the Prisma schema. Tools like zod-prisma-types or prisma-zod-generator could generate Zod schemas from the Prisma schema, eliminating the duplication.

4. Transaction support in the adapter

Our adapter registers a singleton PrismaClient. For transactions (prisma.$transaction), you need the client directly. We should expose a withTransaction helper or a @Transactional decorator that wraps the use case in prisma.$transaction.

Try It

# Scaffold a new project
npx @forinda/kickjs-cli new my-api
cd my-api

# Add Prisma
kick add prisma

# Generate a module
kick g module user --repo prisma

# Start dev server
kick dev

Or check out the full Jira clone examples:

jira-prisma-api (Prisma 6)
jira-prisma-v7-api (Prisma 7)

Summary of Shortcomings

#	Issue	Impact	Status
1	Adapter uses `client: any` — no compile-time client validation	Low — runtime errors are clear	By design
2	~~CLI template had `as any` on every model accessor~~	~~High~~	Fixed with PrismaModelDelegate
3	PrismaModelDelegate returns `Promise<unknown>` — return casts needed	Medium — safe narrowing, not unsafe `any`	By design
4	`data` param typed as `Record<string, unknown>` — no field validation on writes	Medium — runtime errors instead of compile-time	Upgrade to full PrismaClient
5	Prisma client import path differs between v6 and v7	Low — `prismaClientPath` config handles it	Fixed
6	`@prisma/client` runtime still needed in Prisma 7	Low — confusing but functional	Documented
7	`searchColumns` typed but `filterable`/`sortable` not unified	Low — validated at different layers	Planned

KickJS is an open-source, decorator-driven Node.js framework. If you're building REST APIs with TypeScript and want NestJS-like DX without the weight, check it out.

Building a Jira-Like Task API with KickJS — Auth, WebSocket Chat, SSE, Queues & More

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:40:09 +0000

Update: This article documents the initial build and the problems encountered along the way. Many of the gotchas described here (ctx.set/get isolation, DI registration, controller HMR) have been resolved in KickJS v1.2.5–v1.2.7. The workarounds shown are still valid but no longer necessary on the latest version. See the complete project guide for the current patterns.

TL;DR

🏗️ Built a full Jira-like task management API (65 endpoints, 17 modules) using KickJS — a decorator-driven TypeScript framework
🔐 Auth with JWT + refresh tokens + role-based guards — and the debugging rabbit hole that came with it
💬 Real-time WebSocket chat with rooms, typing indicators, and read receipts
📡 Server-Sent Events for live dashboard updates on task changes
⚡ Background job queues with BullMQ for emails, reminders, and audit logs
🤕 10 gotchas that cost me hours so they don't have to cost you hours

Why This Exists

I wanted to stress-test KickJS beyond a "Hello World." So I built Vibed — a task management backend with categories, labels, sprints, comments, file attachments, real-time chat, SSE dashboards, background jobs, and cron-scheduled reminders.

Think Jira's API, but TypeScript-native, decorator-driven, and built in a weekend (okay, a long weekend).

Let's walk through the interesting parts.

The Stack

Concern	Tool
Framework	KickJS (Express under the hood)
Database	MongoDB + Mongoose
Auth	JWT access + refresh tokens
Email	Resend SDK
Real-time	WebSocket (native ws)
Live updates	Server-Sent Events
Job queue	BullMQ + Redis
Scheduled tasks	Cron module
Docs	Swagger / OpenAPI

Getting Started

KickJS has a CLI that scaffolds everything:

kick new vibed --pm pnpm
kick add auth ws mailer queue cron swagger devtools
kick g module tasks

That last command generates a full DDD module — controller, service, repository, DTOs, the works. More on that structure in a sec.

The DDD Module Pattern

Every feature in KickJS lives in a module. Each module follows a layered architecture:

src/modules/tasks/
├── task.module.ts          # Wires everything together
├── task.controller.ts      # HTTP routes + decorators
├── task.service.ts         # Business logic
├── task.repository.ts      # Mongoose queries
├── dto/
│   ├── create-task.dto.ts  # Validation schemas
│   └── update-task.dto.ts
├── schemas/
│   └── task.schema.ts      # Mongoose model
└── interfaces/
    └── task.interface.ts   # TypeScript types

Here's what a module registration looks like:

@Module({
  controllers: [TaskController],
  providers: [TaskService, TaskRepository],
  imports: [MongooseModule.forFeature([
    { name: 'Task', schema: TaskSchema }
  ])],
})
export class TaskModule {}

And a typical controller:

@Controller('/tasks')
@UseGuards(AuthGuard)
export class TaskController {
  @Autowired() private taskService!: TaskService;

  @Get('/')
  async findAll(ctx: Context) {
    const user = getUser(ctx);
    const query = ctx.query as ApiQueryParamsConfig;
    const tasks = await this.taskService.findByWorkspace(
      user.workspaceId,
      query
    );
    return ctx.json({ data: tasks });
  }

  @Post('/')
  @Validate(CreateTaskDto)
  async create(ctx: Context) {
    const user = getUser(ctx);
    const body = ctx.body as CreateTaskDto;
    const task = await this.taskService.create({
      ...body,
      createdBy: user._id,
      workspaceId: user.workspaceId,
    });
    return ctx.json({ data: task }, 201);
  }
}

Clean. Predictable. Every module follows the same shape.

Authentication — The Hard Way

This section is a debugging story. Buckle up.

Chapter 1: @public() Didn't Work

KickJS ships with an auth module that has a defaultPolicy: 'RESTRICTED' setting. Every route is locked down by default — which is great, until you need public routes.

The @Public() decorator is supposed to mark routes as open. Except... it wasn't working. Every public route still returned 401 Unauthorized.

After digging through the source, I found the issue: the resolveHandler in the auth config was throwing before the @Public() metadata could be checked. The auth middleware runs globally, and when resolveHandler fails, it short-circuits.

Chapter 2: The Bridge Middleware

Solution? I built authBridgeMiddleware — a global middleware that sits before the auth guard:

export function authBridgeMiddleware(
  ctx: Context,
  next: NextFunction
) {
  const token = ctx.headers.authorization?.split(' ')[1];

  if (!token) {
    ctx.set('user', null);
    return next();
  }

  try {
    const payload = verifyAccessToken(token);
    ctx.set('user', payload);
  } catch {
    ctx.set('user', null);
  }

  return next();
}

This way, the auth guard always has a user (or null) to work with, and @Public() routes can proceed even without a token.

Chapter 3: The ctx.set()/ctx.get() Fix

This used to be a major gotcha — ctx.set() in middleware was invisible to ctx.get() in the handler because each got a separate RequestContext instance with its own metadata Map.

Good news: fixed in KickJS v1.2.5. The metadata Map is now stored on req and shared across all RequestContext instances for the same request. ctx.set()/ctx.get() works exactly as you'd expect:

// In middleware:
ctx.set('user', payload);  // ✅ Sets on shared metadata

// In route handler:
const user = ctx.get<AuthUser>('user');  // ✅ Works!

A clean helper keeps it centralized:

export function getUser(ctx: Context): AuthUser {
  const user = ctx.get<AuthUser>('user');

  if (!user) {
    throw new UnauthorizedException('Not authenticated');
  }

  return user;
}

Real-Time Chat with WebSocket

KickJS has first-class WebSocket support via @WsController:

@WsController('/chat')
export class ChatGateway {
  @Autowired() private chatService!: ChatService;

  @OnConnect()
  async handleConnect(socket: WsSocket) {
    const user = await this.authenticateSocket(socket);
    socket.data = { userId: user._id };
    console.log(`🟢 ${user.name} connected`);
  }

  @OnMessage('join-room')
  async handleJoinRoom(
    socket: WsSocket,
    payload: { roomId: string }
  ) {
    socket.join(payload.roomId);
    socket.to(payload.roomId).emit('user-joined', {
      userId: socket.data.userId,
      timestamp: new Date(),
    });
  }

  @OnMessage('send-message')
  async handleMessage(
    socket: WsSocket,
    payload: { roomId: string; content: string }
  ) {
    const message = await this.chatService.create({
      roomId: payload.roomId,
      senderId: socket.data.userId,
      content: payload.content,
    });

    socket.to(payload.roomId).emit('new-message', message);
  }

  @OnMessage('typing')
  async handleTyping(
    socket: WsSocket,
    payload: { roomId: string; isTyping: boolean }
  ) {
    socket.to(payload.roomId).emit('user-typing', {
      userId: socket.data.userId,
      isTyping: payload.isTyping,
    });
  }
}

Rooms, typing indicators, message persistence — all decorator-driven. The socket.join() / socket.to() API mirrors Socket.IO, which makes it easy to reason about.

Live Dashboard with SSE

For the dashboard, I didn't want WebSocket overhead. SSE is perfect for one-way server-to-client updates:

@Get('/stream')
@UseGuards(AuthGuard)
async streamUpdates(ctx: Context) {
  const user = getUser(ctx);

  ctx.sse((send, close) => {
    const interval = setInterval(async () => {
      const stats = await this.dashboardService.getStats(
        user.workspaceId
      );
      send({ event: 'dashboard-update', data: stats });
    }, 5000);

    ctx.req.on('close', () => {
      clearInterval(interval);
      close();
    });
  });
}

ctx.sse() handles the headers (text/event-stream, Cache-Control, etc.) and gives you a clean send/close interface. The client just uses EventSource:

const es = new EventSource('/api/dashboard/stream', {
  headers: { Authorization: `Bearer ${token}` }
});

es.addEventListener('dashboard-update', (e) => {
  updateDashboard(JSON.parse(e.data));
});

Background Jobs That Actually Work

Email notifications, reminder scheduling, audit logging — all of this needs to happen off the request cycle. KickJS wraps BullMQ:

@Job('email-queue')
export class EmailJob {
  @Autowired() private mailer!: MailerService;

  @Process('send-welcome')
  async handleWelcome(job: JobData<WelcomePayload>) {
    await this.mailer.send({
      to: job.data.email,
      subject: 'Welcome to Vibed!',
      template: 'welcome',
      context: { name: job.data.name },
    });
  }

  @Process('send-reminder')
  async handleReminder(job: JobData<ReminderPayload>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `Reminder: ${job.data.taskTitle}`,
      template: 'task-reminder',
      context: job.data,
    });
  }
}

Dispatching a job from anywhere:

@Autowired() private queueService!: QueueService;

async createTask(data: CreateTaskDto) {
  const task = await this.taskRepo.create(data);

  // Fire-and-forget background job
  await this.queueService.add('email-queue', 'send-reminder', {
    email: data.assigneeEmail,
    taskTitle: task.title,
    dueDate: task.dueDate,
  });

  return task;
}

Pro tip: In development, skip Redis entirely with the ConsoleProvider:

QueueModule.register({
  provider: process.env.NODE_ENV === 'development'
    ? 'console'    // Logs jobs to terminal
    : 'bullmq',   // Real Redis-backed queue
  connection: { host: 'localhost', port: 6379 },
})

File Uploads → Base64 → MongoDB

No S3, no Cloudinary. For a task management MVP, storing files as base64 in MongoDB is fine:

@Post('/attachments')
@FileUpload({ maxSize: 5 * 1024 * 1024 }) // 5MB
async uploadAttachment(ctx: Context) {
  const file = ctx.file;
  const user = getUser(ctx);

  const attachment = await this.attachmentService.create({
    taskId: ctx.params.taskId,
    fileName: file.originalname,
    mimeType: file.mimetype,
    data: file.buffer.toString('base64'),
    uploadedBy: user._id,
  });

  return ctx.json({ data: attachment }, 201);
}

Is this production-ready for large files? No. Is it perfect for an MVP with < 5MB attachments? Absolutely.

10 Gotchas That'll Save You Hours

These are the things I wish someone had told me before I started. Each one cost me at least 30 minutes of head-scratching.

1. Mongoose HMR Guard

Hot module reload re-runs your schema definitions. Mongoose hates that.

// ❌ Crashes on HMR
export const TaskModel = model('Task', TaskSchema);

// ✅ Guard it
export const TaskModel =
  models.Task || model('Task', TaskSchema);

2. Double-Slash Routes

If your module prefix is /api and your controller has @Controller('/tasks'), you get /api//tasks. Both start with /.

// ❌ Results in /api//tasks
@Module({ prefix: '/api' })
@Controller('/tasks')

// ✅ Drop the leading slash on one
@Module({ prefix: '/api' })
@Controller('tasks')

3. Global vs Route Middleware Signatures

Global middleware gets (ctx, next). Route middleware gets (ctx, next) too — but the ctx object is different. Global middleware runs on the raw Express context; route middleware runs on the KickJS-wrapped context.

// Global middleware — req/res under the hood
app.use((ctx, next) => {
  ctx.req.headers; // ✅ works
  ctx.body;        // ❌ might not be parsed yet
  next();
});

// Route middleware — full KickJS context
@UseMiddleware(myMiddleware)
// ctx.body ✅, ctx.query ✅, ctx.params ✅

4. ctx.set/get Shared Across Middleware/Handler (Fixed in v1.2.5)

This was a pain point in earlier versions but is now fixed. Use ctx.set()/ctx.get() directly — no res.locals workaround needed.

5. @Inject for Constructors, @Autowired for Properties

// Constructor injection
class TaskService {
  constructor(@Inject(TaskRepository) private repo: TaskRepository) {}
}

// Property injection (no constructor needed)
class TaskController {
  @Autowired() private taskService!: TaskService;
}

Mix them up and you get silent undefined values. Pick one pattern per class.

6. QueueAdapter Wants String Names, Not Classes

// ❌ Nope
this.queueService.add(EmailJob, 'send-welcome', data);

// ✅ String name matching @Job('email-queue')
this.queueService.add('email-queue', 'send-welcome', data);

7. Route-less Modules Crash Express

If a module has no controllers (e.g., a pure service module), KickJS still tries to register it as a router. Empty router = Express crash.

// ✅ Add a health controller or use forRoot() pattern
@Module({
  controllers: [],  // This can cause issues
  providers: [MyService],
})

// ✅ Better: export the service from a module that HAS routes

8. Auth defaultPolicy Blocks When resolveHandler Fails

If your resolveHandler throws, every route gets a 401 — even @Public() ones. Always wrap it:

authConfig({
  defaultPolicy: 'RESTRICTED',
  resolveHandler: async (ctx) => {
    try {
      return await verifyToken(ctx);
    } catch {
      return null;  // Let @Public() routes through
    }
  },
})

9. ApiQueryParamsConfig Type Name

The type for pagination/filter/sort query params is called ApiQueryParamsConfig, not QueryParams, not ApiQuery, not PaginationOptions. Ask me how many times I searched for the wrong name.

import { ApiQueryParamsConfig } from '@kickjs/core';

@Get('/')
async findAll(ctx: Context) {
  const query = ctx.query as ApiQueryParamsConfig;
  // query.page, query.limit, query.sort, query.filter
}

10. loadEnv() Type Erasure

loadEnv() returns Record<string, string>. Everything is a string. Your "boolean" ENABLE_SWAGGER=true is the string "true".

// ❌ This is always truthy (it's a non-empty string)
if (env.ENABLE_SWAGGER) { ... }

// ✅ Compare strings explicitly
if (env.ENABLE_SWAGGER === 'true') { ... }

// ✅ Or parse once at startup
const config = {
  enableSwagger: env.ENABLE_SWAGGER === 'true',
  port: parseInt(env.PORT, 10) || 3000,
};

The Numbers

After a long weekend of building:

Metric	Count
Modules	17
API Endpoints	65
MongoDB Collections	13
TypeScript Files	159
Type Errors	0

Modules include: auth, users, workspaces, projects, sprints, tasks, task-comments, task-labels, task-categories, task-attachments, task-reminders, chat, notifications, dashboard, audit-log, file-uploads, and health.

What I'd Do Differently

Start with the auth bridge middleware — don't fight @Public() for two hours first
Use property injection everywhere — @Autowired() is simpler than constructor @Inject()
String-based queue names from day one — saves a refactor later
Build the getUser(ctx) helper immediately — uses ctx.get<AuthUser>('user') under the hood, called in every guarded route

What's Next

In the next article in this series, I'll cover:

Role-based access control — workspace admins vs members vs viewers
Advanced query filtering — how to build a flexible filter/sort/paginate layer on top of Mongoose
Deployment — containerizing the whole stack with Docker Compose

If you've been looking for a NestJS alternative that's lighter, faster to scaffold, and doesn't require a PhD in dependency injection — give KickJS a shot.

Star KickJS on GitHub

Got questions? Drop them in the comments — I'll answer everything. If you hit any of these gotchas yourself, I'd love to hear your war stories too.

KickJS Module Generator: 4 Architecture Patterns for Every Backend Need

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:35:23 +0000

One of the things I appreciate most about working with a framework is when it meets me where I am. Not every feature I build needs the same level of ceremony. A health check endpoint does not need domain-driven design. A real-time collaboration feature probably does. The KickJS module generator understands this distinction, and it changed how I think about scaffolding backend code.

The command is simple:

kick g module <name> --pattern <pattern>

That --pattern flag is where the magic lives. KickJS ships four architecture patterns: minimal, rest, ddd, and cqrs. Each one generates a different number of files with a different structural philosophy. Instead of forcing you into one way of building modules, the generator lets you pick the right level of complexity for the job at hand. I have been building Vibed, a Jira-like task management backend, with KickJS for several months now. Along the way I have used all four patterns, and I want to walk through what each one gives you and when to reach for it.

Pattern 1: minimal (2 files)

kick g module health --pattern minimal

This is the lightest possible module. Two files. That is it.

health/
├── index.ts
└── health.controller.ts

The index.ts file is your module definition. It implements AppModule, registers nothing in the DI container, and returns a single route pointing at the controller:

import type { AppModule, ModuleRoutes, Container } from '@forinda/kickjs-core';
import { buildRoutes } from '@forinda/kickjs-http';
import { HealthController } from './health.controller';

export class HealthModule implements AppModule {
  register(_container: Container): void {
    // No DI bindings needed
  }

  routes(): ModuleRoutes {
    return {
      path: '/',
      router: buildRoutes(HealthController),
      controller: HealthController,
    };
  }
}

The controller is equally lean. No services, no repositories, no DTOs. Just decorated route handlers returning responses directly:

import { Controller, Get } from '@forinda/kickjs-core';
import type { RequestContext } from '@forinda/kickjs-http';

@Controller()
export class HealthController {
  @Get('/health')
  async check(ctx: RequestContext) {
    ctx.json({ status: 'ok', timestamp: new Date().toISOString() });
  }
}

I use the minimal pattern for endpoints that do not touch the database or require any business logic. Health checks, version endpoints, static configuration responses, debug routes during development. In Vibed, the StatsModule started as a minimal module before it grew to need actual service dependencies. The pattern gives you a place to put code without imposing structure you do not need yet.

When to use it: Quick prototypes, static endpoints, health checks, anything where a controller alone is sufficient.

Pattern 2: rest (11 files)

kick g module cats --pattern rest

This is the workhorse pattern. Eleven files in a flat structure that covers the full CRUD lifecycle:

cats/
├── index.ts
├── cats.controller.ts
├── cats.service.ts
├── cats.repository.ts
├── cats.types.ts
├── cats.dto.ts
├── cats.config.ts
├── cats.controller.test.ts
├── cats.service.test.ts
├── cats.repository.test.ts
└── _glob.ts

The service wraps the repository, the controller delegates to the service, and DTOs handle validation. No subdirectories, no layers to navigate. Everything for the cats module lives in one folder.

The generated repository ships with an in-memory implementation by default:

import type { Cat, CreateCatDto, UpdateCatDto } from './cats.types';

export class CatsRepository {
  private items: Cat[] = [];
  private nextId = 1;

  async findAll(): Promise<Cat[]> {
    return [...this.items];
  }

  async findById(id: string): Promise<Cat | null> {
    return this.items.find(item => item.id === id) ?? null;
  }

  async create(dto: CreateCatDto): Promise<Cat> {
    const item: Cat = { id: String(this.nextId++), ...dto, createdAt: new Date(), updatedAt: new Date() };
    this.items.push(item);
    return item;
  }

  // ... update, delete methods
}

This is intentional. You get a working module the instant the generator finishes. No database setup required. When you are ready, you swap the in-memory store for your real persistence layer. A comment in the generated file even tells you where to make the swap for Drizzle or Prisma. In Vibed, we use MongoDB with Mongoose, so we replaced these with Mongo repository implementations, but the interface stayed the same.

The cats.config.ts file contains a QueryFieldConfig for pagination:

import type { ApiQueryParamsConfig } from '@forinda/kickjs-core';

export const CATS_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['breed', 'color'],
  sortable: ['name', 'createdAt'],
  searchable: ['name'],
};

This integrates directly with ctx.paginate() and @ApiQueryParams() for Swagger documentation. In Vibed, we centralized these configs in shared/constants/query-configs.ts, but the generator gives each module its own config file so it works out of the box.

The _glob.ts file is the auto-wiring mechanism:

import.meta.glob(['./*.ts', '!./_glob.ts', '!./*.test.ts'], { eager: true });

I will explain why this matters in a dedicated section below.

When to use it: Most CRUD modules, rapid development, any time you want a flat structure with no ceremony. This is the pattern I reach for most often.

Pattern 3: ddd (18 files)

kick g module cats --pattern ddd

Eighteen files across a full domain-driven design directory structure:

cats/
├── index.ts
├── _glob.ts
├── presentation/
│   └── cats.controller.ts
├── application/
│   ├── dtos/
│   │   ├── create-cat.dto.ts
│   │   └── update-cat.dto.ts
│   └── use-cases/
│       ├── create-cat.use-case.ts
│       ├── get-cat.use-case.ts
│       ├── list-cats.use-case.ts
│       ├── update-cat.use-case.ts
│       └── delete-cat.use-case.ts
├── domain/
│   ├── entities/
│   │   └── cat.entity.ts
│   ├── value-objects/
│   │   └── cat-id.vo.ts
│   ├── services/
│   │   └── cat-domain.service.ts
│   └── repositories/
│       └── cat.repository.ts
└── infrastructure/
    └── repositories/
        └── in-memory-cat.repository.ts

This is where things get interesting. The generator does not just create more files. It creates files with real architectural opinions baked in.

The domain entity uses a private constructor with factory methods:

export class Cat {
  private constructor(
    public readonly id: CatId,
    public name: string,
    public breed: string,
    public age: number,
    public readonly createdAt: Date,
    public updatedAt: Date,
  ) {}

  static create(props: { name: string; breed: string; age: number }): Cat {
    return new Cat(
      CatId.generate(),
      props.name,
      props.breed,
      props.age,
      new Date(),
      new Date(),
    );
  }

  static reconstitute(props: {
    id: string; name: string; breed: string; age: number;
    createdAt: Date; updatedAt: Date;
  }): Cat {
    return new Cat(
      CatId.from(props.id),
      props.name,
      props.breed,
      props.age,
      props.createdAt,
      props.updatedAt,
    );
  }
}

The create factory is for new entities. The reconstitute factory is for rehydrating from persistence. This distinction matters because creation might involve generating IDs, setting defaults, or validating invariants, while reconstitution assumes the data is already valid. It is a pattern from the DDD playbook that the generator hands you for free.

The CatId value object wraps the raw string identifier:

export class CatId {
  private constructor(private readonly value: string) {}

  static generate(): CatId {
    return new CatId(crypto.randomUUID());
  }

  static from(value: string): CatId {
    return new CatId(value);
  }

  toString(): string {
    return this.value;
  }

  equals(other: CatId): boolean {
    return this.value === other.value;
  }
}

The domain service layer is separate from the use cases. Use cases orchestrate application flow -- they call repositories, invoke domain services, and return results. Domain services contain business rules that do not belong to a single entity. This separation means your business logic survives even if you swap out your application framework.

The repository interface lives in domain/repositories/, and the implementation lives in infrastructure/repositories/. The use cases depend only on the interface:

@Service()
export class CreateCatUseCase {
  constructor(
    @Inject(TOKENS.CAT_REPOSITORY) private catRepo: ICatRepository,
  ) {}

  async execute(dto: CreateCatDto): Promise<Cat> {
    const cat = Cat.create(dto);
    return this.catRepo.save(cat);
  }
}

Five use cases are generated: create, get, list, update, delete. Each one is a single-responsibility class. The controller uses @Autowired() to inject them all, and each route handler delegates to exactly one use case. This is the exact pattern we use throughout Vibed for modules like workspaces, tasks, and projects.

The _glob.ts in the DDD pattern casts a wider net:

import.meta.glob([
  './presentation/**/*.ts',
  './application/**/*.ts',
  './domain/services/**/*.ts',
  './infrastructure/**/*.ts',
  '!./**/*.test.ts',
], { eager: true });

It reaches into every layer to ensure all decorated classes are loaded and registered in the DI container.

When to use it: Complex business logic, team projects where multiple developers touch the same module, long-lived codebases where you need clear boundaries between layers.

Pattern 4: cqrs (17 files)

kick g module cats --pattern cqrs

Seventeen files with command/query separation and an event system:

cats/
├── index.ts
├── _glob.ts
├── commands/
│   ├── create-cat.command.ts
│   ├── update-cat.command.ts
│   └── delete-cat.command.ts
├── queries/
│   ├── get-cat.query.ts
│   └── list-cats.query.ts
├── events/
│   ├── cat-events.ts
│   ├── cat-created.handler.ts
│   ├── cat-updated.handler.ts
│   └── cat-deleted.handler.ts
├── dtos/
│   ├── create-cat.dto.ts
│   └── update-cat.dto.ts
├── cats.controller.ts
├── cats.types.ts
├── cats.repository.ts
└── cats.event-emitter.ts

The core idea here is that reads and writes are different operations with different concerns. Commands mutate state. Queries read it. Events broadcast what happened so other parts of the system can react.

The event emitter is strongly typed with a domain event map:

import { EventEmitter } from 'events';
import type { Cat } from './cats.types';

export interface CatEventMap {
  'cat.created': [cat: Cat];
  'cat.updated': [cat: Cat];
  'cat.deleted': [id: string];
}

class CatEventEmitter extends EventEmitter {
  emit<K extends keyof CatEventMap>(event: K, ...args: CatEventMap[K]): boolean {
    return super.emit(event, ...args);
  }

  on<K extends keyof CatEventMap>(event: K, listener: (...args: CatEventMap[K]) => void): this {
    return super.on(event, listener as any);
  }
}

export const catEvents = new CatEventEmitter();

This is not just a generic EventEmitter. The type parameter on CatEventMap means TypeScript enforces that you emit the right payload for each event name. If cat.created expects a Cat object, you cannot accidentally emit a string.

Commands emit events after performing their mutation:

@Service()
export class CreateCatCommand {
  constructor(@Inject(TOKENS.CAT_REPOSITORY) private repo: CatsRepository) {}

  async execute(dto: CreateCatDto): Promise<Cat> {
    const cat = await this.repo.create(dto);
    catEvents.emit('cat.created', cat);
    return cat;
  }
}

Event handlers pick up those events for side effects:

import { catEvents } from '../cats.event-emitter';

// WebSocket broadcast
catEvents.on('cat.created', (cat) => {
  // Broadcast via WS adapter
  console.log(`[WS] Broadcasting cat.created: ${cat.id}`);
});

// Queue dispatch
catEvents.on('cat.created', (cat) => {
  // Dispatch to BullMQ for async processing
  console.log(`[Queue] Dispatching cat.created job: ${cat.id}`);
});

The handlers are stubs, but they show you where to plug in WebSocket broadcasts, queue dispatches, audit trail logging, or cache invalidation. In Vibed, we use this pattern for features like real-time notifications and activity feeds, where creating a task should trigger events that multiple subsystems consume.

The _glob.ts for CQRS covers all the directories:

import.meta.glob([
  './commands/**/*.ts',
  './queries/**/*.ts',
  './events/**/*.ts',
  '!./**/*.test.ts',
], { eager: true });

When to use it: Event-driven features, real-time applications, systems that need audit trails, anything where the write path and read path have fundamentally different requirements.

Auto-Wiring: The Generator Updates Your Module Registry

When you run kick g module, the generator does not just create files in a new directory. It also updates src/modules/index.ts automatically. In Vibed, that file looks like this:

import type { AppModuleClass } from '@forinda/kickjs-core';
import { AuthModule } from './auth/auth.module';
import { UsersModule } from './users/users.module';
import { WorkspacesModule } from './workspaces/workspaces.module';
// ... other imports

export const modules: AppModuleClass[] = [
  AuthModule,
  UsersModule,
  WorkspacesModule,
  // ... other modules
];

The generator appends your new module's import and adds it to the array. No manual wiring. This matters more than it sounds, because forgetting to register a module is one of those bugs that gives you no error message -- your routes simply do not exist, and you spend twenty minutes wondering why Postman returns 404.

The import.meta.glob Pattern

Every generated pattern except minimal includes a _glob.ts file (or inlines the glob in index.ts). This file uses Vite's import.meta.glob with { eager: true }:

import.meta.glob(['./**/*.ts', '!./**/*.test.ts'], { eager: true });

Why does this exist? In KickJS, decorated classes (@Service(), @Controller(), etc.) register themselves in the DI container as a side effect of being imported. If a file is never imported, its decorators never run, and the container does not know it exists.

Explicit imports work, but they are fragile. Every time you add a new use case or service, you have to remember to import it somewhere. import.meta.glob solves this by loading all .ts files in the module directory tree at build time.

Here is what happens under the hood:

Vite evaluates the glob pattern at build time, resolving it to a static list of file paths.
The { eager: true } option loads all matched files synchronously, as if you had written individual import statements for each one.
Each imported file's top-level code executes, which includes decorator registration as a side effect.
During HMR, when a file changes, Vite re-evaluates the glob and re-imports the affected modules.

This is why the pattern survives hot module replacement. The glob re-evaluates on every rebuild, picking up new files and dropping deleted ones without any manual intervention. You add a new use case file, save it, and HMR ensures it is registered in the container immediately.

Choosing a Pattern: The Decision Matrix

After months of building with all four patterns, here is how I decide:

Scenario	Pattern	Why
Prototype or spike	`minimal`	Two files, zero overhead, prove the concept first
Standard CRUD resource	`rest`	Flat structure, fast to navigate, covers 80% of modules
Complex business domain	`ddd`	Layer separation protects invariants, scales with team size
Event-driven feature	`cqrs`	Command/query split, typed events, natural fit for real-time

The patterns are not mutually exclusive within a project. In Vibed, we have modules at different complexity levels. The stats module is essentially minimal. The workspaces module follows DDD conventions. If we were to add a live collaboration feature, CQRS would be the natural choice. KickJS does not enforce uniformity -- you pick the right tool for each module.

The --repo Flag

The generator also accepts a --repo flag to control what persistence layer the generated repository uses:

kick g module cats --pattern rest --repo inmemory
kick g module cats --pattern rest --repo drizzle
kick g module cats --pattern rest --repo prisma

The inmemory option is the default. It gives you a working module with no database dependency, which is great for prototyping and testing. The drizzle option generates a repository that uses Drizzle ORM with typed schemas. The prisma option generates one that delegates to a Prisma client.

In Vibed, we use MongoDB with Mongoose, which is not one of the generator's built-in options. We wrote our repository implementations by hand, following the interface contracts that the DDD pattern generates. The key point is that the generator gives you a starting point and a clear interface boundary. Whether you use the generated repository or write your own, the rest of the module -- controllers, use cases, DTOs -- does not change.

Wrapping Up

The kick g module command is more than a code generator. It is a decision framework. By offering four distinct patterns, it forces you to think about the architectural needs of each module before you write a single line of business logic. The minimal pattern keeps you honest about simplicity. The rest pattern gets you moving fast. The DDD pattern protects your domain. The CQRS pattern embraces events as first-class citizens.

After building Vibed across all four patterns, my advice is straightforward: start with minimal or rest, and promote to ddd or cqrs when the module's complexity demands it. The generator makes that promotion path cheap, and import.meta.glob ensures you never have to manually wire up your DI container along the way.

# Start simple
kick g module health --pattern minimal

# Standard CRUD
kick g module cats --pattern rest

# When the domain gets complex
kick g module billing --pattern ddd

# When events drive the feature
kick g module notifications --pattern cqrs

Four commands, four architectures, one framework. That is the kind of flexibility I want in a backend toolkit.

KickJS Query Engine Deep Dive: Filtering, Sorting, Search, and Pagination with MongoDB

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:32:46 +0000

KickJS Query Engine Deep Dive: Filtering, Sorting, Search, and Pagination with MongoDB

When you're building an API with 60+ endpoints and 10+ list views, you can't afford inconsistency. Some endpoints return everything. Some paginate but don't filter. Some sort by createdAt, others by name, and the client has no idea which is which.

We solved this in Vibed — a Jira-like task management backend — by building a querying pipeline that flows from URL query strings, through KickJS's ctx.paginate(), into MongoDB helpers, and back out as a standardized paginated response. Every list endpoint works the same way.

Here's how the full pipeline works.

The Query Pipeline

Client request
  GET /api/v1/projects/abc/tasks?status=eq:open&priority=in:high,critical&sort=-dueDate&search=login&page=2&limit=10
       │
       ▼
  ctx.paginate(fetcher, TASK_QUERY_CONFIG)
       │
       ├── ctx.qs(config) parses the query string
       │   → filters: [{ field: 'status', operator: 'eq', value: 'open' }, ...]
       │   → sort: [{ field: 'dueDate', direction: 'desc' }]
       │   → search: 'login'
       │   → pagination: { page: 2, limit: 10, offset: 10 }
       │
       ▼
  fetcher(parsed) → repository.findPaginated(parsed)
       │
       ├── buildMongoFilter(filters) → { status: 'open', priority: { $in: ['high', 'critical'] } }
       ├── buildMongoSort(sort)      → { dueDate: -1 }
       ├── buildMongoSearch(search)  → { $text: { $search: 'login' } }
       │
       ▼
  MongoDB: Model.find(filter).sort(sort).skip(10).limit(10) + countDocuments(filter)
       │
       ▼
  Response: { data: [...], meta: { page: 2, limit: 10, total: 47, totalPages: 5, hasNext: true, hasPrev: true } }

One pipeline. Every endpoint. Let's break down each layer.

Layer 1: Query Configs

The foundation is a centralized config file that declares what each endpoint supports:

// src/shared/constants/query-configs.ts
import type { ApiQueryParamsConfig } from '@forinda/kickjs-core';

export const TASK_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['status', 'priority', 'assigneeId', 'labelId', 'projectId'],
  sortable: ['createdAt', 'title', 'priority', 'dueDate', 'orderIndex'],
  searchable: ['title', 'description'],
};

export const WORKSPACE_QUERY_CONFIG: ApiQueryParamsConfig = {
  sortable: ['name', 'createdAt'],
  searchable: ['name', 'description'],
};

export const NOTIFICATION_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['type', 'isRead'],
  sortable: ['createdAt'],
};

Each config serves three purposes:

Runtime parsing — ctx.qs(config) only parses fields listed here, ignoring anything else
Swagger docs — @ApiQueryParams(config) generates query parameter documentation automatically
Validation — prevents clients from filtering or sorting on fields you haven't whitelisted

We defined 11 configs for our endpoints: tasks, users, notifications, activity, labels, channels, workspaces, projects, comments, attachments, and members.

Layer 2: The Controller

The controller is where it all comes together — one decorator and one method call:

@Get('/projects/:projectId/tasks', {
  params: z.object({ projectId: z.string() }),
})
@Middleware(projectAccessGuard)
@ApiQueryParams(TASK_QUERY_CONFIG)
async list(ctx: RequestContext) {
  await ctx.paginate(
    async (parsed) => {
      // Inject the projectId as an additional filter
      parsed.filters.push({
        field: 'projectId',
        operator: 'eq',
        value: ctx.params.projectId,
      });
      return this.taskRepo.findPaginated(parsed);
    },
    TASK_QUERY_CONFIG,
  );
}

ctx.paginate() does everything:

Calls ctx.qs(config) internally to parse the query string
Passes the parsed result to your fetcher function
Wraps the { data, total } response with pagination metadata
Sends the JSON response

You never call ctx.qs() separately. You never manually build the response envelope. You just return { data, total } from the fetcher.

Injecting extra filters

Notice parsed.filters.push() — this is how you scope queries to a parent resource. The URL already has ?status=eq:open, and we add projectId programmatically. Both end up in the same MongoDB filter.

For simpler cases, you can pass the scope filter directly:

// Labels scoped to a workspace
async list(ctx: RequestContext) {
  await ctx.paginate(
    (parsed) => this.labelRepo.findPaginated(parsed, {
      workspaceId: ctx.params.workspaceId,
    }),
    LABEL_QUERY_CONFIG,
  );
}

Layer 3: The MongoDB Helpers

Three small functions translate the parsed query into MongoDB operations.

buildMongoFilter — 10 operators

export function buildMongoFilter(
  filters: Array<{ field: string; operator: string; value: string }>
): Record<string, any> {
  const mongoFilter: Record<string, any> = {};

  for (const { field, operator, value } of filters) {
    switch (operator) {
      case 'eq':       mongoFilter[field] = value; break;
      case 'neq':      mongoFilter[field] = { $ne: value }; break;
      case 'gt':       mongoFilter[field] = { $gt: value }; break;
      case 'gte':      mongoFilter[field] = { $gte: value }; break;
      case 'lt':       mongoFilter[field] = { $lt: value }; break;
      case 'lte':      mongoFilter[field] = { $lte: value }; break;
      case 'between': {
        const [min, max] = value.split(',');
        mongoFilter[field] = { $gte: min, $lte: max };
        break;
      }
      case 'in':       mongoFilter[field] = { $in: value.split(',') }; break;
      case 'contains': mongoFilter[field] = { $regex: value, $options: 'i' }; break;
      case 'starts':   mongoFilter[field] = { $regex: `^${value}`, $options: 'i' }; break;
      case 'ends':     mongoFilter[field] = { $regex: `${value}$`, $options: 'i' }; break;
      default:         mongoFilter[field] = value;
    }
  }

  return mongoFilter;
}

The URL syntax is field=operator:value:

?status=eq:open → { status: 'open' }
?priority=in:high,critical → { priority: { $in: ['high', 'critical'] } }
?dueDate=lte:2026-04-01 → { dueDate: { $lte: '2026-04-01' } }
?title=contains:auth → { title: { $regex: 'auth', $options: 'i' } }
?points=between:3,8 → { points: { $gte: '3', $lte: '8' } }

buildMongoSort — with default fallback

export function buildMongoSort(
  sort: Array<{ field: string; direction: 'asc' | 'desc' }>
): Record<string, 1 | -1> {
  const mongoSort: Record<string, 1 | -1> = {};
  for (const { field, direction } of sort) {
    mongoSort[field] = direction === 'asc' ? 1 : -1;
  }
  if (Object.keys(mongoSort).length === 0) {
    mongoSort.createdAt = -1; // default: newest first
  }
  return mongoSort;
}

URL syntax: ?sort=-dueDate,title → { dueDate: -1, title: 1 }. Prefix - means descending.

buildMongoSearch — full-text search

export function buildMongoSearch(search: string): Record<string, any> {
  if (!search) return {};
  return { $text: { $search: search } };
}

Uses MongoDB's $text operator, which requires a text index on the schema:

taskSchema.index({ title: 'text', description: 'text' });
userSchema.index({ firstName: 'text', lastName: 'text', email: 'text' });

URL: ?search=authentication searches across all indexed text fields.

Layer 4: The Repository

The findPaginated method brings it all together:

async findPaginated(
  parsed: any,
  extraFilter: Record<string, any> = {},
): Promise<{ data: TaskEntity[]; total: number }> {
  const {
    filters = [],
    sort = [],
    pagination = { page: 1, limit: 20, offset: 0 },
    search = '',
  } = parsed;

  const mongoFilter = {
    ...extraFilter,
    ...buildMongoFilter(filters),
    ...buildMongoSearch(search),
  };
  const mongoSort = buildMongoSort(sort);

  const [data, total] = await Promise.all([
    TaskModel.find(mongoFilter)
      .sort(mongoSort)
      .skip(pagination.offset)
      .limit(pagination.limit)
      .lean(),
    TaskModel.countDocuments(mongoFilter),
  ]);

  return { data: data as any[], total };
}

Key details:

extraFilter merges with parsed filters — used for scoping (e.g., { workspaceId })
Promise.all runs the data query and count query in parallel
.lean() returns plain objects instead of Mongoose documents (faster, smaller)
Returns { data, total } — that's the contract ctx.paginate() expects

For aggregation pipelines ($lookup)

When you need joins — like listing workspaces with the user's role — use aggregation instead:

async findPaginatedForUser(parsed: any, userId: string) {
  const { filters = [], sort = [], pagination = { ... } } = parsed;
  const matchStage = {
    userId: new mongoose.Types.ObjectId(userId),
    ...buildMongoFilter(filters),
  };
  const mongoSort = buildMongoSort(sort);

  const pipeline = [
    { $match: matchStage },
    { $lookup: {
      from: 'workspaces',
      localField: 'workspaceId',
      foreignField: '_id',
      as: 'workspace',
    }},
    { $unwind: '$workspace' },
    { $project: {
      _id: '$workspace._id',
      name: '$workspace.name',
      slug: '$workspace.slug',
      role: '$role',
      createdAt: '$workspace.createdAt',
    }},
    { $sort: mongoSort },
  ];

  const countPipeline = [...pipeline, { $count: 'total' }];
  const dataPipeline = [...pipeline, { $skip: pagination.offset }, { $limit: pagination.limit }];

  const [countResult, data] = await Promise.all([
    WorkspaceMemberModel.aggregate(countPipeline),
    WorkspaceMemberModel.aggregate(dataPipeline),
  ]);

  return { data, total: countResult[0]?.total ?? 0 };
}

Same { data, total } contract. ctx.paginate() doesn't care whether you used find() or aggregate().

The Response Shape

Every paginated endpoint returns the same structure:

{
  "data": [
    { "_id": "abc", "title": "Fix login bug", "status": "open", "priority": "high" },
    { "_id": "def", "title": "Add dark mode", "status": "todo", "priority": "medium" }
  ],
  "meta": {
    "page": 2,
    "limit": 10,
    "total": 47,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": true
  }
}

Frontend developers love this. They get hasNext/hasPrev for pagination controls, total for "showing 11-20 of 47 results", and totalPages for page number navigation. No guessing.

Real API Examples

Here are actual queries you can make against the Vibed API:

# Tasks in a project, filtered by status and priority, sorted by due date
GET /api/v1/projects/abc/tasks?status=eq:in-progress&priority=in:high,critical&sort=-dueDate&limit=5

# Search tasks by title/description
GET /api/v1/projects/abc/tasks?search=authentication&sort=-createdAt

# Labels in a workspace, sorted alphabetically
GET /api/v1/workspaces/xyz/labels?sort=name&limit=50

# Workspace members filtered by role
GET /api/v1/workspaces/xyz/members?role=eq:admin&sort=-joinedAt

# Notifications, unread only, newest first
GET /api/v1/notifications?isRead=eq:false&sort=-createdAt&page=1&limit=20

# Activity feed for a project, filtered by action type
GET /api/v1/projects/abc/activity?action=eq:task.created&sort=-createdAt

All return the same { data, meta } shape. All support the same filter operators.

Adding a New Paginated Endpoint

The process is mechanical — about 5 minutes per endpoint:

Define the query config in query-configs.ts:

export const INVOICE_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['status', 'clientId', 'dueDate'],
  sortable: ['createdAt', 'amount', 'dueDate'],
  searchable: ['number', 'clientName'],
};

Add findPaginated to the repository (copy-paste the pattern, change the model name)
Update the controller:

@ApiQueryParams(INVOICE_QUERY_CONFIG)
async list(ctx: RequestContext) {
  await ctx.paginate(
    (parsed) => this.invoiceRepo.findPaginated(parsed, { workspaceId: ctx.params.workspaceId }),
    INVOICE_QUERY_CONFIG,
  );
}

That's it. Swagger docs, query parsing, filtering, sorting, search, pagination — all handled.

What We'd Change

A few things that could be better:

Type the parsed parameter — right now it's any. A ParsedQuery type from KickJS would make the contract explicit.
Date coercion — buildMongoFilter passes values as strings. Date fields like dueDate=lte:2026-04-01 should be coerced to Date objects. We handle this per-field in some repos but it should be generic.
Aggregation helper — The findPaginated pattern for $lookup pipelines is more boilerplate than the simple find() version. A buildPaginatedAggregation(pipeline, parsed) helper would reduce that.
Cursor-based pagination — For real-time feeds (messages, activity), offset-based pagination has issues with insertions shifting pages. Our messages controller uses cursor-based (before/after) pagination, which is better for those cases.

Conclusion

The full querying pipeline — query configs, ctx.paginate(), buildMongo* helpers, and the findPaginated repository pattern — gives us:

Consistency: every list endpoint works the same way
Discoverability: Swagger docs auto-generated from the same config
Safety: only whitelisted fields can be filtered/sorted
Performance: parallel data + count queries, MongoDB indexes
DX: adding a new paginated endpoint takes 5 minutes

If you're building an API with more than a handful of list endpoints, standardize early. Your frontend team will thank you.

This article is part of a series on building Vibed, a Jira-like task management backend with KickJS. Check out the complete project guide for the full walkthrough.

Building a Complete Jira-like Task Management Backend with KickJS — From Scaffold to Production

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:30:10 +0000

TL;DR

This is the complete project guide for Vibed — a Jira-like task management backend built with KickJS v1.2.2. It covers everything from initial scaffold to production-ready features: 14 modules, 65+ endpoints, real-time WebSocket chat, SSE live dashboards, BullMQ background jobs, cron scheduling, and the framework issues we filed along the way.

If you've been following the article series, this brings it all together. If you're starting here, this is everything you need to build a non-trivial backend with KickJS.

1. Project Overview and Tech Stack

Vibed is a task management platform modeled after Jira's API surface. It supports workspaces, projects, task boards with drag-and-drop reordering, comments with @mentions, file attachments, real-time chat channels, live dashboard stats, email notifications, and activity feeds.

Concern	Technology
Framework	KickJS v1.2.2 (`@forinda/kickjs-*` packages)
Language	TypeScript (ESM)
Database	MongoDB via Mongoose 9
Cache / Queue broker	Redis (ioredis)
Background jobs	BullMQ
Auth	JWT (access + refresh token rotation), bcryptjs
Email	Resend (production) / ConsoleProvider (development)
Real-time	WebSocket chat (Socket.IO via WsAdapter)
Live updates	Server-Sent Events via `ctx.sse()`
Scheduled jobs	CronAdapter (overdue reminders, daily digest, token cleanup, presence cleanup)
API docs	Swagger via SwaggerAdapter
Dev tools	DevToolsAdapter at `/_debug/*`
Build	Vite + SWC
Package manager	pnpm

KickJS is a decorator-driven Node.js framework built on Express 5. It uses TypeScript decorators for routing (@Get, @Post), dependency injection (@Service, @Inject, @Autowired), validation (@Validate with Zod), and documentation (@ApiTags, @ApiOperation). If you've used NestJS, the patterns will feel familiar — but KickJS is lighter, uses Express directly, and emphasizes convention over configuration.

2. Project Setup

Scaffolding

kick new vibed --pm pnpm
kick add auth ws mailer queue cron swagger devtools

The first command scaffolds a KickJS project with the REST template. The second adds adapter packages for auth, WebSocket, email, queues, cron, Swagger, and dev tools.

Module Generation

kick g module tasks
kick g module workspaces
kick g module comments
# ... repeat for each module

Each kick g module creates the full DDD directory structure:

module/
├── <name>.module.ts              # AppModule: register() + routes()
├── presentation/
│   └── <name>.controller.ts      # @Controller, @Get, @Post, etc.
├── application/
│   ├── dtos/                     # Zod validation schemas
│   └── use-cases/                # Single-purpose business logic classes
├── domain/
│   ├── entities/                 # TypeScript interfaces
│   └── repositories/            # Repository interfaces
└── infrastructure/
    ├── schemas/                  # Mongoose schemas + models
    └── repositories/            # Mongo repository implementations

Environment Configuration with Zod

All environment variables are validated at startup via Zod:

// src/config/env.ts
import { z } from 'zod';
import { defineEnv, loadEnv } from '@forinda/kickjs-config';

const envSchema = defineEnv((base) =>
  base.extend({
    MONGODB_URI: z.string().url(),
    REDIS_URL: z.string().url(),
    JWT_SECRET: z.string().min(32),
    JWT_REFRESH_SECRET: z.string().min(32),
    JWT_ACCESS_EXPIRES_IN: z.string().default('15m'),
    JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
    RESEND_API_KEY: z.string().min(1),
    MAIL_FROM_NAME: z.string().default('Vibed'),
    MAIL_FROM_EMAIL: z.string().email(),
    APP_URL: z.string().url(),
    APP_NAME: z.string().default('Vibed'),
  }),
);

export const env = loadEnv(envSchema);

If any required variable is missing or invalid, the app fails fast at startup with a clear Zod validation error. No more "undefined is not a function" errors 10 minutes into runtime because REDIS_URL was misspelled.

Entry Point

The entry point is deliberately minimal — all configuration is delegated to dedicated files:

// src/index.ts
import 'reflect-metadata';
import { bootstrap } from '@forinda/kickjs-http';
import { modules } from './modules';
import { adapters } from './config/adapters';
import { middleware } from './config/middleware';

bootstrap({
  modules,
  apiPrefix: '/api',
  defaultVersion: 1,
  middleware,
  adapters,
});

Global middleware uses Express signatures (not KickJS RequestContext):

// src/config/middleware.ts
import express from 'express';
import cors from 'cors';
import helmet from 'helmet';
import { requestIdMiddleware } from '@/shared/presentation/middlewares/request-id.middleware';

export const middleware = [
  requestIdMiddleware,
  cors(),
  helmet(),
  express.json({ limit: '5mb' }),
  express.urlencoded({ extended: true }),
];

3. Authentication: JWT with Refresh Rotation

The Auth Controller

Auth endpoints are public — no authBridgeMiddleware:

@ApiTags('Auth')
@Controller()
export class AuthController {
  @Autowired() private registerUseCase!: RegisterUseCase;
  @Autowired() private loginUseCase!: LoginUseCase;
  @Autowired() private refreshTokenUseCase!: RefreshTokenUseCase;
  @Autowired() private logoutUseCase!: LogoutUseCase;

  @Post('/register', { body: registerSchema })
  @Public()
  @ApiOperation({ summary: 'Register a new user account' })
  async register(ctx: RequestContext) {
    const result = await this.registerUseCase.execute(ctx.body);
    ctx.created(successResponse(result, 'Registration successful'));
  }

  @Post('/login', { body: loginSchema })
  @Public()
  async login(ctx: RequestContext) {
    const result = await this.loginUseCase.execute(ctx.body);
    ctx.json(successResponse(result, 'Login successful'));
  }

  @Post('/refresh', { body: refreshTokenSchema })
  @Public()
  async refresh(ctx: RequestContext) {
    const result = await this.refreshTokenUseCase.execute(ctx.body);
    ctx.json(successResponse(result));
  }
}

DTOs are Zod schemas:

// register.dto.ts
export const registerSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8).max(128),
  firstName: z.string().min(1).max(50),
  lastName: z.string().min(1).max(50),
});

// login.dto.ts
export const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(1),
});

The Auth Bridge Middleware

Every protected controller uses authBridgeMiddleware at the class level:

// src/shared/presentation/middlewares/auth-bridge.middleware.ts
export const authBridgeMiddleware: MiddlewareHandler = (ctx: RequestContext, next) => {
  const user = (ctx.req as any).user;
  if (user) {
    ctx.set('user', user);
  }
  next();
};

The AuthAdapter with JwtStrategy validates the JWT and puts the user on req.user. The bridge middleware copies it to ctx metadata so handlers can use ctx.get('user') or the getUser() helper.

The getUser Helper

// src/shared/utils/auth.ts
export function getUser(ctx: RequestContext): AuthUser {
  const user = ctx.get<AuthUser>('user');
  if (!user) throw HttpException.unauthorized('Authentication required');
  return user;
}

Every controller that needs the current user calls getUser(ctx) instead of accessing context directly. This abstraction saved us when the framework fixed the ctx.set/get sharing bug in v1.2.5 — one file changed, zero controllers touched.

Guards

Role-based access uses guard middleware that composes with authBridgeMiddleware:

// src/shared/guards/workspace-membership.guard.ts
export const workspaceMembershipGuard: MiddlewareHandler = async (ctx, next) => {
  const user = ctx.get('user');
  if (!user) throw HttpException.unauthorized('Authentication required');

  const workspaceId = ctx.params.workspaceId;
  if (!workspaceId) return next();

  const container = Container.getInstance();
  const memberRepo = container.resolve<IWorkspaceMemberRepository>(
    TOKENS.WORKSPACE_MEMBER_REPOSITORY,
  );
  const member = await memberRepo.findByUserAndWorkspace(user.id, workspaceId);

  if (!member) throw HttpException.forbidden(ErrorCode.NOT_WORKSPACE_MEMBER);

  ctx.set('workspaceMember', member);
  next();
};

Guards resolve repositories from the DI container at request time via Container.getInstance(). This avoids circular dependency issues that arise when guards depend on repositories that depend on modules.

4. Core Modules: DDD Structure Walkthrough

The Module Registry

All modules are registered in src/modules/index.ts:

import type { AppModuleClass } from '@forinda/kickjs-core';
import { AuthModule } from './auth/auth.module';
import { UsersModule } from './users/users.module';
import { WorkspacesModule } from './workspaces/workspaces.module';
import { ProjectsModule } from './projects/projects.module';
import { TasksModule } from './tasks/tasks.module';
import { CommentsModule } from './comments/comments.module';
import { LabelsModule } from './labels/labels.module';
import { ChannelsModule } from './channels/channels.module';
import { MessagesModule } from './messages/messages.module';
import { NotificationsModule } from './notifications/notifications.module';
import { ActivityModule } from './activity/activity.module';
import { AttachmentsModule } from './attachments/attachments.module';
import { StatsModule } from './stats/stats.module';
import { QueueModule } from './queue/queue.module';

export const modules: AppModuleClass[] = [
  QueueModule,
  AuthModule,
  UsersModule,
  WorkspacesModule,
  ProjectsModule,
  LabelsModule,
  TasksModule,
  CommentsModule,
  AttachmentsModule,
  ActivityModule,
  NotificationsModule,
  ChannelsModule,
  MessagesModule,
  StatsModule,
];

Tasks Module — A Complete Walkthrough

The tasks module is the most feature-rich. Let me walk through each layer.

Module registration maps the DI token to the concrete repository:

// src/modules/tasks/tasks.module.ts
export class TasksModule implements AppModule {
  register(container: Container): void {
    container.registerFactory(TOKENS.TASK_REPOSITORY, () =>
      container.resolve(MongoTaskRepository),
    );
  }

  routes(): ModuleRoutes {
    return {
      path: '/',
      router: buildRoutes(TasksController),
      controller: TasksController,
    };
  }
}

The path: '/' means routes are mounted at the API root. The controller defines the full paths: /projects/:projectId/tasks, /tasks/:taskId, etc.

Mongoose schema with HMR guard:

// src/modules/tasks/infrastructure/schemas/task.schema.ts
const taskSchema = new Schema<TaskDocument>(
  {
    projectId: { type: Schema.Types.ObjectId, ref: 'Project', required: true, index: true },
    workspaceId: { type: Schema.Types.ObjectId, ref: 'Workspace', required: true, index: true },
    key: { type: String, required: true, unique: true, index: true },
    title: { type: String, required: true, trim: true },
    description: { type: String },
    status: { type: String, default: 'todo' },
    priority: { type: String, enum: ['critical', 'high', 'medium', 'low', 'none'], default: 'none' },
    assigneeIds: [{ type: Schema.Types.ObjectId, ref: 'User' }],
    reporterId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
    labelIds: [{ type: Schema.Types.ObjectId, ref: 'Label' }],
    parentTaskId: { type: Schema.Types.ObjectId, ref: 'Task' },
    dueDate: { type: Date },
    estimatePoints: { type: Number },
    orderIndex: { type: Number, default: 0 },
  },
  { timestamps: true },
);

// HMR guard — REQUIRED for Vite dev server
export const TaskModel =
  (mongoose.models.Task as mongoose.Model<TaskDocument>) ||
  mongoose.model<TaskDocument>('Task', taskSchema);

Without the HMR guard, every file save that triggers a re-import crashes with OverwriteModelError.

Use case with constructor DI injection:

// src/modules/tasks/application/use-cases/create-task.use-case.ts
@Service()
export class CreateTaskUseCase {
  constructor(
    @Inject(TOKENS.TASK_REPOSITORY) private taskRepo: ITaskRepository,
    @Inject(TOKENS.PROJECT_REPOSITORY) private projectRepo: IProjectRepository,
  ) {}

  async execute(projectId: string, userId: string, dto: CreateTaskDto) {
    const project = await this.projectRepo.findById(projectId);
    if (!project) throw new Error('Project not found');

    const counter = await this.projectRepo.incrementTaskCounter(projectId);
    const key = `${project.key}-${counter}`;

    const maxOrderTask = await this.taskRepo.findByProject(projectId);
    const maxOrder = maxOrderTask.length > 0
      ? Math.max(...maxOrderTask.filter(t => t.status === dto.status).map(t => t.orderIndex))
      : -1;

    return this.taskRepo.create({
      ...dto,
      projectId: projectId as any,
      workspaceId: project.workspaceId,
      key,
      reporterId: userId as any,
      orderIndex: maxOrder + 1,
    });
  }
}

The task key pattern (PROJ-1, PROJ-2, etc.) mirrors Jira's issue keys. incrementTaskCounter atomically increments a counter on the project document to ensure uniqueness.

Controller with property injection via @Autowired():

@ApiTags('Tasks')
@ApiBearerAuth()
@Middleware(authBridgeMiddleware)
@Controller()
export class TasksController {
  @Autowired() private createTaskUseCase!: CreateTaskUseCase;
  @Autowired() private taskRepo!: MongoTaskRepository;

  @Post('/projects/:projectId/tasks', {
    params: z.object({ projectId: z.string() }),
    body: createTaskSchema,
  })
  @Middleware(projectAccessGuard)
  @ApiOperation({ summary: 'Create a new task in a project' })
  @ApiResponse({ status: 201, description: 'Task created successfully' })
  async create(ctx: RequestContext) {
    const user = ctx.get('user');
    const result = await this.createTaskUseCase.execute(ctx.params.projectId, user.id, ctx.body);
    ctx.created(successResponse(result, 'Task created'));
  }

  @Get('/projects/:projectId/tasks', {
    params: z.object({ projectId: z.string() }),
  })
  @Middleware(projectAccessGuard)
  @ApiQueryParams(TASK_QUERY_CONFIG)
  async list(ctx: RequestContext) {
    await ctx.paginate(
      async (parsed) => {
        parsed.filters.push({ field: 'projectId', operator: 'eq', value: ctx.params.projectId });
        return this.taskRepo.findPaginated(parsed);
      },
      TASK_QUERY_CONFIG,
    );
  }
}

DI Pattern Summary

Where	Technique	When to Use
Controller properties	`@Autowired()`	Concrete classes (use cases, repos)
Use case constructor	`@Inject(TOKENS.X)`	Interface-based repos via Symbol tokens
Processor constructor	`@Inject(MAILER)`	Framework service symbols
Module `register()`	`container.registerFactory()`	Mapping tokens to implementations

Critical rule: @Inject(TOKEN) only works on constructor parameters. @Autowired() only works on properties (resolves by class type). Mixing them up causes silent failures.

5. Supporting Modules

Labels

Workspace-scoped label CRUD. Labels can be attached to tasks via labelIds. Nothing complex — standard CRUD with workspaceMembershipGuard.

Comments

Comment CRUD with @mention parsing. Creating a comment triggers a notification job via BullMQ. The @mention pattern is parsed from the comment content and stored as a mentions array on the comment document.

Attachments

File upload using multipart form data. Files are converted to base64 and stored in MongoDB (not ideal for production, but keeps the stack simple). The controller increments task.attachmentCount for denormalized display.

Notifications

In-app notification system. Notifications are created by background jobs (not directly by controllers). Endpoints: list paginated, mark as read, mark all as read, unread count. The unread count endpoint is what the frontend polls for the notification badge.

6. Real-Time: WebSocket Chat and SSE Stats

WebSocket Chat

The ChatWsController handles real-time messaging via Socket.IO rooms:

@WsController('/chat')
export class ChatWsController {
  @Autowired() private messageRepo!: MongoMessageRepository;

  @OnConnect()
  handleConnect(ctx: WsContext) {
    const token = ctx.data?.token || '';
    const payload = jwt.verify(token, env.JWT_SECRET) as any;
    ctx.set('userId', payload.sub);
    onlineUsers.set(ctx.id, { userId: payload.sub, userName: payload.email });
    ctx.broadcastAll('presence:online', { userId: payload.sub, userName: payload.email });
  }

  @OnMessage('channel:join')
  handleJoin(ctx: WsContext) {
    const channelId = ctx.data?.channelId;
    ctx.join(`channel:${channelId}`);
    ctx.to(`channel:${channelId}`).send('channel:user_joined', {
      channelId,
      userId: ctx.get('userId'),
    });
  }

  @OnMessage('channel:typing')
  handleTyping(ctx: WsContext) {
    const { channelId } = ctx.data || {};
    const info = onlineUsers.get(ctx.id);
    ctx.to(`channel:${channelId}`).send('channel:typing', {
      channelId,
      userId: ctx.get('userId'),
      userName: info?.userName,
    });
  }

  @OnMessage('message:send')
  async handleSend(ctx: WsContext) {
    const userId = ctx.get('userId');
    const { channelId, content } = ctx.data || {};

    const message = await this.messageRepo.create({
      channelId, senderId: userId, content, mentions: [],
    });

    const payload = {
      messageId: message._id.toString(),
      channelId,
      senderId: userId,
      content: message.content,
      createdAt: message.createdAt,
    };

    ctx.to(`channel:${channelId}`).send('message:new', payload);
    ctx.send('message:new', payload); // Echo to sender
  }
}

WebSocket events: channel:join, channel:leave, message:send, message:edit, message:delete, channel:typing, channel:stop_typing.

REST endpoints handle message history and editing: GET /channels/:channelId/messages, PATCH /messages/:messageId, DELETE /messages/:messageId.

SSE Live Stats

The stats module uses ctx.sse() for server-pushed updates:

@Controller()
@Middleware(authBridgeMiddleware)
export class StatsController {
  @Autowired() private taskRepo!: MongoTaskRepository;

  @Get('/projects/:projectId/stats/live')
  @Middleware(projectAccessGuard)
  async projectLive(ctx: RequestContext) {
    const sse = ctx.sse();
    const projectId = ctx.params.projectId;

    const sendStats = async () => {
      const tasksByStatus = await this.taskRepo.countByStatus(projectId);
      const totalTasks = Object.values(tasksByStatus).reduce((sum, c) => sum + c, 0);
      const doneTasks = tasksByStatus['done'] ?? 0;
      const completionRate = totalTasks > 0 ? Math.round((doneTasks / totalTasks) * 100) : 0;

      sse.send({ tasksByStatus, totalTasks, completionRate }, 'stats:update');
    };

    await sendStats();
    const interval = setInterval(sendStats, 10000);
    sse.onClose(() => clearInterval(interval));
  }
}

SSE endpoints: workspace live stats, project live stats, workspace activity live.

7. Background Jobs: BullMQ Processors

Queue Configuration

// src/config/adapters.ts
const queueAdapter = new QueueAdapter({
  redis: {
    host: redisUrl.hostname,
    port: Number(redisUrl.port) || 6379,
    password: redisUrl.password || undefined,
  },
  queues: ['email', 'notifications', 'activity'],
  concurrency: 5,
});

Email Processor

@Service()
@Job('email')
export class EmailProcessor {
  @Autowired(MAILER) private mailer!: MailerService;

  @Process('send-welcome-email')
  async sendWelcome(job: BullMQJob<{ email: string; firstName: string }>) {
    logger.info(`Sending welcome email to ${job.data.email}`);
    await this.mailer.send({
      to: job.data.email,
      subject: `Welcome to Vibed, ${job.data.firstName}!`,
      html: `<h1>Welcome to Vibed!</h1><p>Hi ${job.data.firstName}, your account is ready.</p>`,
    });
  }

  @Process('send-task-assigned')
  async sendTaskAssigned(job: BullMQJob<{ email: string; taskKey: string; taskTitle: string }>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `You were assigned to ${job.data.taskKey}: ${job.data.taskTitle}`,
      html: `<p>You were assigned to <strong>${job.data.taskKey}</strong></p>`,
    });
  }

  @Process('send-overdue-reminder')
  async sendOverdueReminder(job: BullMQJob<{ email: string; taskKey: string; dueDate: string }>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `Overdue: ${job.data.taskKey}`,
      html: `<p>Task ${job.data.taskKey} was due on ${job.data.dueDate}</p>`,
    });
  }
}

The QueueModule imports processors as side-effects so @Job() decorators register in the job registry:

// src/modules/queue/queue.module.ts
import './infrastructure/processors/email.processor';
import './infrastructure/processors/notification.processor';
import './infrastructure/processors/activity.processor';

export class QueueModule implements AppModule {
  register(_container: Container): void {
    // QueueAdapter v1.2.6+ auto-registers @Job classes
  }

  routes(): ModuleRoutes | null {
    return null; // No HTTP routes
  }
}

Cron Jobs

@Service()
export class PresenceCronJobs {
  @Cron('*/5 * * * *', { description: 'Clean up stale presence entries' })
  async cleanupPresence() {
    logger.info('Running presence cleanup...');
  }
}

Cron services are registered in the CronAdapter, not in the modules array:

new CronAdapter({
  services: [TaskCronJobs, DigestCronJobs, CleanupCronJobs, PresenceCronJobs, HealthCheckCronJobs],
  enabled: true,
});

8. Pagination: ctx.paginate and Query Configs

Defining Query Configs

All query configurations are centralized in shared/constants/query-configs.ts:

import type { ApiQueryParamsConfig } from '@forinda/kickjs-core';

export const TASK_QUERY_CONFIG: ApiQueryParamsConfig = {
  filterable: ['status', 'priority', 'assigneeId', 'labelId', 'projectId'],
  sortable: ['createdAt', 'title', 'priority', 'dueDate', 'orderIndex'],
  searchable: ['title', 'description'],
};

export const WORKSPACE_QUERY_CONFIG: ApiQueryParamsConfig = {
  sortable: ['name', 'createdAt'],
  searchable: ['name', 'description'],
};

Using ctx.paginate

The controller passes a fetcher function and the config to ctx.paginate():

@Get('/projects/:projectId/tasks')
@ApiQueryParams(TASK_QUERY_CONFIG)
async list(ctx: RequestContext) {
  await ctx.paginate(
    async (parsed) => {
      parsed.filters.push({ field: 'projectId', operator: 'eq', value: ctx.params.projectId });
      return this.taskRepo.findPaginated(parsed);
    },
    TASK_QUERY_CONFIG,
  );
}

ctx.paginate() calls ctx.qs() internally to parse query string parameters, then calls the fetcher with the parsed result. The response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Query Helpers

Repositories use helper functions to convert parsed query params to Mongoose operations:

export function buildMongoFilter(
  filters: Array<{ field: string; operator: string; value: string }>,
): Record<string, any> {
  const mongoFilter: Record<string, any> = {};
  for (const { field, operator, value } of filters) {
    switch (operator) {
      case 'eq': mongoFilter[field] = value; break;
      case 'neq': mongoFilter[field] = { $ne: value }; break;
      case 'in': mongoFilter[field] = { $in: value.split(',') }; break;
      case 'contains': mongoFilter[field] = { $regex: value, $options: 'i' }; break;
      // ... gt, gte, lt, lte, between, starts, ends
    }
  }
  return mongoFilter;
}

export function buildMongoSort(
  sort: Array<{ field: string; direction: 'asc' | 'desc' }>,
): Record<string, 1 | -1> {
  const mongoSort: Record<string, 1 | -1> = {};
  for (const { field, direction } of sort) {
    mongoSort[field] = direction === 'asc' ? 1 : -1;
  }
  if (Object.keys(mongoSort).length === 0) mongoSort.createdAt = -1;
  return mongoSort;
}

9. DI Tokens

All DI Symbol tokens are centralized in one file:

// src/shared/constants/tokens.ts
export const TOKENS = {
  USER_REPOSITORY: Symbol('UserRepository'),
  REFRESH_TOKEN_REPOSITORY: Symbol('RefreshTokenRepository'),
  WORKSPACE_REPOSITORY: Symbol('WorkspaceRepository'),
  WORKSPACE_MEMBER_REPOSITORY: Symbol('WorkspaceMemberRepository'),
  PROJECT_REPOSITORY: Symbol('ProjectRepository'),
  TASK_REPOSITORY: Symbol('TaskRepository'),
  COMMENT_REPOSITORY: Symbol('CommentRepository'),
  LABEL_REPOSITORY: Symbol('LabelRepository'),
  CHANNEL_REPOSITORY: Symbol('ChannelRepository'),
  MESSAGE_REPOSITORY: Symbol('MessageRepository'),
  NOTIFICATION_REPOSITORY: Symbol('NotificationRepository'),
  ACTIVITY_REPOSITORY: Symbol('ActivityRepository'),
  ATTACHMENT_REPOSITORY: Symbol('AttachmentRepository'),
  PRESENCE_SERVICE: Symbol('PresenceService'),
  QUEUE_SERVICE: Symbol('QueueService'),
} as const;

10. Full Module Structure

src/
├── index.ts                          # Entry point
├── config/
│   ├── env.ts                        # Zod env validation
│   ├── adapters.ts                   # All adapter configurations
│   └── middleware.ts                  # Global Express middleware
├── shared/
│   ├── constants/
│   │   ├── tokens.ts                 # DI Symbol tokens
│   │   ├── error-codes.ts            # Error code enum
│   │   └── query-configs.ts          # Pagination configs
│   ├── guards/
│   │   ├── workspace-membership.guard.ts
│   │   ├── project-access.guard.ts
│   │   └── channel-membership.guard.ts
│   ├── presentation/middlewares/
│   │   ├── auth-bridge.middleware.ts
│   │   └── request-id.middleware.ts
│   ├── utils/
│   │   └── auth.ts                   # getUser(ctx) helper
│   └── infrastructure/
│       ├── database/
│       │   ├── mongoose.adapter.ts
│       │   └── query-helpers.ts
│       ├── redis/
│       │   └── redis.config.ts
│       └── mail/
│           └── resend.provider.ts
└── modules/
    ├── index.ts                      # Module registry
    ├── auth/                         # Register, login, refresh, logout
    ├── users/                        # Profile CRUD
    ├── workspaces/                   # CRUD + membership + invite
    ├── projects/                     # CRUD + board view
    ├── tasks/                        # CRUD + status/priority/assignees/reorder
    ├── comments/                     # CRUD + @mention parsing
    ├── labels/                       # Workspace-scoped label CRUD
    ├── channels/                     # Chat channel CRUD + membership
    ├── messages/                     # REST history + WebSocket chat
    ├── notifications/                # In-app notifications + unread count
    ├── activity/                     # Activity feed
    ├── attachments/                  # File upload
    ├── stats/                        # SSE live dashboards
    ├── queue/                        # BullMQ processors
    └── cron/                         # Scheduled jobs

11. API Endpoint Summary

Base prefix: /api/v1

Auth (`/api/v1/auth`) — No auth required

Method	Path	Description
POST	`/register`	Register new user
POST	`/login`	Login with credentials
POST	`/refresh`	Refresh JWT token pair
POST	`/logout`	Logout (invalidate refresh)

Users (`/api/v1/users`)

Method	Path	Description
GET	`/me`	Current user profile
PATCH	`/me`	Update profile
GET	`/:id`	Get user by ID
GET	`/`	List users (paginated)

Workspaces (`/api/v1/workspaces`)

Method	Path	Description
POST	`/`	Create workspace
GET	`/`	List user's workspaces
GET	`/:workspaceId`	Get workspace
PATCH	`/:workspaceId`	Update workspace
DELETE	`/:workspaceId`	Delete workspace
POST	`/:workspaceId/invite`	Invite member
GET	`/:workspaceId/members`	List members
PATCH	`/:workspaceId/members/:userId`	Update member role
DELETE	`/:workspaceId/members/:userId`	Remove member
POST	`/:workspaceId/leave`	Leave workspace

Projects (`/api/v1`)

Method	Path	Description
POST	`/workspaces/:workspaceId/projects`	Create project
GET	`/workspaces/:workspaceId/projects`	List projects
GET	`/projects/:projectId`	Get project
PATCH	`/projects/:projectId`	Update project
DELETE	`/projects/:projectId`	Delete project
GET	`/projects/:projectId/board`	Board view

Tasks (`/api/v1`)

Method	Path	Description
POST	`/projects/:projectId/tasks`	Create task
GET	`/projects/:projectId/tasks`	List tasks (paginated)
GET	`/tasks/:taskId`	Get task
PATCH	`/tasks/:taskId`	Update task
DELETE	`/tasks/:taskId`	Delete task
PATCH	`/tasks/:taskId/status`	Change status
PATCH	`/tasks/:taskId/assignees`	Update assignees
POST	`/tasks/:taskId/reorder`	Reorder in column
GET	`/tasks/:taskId/subtasks`	List subtasks

Comments (`/api/v1`)

Method	Path	Description
POST	`/tasks/:taskId/comments`	Create comment
GET	`/tasks/:taskId/comments`	List comments
PATCH	`/comments/:commentId`	Update comment
DELETE	`/comments/:commentId`	Delete comment

Labels (`/api/v1`)

Method	Path	Description
POST	`/workspaces/:workspaceId/labels`	Create label
GET	`/workspaces/:workspaceId/labels`	List labels
PATCH	`/labels/:labelId`	Update label
DELETE	`/labels/:labelId`	Delete label

Attachments (`/api/v1`)

Method	Path	Description
POST	`/tasks/:taskId/attachments`	Upload
GET	`/tasks/:taskId/attachments`	List
GET	`/attachments/:attachmentId`	Metadata
GET	`/attachments/:attachmentId/download`	Download
DELETE	`/attachments/:attachmentId`	Delete

Channels (`/api/v1`)

Method	Path	Description
POST	`/workspaces/:workspaceId/channels`	Create channel
GET	`/workspaces/:workspaceId/channels`	List channels
GET	`/channels/:channelId`	Get channel
DELETE	`/channels/:channelId`	Delete channel
POST	`/channels/:channelId/members`	Add member
DELETE	`/channels/:channelId/members/:userId`	Remove member

Messages (`/api/v1`)

Method	Path	Description
GET	`/channels/:channelId/messages`	Message history
PATCH	`/messages/:messageId`	Edit message
DELETE	`/messages/:messageId`	Delete message

Notifications (`/api/v1/notifications`)

Method	Path	Description
GET	`/`	List (paginated)
PATCH	`/:id/read`	Mark as read
POST	`/read-all`	Mark all as read
GET	`/unread-count`	Unread count

Activity (`/api/v1`)

Method	Path	Description
GET	`/workspaces/:workspaceId/activity`	Workspace activity
GET	`/projects/:projectId/activity`	Project activity
GET	`/tasks/:taskId/activity`	Task activity

Stats — SSE (`/api/v1`)

Method	Path	Description
GET	`/workspaces/:workspaceId/stats/live`	SSE workspace stats
GET	`/projects/:projectId/stats/live`	SSE project stats
GET	`/workspaces/:workspaceId/activity/live`	SSE activity stream

WebSocket (`/ws/chat`)

Event	Direction	Description
`channel:join`	Client -> Server	Join room
`channel:leave`	Client -> Server	Leave room
`message:send`	Client -> Server	Send message
`message:edit`	Client -> Server	Edit message
`message:delete`	Client -> Server	Delete message
`channel:typing`	Client -> Server	Typing indicator
`channel:stop_typing`	Client -> Server	Stop typing

12. Framework Issues and Contributing Back

We tracked 18 framework issues in framework-filed-issues/ — 13 bug reports, 1 documentation issue, and 4 feature requests. Seven issues were fixed across four KickJS releases (v1.2.3, v1.2.5, v1.2.6, v1.2.7).

Key issues and their resolutions:

Issue	Problem	Resolution
KICK-003	Modules without routes crash Express	v1.2.3: `routes()` can return `null`
KICK-009	`ctx.set/get` not shared across middleware/handler	v1.2.5: Metadata Map stored on `req`
KICK-016	`@Service + @Job` not auto-registered in DI	v1.2.6: QueueAdapter auto-registers
KICK-017	`@Service()` should mean auto-DI-registration	v1.2.7: Container.bootstrap() scans

The feedback loop that made this work: discover the bug during development, build a workaround, file a detailed issue with a suggested fix, validate the upstream fix, remove the workaround, update the docs.

13. What's Next

Features planned but not yet implemented:

Typed API Client (KICK-018)

A kick generate:client command that produces a tRPC-like typed client from the existing route decorators and Zod DTOs. All the metadata exists — it just needs to be surfaced to a client generator.

Subtask CRUD

The task schema already has parentTaskId. Full subtask CRUD (create, list, reparent, delete) is the next module addition.

Forgot Password Flow

The email processor already has send-password-reset. The missing piece is the auth controller endpoint (POST /auth/forgot-password) and a time-limited reset token stored in Redis.

Redis-Backed Presence

The current in-memory onlineUsers Map works for single-instance deployments. For horizontal scaling, presence needs to move to Redis with the @socket.io/redis-adapter.

Full-Text Search Upgrade

The current $text search works but is limited. Moving to MongoDB Atlas Search or Elasticsearch would enable fuzzy matching, typo tolerance, and field-weighted ranking.

Quick Reference

Commands

kick dev              # Dev server with Vite HMR
kick build            # Production build
kick start            # Run production build
kick g module <name>  # Generate DDD module scaffold
kick g controller <n> # Generate controller
kick g dto <name>     # Generate Zod DTO

What Survives HMR

Controller logic, use cases, DTOs, guards, middleware, Mongoose schemas (with guard)

What Needs Full Restart

Adapter config changes, new modules in array, new adapters, queue processor class changes

Key File Paths

File	Purpose
`src/index.ts`	Entry point
`src/config/adapters.ts`	All adapter configurations
`src/config/env.ts`	Zod env validation
`src/modules/index.ts`	Module registry
`src/shared/constants/tokens.ts`	DI Symbol tokens
`src/shared/constants/query-configs.ts`	Pagination configs
`src/shared/utils/auth.ts`	`getUser(ctx)` helper
`src/shared/guards/`	Access control guards
`framework-filed-issues/`	Framework issue tracker

This is the final article in the "Building with KickJS" series. The full project source is available on GitHub. If you build something with KickJS, I'd genuinely like to hear about it.

Real-Time Typing Indicators and Presence Tracking with KickJS and Socket.IO

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:26:13 +0000

TL;DR

KickJS WsAdapter wraps Socket.IO with decorator-driven WebSocket controllers
Room-based broadcasting (ctx.join(), ctx.to().send()) is the right abstraction for channel-based apps like Slack or Jira comments
Typing indicators use channel:typing / channel:stop_typing events with room-scoped broadcasting
In-memory presence tracking with a Map<socketId, userInfo> handles online/offline status
A cron job cleans up stale presence entries for resilience
Rooms beat individual socket tracking for multi-channel apps because they eliminate manual fan-out logic

The Setup: WebSocket Namespaces with KickJS

Vibed has a real-time chat system built into its task management backend. Users join workspace channels and exchange messages in real time. The WebSocket layer handles message delivery, typing indicators, and presence — while REST endpoints handle message history, editing, and deletion.

KickJS wraps Socket.IO behind a decorator-driven API via WsAdapter. The adapter is configured in config/adapters.ts:

import { WsAdapter } from '@forinda/kickjs-ws';

const wsAdapter = new WsAdapter({
  path: '/ws',
  heartbeatInterval: 30000,
  maxPayload: 1048576, // 1MB
});

export const adapters = [
  // ... other adapters
  wsAdapter,
  // ...
];

The path: '/ws' sets the Socket.IO handshake endpoint. Clients connect with:

const socket = io('http://localhost:3000', { path: '/ws' });

The heartbeatInterval: 30000 means Socket.IO pings every 30 seconds to detect dead connections. The maxPayload caps message size at 1MB to prevent abuse.

The WebSocket Controller

KickJS provides decorators for WebSocket event handling that mirror the HTTP controller pattern. Instead of @Get and @Post, you use @OnConnect, @OnDisconnect, and @OnMessage.

Here's the complete ChatWsController from Vibed:

import { WsController, OnConnect, OnDisconnect, OnMessage } from '@forinda/kickjs-ws';
import type { WsContext } from '@forinda/kickjs-ws';
import { Autowired, Logger } from '@forinda/kickjs-core';
import jwt from 'jsonwebtoken';
import { env } from '@/config/env';
import { MongoMessageRepository } from '../infrastructure/repositories/mongo-message.repository';

const logger = Logger.for('ChatWsController');

// In-memory online users map
const onlineUsers = new Map<string, { userId: string; userName: string }>();

@WsController('/chat')
export class ChatWsController {
  @Autowired() private messageRepo!: MongoMessageRepository;

  @OnConnect()
  handleConnect(ctx: WsContext) {
    try {
      const token = ctx.data?.token || '';
      const payload = jwt.verify(token, env.JWT_SECRET) as any;
      const userId = payload.sub;
      const email = payload.email;

      ctx.set('userId', userId);
      ctx.set('email', email);
      onlineUsers.set(ctx.id, { userId, userName: email });

      ctx.send('welcome', { id: ctx.id, userId });
      ctx.broadcastAll('presence:online', { userId, userName: email });
      logger.info(`User ${email} connected (${ctx.id})`);
    } catch {
      ctx.send('error', { message: 'Invalid authentication token' });
      logger.warn(`Connection rejected: invalid token (${ctx.id})`);
    }
  }

  @OnDisconnect()
  handleDisconnect(ctx: WsContext) {
    const info = onlineUsers.get(ctx.id);
    if (info) {
      ctx.broadcastAll('presence:offline', { userId: info.userId });
      onlineUsers.delete(ctx.id);
      logger.info(`User ${info.userName} disconnected (${ctx.id})`);
    }
  }

  // ... message and typing handlers below
}

The @WsController('/chat') decorator registers this controller under the /chat namespace. So the full connection URL is ws://localhost:3000/ws/chat. The namespace is important — it means Vibed could add other namespaces later (like /notifications for real-time notification push) without interference.

Authentication on Connect

WebSocket connections don't carry HTTP headers the same way REST calls do. I handle auth during the connection handshake by requiring the client to send a JWT token in the connection payload:

// Client-side
const socket = io('http://localhost:3000/chat', {
  path: '/ws',
  auth: { token: accessToken },
});

On the server, ctx.data?.token reads the auth payload. If jwt.verify() throws, the connection stays alive but the user gets an error event. In a stricter setup, you could disconnect them immediately — but for Vibed, I let the connection stay open so the client can retry with a fresh token.

The verified user info is stored in two places:

ctx.set('userId', userId) — for the current connection's context, so later event handlers can read it
onlineUsers.set(ctx.id, ...) — for the global presence map, so other connections can query who's online

Room-Based Broadcasting

This is the core concept that makes channel-based chat work efficiently. Instead of maintaining a list of socket IDs per channel and manually emitting to each one, Socket.IO (and KickJS's WsContext) provides rooms.

Joining and Leaving Rooms

When a user opens a channel in the UI, the client emits channel:join. When they navigate away, it emits channel:leave:

@OnMessage('channel:join')
handleJoin(ctx: WsContext) {
  const channelId = ctx.data?.channelId;
  if (!channelId) return;
  ctx.join(`channel:${channelId}`);
  ctx.to(`channel:${channelId}`).send('channel:user_joined', {
    channelId,
    userId: ctx.get('userId'),
  });
}

@OnMessage('channel:leave')
handleLeave(ctx: WsContext) {
  const channelId = ctx.data?.channelId;
  if (!channelId) return;
  ctx.leave(`channel:${channelId}`);
  ctx.to(`channel:${channelId}`).send('channel:user_left', {
    channelId,
    userId: ctx.get('userId'),
  });
}

The key methods:

ctx.join('channel:abc') — Adds this socket to the channel:abc room. The socket can be in multiple rooms simultaneously (a user can have multiple channels open in tabs).
ctx.leave('channel:abc') — Removes this socket from the room.
ctx.to('channel:abc').send(event, data) — Broadcasts to all sockets in the room except the sender.

The room name is prefixed with channel: as a namespace convention. This prevents collisions if I later add project: or workspace: rooms for different broadcast purposes.

Sending Messages

When a user sends a message, it's persisted to MongoDB via the message repository and then broadcast to the room:

@OnMessage('message:send')
async handleSend(ctx: WsContext) {
  const userId = ctx.get('userId');
  if (!userId) return ctx.send('error', { message: 'Not authenticated' });

  const { channelId, content } = ctx.data || {};
  if (!channelId || !content) return;

  const message = await this.messageRepo.create({
    channelId: channelId as any,
    senderId: userId as any,
    content,
    mentions: [],
  });

  const info = onlineUsers.get(ctx.id);
  const payload = {
    messageId: message._id.toString(),
    channelId,
    senderId: userId,
    senderName: info?.userName ?? 'Unknown',
    content: message.content,
    createdAt: message.createdAt,
  };

  ctx.to(`channel:${channelId}`).send('message:new', payload);
  ctx.send('message:new', payload); // Echo back to sender
}

Notice that ctx.to().send() excludes the sender, so I explicitly send the message back to the sender with ctx.send(). This is intentional — the sender needs the server-generated messageId and createdAt to update their local UI. In an optimistic-UI approach, you'd show the message immediately and then reconcile when the echo arrives.

Typing Indicators

Typing indicators are the "X is typing..." status you see in Slack, Discord, and every modern chat app. They need to be fast (low latency), cheap (no database writes), and scoped (only visible to users in the same channel).

The Events

Two events handle the full lifecycle:

@OnMessage('channel:typing')
handleTyping(ctx: WsContext) {
  const { channelId } = ctx.data || {};
  if (!channelId) return;
  const info = onlineUsers.get(ctx.id);
  ctx.to(`channel:${channelId}`).send('channel:typing', {
    channelId,
    userId: ctx.get('userId'),
    userName: info?.userName,
  });
}

@OnMessage('channel:stop_typing')
handleStopTyping(ctx: WsContext) {
  const { channelId } = ctx.data || {};
  if (!channelId) return;
  ctx.to(`channel:${channelId}`).send('channel:stop_typing', {
    channelId,
    userId: ctx.get('userId'),
  });
}

The server is a pure relay here. It doesn't track typing state — it just broadcasts the event to the room. This is by design: typing indicators are ephemeral, and storing them adds complexity with zero value.

Client-Side Implementation

The client needs debouncing to avoid flooding the server with typing events on every keystroke:

// Client-side typing indicator logic
let typingTimeout: ReturnType<typeof setTimeout> | null = null;
let isTyping = false;

function handleInput(channelId: string) {
  if (!isTyping) {
    socket.emit('channel:typing', { channelId });
    isTyping = true;
  }

  if (typingTimeout) clearTimeout(typingTimeout);

  typingTimeout = setTimeout(() => {
    socket.emit('channel:stop_typing', { channelId });
    isTyping = false;
  }, 2000); // Stop typing after 2 seconds of inactivity
}

// Listening for others typing
const typingUsers = new Map<string, string>();

socket.on('channel:typing', ({ userId, userName }) => {
  typingUsers.set(userId, userName);
  updateTypingUI();
});

socket.on('channel:stop_typing', ({ userId }) => {
  typingUsers.delete(userId);
  updateTypingUI();
});

function updateTypingUI() {
  const names = Array.from(typingUsers.values());
  if (names.length === 0) {
    typingLabel.textContent = '';
  } else if (names.length === 1) {
    typingLabel.textContent = `${names[0]} is typing...`;
  } else if (names.length === 2) {
    typingLabel.textContent = `${names[0]} and ${names[1]} are typing...`;
  } else {
    typingLabel.textContent = `${names[0]} and ${names.length - 1} others are typing...`;
  }
}

The debounce pattern: emit typing on first keystroke, then wait 2 seconds after the last keystroke to emit stop_typing. This gives a natural "typing..." experience without sending an event per character.

Why Rooms Make This Trivial

Without rooms, the typing handler would need to:

Look up which users are in the channel (database query or in-memory lookup)
Find their socket IDs (another lookup)
Emit to each socket individually (loop)
Handle the case where a user has multiple tabs open (deduplication)

With rooms, it's one line: ctx.to('channel:${channelId}').send(...). Socket.IO handles fan-out, multi-tab, and cleanup automatically. This is why rooms exist — they're the right primitive for group-scoped broadcasting.

In-Memory Presence Tracking

Presence tracking answers the question: "Who's online right now?" Vibed uses a module-level Map for this:

const onlineUsers = new Map<string, { userId: string; userName: string }>();

The key is the socket ID (ctx.id), and the value contains the user's identity. This map is updated on connect and disconnect:

// On connect
onlineUsers.set(ctx.id, { userId, userName: email });
ctx.broadcastAll('presence:online', { userId, userName: email });

// On disconnect
const info = onlineUsers.get(ctx.id);
if (info) {
  ctx.broadcastAll('presence:offline', { userId: info.userId });
  onlineUsers.delete(ctx.id);
}

The ctx.broadcastAll() sends to every connected socket, not just a room. Presence is a global concern — you want to show who's online in the workspace sidebar, not just in a specific channel.

Multi-Tab Handling

One user might have multiple tabs open, each with its own socket connection. The onlineUsers map has one entry per socket, not per user. This means a user with 3 tabs has 3 entries.

When broadcasting presence:offline, you need to check whether the user has other connections still alive:

@OnDisconnect()
handleDisconnect(ctx: WsContext) {
  const info = onlineUsers.get(ctx.id);
  if (info) {
    onlineUsers.delete(ctx.id);

    // Check if user has other active connections
    const stillOnline = Array.from(onlineUsers.values())
      .some(u => u.userId === info.userId);

    if (!stillOnline) {
      ctx.broadcastAll('presence:offline', { userId: info.userId });
    }

    logger.info(`User ${info.userName} disconnected (${ctx.id})`);
  }
}

Without this check, closing one tab would show the user as offline while they're still active in another tab.

Exporting the Presence Map

The onlineUsers map is exported so other parts of the application can query it. For example, the SSE stats endpoint uses it to show the number of online users:

// In chat.ws-controller.ts
export function getOnlineUsers() {
  return onlineUsers;
}

// In stats.controller.ts
import { getOnlineUsers } from '@/modules/messages/presentation/chat.ws-controller';

@Get('/workspaces/:workspaceId/stats/live')
@Middleware(workspaceMembershipGuard)
async workspaceLive(ctx: RequestContext) {
  const sse = ctx.sse();

  const sendStats = async () => {
    const onlineUsers = getOnlineUsers();
    sse.send({
      onlineUsersCount: onlineUsers.size,
      timestamp: new Date().toISOString(),
    }, 'stats:update');
  };

  await sendStats();
  const interval = setInterval(sendStats, 10000);
  sse.onClose(() => clearInterval(interval));
}

This bridges WebSocket presence data into the SSE-powered dashboard. The SSE endpoint pushes the online user count every 10 seconds without the dashboard needing a WebSocket connection itself.

Presence Cleanup Cron

In-memory presence tracking is fast but fragile. If the server crashes, all presence data is lost. If a client disconnects without a clean disconnect event (network failure, browser kill), the onlineUsers entry becomes stale.

KickJS's CronAdapter provides scheduled job support. I use it to clean up stale presence entries:

import { Service, Logger } from '@forinda/kickjs-core';
import { Cron } from '@forinda/kickjs-cron';

const logger = Logger.for('PresenceCronJobs');

@Service()
export class PresenceCronJobs {
  @Cron('*/5 * * * *', { description: 'Clean up stale presence entries' })
  async cleanupPresence() {
    logger.info('Running presence cleanup...');
    // Check Redis presence hash, remove entries with stale heartbeats
  }
}

The cron runs every 5 minutes. In a production implementation, you'd:

Store each user's last heartbeat timestamp in Redis
On each cron run, find entries where the heartbeat is older than the heartbeatInterval (30 seconds) plus some grace period
Remove those entries from both Redis and the in-memory map
Broadcast presence:offline for cleaned-up users

The cron adapter is registered in config/adapters.ts:

import { CronAdapter } from '@forinda/kickjs-cron';
import { PresenceCronJobs } from '@/modules/cron/infrastructure/jobs/presence-cleanup.cron';

new CronAdapter({
  services: [PresenceCronJobs, /* other cron services */],
  enabled: true,
});

Why Rooms Beat Individual Socket Tracking

For channel-based applications, rooms are categorically better than tracking individual sockets. Here's the comparison:

Without Rooms (Manual Tracking)

// You'd need to maintain this yourself
const channelMembers = new Map<string, Set<string>>(); // channelId -> socketIds

function joinChannel(channelId: string, socketId: string) {
  if (!channelMembers.has(channelId)) {
    channelMembers.set(channelId, new Set());
  }
  channelMembers.get(channelId)!.add(socketId);
}

function broadcastToChannel(channelId: string, event: string, data: any, excludeId?: string) {
  const members = channelMembers.get(channelId);
  if (!members) return;
  for (const socketId of members) {
    if (socketId === excludeId) continue;
    const socket = io.sockets.get(socketId);
    if (socket) {
      socket.emit(event, data);
    } else {
      // Socket disconnected without cleanup — stale entry
      members.delete(socketId);
    }
  }
}

function leaveChannel(channelId: string, socketId: string) {
  channelMembers.get(channelId)?.delete(socketId);
  if (channelMembers.get(channelId)?.size === 0) {
    channelMembers.delete(channelId);
  }
}

You're managing membership, fan-out, cleanup, and stale detection manually. Every edge case (disconnect without leave, server crash, multi-tab) needs explicit handling.

With Rooms (Socket.IO + KickJS)

// Join
ctx.join(`channel:${channelId}`);

// Broadcast to room (excludes sender automatically)
ctx.to(`channel:${channelId}`).send('channel:typing', { userId, userName });

// Leave
ctx.leave(`channel:${channelId}`);

// Automatic cleanup on disconnect — Socket.IO removes the socket from all rooms

Four lines replace 30+ lines of manual tracking. Socket.IO handles:

Membership management: join() and leave() maintain the room's socket set
Fan-out: to().send() iterates the room's members and emits to each
Disconnect cleanup: When a socket disconnects, Socket.IO automatically removes it from all rooms
Multi-tab: Each socket (each tab) joins independently; closing one tab doesn't affect other tabs in the same room

When Individual Tracking Makes Sense

Rooms aren't always the answer. For direct messages (1-to-1), you might track socket IDs per user because there's no "room" concept. For notifications, you might use the user ID as a room name (room:user_${userId}) and join every socket for that user.

But for channel-based communication — Slack channels, Discord servers, Jira project boards — rooms are the natural primitive. They match the domain model: a channel is a group, a room is a group.

The Complete Event Flow

Here's how all the pieces fit together for a typical interaction:

User A opens #general channel
  → Client emits: channel:join { channelId: 'general' }
  → Server: ctx.join('channel:general')
  → Server broadcasts to room: channel:user_joined { userId: 'A' }

User A starts typing
  → Client emits: channel:typing { channelId: 'general' }
  → Server: ctx.to('channel:general').send('channel:typing', { userId: 'A', userName: 'alice' })
  → User B's client receives: channel:typing → shows "alice is typing..."

User A sends a message
  → Client emits: message:send { channelId: 'general', content: 'Hello!' }
  → Server: persists message to MongoDB
  → Server: ctx.to('channel:general').send('message:new', { ... })
  → Server: ctx.send('message:new', { ... }) // echo to sender
  → User B receives: message:new → renders message in chat
  → User A receives: message:new echo → confirms delivery, gets messageId

User A stops typing (2s timeout on client)
  → Client emits: channel:stop_typing { channelId: 'general' }
  → Server: ctx.to('channel:general').send('channel:stop_typing', { userId: 'A' })
  → User B's client receives: channel:stop_typing → removes typing indicator

User A navigates away from #general
  → Client emits: channel:leave { channelId: 'general' }
  → Server: ctx.leave('channel:general')
  → Server broadcasts to room: channel:user_left { userId: 'A' }

The REST API handles everything that needs persistence or history:

GET /channels/:channelId/messages   → Paginated message history
PATCH /messages/:messageId          → Edit message (author only)
DELETE /messages/:messageId         → Soft-delete message (author only)

WebSocket handles everything that's ephemeral or real-time: message delivery, typing indicators, presence, and join/leave events.

Scaling Considerations

The in-memory onlineUsers Map works for a single server instance. For horizontal scaling, you'd need:

Redis-backed presence: Store presence in a Redis hash instead of (or in addition to) the in-memory map. All server instances read/write the same Redis store.
Socket.IO Redis adapter: @socket.io/redis-adapter makes rooms work across multiple server instances. A join() on server 1 is visible to to().send() on server 2.
Sticky sessions: Socket.IO long-polling fallback requires sticky sessions. WebSocket transport doesn't, but the initial handshake does.

KickJS's WsAdapter uses Socket.IO under the hood, so the Redis adapter integration is straightforward:

import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

const pubClient = createClient({ url: env.REDIS_URL });
const subClient = pubClient.duplicate();

const wsAdapter = new WsAdapter({
  path: '/ws',
  heartbeatInterval: 30000,
  adapter: createAdapter(pubClient, subClient), // Multi-instance rooms
});

Key Takeaways

Use rooms for group-scoped events — channels, projects, workspaces. Don't manually track socket sets.
Keep typing indicators stateless on the server — the server is a relay, not a state machine. Clients manage their own typing debounce timers.
Export presence data for cross-concern access — the SSE stats endpoint needs WebSocket presence data. Export the map, don't duplicate the tracking.
Clean up stale presence with cron — in-memory tracking is fast but fragile. A periodic cleanup prevents ghost users.
Separate persistence from real-time — messages are persisted via REST or during WebSocket message:send. Typing indicators and presence are never persisted. Use the right transport for the right data.
Auth on connect, not on every message — verify the JWT once during @OnConnect, store the user in context, and trust it for the connection's lifetime. Re-auth on reconnect.

This is part of a series on building a Jira-like backend with KickJS. Next up: the complete project guide covering everything from scaffold to production.

Filing KickJS Framework Issues as You Build — A Living Bug Tracker That Improves Your Tools

Orinda Felix Ochieng — Sun, 22 Mar 2026 16:24:04 +0000

TL;DR

We created framework-filed-issues/ inside our project to track every KickJS bug and quirk we hit while building Vibed
Each issue follows a consistent template: Status, Severity, Found in, Fixed in, Description, Steps to Reproduce, Workaround, Suggested Fix
Filing detailed issues with reproduction steps and suggested fixes led to actual framework releases (v1.2.3, v1.2.5, v1.2.6, v1.2.7)
The feedback loop — discover, workaround, file, fix, validate, update docs — is the most effective way to improve the tools you depend on
Tips for working with small/personal framework maintainers without burning them out

Why Track Framework Issues Inside Your Project?

When I started building Vibed — a Jira-like task management backend — with KickJS v1.2.2, I knew I was adopting a young framework. The docs were good enough to get started, but any non-trivial project was going to surface edge cases the framework author hadn't hit yet.

The question was: what do I do when I hit those edges?

Option one: complain on Twitter. Option two: switch frameworks. Option three: document every issue systematically, build workarounds, and file them upstream so they get fixed.

I went with option three, and it changed the trajectory of both my project and the framework itself.

The first thing I did was create a framework-filed-issues/ directory right in the project root. Not a separate repo. Not a Notion doc. Not a GitHub issue dump. A structured directory of markdown files, living alongside the code that surfaced the bugs.

vibed/
├── src/
├── framework-issues.md           # Quick reference of known issues
├── framework-filed-issues/
│   ├── README.md                 # Issue index with status table
│   ├── KICK-001.md
│   ├── KICK-002.md
│   ├── ...
│   └── KICK-018.md
└── articles/

Why inside the project? Because the issues are discovered in context. The reproduction steps reference real code. The workarounds are applied in real files. When an issue gets fixed upstream, I need to update both the workaround code and the issue file. Keeping them together means nothing falls through the cracks.

The Issue Template

Every issue file follows a consistent structure. I modeled it after the KickJS GitHub issue templates (bug_report.yml, feature_request.yml, documentation.yml) so that when I'm ready to file upstream, I can copy-paste with minimal reformatting.

Here's the template:

# KICK-NNN: Short descriptive title

- **Status**: Open | Confirmed | In Progress | Fixed | Released | Won't Fix
- **Severity**: Critical | High | Medium | Low
- **Found in**: v1.2.2
- **Fixed in**: —
- **Component**: http | core | queue | auth | mailer | cli

## Description
What's broken, in 2-3 sentences.

## Steps to Reproduce
1. Numbered steps
2. That anyone can follow
3. To trigger the bug

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens, including error messages.

## Error / Stack Trace

Paste the actual error output here


## Environment
- Node.js version
- OS
- Package manager

## Workaround
What I'm doing right now to get past this.

## Suggested Fix
How I think the framework should fix it, with code if possible.

The Status field is the most important one. It tracks the issue through its lifecycle:

Status	Meaning
Open	Filed locally, not yet submitted upstream
Confirmed	Framework maintainer acknowledged
In Progress	Fix being worked on
Fixed	Fix merged, awaiting release
Released	Fix available in a published version
Won't Fix	Intentional behavior or out of scope

And the README.md file serves as an index table that gives me a bird's-eye view of all issues at a glance:

| ID | Title | Package | Severity | Status | Fixed In |
|---|---|---|---|---|---|
| KICK-001 | `kick new` interactive prompt not scriptable | cli | Low | Open | — |
| KICK-003 | Modules without routes crash Express | http | High | Released | v1.2.3 |
| KICK-009 | `ctx.set()`/`ctx.get()` not shared | http | Critical | Released | v1.2.5 |
| KICK-016 | `@Service()` + `@Job()` not auto-registered | queue, core | High | Released | v1.2.6 |

Real Example: KICK-009 — The Critical Context Bug

This is the issue that cost me the most hours and ultimately drove the most impactful framework fix.

I was building the auth middleware for Vibed. The pattern was simple: middleware validates the JWT, stores the user in context, handler reads the user from context. Every framework works this way.

// Middleware: validate JWT and store user
export const authBridgeMiddleware: MiddlewareHandler = (ctx, next) => {
  const token = ctx.headers.authorization?.split(' ')[1];
  const payload = jwt.verify(token, env.JWT_SECRET);
  ctx.set('user', { id: payload.sub, email: payload.email });
  next();
};

// Handler: read user from context
async create(ctx: RequestContext) {
  const user = ctx.get<AuthUser>('user'); // undefined!
  // TypeError: Cannot read properties of undefined (reading 'id')
}

ctx.get('user') returned undefined. Every single time. The middleware was running — I could verify that with console logs — but the handler couldn't see what the middleware had set.

After digging into the KickJS source, I found the root cause: router-builder.ts created a new RequestContext instance for each middleware and each handler. Every instance had its own private metadata Map. ctx.set() in middleware wrote to Map A. ctx.get() in the handler read from Map B. They were completely isolated.

Here's what I filed in KICK-009:

# KICK-009: `ctx.set()`/`ctx.get()` not shared between middleware and handler

- **Status**: Released
- **Severity**: Critical
- **Found in**: v1.2.2
- **Fixed in**: v1.2.5
- **Component**: http

## Description
In `router-builder.ts`, each middleware and handler receive separate
`new RequestContext(req, res, next)` instances. The `metadata` property
is a private `new Map()` per instance. `ctx.set('user', user)` in
middleware is invisible to `ctx.get('user')` in the handler.

## Suggested Fix
Attach the metadata Map to `req` on first creation, then reuse it:

function getOrCreateContext(req, res, next) {
  if (!req.__ctx) {
    req.__ctx = new RequestContext(req, res, next);
  }
  return req.__ctx;
}

The workaround I used in Vibed while waiting for the fix was to mutate req directly:

// Workaround: store on req, read with a helper
export const authBridgeMiddleware: MiddlewareHandler = (ctx, next) => {
  const user = (ctx.req as any).user; // Set by AuthAdapter
  if (user) {
    ctx.set('user', user);
  }
  next();
};

// Helper that abstracts the workaround
export function getUser(ctx: RequestContext): AuthUser {
  const user = ctx.get<AuthUser>('user');
  if (!user) throw HttpException.unauthorized('Authentication required');
  return user;
}

By wrapping the workaround in getUser(), every controller called one function. When v1.2.5 fixed the underlying issue, I updated the middleware and the helper — zero changes needed in 14 controllers.

Real Example: KICK-016 — DI Auto-Registration

This one hit when I was adding BullMQ job processors. The pattern should have been straightforward:

@Service()
@Job('email')
export class EmailProcessor {
  @Autowired(MAILER) private mailer!: MailerService;

  @Process('send-welcome-email')
  async sendWelcome(job: BullMQJob<{ email: string; firstName: string }>) {
    await this.mailer.send({
      to: job.data.email,
      subject: `Welcome to Vibed, ${job.data.firstName}!`,
      html: `<h1>Welcome!</h1>`,
    });
  }
}

But when the app started, I got:

Error: No binding found for: EmailProcessor
    at Container.resolve (container.ts:105:13)
    at QueueAdapter.beforeStart (queue.adapter.ts:75:35)

The @Service() decorator only set metadata. It did not call container.register(). So when QueueAdapter.beforeStart() tried to resolve the processor class, the container had no idea it existed.

My workaround was a ProcessorRegistrarAdapter that manually registered processor classes before the QueueAdapter:

export class ProcessorRegistrarAdapter implements AppAdapter {
  name = 'ProcessorRegistrarAdapter';

  beforeStart(_app: any, container: Container) {
    if (!container.has(EmailProcessor)) {
      container.register(EmailProcessor, EmailProcessor);
    }
  }
}

// In adapters array — MUST come before queueAdapter
export const adapters = [
  new ProcessorRegistrarAdapter(),
  queueAdapter,
  // ...
];

In my issue file, I suggested two fix options. The framework implemented Option B first in v1.2.6 — QueueAdapter.beforeStart() auto-registers @Job classes before resolving them. Then v1.2.7 implemented the more general fix: Container.bootstrap() now auto-registers all @Service()-decorated classes.

Real Example: KICK-017 — Feature Request

Not every issue is a bug. KICK-017 was a feature request born from the KICK-016 workaround. After filing the bug, I realized the real problem was deeper: @Service() should mean "this class is resolvable from the container" without any manual registration step.

# KICK-017: `@Service()` classes should be auto-registered in DI container

- **Status**: Released
- **Type**: Feature Request
- **Fixed in**: v1.2.6 (QueueAdapter), v1.2.7 (Container auto-registration)

## Problem
The `@Service()` decorator only sets metadata — it does not register
the class in the DI container. Any code that calls
`container.resolve(ServiceClass)` fails unless the consumer manually
calls `container.register()`.

The distinction between bug reports and feature requests matters. Bugs say "this is broken." Feature requests say "this could be better." Framework maintainers prioritize differently based on the category. A critical bug blocking adoption gets immediate attention. A feature request goes into the backlog. Filing them correctly respects the maintainer's time.

The Feedback Loop

Over the course of building Vibed, a clear pattern emerged:

Discover → Workaround → File → Fix → Validate → Update Docs

Discover: Hit a bug during development. The error message is usually cryptic. Spend time understanding the root cause by reading the framework source.

Workaround: Build a workaround that unblocks development. Keep the workaround isolated (in a helper function, in a custom adapter) so it's easy to remove later.

File: Write the issue in framework-filed-issues/ using the template. Include the root cause, reproduction steps, and a suggested fix. The suggested fix is the most valuable part — it tells the maintainer exactly what to change.

Fix: The framework author publishes a new version with the fix.

Validate: Update the project to the new version. Verify the fix actually solves the issue. Remove the workaround code.

Update Docs: Update the issue file status to "Released." Update framework-issues.md with the resolution. Update any articles or documentation that referenced the workaround.

Here's the timeline for Vibed's issues:

Version	Issues Fixed	What Changed
v1.2.3	KICK-003, KICK-004, KICK-010	Modules without routes, env typing, `@Public()` resolution
v1.2.5	KICK-009	Shared `RequestContext` metadata across middleware/handler
v1.2.6	KICK-013, KICK-016	Queue processor DI auto-registration, HMR DI rebinding
v1.2.7	KICK-017	`Container.bootstrap()` auto-registers all `@Service()` classes

Four releases. Seven issues fixed. All because structured bug reports with suggested fixes made the maintainer's job easier.

Tips for Working with Small Framework Maintainers

KickJS is maintained by a solo developer. Most of the Node.js ecosystem runs on projects maintained by one or two people. Here's what I've learned about filing issues productively:

1. Do Your Homework First

Before filing, read the framework source. Understand whether it's actually a bug or a misunderstanding. Half the issues I initially thought were bugs turned out to be undocumented behavior. I still filed them — as documentation issues — but knowing the difference saved back-and-forth.

2. Include the Suggested Fix

The single most impactful thing you can do is include a concrete, code-level suggestion for how to fix the issue. Not "you should fix this" but "here's the specific function in router-builder.ts that creates separate contexts, and here's what it should do instead." The maintainer can disagree with your approach, but you've saved them the debugging time.

3. Separate Bugs from Feature Requests

KICK-016 was a bug: "this doesn't work." KICK-017 was a feature request: "this should work differently." Filing them separately lets the maintainer triage appropriately.

4. Document Your Workaround

If your workaround is good, the maintainer might adopt it as the official fix. If your workaround is terrible, the maintainer knows the pain point and can design something better. Either way, showing that you found a way forward demonstrates that the issue is solvable.

5. Track Resolution Publicly

When an issue gets fixed, update your tracker, update your docs, and thank the maintainer. Open source runs on acknowledgment. A "this is fixed in v1.2.5, thank you" comment on a GitHub issue takes 10 seconds and provides outsized motivation.

6. Batch Related Issues

Don't file 10 issues in one day. Group related issues, reference each other, and space them out. KICK-016 (the bug) and KICK-017 (the feature request) were filed together because they had the same root cause. That context helped the maintainer see the bigger picture.

The README as a Living Dashboard

The framework-filed-issues/README.md file became the project's dashboard for framework health. At any point during development, I could glance at the index table and know:

Which issues were still blocking (severity + status)
Which workarounds were still in the codebase
Which framework versions I needed to upgrade to
Which issues were candidates for upstream filing

## Issue Index

### Bug Reports

| ID | Title | Severity | Status | Fixed In |
|---|---|---|---|---|
| KICK-003 | Modules without routes crash Express | High | Released | v1.2.3 |
| KICK-009 | ctx.set/get not shared | Critical | Released | v1.2.5 |
| KICK-016 | @Service + @Job not auto-registered | High | Released | v1.2.6 |
| KICK-011 | @Inject doesn't work as property decorator | Medium | Open | — |

### Feature Requests

| ID | Title | Status |
|---|---|---|
| KICK-015 | `kick readme` CLI command | Open |
| KICK-017 | @Service auto-registration in DI | Released |
| KICK-018 | Type-safe API client generation | Open |

The "Open" issues tell me what workarounds are still in my codebase. The "Released" issues tell me which versions I should upgrade to. The feature requests tell me what I'm hoping for in future releases.

Why Not Just Use GitHub Issues?

I do file on GitHub — eventually. But the local tracker serves a different purpose:

Speed: I can document an issue the moment I hit it without context-switching to GitHub
Context: The issue file lives next to the code that triggered it
Completeness: I can iterate on the description, reproduction steps, and suggested fix before filing publicly
Cross-referencing: I can reference issue files from code comments, from framework-issues.md, and from articles
Offline-friendly: I can work on issue documentation without an internet connection

The local file is the draft. The GitHub issue is the published version. The two stay in sync via the status field.

What This Approach Gave Us

After 18 issues tracked — 13 bug reports, 1 documentation issue, and 4 feature requests — here's what we got:

7 issues fixed across 4 framework releases
Zero abandoned workarounds — every workaround was either removed (when the fix shipped) or documented (when it's still needed)
Clean upgrade path — when v1.2.5 dropped, I knew exactly which workarounds to remove and which code to update
Better framework — KickJS is genuinely better for having been stress-tested by a real project
Better project — forcing myself to understand root causes made me a better debugger

The cost was maybe 30 minutes per issue for documentation. The return was hundreds of hours of debugging saved for everyone who uses KickJS after me.

If you're building with a young framework — or any framework, really — consider creating a framework-issues/ directory in your project. It's the most productive form of complaining I've ever found.

This is part of a series on building a Jira-like backend with KickJS. The full project source is available on GitHub.

KickJS Custom CLI Commands for Seeding, Resetting, and Testing — Zero Extra Dependencies

Orinda Felix Ochieng — Sun, 22 Mar 2026 15:55:19 +0000

Custom CLI Commands for Seeding, Resetting, and Testing — Zero Extra Dependencies

Every project accumulates scripts. First it is npm run seed. Then npm run db:reset. Then npm run seed:staging, npm run test:integration, npm run format:check, and before you know it, your package.json has 18 scripts and nobody remembers what half of them do.

For Vibed, our Jira-like task management backend built on KickJS, I moved all operational commands into the framework's kick.config.ts file. The result: kick seed, kick db:reset, kick check -- discoverable, documented, and composable. No extra CLI framework, no commander.js, no yargs. Just a config file and the kick binary you already have.

Here is how it works, what the seed and reset scripts look like, and why CLI-level commands beat npm scripts for developer experience.

kick.config.ts: The Command Registry

KickJS uses a kick.config.ts file at the project root for framework configuration. It tells the scaffolding generator where modules live, what patterns to follow, and -- the feature I care about here -- what custom commands to register.

// kick.config.ts
import { defineConfig } from '@forinda/kickjs-cli'

export default defineConfig({
  pattern: 'rest',
  modulesDir: 'src/modules',
  defaultRepo: 'inmemory',

  commands: [
    {
      name: 'seed',
      description: 'Populate database with sample data',
      steps: 'npx vite-node src/db/seed.ts',
    },
    {
      name: 'db:reset',
      description: 'Drop database and reseed',
      steps: ['npx vite-node src/db/reset.ts', 'npx vite-node src/db/seed.ts'],
    },
    {
      name: 'test',
      description: 'Run tests with Vitest',
      steps: 'npx vitest run',
    },
    {
      name: 'format',
      description: 'Format code with Prettier',
      steps: 'npx prettier --write src/',
    },
    {
      name: 'format:check',
      description: 'Check formatting without writing',
      steps: 'npx prettier --check src/',
    },
    {
      name: 'check',
      description: 'Run typecheck + format check',
      steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
      aliases: ['verify', 'ci'],
    },
  ],
})

Each command has a name, a description (shown when you run kick --help), and steps which can be a single string or an array of strings. Arrays execute sequentially -- if any step fails, the chain stops. The optional aliases field lets you run the same command under different names.

After this config, your terminal gets:

kick seed          # Insert test data
kick db:reset      # Drop everything and reseed
kick test          # Run Vitest
kick format        # Format with Prettier
kick format:check  # Check formatting
kick check         # Typecheck + format check
kick verify        # Same as check (alias)
kick ci            # Same as check (alias)

All discoverable with kick --help.

The Seed Script: Realistic Test Data

The seed script is the most important operational script in any backend project. Bad seed data leads to bugs that only surface with real users. Good seed data exposes edge cases during development.

Here is the Vibed seed script in full:

// src/db/seed.ts
import 'reflect-metadata';
import mongoose from 'mongoose';
import bcrypt from 'bcryptjs';
import { UserModel }
  from '@/modules/users/infrastructure/schemas/user.schema';
import { WorkspaceModel }
  from '@/modules/workspaces/infrastructure/schemas/workspace.schema';
import { WorkspaceMemberModel }
  from '@/modules/workspaces/infrastructure/schemas/workspace-member.schema';
import { ProjectModel }
  from '@/modules/projects/infrastructure/schemas/project.schema';
import { LabelModel }
  from '@/modules/labels/infrastructure/schemas/label.schema';
import { TaskModel }
  from '@/modules/tasks/infrastructure/schemas/task.schema';
import { ChannelModel }
  from '@/modules/channels/infrastructure/schemas/channel.schema';

const MONGODB_URI = process.env.MONGODB_URI!;
if (!MONGODB_URI) {
  console.error('MONGODB_URI env variable is required');
  process.exit(1);
}

async function seed() {
  console.log('Connecting to MongoDB...');
  await mongoose.connect(MONGODB_URI);
  console.log('Connected. Seeding database...\n');

  // ── Users ──────────────────────────────────────────────
  const passwordHash = await bcrypt.hash('Password123!', 10);

  const users = await UserModel.insertMany([
    {
      email: 'admin@vibed.dev', passwordHash,
      firstName: 'Admin', lastName: 'User',
      globalRole: 'superadmin',
    },
    {
      email: 'alice@vibed.dev', passwordHash,
      firstName: 'Alice', lastName: 'Johnson',
      globalRole: 'user',
    },
    {
      email: 'bob@vibed.dev', passwordHash,
      firstName: 'Bob', lastName: 'Smith',
      globalRole: 'user',
    },
    {
      email: 'carol@vibed.dev', passwordHash,
      firstName: 'Carol', lastName: 'Williams',
      globalRole: 'user',
    },
  ]);
  console.log(`Created ${users.length} users`);

  const [admin, alice, bob, carol] = users;

  // ── Workspace ──────────────────────────────────────────
  const workspace = await WorkspaceModel.create({
    name: 'Vibed HQ',
    slug: 'vibed-hq',
    description: 'Main workspace for the Vibed team',
    ownerId: admin._id,
  });
  console.log(`Created workspace: ${workspace.name}`);

  // ── Workspace Members ──────────────────────────────────
  await WorkspaceMemberModel.insertMany([
    { workspaceId: workspace._id, userId: admin._id, role: 'admin' },
    { workspaceId: workspace._id, userId: alice._id, role: 'admin' },
    { workspaceId: workspace._id, userId: bob._id, role: 'member' },
    { workspaceId: workspace._id, userId: carol._id, role: 'member' },
  ]);
  console.log('Added 4 workspace members');

  // ── Labels ─────────────────────────────────────────────
  const labels = await LabelModel.insertMany([
    { workspaceId: workspace._id, name: 'bug', color: '#ef4444' },
    { workspaceId: workspace._id, name: 'feature', color: '#3b82f6' },
    { workspaceId: workspace._id, name: 'improvement', color: '#8b5cf6' },
    { workspaceId: workspace._id, name: 'docs', color: '#10b981' },
    { workspaceId: workspace._id, name: 'urgent', color: '#f97316' },
  ]);
  console.log(`Created ${labels.length} labels`);

  const [bugLabel, featureLabel, , docsLabel, urgentLabel] = labels;

  // ── Projects ───────────────────────────────────────────
  const backend = await ProjectModel.create({
    workspaceId: workspace._id,
    name: 'Backend API', key: 'API',
    description: 'KickJS backend for Vibed',
    leadId: alice._id, taskCounter: 6,
  });

  const frontend = await ProjectModel.create({
    workspaceId: workspace._id,
    name: 'Frontend App', key: 'FE',
    description: 'React frontend for Vibed',
    leadId: bob._id, taskCounter: 4,
  });
  console.log('Created 2 projects: Backend API, Frontend App');

  // ── Tasks ──────────────────────────────────────────────
  const backendTasks = await TaskModel.insertMany([
    {
      projectId: backend._id, workspaceId: workspace._id,
      key: 'API-1', title: 'Set up JWT authentication',
      status: 'done', priority: 'critical',
      assigneeIds: [alice._id], reporterId: admin._id,
      labelIds: [featureLabel._id], orderIndex: 0,
    },
    {
      projectId: backend._id, workspaceId: workspace._id,
      key: 'API-2', title: 'Add workspace CRUD and membership',
      status: 'done', priority: 'high',
      assigneeIds: [alice._id, bob._id], reporterId: admin._id,
      labelIds: [featureLabel._id], orderIndex: 1,
    },
    {
      projectId: backend._id, workspaceId: workspace._id,
      key: 'API-3', title: 'Implement task management',
      status: 'in-progress', priority: 'high',
      assigneeIds: [alice._id], reporterId: alice._id,
      labelIds: [featureLabel._id], orderIndex: 2,
    },
    // ... more tasks
  ]);

  const frontendTasks = await TaskModel.insertMany([
    {
      projectId: frontend._id, workspaceId: workspace._id,
      key: 'FE-1', title: 'Scaffold React app with Vite',
      status: 'done', priority: 'high',
      assigneeIds: [bob._id], reporterId: bob._id,
      labelIds: [featureLabel._id], orderIndex: 0,
    },
    {
      projectId: frontend._id, workspaceId: workspace._id,
      key: 'FE-2', title: 'Build kanban board component',
      status: 'in-progress', priority: 'high',
      assigneeIds: [bob._id, carol._id], reporterId: bob._id,
      labelIds: [featureLabel._id, urgentLabel._id], orderIndex: 1,
    },
    // ... more tasks
  ]);

  console.log(`Created ${backendTasks.length + frontendTasks.length} tasks`);

  // ── Channels ───────────────────────────────────────────
  await ChannelModel.insertMany([
    {
      workspaceId: workspace._id, name: 'general',
      description: 'General discussion', type: 'public',
      memberIds: [admin._id, alice._id, bob._id, carol._id],
      createdById: admin._id,
    },
    {
      workspaceId: workspace._id, projectId: backend._id,
      name: 'backend-dev', description: 'Backend development chat',
      type: 'public', memberIds: [alice._id, bob._id, carol._id],
      createdById: alice._id,
    },
    {
      workspaceId: workspace._id, projectId: frontend._id,
      name: 'frontend-dev', description: 'Frontend development chat',
      type: 'public', memberIds: [bob._id, carol._id],
      createdById: bob._id,
    },
  ]);
  console.log('Created 3 channels');

  // ── Summary ────────────────────────────────────────────
  console.log('\n--- Seed complete ---');
  console.log(`Users:      ${users.length}`);
  console.log(`Workspace:  1 (${workspace.name})`);
  console.log(`Projects:   2`);
  console.log(`Tasks:      ${backendTasks.length + frontendTasks.length}`);
  console.log(`Labels:     ${labels.length}`);
  console.log(`Channels:   3`);
  console.log('\nLogin credentials (all users): Password123!');
  console.log('Admin: admin@vibed.dev');
  console.log('Users: alice@vibed.dev, bob@vibed.dev, carol@vibed.dev');

  await mongoose.disconnect();
}

seed().catch((err) => {
  console.error('Seed failed:', err);
  process.exit(1);
});

A few design decisions worth explaining.

A shared password for all seed users

Every seed user gets Password123!. This is intentional for local development. When I (or a new team member) run kick seed and want to test the login flow, the password is right there in the console output. No need to look anything up.

Realistic relationships, not random data

The seed creates a proper hierarchy: users belong to a workspace, workspace has projects, projects have tasks with assignees, tasks have labels. This is not random UUIDs thrown into collections. It is a coherent dataset that exercises foreign key relationships, permission checks, and query filters.

For example, API-3 ("Implement task management") is assigned to Alice and has status in-progress. When I test the kanban board endpoint, I see a card in the right column. When I test the "my tasks" filter, Alice's tasks show up. When I test overdue reminders, FE-4 has a due date 3 days from now that will eventually trigger.

The order matters

Users are created first because workspaces need owner IDs. Workspaces before members. Labels before tasks (tasks reference label IDs). This sequential dependency is why insertMany is used per collection rather than some parallel bulk insert.

The Reset Script: Drop and Rebuild

Sometimes seed data gets corrupted during development. Maybe I manually deleted a user but left orphaned workspace members. Maybe a schema migration changed a field name. The reset script gives me a clean slate:

// src/db/reset.ts
import mongoose from 'mongoose';

const MONGODB_URI = process.env.MONGODB_URI!;
if (!MONGODB_URI) {
  console.error('MONGODB_URI env variable is required');
  process.exit(1);
}

async function reset() {
  console.log('Connecting to MongoDB...');
  await mongoose.connect(MONGODB_URI);

  const db = mongoose.connection.db!;
  const collections = await db.listCollections().toArray();

  for (const col of collections) {
    await db.dropCollection(col.name);
    console.log(`Dropped: ${col.name}`);
  }

  console.log(
    `\nReset complete — dropped ${collections.length} collections`
  );
  await mongoose.disconnect();
}

reset().catch((err) => {
  console.error('Reset failed:', err);
  process.exit(1);
});

It drops every collection in the database, then disconnects. It does not drop the database itself because that would require elevated permissions on some MongoDB hosting providers.

The kick db:reset command chains this with the seed:

{
  name: 'db:reset',
  description: 'Drop database and reseed',
  steps: ['npx vite-node src/db/reset.ts', 'npx vite-node src/db/seed.ts'],
},

Run kick db:reset and 10 seconds later you have a fresh database with all the test data. This is the command I run most often during development -- probably 5-10 times a day.

Using vite-node for Path Aliases

Notice that the seed script imports from @/modules/users/infrastructure/schemas/user.schema. That @/ prefix is a path alias configured in tsconfig.json that maps to src/. Standard node --loader ts-node does not resolve these aliases. Neither does tsx out of the box.

The solution is vite-node, which comes free with the KickJS dev setup (KickJS uses Vite under the hood for HMR). vite-node reads your vite.config.ts (or falls back to tsconfig.json paths) and resolves aliases the same way your dev server does.

npx vite-node src/db/seed.ts

This runs the TypeScript file directly, with full path alias support, ESM module resolution, and access to environment variables from .env. No compilation step, no intermediate JavaScript files. It just works.

If your project does not use Vite, tsx with tsconfig-paths achieves the same thing:

npx tsx --require tsconfig-paths/register src/db/seed.ts

But if you already have Vite in your stack, vite-node is the simpler choice.

The Check Command: Pre-Push Validation

The check command runs typecheck and format check in sequence:

{
  name: 'check',
  description: 'Run typecheck + format check',
  steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
  aliases: ['verify', 'ci'],
},

I run this before every push. The aliases matter: kick ci is what our CI pipeline runs, and kick verify is what I tell new contributors to run before opening a PR. Same command, different mental models.

If tsc --noEmit finds type errors, the chain stops and prettier --check never runs. This is intentional -- there is no point checking formatting if the code does not compile.

Why CLI-Level Commands Beat npm Scripts

I have used npm scripts in every Node.js project for the last decade. They work. But kick commands are better for operational scripts, and here is why.

Discoverability

Run kick --help and you see every custom command with its description. Run npm run and you see a wall of script names with no context:

Lifecycle scripts included in vibed@1.2.7:
  test
    vitest run

available via `npm run-script`:
  dev
    kick dev
  build
    kick build
  ...

No descriptions. No grouping. No way to tell which scripts are for developers vs. CI vs. operations.

Composition

npm scripts compose awkwardly. You need && for sequencing, concurrently for parallelism, and cross-env for environment variables. kick commands support arrays for sequential steps natively:

steps: ['npx vite-node src/db/reset.ts', 'npx vite-node src/db/seed.ts'],

No shell operator gymnastics. If a step fails, it stops.

Coexistence with npm scripts

kick commands do not replace npm scripts. The standard lifecycle scripts (dev, build, start, test) still live in package.json because that is where CI tools, IDEs, and other developers expect them. But operational commands (seed, db:reset, check) work better in kick.config.ts.

In Vibed, the package.json scripts are thin wrappers:

{
  "scripts": {
    "dev": "kick dev",
    "build": "kick build",
    "start": "kick start",
    "test": "vitest run",
    "typecheck": "tsc --noEmit",
    "format": "prettier --write src/"
  }
}

Six scripts, all obvious. The operational commands live in kick.config.ts where they have descriptions and can compose steps.

No extra dependencies

I have seen projects pull in commander, yargs, inquirer, chalk, and ora just to build a CLI for seed scripts. That is five dependencies (and their transitive dependencies) for something that should be configuration.

KickJS's defineConfig reads the command list and registers them with the kick binary. No runtime overhead, no additional packages, no CLI framework to learn. If you already use kick dev and kick build, custom commands are free.

Practical Tips for Seed Scripts

After writing seed scripts for a dozen projects, here are the patterns that consistently work:

Print credentials at the end. Developers will forget the test passwords. Print them every time the seed runs.
Make seeds idempotent or make reset easy. Either use upsert so running seed twice does not fail on duplicate keys, or provide a reset command that clears everything first. I chose the reset approach because it is simpler and guarantees clean state.
Use real-looking data. "Test User 1" is useless for testing search, sorting, or display truncation. "Alice Johnson" tells you something when it shows up in a dropdown.
Create enough data to exercise pagination. If your API paginates at 20 items per page, seed at least 25 of something. Vibed seeds 10 tasks across 2 projects, which is enough for basic development but should grow as the API matures.
Seed all entity types. If your app has users, workspaces, projects, tasks, labels, and channels, the seed should create all of them with proper relationships. Skipping channels means you cannot test the messaging endpoints without manual setup.
Log counts, not data. Print Created 4 users not the full user objects. Keep the output scannable.

Putting It All Together

Here is my typical development workflow with these commands:

# First day on the project
kick seed

# Messed up the data
kick db:reset

# Before pushing
kick check

# Before opening a PR
kick test && kick check

# After pulling changes that modified schemas
kick db:reset

Five commands that cover the full development lifecycle. All discoverable with --help. All defined in a single config file. No dependency bloat, no shell script spaghetti, no undocumented tribal knowledge.

The key insight is that developer experience tooling does not need to be complex. A config file with a commands array, a script runner that supports path aliases, and sensible defaults cover 90% of what teams need. The remaining 10% -- interactive prompts, environment selection, dry-run modes -- can wait until you actually need them. Start simple, add complexity only when the pain demands it.

Vibed's entire operational CLI is 41 lines of configuration. That is the kind of leverage I want from my tools.

Forem: Orinda Felix Ochieng

Building Production-Grade Authentication with kickjs Every Mistake You'll Make

Build auth with kickjs

What We Built

Mistake 1: Accessing the User Wrong

Mistake 2: @public Routes Returning 401

Mistake 3: CSRF Blocking Your Login Endpoint

Mistake 4: Roles in JWT Don't Match Roles in Your Decorator

Mistake 5: Rate Limit State Leaking Between Tests

Mistake 6: Multi-Tenant Role Leakage

Mistake 7: Per-Tenant JWT Secrets — The Cross-Tenant Token Attack

Mistake 8: Token Revocation That Un-Revokes

Mistake 9: The Subdomain Tenant That Never Resolves

Mistake 10: The Decorator Precedence Trap

The Architecture That Made This Possible

What We Filed

TL;DR

The KickJS CLI: Scaffolding Production-Ready Node.js Backends in Seconds

Why a CLI Matters

Installing the CLI

1. Global install (recommended for daily use)

2. npx / pnpm dlx / yarn dlx (no install)

3. Project-local (inside the monorepo or a single project)

Creating a Project: kick new

The Five Templates

Safety Nets

The Dev Loop: kick dev, kick build, kick start

kick dev

kick dev:debug

kick build

kick start

Code Generation: kick g

kick g module — Your New Best Friend

Generate Multiple Modules at Once

Pattern Overrides

kick g scaffold — CRUD From a Field Description

About That :optional Suffix

kick g Inside a Module: The -m Flag

kick g With Dry Run

kick rm module

Package Management: kick list, kick add

kick list

kick add

Environment Diagnostics: kick info

Inspecting a Running App: kick inspect

Custom Commands in kick.config.ts

kick g config

Typed Routes: kick typegen

The One-Liner Shortcuts

What Makes a Good Generator

Closing Thoughts

Build a Task Management API with KickJS — Categories, User Assignment, and Typed Everything

Why KickJS?

What We're Building

Step 1: Scaffold the Project

Step 2: Generate the User Module

The Query Parsing You Didn't Write

Step 3: Generate the Category Module

Step 4: The Task Module — Where It Gets Interesting

Step 5: The Assignment Endpoint

Step 6: Filtering Tasks by Category and Assignee

Step 7: Seeding Some Data

Step 8: Adding Swagger Docs (You Already Have Them)

Step 9: Writing a Test

Swapping In a Real Database

What You Built

Where to Go Next

Closing Thoughts

KickJS: Decorator-Driven APIs on Express 5 — NestJS Ergonomics, Zero Overhead

TL;DR

Why Though

Show Me the Code

The CLI Is the Star

Built-in Middleware (No Extra Installs)

Vite 8 Powers Everything

836+ Real Tests

The 19 Packages

What's Coming

Get Started

forinda / kick-js

Creating a Project: `kick new`

The Dev Loop: `kick dev`, `kick build`, `kick start`

`kick dev`

`kick dev:debug`

`kick build`

`kick start`

Code Generation: `kick g`

`kick g module` — Your New Best Friend

`kick g scaffold` — CRUD From a Field Description

About That `:optional` Suffix

`kick g` Inside a Module: The `-m` Flag

`kick g` With Dry Run

`kick rm module`

Package Management: `kick list`, `kick add`

`kick list`

`kick add`

Environment Diagnostics: `kick info`

Inspecting a Running App: `kick inspect`

Custom Commands in `kick.config.ts`

`kick g config`

Typed Routes: `kick typegen`

1. No more `datasource.url` in schema

3. `$on` removed for logging