create-nexst-monorepo 0.1.0

package/template/apps/web/vitest.config.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
+import { playwright } from "@vitest/browser-playwright";
+import { defineConfig } from "vitest/config";
+
+const dirname = import.meta.dirname;
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@": path.join(dirname, "src"),
+      "~sb": path.join(dirname, ".storybook"),
+    },
+  },
+  test: {
+    projects: [
+      {
+        extends: true,
+        test: {
+          include: ["src/**/*.test.ts"],
+          name: "unit",
+        },
+      },
+      {
+        extends: true,
+        plugins: [storybookTest({ configDir: path.join(dirname, ".storybook") })],
+        test: {
+          browser: {
+            enabled: true,
+            headless: true,
+            instances: [{ browser: "chromium", viewport: { height: 900, width: 1440 } }],
+            provider: playwright({}),
+          },
+          name: "storybook",
+          setupFiles: [".storybook/vitest.setup.ts"],
+        },
+      },
+    ],
+  },
+});

package/template/apps/web/vitest.shims.d.ts

@@ -0,0 +1 @@
+/// <reference types="@vitest/browser/providers/playwright" />

package/template/apps/worker/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env (bun loads it automatically) and adjust.
+LOG_LEVEL=debug
+REDIS_HOST=localhost
+REDIS_PORT=6379

package/template/apps/worker/AGENTS.md

@@ -0,0 +1,11 @@
+# worker (BullMQ)
+
+Plain bun process (no NestJS) that consumes the queues apps/api enqueues. Queue names,
+payload types and Redis connection options live in `packages/queues` — change them
+there so producer and consumer stay in sync.
+
+- Processors in `src/processors/` are pure functions of the job; unit-test them
+  without Redis (`bun run test:unit`).
+- `src/worker/worker.ts` wires processors to BullMQ; shutdown closes the worker before
+  quitting Redis (`src/lib/graceful-shutdown.ts`).
+- Deploy the worker before an API change that enqueues a new job shape.

package/template/apps/worker/Dockerfile

@@ -0,0 +1,35 @@
+ARG BUN_VERSION
+
+# ---------------------------------------------------
+# Stage 1: Pruner
+# ---------------------------------------------------
+FROM toolchain AS pruner
+RUN turbo prune @nexst/worker --docker
+
+# ---------------------------------------------------
+# Stage 2: Deps
+# ---------------------------------------------------
+FROM dhi.io/bun:${BUN_VERSION}-alpine-dev AS deps
+WORKDIR /app
+COPY --from=pruner /app/out/json/ .
+RUN --mount=type=cache,id=bun-install,sharing=locked,target=/root/.bun/install/cache \
+    bun install --frozen-lockfile --production --omit=peer
+
+# ---------------------------------------------------
+# Stage 3: Runtime
+# ---------------------------------------------------
+FROM dhi.io/bun:${BUN_VERSION}-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+COPY --from=deps --chown=nonroot:nonroot /app/node_modules ./node_modules
+COPY --from=deps --chown=nonroot:nonroot /app/apps/worker/node_modules ./apps/worker/node_modules
+COPY --from=pruner --chown=nonroot:nonroot /app/out/full/packages/queues ./packages/queues
+COPY --from=pruner --chown=nonroot:nonroot /app/out/full/apps/worker ./apps/worker
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
+  CMD ["bun", "-e", "new (require('ioredis').default)({ host: process.env.REDIS_HOST || 'localhost', port: Number(process.env.REDIS_PORT) || 6379 }).ping().then(() => process.exit(0), () => process.exit(1))"]
+
+STOPSIGNAL SIGTERM
+WORKDIR /app/apps/worker
+CMD ["bun", "src/main.ts"]

package/template/apps/worker/knip.config.ts

@@ -0,0 +1,3 @@
+import { createKnipConfig } from "@nexst/lint/knip";
+
+export default createKnipConfig();

package/template/apps/worker/kustomize/base/application.properties

@@ -0,0 +1,4 @@
+NODE_ENV=production
+LOG_LEVEL=info
+REDIS_HOST=redis-master
+REDIS_PORT=6379

package/template/apps/worker/kustomize/base/deployment.yaml

