@idevconn/create-icore 0.4.1 → 0.5.1

package/templates/libs/jobs-client/src/lib/jobs-client.module.ts

@@ -2,7 +2,7 @@ import { DynamicModule, Module } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { JobsClientService } from './jobs-client.service';
 
-export const JOBS_REDIS_URL = 'JOBS_REDIS_URL';
+import { JOBS_REDIS_URL } from './jobs-client.tokens';
 
 @Module({})
 export class JobsClientModule {

package/templates/libs/jobs-client/src/lib/jobs-client.service.ts

@@ -1,16 +1,28 @@
-import { Inject, Injectable, OnModuleDestroy } from '@nestjs/common';
+import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
 import { Queue, type JobsOptions } from 'bullmq';
 import IORedis from 'ioredis';
 import { ICORE_QUEUES, type JobsMap } from '@icore/shared';
-import { JOBS_REDIS_URL } from './jobs-client.module';
+import { JOBS_REDIS_URL } from './jobs-client.tokens';
 
 @Injectable()
 export class JobsClientService implements OnModuleDestroy {
+  private readonly logger = new Logger(JobsClientService.name);
   private readonly connection: IORedis;
   private readonly queues = new Map<string, Queue>();
 
   constructor(@Inject(JOBS_REDIS_URL) redisUrl: string) {
-    this.connection = new IORedis(redisUrl, { maxRetriesPerRequest: null });
+    this.connection = new IORedis(redisUrl, {
+      maxRetriesPerRequest: null,
+      retryStrategy: (times) => Math.min(times * 200, 5000),
+    });
+    // Without an 'error' handler ioredis throws an unhandled 'error' event and
+    // crashes the host process when Redis is down. Log once, keep retrying.
+    let warned = false;
+    this.connection.on('error', (err: Error) => {
+      if (warned) return;
+      warned = true;
+      this.logger.warn(`Redis unreachable at ${redisUrl}: ${err.message}. enqueue() will retry.`);
+    });
   }
 
   async enqueue<K extends keyof JobsMap>(

package/templates/libs/jobs-client/src/lib/jobs-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const JOBS_REDIS_URL = 'JOBS_REDIS_URL';

package/templates/libs/notes-client/src/index.ts

@@ -1,2 +1,3 @@
+export * from './lib/notes-client.tokens';
 export * from './lib/notes-client.module';
 export * from './lib/notes-client.service';

package/templates/libs/notes-client/src/lib/notes-client.module.ts

@@ -3,7 +3,7 @@ import { ClientsModule } from '@nestjs/microservices';
 import { buildTransport } from '@icore/shared';
 import { NotesClientService } from './notes-client.service';
 
-export const NOTES_CLIENT = 'NOTES_CLIENT';
+import { NOTES_CLIENT } from './notes-client.tokens';
 
 @Module({})
 export class NotesClientModule {

package/templates/libs/notes-client/src/lib/notes-client.service.ts

@@ -2,7 +2,7 @@ import { Inject, Injectable } from '@nestjs/common';
 import { ClientProxy } from '@nestjs/microservices';
 import { firstValueFrom } from 'rxjs';
 import type { ListNotesOptions, Note } from '@icore/shared';
-import { NOTES_CLIENT } from './notes-client.module';
+import { NOTES_CLIENT } from './notes-client.tokens';
 
 @Injectable()
 export class NotesClientService {

package/templates/libs/notes-client/src/lib/notes-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const NOTES_CLIENT = 'NOTES_CLIENT';

package/templates/libs/payment-client/src/index.ts

@@ -1,2 +1,3 @@
+export * from './lib/payment-client.tokens';
 export * from './lib/payment-client.module';
 export * from './lib/payment-client.service';

package/templates/libs/payment-client/src/lib/payment-client.module.ts

@@ -3,7 +3,7 @@ import { ClientsModule } from '@nestjs/microservices';
 import { buildTransport } from '@icore/shared';
 import { PaymentClientService } from './payment-client.service';
 
-export const PAYMENT_CLIENT = 'PAYMENT_CLIENT';
+import { PAYMENT_CLIENT } from './payment-client.tokens';
 
 @Module({})
 export class PaymentClientModule {

package/templates/libs/payment-client/src/lib/payment-client.service.ts

@@ -7,7 +7,7 @@ import type {
   OrderResult,
   RequestOptions,
 } from '@idevconn/payment';
-import { PAYMENT_CLIENT } from './payment-client.module';
+import { PAYMENT_CLIENT } from './payment-client.tokens';
 
 @Injectable()
 export class PaymentClientService {

package/templates/libs/payment-client/src/lib/payment-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const PAYMENT_CLIENT = 'PAYMENT_CLIENT';

package/templates/libs/shared/src/__tests__/bootstrap.unit.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { bootstrapMicroservice } from '../bootstrap';
+
+interface FakeApp {
+  listen: () => Promise<void>;
+  close: () => Promise<void>;
+}
+
+function makeLogger() {
+  return { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+}
+
+const ORIG = { ...process.env };
+
+describe('bootstrapMicroservice', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    delete process.env['AUTH_TRANSPORT'];
+    delete process.env['NODE_ENV'];
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    Object.assign(process.env, ORIG);
+  });
+
+  it('redis in dev: retries with a banner instead of exiting, then binds when the broker appears', async () => {
+    process.env['AUTH_TRANSPORT'] = 'redis';
+    const logger = makeLogger();
+    const close = vi.fn().mockResolvedValue(undefined);
+    let attempts = 0;
+    const createApp = vi.fn(async (): Promise<FakeApp> => {
+      attempts += 1;
+      return {
+        // first attempt fails (broker down), second succeeds
+        listen:
+          attempts < 2 ? () => Promise.reject(new Error('ECONNREFUSED')) : () => Promise.resolve(),
+        close,
+      };
+    });
+
+    const done = bootstrapMicroservice('AUTH', createApp, logger);
+    // let the first attempt fail + the retry delay elapse
+    await vi.advanceTimersByTimeAsync(3000);
+    await done;
+
+    expect(createApp).toHaveBeenCalledTimes(2);
+    expect(close).toHaveBeenCalledTimes(1); // failed app cleaned up before retry
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn.mock.calls[0][0]).toContain('broker unreachable');
+    expect(logger.log).toHaveBeenCalledTimes(1); // "listening" on success
+  });
+
+  it('tcp: fails fast (process.exit) rather than retrying', async () => {
+    process.env['AUTH_TRANSPORT'] = 'tcp';
+    const logger = makeLogger();
+    const exit = vi.spyOn(process, 'exit').mockImplementation(((): never => {
+      throw new Error('__exit__');
+    }) as never);
+    const createApp = vi.fn(
+      async (): Promise<FakeApp> => ({
+        listen: () => Promise.reject(new Error('EADDRINUSE')),
+        close: () => Promise.resolve(),
+      }),
+    );
+
+    await expect(bootstrapMicroservice('AUTH', createApp, logger)).rejects.toThrow('__exit__');
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('production: fails fast even on a broker transport', async () => {
+    process.env['AUTH_TRANSPORT'] = 'redis';
+    process.env['NODE_ENV'] = 'production';
+    const logger = makeLogger();
+    const exit = vi.spyOn(process, 'exit').mockImplementation(((): never => {
+      throw new Error('__exit__');
+    }) as never);
+    const createApp = vi.fn(
+      async (): Promise<FakeApp> => ({
+        listen: () => Promise.reject(new Error('ECONNREFUSED')),
+        close: () => Promise.resolve(),
+      }),
+    );
+
+    await expect(bootstrapMicroservice('AUTH', createApp, logger)).rejects.toThrow('__exit__');
+    expect(exit).toHaveBeenCalledWith(1);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+});

package/templates/libs/shared/src/__tests__/transport.unit.test.ts

@@ -33,8 +33,12 @@ describe('buildTransport', () => {
     process.env.AUTH_REDIS_URL = 'redis://localhost:6379';
     const opts = buildTransport('AUTH');
     expect(opts.transport).toBe(Transport.REDIS);
-    const redis = opts.options as { url: string };
+    const redis = opts.options as { url: string; retryAttempts: number; retryDelay: number };
     expect(redis.url).toBe('redis://localhost:6379');
+    // Resilience: NestJS gives up (and app.listen() rejects) when retryAttempts
+    // is unset — an effectively-infinite retry keeps reconnecting instead.
+    expect(redis.retryAttempts).toBe(Number.POSITIVE_INFINITY);
+    expect(redis.retryDelay).toBeGreaterThan(0);
   });
 
   it('selects NATS when ${PREFIX}_TRANSPORT=nats', () => {
@@ -42,8 +46,16 @@ describe('buildTransport', () => {
     process.env.AUTH_NATS_URL = 'nats://localhost:4222,nats://localhost:4223';
     const opts = buildTransport('AUTH');
     expect(opts.transport).toBe(Transport.NATS);
-    const nats = opts.options as { servers: string[] };
+    const nats = opts.options as {
+      servers: string[];
+      reconnect: boolean;
+      maxReconnectAttempts: number;
+    };
     expect(nats.servers).toEqual(['nats://localhost:4222', 'nats://localhost:4223']);
+    // Resilience: reconnect forever once connected (the initial connect is left
+    // to reject so bootstrapMicroservice() can banner + retry).
+    expect(nats.reconnect).toBe(true);
+    expect(nats.maxReconnectAttempts).toBe(-1);
   });
 
   it('throws on unknown transport', () => {

package/templates/libs/shared/src/bootstrap.ts

@@ -0,0 +1,79 @@
+import { formatEnvBanner } from './env';
+
+interface MicroserviceLike {
+  listen: () => Promise<unknown>;
+  close: () => Promise<void>;
+}
+
+interface LoggerLike {
+  log: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string, trace?: unknown) => void;
+}
+
+const RETRY_DELAY_MS = 3000;
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Boots a microservice and binds its transport, surviving a broker that isn't
+ * up yet.
+ *
+ * NestJS `ServerRedis`/`ServerNats` REJECT `app.listen()` on the *initial*
+ * connect failure — the ioredis retryStrategy / NATS reconnect only governs
+ * re-connection after a first successful connect. So without this helper a MS
+ * would `process.exit(1)` whenever Redis/NATS is down on boot, even though the
+ * transport options ask for infinite retries.
+ *
+ * Behaviour (honours the "never crash on missing infra" rule):
+ *  - tcp transport, or NODE_ENV=production → fail fast: `process.exit(1)`.
+ *  - redis/nats in dev → log a boxed banner and retry `listen()` forever, so
+ *    the service idles until the broker appears, then binds automatically.
+ *
+ * `createApp` must construct a *fresh* app each call: a failed listen closes
+ * the transport's clients, so the next attempt needs a new instance.
+ */
+export async function bootstrapMicroservice(
+  prefix: string,
+  createApp: () => Promise<MicroserviceLike>,
+  logger: LoggerLike,
+): Promise<void> {
+  const transport = (process.env[`${prefix}_TRANSPORT`] ?? 'tcp').toLowerCase();
+  const isProd = process.env['NODE_ENV'] === 'production';
+  const failFast = transport === 'tcp' || isProd;
+
+  for (let attempt = 1; ; attempt++) {
+    let app: MicroserviceLike | undefined;
+    try {
+      app = await createApp();
+      await app.listen();
+      logger.log(`${prefix} microservice listening — transport=${transport}`);
+      return;
+    } catch (err) {
+      if (app) await app.close().catch(() => undefined);
+      const reason = err instanceof Error ? err.message : String(err);
+
+      if (failFast) {
+        logger.error(
+          `${prefix} microservice bootstrap failed`,
+          err instanceof Error ? err.stack : err,
+        );
+        process.exit(1);
+      }
+
+      logger.warn(
+        formatEnvBanner({
+          service: `${prefix} microservice`,
+          provider: transport,
+          missing: [],
+          envPath: `the service .env (${prefix}_${transport.toUpperCase()}_URL)`,
+          reason: `${reason} — retry ${attempt} in ${RETRY_DELAY_MS / 1000}s; idling until the ${transport} broker is reachable`,
+          headline: `⚠  ${prefix} microservice — ${transport} broker unreachable (idling, not crashing)`,
+        }),
+      );
+      await delay(RETRY_DELAY_MS);
+    }
+  }
+}

package/templates/libs/shared/src/env.ts

@@ -0,0 +1,88 @@
+// Server-side env helpers. NOT exported from ./client (browser-safe entry) —
+// generated microservices import these to report which provider credentials
+// are missing on startup instead of crashing.
+
+/**
+ * Returns the keys whose value is missing or blank.
+ * @param get   accessor (e.g. ConfigService.get bound to the MS config)
+ * @param keys  env var names required for the selected provider
+ */
+export function missingEnv(get: (key: string) => string | undefined, keys: string[]): string[] {
+  return keys.filter((k) => !get(k)?.trim());
+}
+
+/**
+ * Builds an eye-catching boxed banner listing the env vars a microservice
+ * needs but is missing, so it stands out in the `yarn dev` log noise.
+ */
+export function formatEnvBanner(opts: {
+  service: string;
+  provider: string | undefined;
+  missing: string[];
+  envPath: string;
+  reason?: string;
+  /** Override the first line. Defaults to the in-memory-fake warning. */
+  headline?: string;
+}): string {
+  const { service, provider, missing, envPath, reason, headline } = opts;
+  const lines: string[] = [];
+  lines.push(headline ?? `⚠  ${service} — running with an IN-MEMORY FAKE (requests will fail)`);
+  lines.push('');
+  if (!provider) {
+    lines.push(`Provider env var is not set.`);
+  } else if (missing.length > 0) {
+    lines.push(`"${provider}" needs these env vars, currently missing:`);
+    for (const k of missing) lines.push(`  • ${k}`);
+  } else if (reason) {
+    // Vars are present but invalid (e.g. placeholder URL the SDK rejected).
+    lines.push(`"${provider}" failed to initialise:`);
+    lines.push(`  ${reason}`);
+  }
+  lines.push('');
+  lines.push(`Set real values in:  ${envPath}`);
+
+  const width = Math.max(...lines.map((l) => l.length), 50);
+  const top = `╔═${'═'.repeat(width)}═╗`;
+  const bot = `╚═${'═'.repeat(width)}═╝`;
+  const body = lines.map((l) => `║ ${l.padEnd(width)} ║`).join('\n');
+  return `\n${top}\n${body}\n${bot}`;
+}
+
+/**
+ * Returns a boxed startup info banner listing every MS the gateway will
+ * connect to, reading the current transport env vars.
+ */
+export function formatGatewayBanner(opts: {
+  port: number;
+  origin: string;
+  services: Array<{ name: string; prefix: string }>;
+}): string {
+  const { port, origin, services } = opts;
+  const lines: string[] = [];
+  lines.push(`Gateway listening on  ${origin}:${port}/api`);
+  lines.push(`Swagger UI            ${origin}:${port}/api/docs`);
+  lines.push('');
+  lines.push('Microservice transports:');
+  for (const { name, prefix } of services) {
+    const kind = (process.env[`${prefix}_TRANSPORT`] ?? 'tcp').toLowerCase();
+    let target: string;
+    if (kind === 'tcp') {
+      const host = process.env[`${prefix}_HOST`] ?? '127.0.0.1';
+      const port_ = process.env[`${prefix}_PORT`] ?? '?';
+      target = `tcp  ${host}:${port_}`;
+    } else if (kind === 'redis') {
+      target = `redis  ${process.env[`${prefix}_REDIS_URL`] ?? '(REDIS_URL not set)'}`;
+    } else if (kind === 'nats') {
+      target = `nats  ${process.env[`${prefix}_NATS_URL`] ?? '(NATS_URL not set)'}`;
+    } else {
+      target = kind;
+    }
+    lines.push(`  ${name.padEnd(10)} →  ${target}`);
+  }
+
+  const width = Math.max(...lines.map((l) => l.length), 50);
+  const top = `╔═${'═'.repeat(width)}═╗`;
+  const bot = `╚═${'═'.repeat(width)}═╝`;
+  const body = lines.map((l) => `║ ${l.padEnd(width)} ║`).join('\n');
+  return `\n${top}\n${body}\n${bot}`;
+}

package/templates/libs/shared/src/index.ts

@@ -1,3 +1,5 @@
+export * from './env';
+export * from './bootstrap';
 export * from './abilities';
 export * from './jobs';
 export * from './strategies';

package/templates/libs/shared/src/transport.ts

@@ -1,4 +1,40 @@
 import { Transport, type ClientOptions, type MicroserviceOptions } from '@nestjs/microservices';
+import { formatEnvBanner } from './env';
+
+// Transport vars each kind needs (besides ${prefix}_TRANSPORT itself).
+function transportKeys(prefix: string, kind: string): string[] {
+  switch (kind) {
+    case 'tcp':
+      return [`${prefix}_HOST`, `${prefix}_PORT`];
+    case 'redis':
+      return [`${prefix}_REDIS_URL`];
+    case 'nats':
+      return [`${prefix}_NATS_URL`];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Throws an eye-catching banner if any transport var for `prefix` is missing.
+ * Used by both the gateway client modules and each MS bootstrap, so transport
+ * misconfiguration surfaces clearly instead of a raw "Missing env var".
+ */
+function assertTransportEnv(prefix: string, kind: string): void {
+  const keys = transportKeys(prefix, kind);
+  const missing = keys.filter((k) => !process.env[k]?.trim());
+  if (missing.length > 0) {
+    throw new Error(
+      formatEnvBanner({
+        service: `${prefix} transport`,
+        provider: kind,
+        missing,
+        envPath: `the service .env (${prefix}_* transport vars)`,
+        headline: `⚠  ${prefix} transport (${kind}) not configured — cannot reach the microservice`,
+      }),
+    );
+  }
+}
 
 function required(name: string): string {
   const value = process.env[name];
@@ -17,6 +53,7 @@ function requiredPort(name: string): number {
 
 export function buildTransport(prefix: string): ClientOptions {
   const kind = (process.env[`${prefix}_TRANSPORT`] ?? 'tcp').toLowerCase();
+  assertTransportEnv(prefix, kind);
   switch (kind) {
     case 'tcp':
       return {
@@ -30,15 +67,37 @@ export function buildTransport(prefix: string): ClientOptions {
       // ioredis accepts a connection URL string; the NestJS RedisOptions type
       // exposes host/port fields but passes options directly to ioredis which
       // also accepts a url field at runtime.
+      //
+      // retryAttempts/retryDelay are mandatory for resilience: NestJS
+      // ServerRedis builds its ioredis retryStrategy from them, and when
+      // retryAttempts is unset it logs "retry attempts not specified", stops
+      // reconnecting, and `app.listen()` REJECTS → the MS process exits. With
+      // an effectively-infinite retry the initial connect stays pending and
+      // keeps reconnecting, so a not-yet-up Redis never crashes the service —
+      // it idles and attaches once Redis is reachable.
       return {
         transport: Transport.REDIS,
-        options: { url: required(`${prefix}_REDIS_URL`) },
+        options: {
+          url: required(`${prefix}_REDIS_URL`),
+          retryAttempts: Number.POSITIVE_INFINITY,
+          retryDelay: 2000,
+        },
       } as unknown as ClientOptions;
     case 'nats':
+      // reconnect/maxReconnectAttempts: -1 retries forever once connected, so a
+      // dropped broker re-attaches instead of giving up. The *initial* connect
+      // is intentionally allowed to reject when NATS is down on boot —
+      // bootstrapMicroservice() catches that, logs a banner, and retries, giving
+      // the same visible behaviour as the Redis transport above.
       return {
         transport: Transport.NATS,
-        options: { servers: required(`${prefix}_NATS_URL`).split(',') },
-      };
+        options: {
+          servers: required(`${prefix}_NATS_URL`).split(','),
+          reconnect: true,
+          maxReconnectAttempts: -1,
+          reconnectTimeWait: 2000,
+        },
+      } as unknown as ClientOptions;
     default:
       throw new Error(`Unknown transport: ${kind}`);
   }

package/templates/libs/upload-client/src/index.ts

@@ -1,2 +1,3 @@
+export * from './lib/upload-client.tokens';
 export * from './lib/upload-client.module';
 export * from './lib/upload-client.service';

package/templates/libs/upload-client/src/lib/upload-client.module.ts

@@ -3,7 +3,7 @@ import { ClientsModule } from '@nestjs/microservices';
 import { buildTransport } from '@icore/shared';
 import { UploadClientService } from './upload-client.service';
 
-export const UPLOAD_CLIENT = 'UPLOAD_CLIENT';
+import { UPLOAD_CLIENT } from './upload-client.tokens';
 
 @Module({})
 export class UploadClientModule {

package/templates/libs/upload-client/src/lib/upload-client.service.ts

@@ -2,7 +2,7 @@ import { Inject, Injectable } from '@nestjs/common';
 import { ClientProxy } from '@nestjs/microservices';
 import { firstValueFrom } from 'rxjs';
 import type { StorageRef } from '@icore/shared';
-import { UPLOAD_CLIENT } from './upload-client.module';
+import { UPLOAD_CLIENT } from './upload-client.tokens';
 
 @Injectable()
 export class UploadClientService {

package/templates/libs/upload-client/src/lib/upload-client.tokens.ts

@@ -0,0 +1,4 @@
+// Injection token — kept in its own file so module and service can both
+// import it without creating a circular dependency (which breaks DI in
+// webpack-bundled NestJS apps).
+export const UPLOAD_CLIENT = 'UPLOAD_CLIENT';

package/templates/libs/vite-plugins/src/index.d.mts

@@ -19,3 +19,9 @@ export declare function commonTestConfig(
   name: string,
   coverageDir: string,
 ): NonNullable<UserConfig['test']>;
+
+export declare function commonServer(
+  port: number,
+): NonNullable<import('vite').UserConfig['server']>;
+
+export declare function apiInfoPlugin(opts?: { proxyTarget?: string }): import('vite').Plugin;

package/templates/libs/vite-plugins/src/index.mjs

@@ -104,3 +104,53 @@ export function commonTestConfig(name, coverageDir) {
     },
   };
 }
+
+/**
+ * Shared Vite dev-server config: binds the given port and proxies `/api`
+ * to the gateway (:3001) so the client's relative API base works in dev.
+ * @param {number} port
+ * @returns {import('vite').UserConfig['server']}
+ */
+export function commonServer(port) {
+  return {
+    port,
+    host: 'localhost',
+    proxy: { '/api': { target: 'http://localhost:3001', changeOrigin: true } },
+  };
+}
+
+function box(lines) {
+  const width = Math.max(...lines.map((l) => l.length), 48);
+  const top = `╔═${'═'.repeat(width)}═╗`;
+  const bot = `╚═${'═'.repeat(width)}═╝`;
+  const body = lines.map((l) => `║ ${l.padEnd(width)} ║`).join('\n');
+  return `\n${top}\n${body}\n${bot}`;
+}
+
+/**
+ * Prints a terminal banner on dev-server start showing the API base the client
+ * will use and the gateway proxy target, so misconfiguration is obvious.
+ * @param {{ proxyTarget?: string }} [opts]
+ * @returns {import('vite').Plugin}
+ */
+export function apiInfoPlugin(opts = {}) {
+  const target = opts.proxyTarget ?? 'http://localhost:3001';
+  return {
+    name: 'icore-api-info',
+    apply: 'serve',
+    configureServer(server) {
+      server.httpServer?.once('listening', () => {
+        const explicit = process.env.VITE_API_URL;
+        const lines = explicit
+          ? [`API base: VITE_API_URL = ${explicit}`, '', `(gateway dev-proxy is bypassed)`]
+          : [
+              `API base: /api  →  proxied to ${target}`,
+              '',
+              `Gateway must be running on ${target}.`,
+              `Override with VITE_API_URL in the client .env.`,
+            ];
+        server.config.logger.info(box([`ℹ  iCore client API wiring`, '', ...lines]));
+      });
+    },
+  };
+}

package/templates/package.json

@@ -23,6 +23,7 @@
     "prepare": "husky"
   },
   "devDependencies": {
+    "@icore/vite-plugins": "workspace:*",
     "@eslint/js": "^9.18.0",
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.0",

package/templates/tools/create-icore/_template-shell/package.json

@@ -23,6 +23,7 @@
     "prepare": "husky"
   },
   "devDependencies": {
+    "@icore/vite-plugins": "workspace:*",
     "@eslint/js": "^9.18.0",
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.0",

package/templates/tsconfig.base.json

@@ -29,7 +29,8 @@
       "@icore/payment-client": ["./libs/payment-client/src/index.ts"],
       "@icore/notes-client": ["./libs/notes-client/src/index.ts"],
       "@icore/jobs-client": ["./libs/jobs-client/src/index.ts"],
-      "@icore/vite-plugins": ["./libs/vite-plugins/src/index.d.mts"]
+      "@icore/vite-plugins": ["./libs/vite-plugins/src/index.d.mts"],
+      "@icore/firebase-admin": ["./libs/firebase-admin/src/index.ts"]
     }
   },
   "exclude": ["node_modules", "dist", ".nx"]