@qlover/create-app 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 
 
+## [0.1.12](https://github.com/qlover/fe-base/compare/create-app-v0.1.11...create-app-v0.1.12) (2025-03-18)
+
+
+### Features
+
+* add inversify ioc ([#270](https://github.com/qlover/fe-base/issues/270)) ([8c7ba06](https://github.com/qlover/fe-base/commit/8c7ba06bc5bef63d85c59a94737afac9be59138f))
+
 ## [0.1.11](https://github.com/qlover/fe-base/compare/create-app-v0.1.10...create-app-v0.1.11) (2025-03-12)
 
 ## [0.1.10](https://github.com/qlover/fe-base/compare/create-app-v0.1.9...create-app-v0.1.10) (2025-02-20)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlover/create-app",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "type": "module",
   "private": false,
   "main": "./dist/es/index.js",

package/templates/react-app/.env

@@ -1,3 +1,24 @@
+NODE_ENV=production
+
+# ci
+NPM_TOKEN=
+GITHUB_TOKEN=
+
+# fe-scripts
+FE_RELEASE_BRANCH=master
+FE_RELEASE=false
+FE_RELEASE_ENV=production
+
+# ===== build
+VITE_PUBLIC_PATH=
 VITE_SERVER_PORT=3200
-VITE_OPENAI_API_URL=
-VITE_OPENAI_API_KEY=
+
+# ===== app config
+VITE_USER_TOKEN_STORAGE_KEY=fe_user_token
+VITE_OPEN_AI_MODELS='["gpt-4o-mini","gpt-3.5-turbo","gpt-3.5-turbo-2","gpt-4","gpt-4-32k"]'
+VITE_OPEN_AI_BASE_URL=https://api.openai.com/v1
+VITE_OPEN_AI_TOKEN=sk-proj-1234567890
+VITE_OPEN_AI_TOKEN_PREFIX=Bearer
+VITE_OPEN_AI_REQUIRE_TOKEN=true
+VITE_LOGIN_USER=admin
+VITE_LOGIN_PASSWORD=123456

package/templates/react-app/config/common.ts

@@ -0,0 +1,3 @@
+export const envPrefix = 'VITE_';
+
+export const browserGlobalsName = 'feGlobals';

package/templates/react-app/lib/bootstrap/Bootstrap.ts

@@ -0,0 +1,36 @@
+import type { IOCContainerInterface } from './IOCContainerInterface';
+import { SyncExecutor } from '@qlover/fe-utils';
+import { BootstrapExecutorPlugin } from './BootstrapExecutorPlugin';
+
+export class Bootstrap extends SyncExecutor {
+  constructor(private IOCContainer: IOCContainerInterface) {
+    super();
+  }
+
+  getIOCContainer(): IOCContainerInterface {
+    return this.IOCContainer;
+  }
+
+  use(plugin: BootstrapExecutorPlugin | BootstrapExecutorPlugin[]): this {
+    if (Array.isArray(plugin)) {
+      plugin.forEach((p) => super.use(p));
+      return this;
+    }
+
+    super.use(plugin);
+
+    return this;
+  }
+
+  start(root: unknown): void {
+    this.exec({ root, ioc: this.IOCContainer }, () => {
+      // nothing to do
+    });
+  }
+
+  startNoError(root: unknown): void {
+    this.execNoError({ root, ioc: this.IOCContainer }, () => {
+      // nothing to do
+    });
+  }
+}

package/templates/react-app/lib/bootstrap/BootstrapExecutorPlugin.ts

@@ -0,0 +1,20 @@
+import { IOCContainerInterface } from './IOCContainerInterface';
+import { ExecutorContext, ExecutorPlugin } from '@qlover/fe-utils';
+
+export type BootstrapArgs = {
+  /**
+   * starup global object
+   *
+   * maybe window or globalThis
+   */
+  root: unknown;
+  /**
+   * IOC container
+   */
+  ioc: IOCContainerInterface;
+};
+
+export interface BootstrapExecutorPlugin
+  extends ExecutorPlugin<BootstrapArgs> {}
+
+export type BootstrapContext = ExecutorContext<BootstrapArgs>;

package/templates/react-app/lib/bootstrap/IOCContainerInterface.ts

@@ -0,0 +1,33 @@
+/**
+ * IOC container
+ *
+ */
+export interface IOCContainerInterface {
+  /**
+   * configure IOC container
+   *
+   * eg. may need to manually bind implementation classes
+   */
+  configure(): void;
+  configure<Container>(registers?: IOCRegisterInterface<Container>[]): void;
+
+  /**
+   * bind instance
+   *
+   * @param serviceIdentifier
+   * @param value
+   */
+  bind<T>(serviceIdentifier: unknown, value: T): void;
+
+  /**
+   * get instance
+   *
+   * @param serviceIdentifier
+   * @returns
+   */
+  get<T>(serviceIdentifier: unknown): T;
+}
+
+export interface IOCRegisterInterface<T> {
+  register(container: T, thisArg: IOCContainerInterface): void;
+}

package/templates/react-app/lib/bootstrap/IOCManagerInterface.ts

@@ -0,0 +1,12 @@
+import type { IOCContainerInterface } from './IOCContainerInterface';
+
+export interface IOCManagerInterface {
+  get<T>(identifier: unknown): T;
+
+  /**
+   * implement IOC container
+   */
+  implement(container: IOCContainerInterface): void;
+
+  get implemention(): IOCContainerInterface | null;
+}

package/templates/react-app/lib/bootstrap/index.ts

@@ -0,0 +1,7 @@
+export * from './Bootstrap';
+export * from './BootstrapExecutorPlugin';
+export * from './plugins/InjectIOC';
+export * from './plugins/InjectEnv';
+export * from './plugins/InjectGlobal';
+export * from './IOCContainerInterface';
+export * from './IOCManagerInterface';

package/templates/react-app/lib/bootstrap/plugins/InjectEnv.ts

@@ -0,0 +1,61 @@
+import type { BootstrapExecutorPlugin } from '../BootstrapExecutorPlugin';
+
+export interface EnvConfigInterface {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+export class InjectEnv implements BootstrapExecutorPlugin {
+  readonly pluginName = 'InjectEnv';
+
+  constructor(
+    private target: EnvConfigInterface,
+    private source: Record<string, unknown>,
+    private envPrefix: string = '',
+    private envWhiteList: string[] = ['env', 'userNodeEnv']
+  ) {}
+
+  static isJSONString(value: string): boolean {
+    return (
+      typeof value === 'string' &&
+      value !== '' &&
+      (value === 'true' ||
+        value === 'false' ||
+        value.startsWith('{') ||
+        value.startsWith('['))
+    );
+  }
+
+  env<D>(key: string, defaultValue?: D): D {
+    // transform key to env key
+    const formattedKey = key.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase();
+
+    const envKey = `${this.envPrefix}${formattedKey}`;
+    const value = this.source[envKey];
+    // if it is a json string, parse it
+    if (typeof value === 'string' && InjectEnv.isJSONString(value)) {
+      return JSON.parse(value);
+    }
+
+    return (value ?? defaultValue) as D;
+  }
+
+  inject(config: EnvConfigInterface): void {
+    for (const key in config) {
+      if (this.envWhiteList.includes(key)) {
+        continue;
+      }
+
+      const value = config[key as keyof typeof config];
+
+      config[key as keyof typeof config] = this.env(key, value);
+    }
+  }
+
+  onBefore(): void {
+    this.inject(this.target);
+
+    // transform readonly to writable
+    Object.freeze(this.target);
+  }
+}

package/templates/react-app/lib/bootstrap/plugins/InjectGlobal.ts

@@ -0,0 +1,36 @@
+import type { ExecutorContext } from '@qlover/fe-utils';
+import type {
+  BootstrapArgs,
+  BootstrapExecutorPlugin
+} from '../BootstrapExecutorPlugin';
+
+export class InjectGlobal implements BootstrapExecutorPlugin {
+  readonly pluginName = 'InjectGlobal';
+
+  constructor(
+    private sources: Record<string, unknown>,
+    private target?: string | Record<string, unknown>
+  ) {}
+
+  onBefore(context: ExecutorContext<BootstrapArgs>): void {
+    // if target is provided, inject globals to target
+    if (typeof this.target === 'string') {
+      Object.assign(context.parameters.root!, {
+        [this.target]: Object.freeze(Object.assign({}, this.sources))
+      });
+      return;
+    }
+
+    const target = this.target || context.parameters.root;
+
+    if (typeof target !== 'object' || target === null) {
+      throw new Error('target must be an object');
+    }
+
+    // inject globals to root
+    for (const key in this.sources) {
+      const element = this.sources[key];
+      Object.assign(target, { [key]: element });
+    }
+  }
+}

package/templates/react-app/lib/bootstrap/plugins/InjectIOC.ts

@@ -0,0 +1,24 @@
+import type { IOCRegisterInterface } from '../IOCContainerInterface';
+import type { IOCManagerInterface } from '../IOCManagerInterface';
+import type {
+  BootstrapContext,
+  BootstrapExecutorPlugin
+} from '../BootstrapExecutorPlugin';
+import { Container } from 'inversify';
+
+export class InjectIOC implements BootstrapExecutorPlugin {
+  readonly pluginName = 'InjectIOC';
+
+  constructor(
+    private IOC: IOCManagerInterface,
+    private registeres: IOCRegisterInterface<Container>[]
+  ) {}
+
+  onBefore(context: BootstrapContext): void {
+    const { ioc } = context.parameters;
+    this.IOC.implement(ioc);
+
+    // maybe runtimes configure
+    ioc.configure(this.registeres);
+  }
+}

package/templates/react-app/lib/env-config/injectPkgConfig.ts

@@ -0,0 +1,11 @@
+export function injectPkgConfig(
+  options: [string, string][],
+  envPrefix: string = ''
+) {
+  options.forEach(([key, value]) => {
+    const envKey = `${envPrefix}${key}`;
+    if (!process.env[envKey]) {
+      process.env[envKey] = value;
+    }
+  });
+}

package/templates/react-app/lib/openAiApi/OpenAIClient.ts

@@ -25,7 +25,7 @@ export interface OpenAIChatParmas {
 
 export type OpenAIAargs = {
   commonPluginConfig: RequestCommonPluginConfig;
-  models: readonly string[];
+  models: string[];
 };
 
 export type OpenAIClientConfig = Partial<RequestAdapterFetchConfig> &

package/templates/react-app/package.json

@@ -56,11 +56,13 @@
     "i18next": "^24.2.0",
     "i18next-browser-languagedetector": "^8.0.2",
     "i18next-http-backend": "^3.0.1",
+    "inversify": "^7.1.0",
     "lodash": "^4.17.21",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-i18next": "^15.2.0",
-    "react-router-dom": "^7.1.5"
+    "react-router-dom": "^7.1.5",
+    "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.11.1",

package/templates/react-app/src/base/consts/IOCIdentifier.ts

@@ -0,0 +1,16 @@
+/**
+ * IOC identifier
+ *
+ * @description
+ * IOC identifier is used to identify the service in the IOC container.
+ *
+ * @example
+ * ```ts
+ * const a = IOC(IOCIdentifier.JSON);
+ * ```
+ */
+export const IOCIdentifier = Object.freeze({
+  JSON: 'JSON',
+  JSONStorage: 'JSONStorage',
+  Logger: 'Logger'
+});

package/templates/react-app/src/base/port/IOCFunctionInterface.ts

@@ -0,0 +1,39 @@
+import type { IOCManagerInterface } from '@lib/bootstrap';
+import type { JSONSerializer, JSONStorage, Logger } from '@qlover/fe-utils';
+import type { ServiceIdentifier } from 'inversify';
+import type { IOCIdentifier } from '@/base/consts/IOCIdentifier';
+
+export type IOCIdentifierMap = {
+  [IOCIdentifier.JSON]: JSONSerializer;
+  [IOCIdentifier.JSONStorage]: JSONStorage;
+  [IOCIdentifier.Logger]: Logger;
+};
+
+/**
+ * IOC function
+ *
+ * eg.
+ * ```ts
+ * const a = IOC(A);
+ * const logger = IOC(ConstanstIdentifier.Logger);
+ * ```
+ *
+ */
+export interface IOCFunctionInterface extends IOCManagerInterface {
+  /**
+   * get constant identifier
+   *
+   * Preferred match for simple types
+   */
+  <K extends keyof IOCIdentifierMap>(serviceIdentifier: K): IOCIdentifierMap[K];
+
+  /**
+   * get service identifier
+   */
+  <T>(serviceIdentifier: ServiceIdentifier<T>): T;
+
+  get<K extends keyof IOCIdentifierMap>(
+    serviceIdentifier: K
+  ): IOCIdentifierMap[K];
+  get<T>(serviceIdentifier: ServiceIdentifier<T>): T;
+}

package/templates/react-app/src/base/port/InversifyIocInterface.ts

@@ -0,0 +1,9 @@
+import type { IOCRegisterInterface } from '@lib/bootstrap';
+import type { Container } from 'inversify';
+
+export type InversifyRegisterContainer = Container;
+/**
+ * Inversify register interface.
+ */
+export interface InversifyRegisterInterface
+  extends IOCRegisterInterface<InversifyRegisterContainer> {}

package/templates/react-app/src/base/port/StorageTokenInterface.ts

@@ -1,5 +1,27 @@
+/**
+ * Storage token interface
+ *
+ * @description
+ * Storage token interface is used to store and retrieve token from the storage.
+ */
 export interface StorageTokenInterface {
+  /**
+   * Get token
+   *
+   * @returns {string} token
+   */
   getToken(): string;
+
+  /**
+   * Set token
+   *
+   * @param {string} token
+   * @param {number} expireTime
+   */
   setToken(token: string, expireTime?: number): void;
+
+  /**
+   * Remove token
+   */
   removeToken(): void;
 }

package/templates/react-app/src/base/types/Page.ts

@@ -1,9 +1,7 @@
-import { LazyExoticComponent, PropsWithChildren } from 'react';
-import { RouteObject } from 'react-router-dom';
-
-import { TFunction } from 'i18next';
-import { UseTranslationResponse } from 'react-i18next';
-import { RouteConfigValue } from '@lib/router-loader/RouterLoader';
+import type { LazyExoticComponent, PropsWithChildren } from 'react';
+import type { TFunction } from 'i18next';
+import type { UseTranslationResponse } from 'react-i18next';
+import type { RouteConfigValue } from '@lib/router-loader/RouterLoader';
 
 export interface BasePageProvider {
   meta: RouteMeta;
@@ -37,10 +35,3 @@ export type PagesMaps = Record<
   | (() => LazyExoticComponent<React.ComponentType<unknown>>)
   | (() => React.ComponentType<unknown>)
 >;
-
-export type LoadProps = {
-  pagesMaps: PagesMaps;
-  componentPath: string;
-  route: RouteType;
-  Provider?: React.ComponentType<PropsWithChildren<RouteMeta>>;
-};

package/templates/react-app/src/base/types/global.d.ts

@@ -1,7 +1,8 @@
 import * as feGlobals from '@/core/globals';
+import type { browserGlobalsName } from '@config/common';
 
 declare global {
   interface Window {
-    feGlobals: Readonly<typeof feGlobals>;
+    [browserGlobalsName]: Readonly<typeof feGlobals>;
   }
 }

package/templates/react-app/src/components/ThemeSwitcher.tsx

@@ -1,4 +1,4 @@
-import { IOC } from '@/core';
+import { IOC } from '@/core/IOC';
 import { useController } from '@lib/fe-react-controller';
 import { ThemeController } from '@lib/fe-react-theme/ThemeController';
 import { useTranslation } from 'react-i18next';

package/templates/react-app/src/core/AppConfig.ts

@@ -0,0 +1,27 @@
+import type { EnvConfigInterface } from '@lib/bootstrap';
+
+class AppConfig implements EnvConfigInterface {
+  readonly appName = '';
+  readonly appVersion = '';
+  /**
+   * vite mode
+   */
+  readonly env = import.meta.env.VITE_USER_NODE_ENV;
+
+  readonly userTokenStorageKey = 'fe_user_token';
+  readonly openAiModels = [
+    'gpt-4o-mini',
+    'gpt-3.5-turbo',
+    'gpt-3.5-turbo-2',
+    'gpt-4',
+    'gpt-4-32k'
+  ];
+  readonly openAiBaseUrl = '';
+  readonly openAiToken = '';
+  readonly openAiTokenPrefix = '';
+  readonly openAiRequireToken = true;
+  readonly loginUser = '';
+  readonly loginPassword = '';
+}
+
+export default new AppConfig();

package/templates/react-app/src/core/AppIOCContainer.ts

@@ -0,0 +1,30 @@
+import type { InversifyRegisterInterface } from '@/base/port/InversifyIocInterface';
+import type { IOCContainerInterface } from '@lib/bootstrap';
+import { ServiceIdentifier, Container } from 'inversify';
+
+export class AppIOCContainer implements IOCContainerInterface {
+  private container: Container;
+
+  constructor() {
+    this.container = new Container({
+      // allow `@injectable` decorator, auto bind injectable classes
+      autobind: true,
+      // use singleton scope
+      defaultScope: 'Singleton'
+    });
+  }
+
+  configure(registers?: InversifyRegisterInterface[]): void {
+    if (registers) {
+      registers.forEach((register) => register.register(this.container, this));
+    }
+  }
+
+  bind<T>(key: ServiceIdentifier<T>, value: T): void {
+    this.container.bind<T>(key).toConstantValue(value);
+  }
+
+  get<T>(key: string): T {
+    return this.container.get<T>(key);
+  }
+}

package/templates/react-app/src/core/IOC.ts

@@ -0,0 +1,48 @@
+// ! dont't import tsx, only ts file
+import type { IOCContainerInterface } from '@lib/bootstrap';
+import type {
+  IOCIdentifierMap,
+  IOCFunctionInterface
+} from '@/base/port/IOCFunctionInterface';
+import type { ServiceIdentifier } from 'inversify';
+
+let implemention: IOCContainerInterface | null;
+
+function ioc<T>(serviceIdentifier: ServiceIdentifier<T>): T;
+function ioc<K extends keyof IOCIdentifierMap>(
+  serviceIdentifier: K
+): IOCIdentifierMap[K];
+function ioc<T, K extends keyof IOCIdentifierMap>(
+  serviceIdentifier: ServiceIdentifier<T> | K
+): T | IOCIdentifierMap[K] {
+  if (!implemention) {
+    throw new Error('IOC is not implemented');
+  }
+  return implemention.get(serviceIdentifier);
+}
+
+/**
+ * IOC manager function.
+ *
+ * eg.
+ * ```ts
+ * class A {}
+ * const a = IOC(A);
+ * ```
+ *
+ * or
+ * ```ts
+ * const a = IOC<A>();
+ * ```
+ *
+ * or use get(),
+ */
+export const IOC: IOCFunctionInterface = Object.assign(ioc, {
+  get implemention() {
+    return implemention;
+  },
+  implement: (container: IOCContainerInterface) => {
+    implemention = container;
+  },
+  get: ioc
+});

package/templates/react-app/src/core/bootstrap.ts

@@ -1,21 +1,66 @@
-import * as feGlobals from '@/core/globals';
-import { IOC } from '.';
-import { IOCInterface } from '@/base/port/IOCInterface';
+import {
+  Bootstrap,
+  BootstrapExecutorPlugin,
+  InjectEnv,
+  InjectIOC,
+  InjectGlobal
+} from '@lib/bootstrap';
+import { AppIOCContainer } from '@/core/AppIOCContainer';
+import AppConfig from '@/core/AppConfig';
+import { envPrefix, browserGlobalsName } from '@config/common';
+import { IOC } from './IOC';
+import * as globals from '@/core/globals';
 import { I18nService } from '@/services/I18nService';
+import { registerList } from './registers';
 
-export class Bootstrap {
-  constructor(private IOCContainer: IOCInterface) {}
+/**
+ * Bootstrap
+ *
+ * 1. inject env config to AppConfig
+ * 2. inject IOC to Application
+ * 3. inject globals to window
+ *
+ */
+export default function startup(root: typeof globalThis) {
+  const window =
+    typeof root !== 'undefined' && root instanceof Window ? root : undefined;
 
-  start(): void {
-    // set global feGlobals
-    if (typeof window !== 'undefined') {
-      window.feGlobals = Object.freeze(Object.assign({}, feGlobals));
-    }
+  if (!window) {
+    throw new Error('Not Found Window');
+  }
+
+  const bootstrap = new Bootstrap(new AppIOCContainer());
 
-    // startup IOC
-    IOC.implement(this.IOCContainer);
+  /**
+   * bootstrap start list
+   *
+   * - inject env config to AppConfig
+   * - inject IOC to Application
+   * - inject globals to window
+   * - inject i18n service to Application
+   */
+  const bootstrapList: BootstrapExecutorPlugin[] = [
+    new InjectEnv(AppConfig, import.meta.env, envPrefix),
+    new InjectIOC(IOC, registerList),
+    new InjectGlobal(globals, browserGlobalsName),
+    new I18nService(window.location.pathname)
+  ];
+
+  if (AppConfig.env !== 'production') {
+    bootstrapList.push({
+      pluginName: 'InjectDevTools',
+      onBefore() {
+        console.log(AppConfig);
+      },
+      onError({ error }) {
+        console.error(`${AppConfig.appName} starup error:`, error);
+      }
+    });
+  }
 
-    // startup i18n
-    I18nService.init();
+  try {
+    bootstrap.use(bootstrapList).start(root);
+  } catch (error) {
+    console.error(`${AppConfig.appName} starup error:`, error);
   }
 }

package/templates/react-app/src/core/globals.ts

@@ -6,7 +6,7 @@ import {
   SyncStorage
 } from '@qlover/fe-utils';
 
-export const env = import.meta.env.VITE_NODE_ENV;
+export const env = import.meta.env.VITE_USER_NODE_ENV;
 export const isProduction = env === 'production';
 
 /**