@@ -0,0 +1,62 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nexst-worker
+spec:
+  replicas: 1
+  selector:
+    matchLabels: {}
+  template:
+    spec:
+      serviceAccountName: ghcr-puller
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 10001
+        runAsGroup: 10001
+        fsGroup: 10001
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+        - name: nexst-worker
+          image: nexst-worker
+          imagePullPolicy: IfNotPresent
+          securityContext:
+            allowPrivilegeEscalation: false
+            runAsNonRoot: true
+            runAsUser: 10001
+            runAsGroup: 10001
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: [ALL]
+            seccompProfile:
+              type: RuntimeDefault
+          envFrom:
+            - configMapRef:
+                name: nexst-worker-config
+          resources:
+            requests:
+              memory: 128Mi
+              cpu: 50m
+            limits:
+              memory: 512Mi
+              cpu: 500m
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+          readinessProbe:
+            exec:
+              command: &redis-ping
+                - bun
+                - -e
+                - "new (require('ioredis').default)({host:process.env.REDIS_HOST,port:Number(process.env.REDIS_PORT)}).ping().then(()=>process.exit(0),()=>process.exit(1))"
+            initialDelaySeconds: 10
+            periodSeconds: 30
+          livenessProbe:
+            exec:
+              command: *redis-ping
+            initialDelaySeconds: 20
+            periodSeconds: 30
+      volumes:
+        - name: tmp
+          emptyDir:
+            sizeLimit: 256Mi

package/template/apps/worker/kustomize/base/kustomization.yaml

@@ -0,0 +1,16 @@
+labels:
+  - pairs:
+      app.kubernetes.io/name: nexst-worker
+      app.kubernetes.io/part-of: nexst
+      app.kubernetes.io/managed-by: kustomize
+      app.kubernetes.io/created-by: your-org
+      app.kubernetes.io/component: worker
+    includeSelectors: true
+
+resources:
+  - deployment.yaml
+
+configMapGenerator:
+  - name: nexst-worker-config
+    envs:
+      - application.properties

package/template/apps/worker/kustomize/overlays/prod/kustomization.yaml

@@ -0,0 +1,12 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+namespace: nexst
+
+images:
+  - name: nexst-worker
+    newName: ghcr.io/your-org/nexst-worker
+    newTag: latest

package/template/apps/worker/kustomize/overlays/staging/application.properties

@@ -0,0 +1 @@
+# Staging overrides for base/application.properties.

package/template/apps/worker/kustomize/overlays/staging/kustomization.yaml

@@ -0,0 +1,18 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+namespace: nexst-staging
+
+images:
+  - name: nexst-worker
+    newName: ghcr.io/your-org/nexst-worker
+    newTag: test
+
+configMapGenerator:
+  - name: nexst-worker-config
+    behavior: merge
+    envs:
+      - application.properties

package/template/apps/worker/oxfmt.config.ts

@@ -0,0 +1,8 @@
+import { baseOxfmtConfig } from "@nexst/lint/oxfmt";
+import { baseIgnorePatterns } from "@nexst/lint/oxlint";
+import { defineConfig } from "oxfmt";
+
+export default defineConfig({
+  ...baseOxfmtConfig,
+  ignorePatterns: baseIgnorePatterns,
+});

package/template/apps/worker/oxlint.config.ts

@@ -0,0 +1,15 @@
+import base, { baseIgnorePatterns } from "@nexst/lint/oxlint";
+import { defineConfig } from "oxlint";
+
+export default defineConfig({
+  extends: [base],
+  ignorePatterns: baseIgnorePatterns,
+  rules: {
+    "typescript/no-floating-promises": "error",
+    "typescript/no-misused-promises": "error",
+    "typescript/no-unnecessary-type-assertion": "warn",
+    "typescript/switch-exhaustiveness-check": "warn",
+
+    "vitest/require-mock-type-parameters": "off",
+  },
+});

package/template/apps/worker/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nexst/worker",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#src/*": "./src/*",
+    "#tests/*": "./tests/*"
+  },
+  "scripts": {
+    "dev": "bun --watch src/main.ts",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "lint:ts": "tsc --noEmit",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "unused": "knip --no-config-hints",
+    "test:unit": "vitest run",
+    "test:cov": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@nexst/queues": "workspace:*",
+    "@t3-oss/env-core": "^0.13.11",
+    "bullmq": "^6.3.9",
+    "ioredis": "6.0.0",
+    "pino": "^10.3.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "pino-pretty": "^13.1.3"
+  }
+}

