@idevconn/create-icore 0.4.1 → 0.5.0

package/templates/apps/microservices/upload/src/app/app.module.ts

@@ -7,15 +7,26 @@ import { v2 as cloudinary } from 'cloudinary';
 import { SupabaseStorageStrategy } from '@icore/storage-supabase';
 import { FirebaseStorageStrategy } from '@icore/storage-firebase';
 import { CloudinaryStorageStrategy, type CloudinaryApiLike } from '@icore/storage-cloudinary';
-import { FakeStorageStrategy } from '@icore/shared';
+import { FakeStorageStrategy, missingEnv, formatEnvBanner } from '@icore/shared';
 import type { StorageStrategy } from '@icore/shared';
 import { Logger } from '@nestjs/common';
 import { StorageController } from './storage.controller';
 
+const ENV_PATH = 'apps/microservices/upload/.env';
+
+const REQUIRED_ENV: Record<string, string[]> = {
+  supabase: ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'SUPABASE_STORAGE_BUCKET'],
+  firebase: [
+    'FIREBASE_STORAGE_BUCKET',
+    'FB_ADMIN_PROJECT_ID',
+    'FB_ADMIN_CLIENT_EMAIL',
+    'FB_ADMIN_PRIVATE_KEY',
+  ],
+  cloudinary: ['CLOUDINARY_CLOUD_NAME', 'CLOUDINARY_API_KEY', 'CLOUDINARY_API_SECRET'],
+};
+
 function requireEnv(cfg: ConfigService, key: string): string {
-  const val = cfg.getOrThrow<string>(key);
-  if (!val) throw new Error(`${key} is not set — check apps/microservices/upload/.env`);
-  return val;
+  return cfg.getOrThrow<string>(key);
 }
 
 function makeFirebaseStorage(cfg: ConfigService): StorageStrategy {
@@ -97,33 +108,42 @@ function makeCloudinaryStorage(cfg: ConfigService): StorageStrategy {
     {
       provide: 'StorageStrategy',
       useFactory: (cfg: ConfigService): StorageStrategy => {
+        const logger = new Logger('StorageStrategy');
+        const provider = cfg.get<string>('STORAGE_PROVIDER')?.trim();
+        const keys = provider ? REQUIRED_ENV[provider] : undefined;
+        const missing = keys ? missingEnv((k) => cfg.get<string>(k), keys) : [];
+
+        const fallback = (reason?: string): StorageStrategy => {
+          const banner = formatEnvBanner({
+            service: 'upload MS',
+            provider,
+            missing,
+            envPath: ENV_PATH,
+            reason,
+          });
+          if (process.env.NODE_ENV === 'production') throw new Error(banner);
+          logger.warn(banner);
+          return new FakeStorageStrategy();
+        };
+
+        if (!keys || missing.length > 0) return fallback();
+
         try {
-          const provider = requireEnv(cfg, 'STORAGE_PROVIDER');
-          switch (provider) {
-            case 'supabase': {
-              const client = createClient(
-                requireEnv(cfg, 'SUPABASE_URL'),
-                requireEnv(cfg, 'SUPABASE_SERVICE_ROLE_KEY'),
-                { auth: { autoRefreshToken: false, persistSession: false } },
-              );
-              return new SupabaseStorageStrategy({
-                client,
-                bucket: requireEnv(cfg, 'SUPABASE_STORAGE_BUCKET'),
-              });
-            }
-            case 'firebase':
-              return makeFirebaseStorage(cfg);
-            case 'cloudinary':
-              return makeCloudinaryStorage(cfg);
-            default:
-              throw new Error(`Unsupported STORAGE_PROVIDER: ${provider}`);
+          if (provider === 'supabase') {
+            const client = createClient(
+              requireEnv(cfg, 'SUPABASE_URL'),
+              requireEnv(cfg, 'SUPABASE_SERVICE_ROLE_KEY'),
+              { auth: { autoRefreshToken: false, persistSession: false } },
+            );
+            return new SupabaseStorageStrategy({
+              client,
+              bucket: requireEnv(cfg, 'SUPABASE_STORAGE_BUCKET'),
+            });
           }
+          if (provider === 'firebase') return makeFirebaseStorage(cfg);
+          return makeCloudinaryStorage(cfg);
         } catch (err) {
-          new Logger('StorageStrategy').warn(
-            `Not configured: ${err instanceof Error ? err.message : String(err)}. ` +
-              `Requests will fail until apps/microservices/upload/.env is set.`,
-          );
-          return new FakeStorageStrategy();
+          return fallback(err instanceof Error ? err.message : String(err));
         }
       },
       inject: [ConfigService],

package/templates/apps/templates/client-antd/.env.example

@@ -0,0 +1,7 @@
+# ─── Client environment variables ────────────────────────────────────────
+# API gateway base URL.
+#   /api   — default; dev-server proxies it to http://localhost:3001 (see vite.config.mts)
+#   http://localhost:3001/api — set explicitly if you want to bypass the proxy
+#   https://your-domain.com/api — production override when building a standalone SPA
+VITE_API_URL=/api
+

package/templates/apps/templates/client-antd/vite.config.mts

@@ -6,8 +6,10 @@ import { tanstackRouter } from '@tanstack/router-plugin/vite';
 import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
 import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
 import {
+  apiInfoPlugin,
   commonDefines,
   commonManualChunks,
+  commonServer,
   commonTestConfig,
   injectAppVersionPlugin,
   noServerModulesPlugin,
@@ -27,10 +29,7 @@ function depVersion(name: string): string {
 export default defineConfig(() => ({
   root: import.meta.dirname,
   cacheDir: '../../../node_modules/.vite/apps/templates/client-antd',
-  server: {
-    port: 4201,
-    host: 'localhost',
-  },
+  server: commonServer(4201),
   preview: {
     port: 4201,
     host: 'localhost',
@@ -49,6 +48,7 @@ export default defineConfig(() => ({
     nxViteTsPaths(),
     nxCopyAssetsPlugin(['*.md']),
     noServerModulesPlugin(),
+    apiInfoPlugin(),
     injectAppVersionPlugin(rootPackageJson),
   ],
   // Uncomment this if you are using workers.

package/templates/apps/templates/client-mui/.env.example

@@ -0,0 +1,7 @@
+# ─── Client environment variables ────────────────────────────────────────
+# API gateway base URL.
+#   /api   — default; dev-server proxies it to http://localhost:3001 (see vite.config.mts)
+#   http://localhost:3001/api — set explicitly if you want to bypass the proxy
+#   https://your-domain.com/api — production override when building a standalone SPA
+VITE_API_URL=/api
+

package/templates/apps/templates/client-mui/vite.config.mts

@@ -6,8 +6,10 @@ import { tanstackRouter } from '@tanstack/router-plugin/vite';
 import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
 import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
 import {
+  apiInfoPlugin,
   commonDefines,
   commonManualChunks,
+  commonServer,
   commonTestConfig,
   injectAppVersionPlugin,
   noServerModulesPlugin,
@@ -27,10 +29,7 @@ function depVersion(name: string): string {
 export default defineConfig(() => ({
   root: import.meta.dirname,
   cacheDir: '../../../node_modules/.vite/client-mui',
-  server: {
-    port: 4202,
-    host: 'localhost',
-  },
+  server: commonServer(4202),
   preview: {
     port: 4202,
     host: 'localhost',
@@ -49,6 +48,7 @@ export default defineConfig(() => ({
     nxViteTsPaths(),
     nxCopyAssetsPlugin(['*.md']),
     noServerModulesPlugin(),
+    apiInfoPlugin(),
     injectAppVersionPlugin(rootPackageJson),
   ],
   // Uncomment this if you are using workers.

package/templates/apps/templates/client-shadcn/.env.example

@@ -1,2 +1,7 @@
-# API base URL — dev server reverse-proxies /api to the gateway
+# ─── Client environment variables ────────────────────────────────────────
+# API gateway base URL.
+#   /api   — default; dev-server proxies it to http://localhost:3001 (see vite.config.mts)
+#   http://localhost:3001/api — set explicitly if you want to bypass the proxy
+#   https://your-domain.com/api — production override when building a standalone SPA
 VITE_API_URL=/api
+

package/templates/apps/templates/client-shadcn/vite.config.mts

@@ -7,8 +7,10 @@ import { tanstackRouter } from '@tanstack/router-plugin/vite';
 import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
 import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
 import {
+  apiInfoPlugin,
   commonDefines,
   commonManualChunks,
+  commonServer,
   commonTestConfig,
   injectAppVersionPlugin,
   noServerModulesPlugin,
@@ -28,10 +30,7 @@ function depVersion(name: string): string {
 export default defineConfig(() => ({
   root: import.meta.dirname,
   cacheDir: '../../../node_modules/.vite/apps/templates/client-shadcn',
-  server: {
-    port: 4200,
-    host: 'localhost',
-  },
+  server: commonServer(4200),
   preview: {
     port: 4200,
     host: 'localhost',
@@ -51,6 +50,7 @@ export default defineConfig(() => ({
     nxViteTsPaths(),
     nxCopyAssetsPlugin(['*.md']),
     noServerModulesPlugin(),
+    apiInfoPlugin(),
     injectAppVersionPlugin(rootPackageJson),
   ],
   // Uncomment this if you are using workers.

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

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

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

@@ -3,7 +3,7 @@ import { ClientsModule } from '@nestjs/microservices';
 import { buildTransport } from '@icore/shared';
 import { AuthClientService } from './auth-client.service';
 
-export const AUTH_CLIENT = 'AUTH_CLIENT';
+import { AUTH_CLIENT } from './auth-client.tokens';
 
 @Module({})
 export class AuthClientModule {

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

@@ -2,7 +2,7 @@ import { Inject, Injectable } from '@nestjs/common';
 import { ClientProxy } from '@nestjs/microservices';
 import { firstValueFrom } from 'rxjs';
 import type { AuthSession, OAuthProvider, OAuthStartResult, VerifiedToken } from '@icore/shared';
-import { AUTH_CLIENT } from './auth-client.module';
+import { AUTH_CLIENT } from './auth-client.tokens';
 
 @Injectable()
 export class AuthClientService {

package/templates/libs/auth-client/src/lib/auth-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 AUTH_CLIENT = 'AUTH_CLIENT';

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

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

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

@@ -2,7 +2,7 @@ import { Inject, Injectable, 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 {

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/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,4 @@
+export * from './env';
 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 {

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",