package/template/apps/worker/sonar-project.properties

@@ -0,0 +1,8 @@
+sonar.projectKey=nexst-worker
+
+sonar.sources=src
+sonar.tests=tests
+sonar.test.inclusions=**/*.test.ts
+
+sonar.javascript.lcov.reportPaths=coverage/lcov.info
+sonar.typescript.tsconfigPath=tsconfig.json

package/template/apps/worker/src/env.ts

@@ -0,0 +1,13 @@
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+export const env = createEnv({
+  runtimeEnv: process.env,
+  server: {
+    LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace"]).default("info"),
+    REDIS_HOST: z.string().min(1).default("redis"),
+    REDIS_PORT: z.coerce.number().min(1).max(65_535).default(6379),
+    REDIS_RETRY_LIMIT: z.coerce.number().min(1).default(5),
+    WORKER_CONCURRENCY: z.coerce.number().int().min(1).optional(),
+  },
+});

package/template/apps/worker/src/lib/graceful-shutdown.ts

@@ -0,0 +1,27 @@
+import type { Worker } from "bullmq";
+import type { Redis } from "ioredis";
+import { logger } from "#src/lib/logger.js";
+
+type ClosableWorker = Pick<Worker, "close">;
+type QuitableRedis = Pick<Redis, "quit">;
+
+export function createGracefulShutdown(worker: ClosableWorker, redis: QuitableRedis) {
+  let shutdownPromise: Promise<void> | undefined;
+
+  return (signal: string): Promise<void> => {
+    if (shutdownPromise) {
+      return shutdownPromise;
+    }
+
+    logger.info(`Received ${signal}, closing server...`);
+    shutdownPromise = (async () => {
+      try {
+        await worker.close();
+      } finally {
+        await redis.quit();
+      }
+    })();
+
+    return shutdownPromise;
+  };
+}

package/template/apps/worker/src/lib/logger.ts

@@ -0,0 +1,20 @@
+import pino from "pino";
+import { env } from "#src/env.js";
+
+export const logger = pino({
+  formatters: {
+    level: (label: string) => ({ level: label.toUpperCase() }),
+  },
+  level: env.LOG_LEVEL,
+  ...(process.env.NODE_ENV !== "production" && {
+    transport: {
+      options: {
+        colorize: true,
+        ignore: "pid,hostname,req,res,context",
+        singleLine: true,
+        translateTime: "dd.mm.yyyy, HH:MM:ss",
+      },
+      target: "pino-pretty",
+    },
+  }),
+});

package/template/apps/worker/src/main.ts

@@ -0,0 +1,17 @@
+import { createGracefulShutdown } from "#src/lib/graceful-shutdown.js";
+import { logger } from "#src/lib/logger.js";
+import { redis } from "#src/worker/redis.js";
+import { createWorker } from "#src/worker/worker.js";
+
+const worker = createWorker(redis);
+const gracefulShutdown = createGracefulShutdown(worker, redis);
+
+const handleShutdown = (signal: string) => {
+  void gracefulShutdown(signal).catch((error: unknown) => {
+    logger.error({ error }, "Error during shutdown");
+  });
+};
+
+process.once("SIGINT", () => handleShutdown("SIGINT"));
+
+process.once("SIGTERM", () => handleShutdown("SIGTERM"));

package/template/apps/worker/src/processors/example-processor.ts

@@ -0,0 +1,15 @@
+import type { ExampleJob, ExampleJobResult } from "@nexst/queues";
+import type { Job } from "bullmq";
+
+/**
+ * Handles one `EXAMPLE_QUEUE` job. Replace with real work — keep processors
+ * pure functions of the job so they stay unit-testable without Redis.
+ */
+export function processExampleJob(job: Pick<Job<ExampleJob>, "data">): ExampleJobResult {
+  return {
+    processedAt: new Date().toISOString(),
+    reversed: Array.from(new Intl.Segmenter().segment(job.data.message), (part) => part.segment)
+      .toReversed()
+      .join(""),
+  };
+}

package/template/apps/worker/src/worker/redis.ts

@@ -0,0 +1,19 @@
+import { createRedisConnectionOptions } from "@nexst/queues";
+import { Redis } from "ioredis";
+import { env } from "#src/env.js";
+import { logger } from "#src/lib/logger.js";
+
+export const redis = new Redis(
+  createRedisConnectionOptions({
+    host: env.REDIS_HOST,
+    port: env.REDIS_PORT,
+    retryLimit: env.REDIS_RETRY_LIMIT,
+  }),
+);
+
+redis.on("connect", () => {
+  logger.info("Connected to Redis");
+});
+redis.on("error", (error) => {
+  logger.error({ error }, "Redis connection error");
+});

package/template/apps/worker/src/worker/worker.ts

@@ -0,0 +1,37 @@
+import os from "node:os";
+import { EXAMPLE_QUEUE } from "@nexst/queues";
+import type { ExampleJob, ExampleJobResult } from "@nexst/queues";
+import type { Job } from "bullmq";
+import { Worker } from "bullmq";
+import type { Redis } from "ioredis";
+import { env } from "#src/env.js";
+import { logger } from "#src/lib/logger.js";
+import { processExampleJob } from "#src/processors/example-processor.js";
+
+const workerConcurrency = env.WORKER_CONCURRENCY ?? Math.max(4, os.cpus().length * 2);
+
+export function createWorker(connection: Redis): Worker<ExampleJob, ExampleJobResult> {
+  const worker = new Worker<ExampleJob, ExampleJobResult>(
+    EXAMPLE_QUEUE,
+    async (job: Job<ExampleJob>) => processExampleJob(job),
+    {
+      concurrency: workerConcurrency,
+      connection,
+      removeOnComplete: { age: 24 * 3600, count: 100 },
+      removeOnFail: { count: 500 },
+      stalledInterval: 30_000,
+    },
+  );
+
+  worker.on("completed", (job: Job<ExampleJob>, result: ExampleJobResult) => {
+    logger.info({ jobId: job.id, result }, "Job completed");
+  });
+
+  worker.on("failed", (job: Job<ExampleJob> | undefined, error: unknown) => {
+    logger.error({ error: String(error), jobId: job?.id }, "Job failed");
+  });
+
+  logger.info({ concurrency: workerConcurrency, queue: EXAMPLE_QUEUE }, "Worker started");
+
+  return worker;
+}

package/template/apps/worker/tests/example-processor.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { processExampleJob } from "#src/processors/example-processor.js";
+
+describe("processExampleJob", () => {
+  it("reverses the message and stamps the processing time", () => {
+    const result = processExampleJob({
+      data: { message: "hello", requestedAt: new Date(0).toISOString() },
+    });
+
+    expect(result.reversed).toBe("olleh");
+    expect(Number.isNaN(Date.parse(result.processedAt))).toBe(false);
+  });
+});

package/template/apps/worker/tests/graceful-shutdown.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from "vitest";
+import { createGracefulShutdown } from "#src/lib/graceful-shutdown.js";
+
+vi.mock("#src/lib/logger.js", () => ({
+  logger: {
+    info: vi.fn(),
+  },
+}));
+
+describe("createGracefulShutdown", () => {
+  it("shares one shutdown when multiple signals arrive", async () => {
+    let finishWorkerClose!: () => void;
+    const workerClose = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finishWorkerClose = resolve;
+        }),
+    );
+    const redisQuit = vi.fn().mockResolvedValue("OK");
+    const shutdown = createGracefulShutdown({ close: workerClose }, { quit: redisQuit });
+
+    const firstShutdown = shutdown("SIGINT");
+    const secondShutdown = shutdown("SIGINT");
+
+    expect(secondShutdown).toBe(firstShutdown);
+    expect(workerClose).toHaveBeenCalledOnce();
+    expect(redisQuit).not.toHaveBeenCalled();
+
+    finishWorkerClose();
+    await firstShutdown;
+
+    expect(redisQuit).toHaveBeenCalledOnce();
+  });
+});

package/template/apps/worker/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@nexst/tsconfig/node.json",
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/template/apps/worker/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      include: ["src/**/*.ts"],
+      provider: "v8",
+      reporter: ["text", "lcov"],
+    },
+    include: ["tests/**/*.test.ts"],
+    isolate: true,
+  },
+});