@qlover/create-app 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 
 
+## [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)
 
 ## [0.1.9](https://github.com/qlover/fe-base/compare/create-app-v0.1.8...create-app-v0.1.9) (2025-02-20)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qlover/create-app",
-  "version": "0.1.10",
+  "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/lib/router-loader/Page.ts

@@ -0,0 +1,64 @@
+import { LazyExoticComponent, PropsWithChildren } from 'react';
+import { RouteObject } from 'react-router-dom';
+
+import { TFunction } from 'i18next';
+import { UseTranslationResponse } from 'react-i18next';
+
+export interface BasePageProvider {
+  meta: RouteMeta;
+  i18n: UseTranslationResponse<string, string>;
+  t: TFunction<string, string>;
+}
+
+export type RouteCategory = 'main' | 'auth' | 'common';
+
+export interface RouteMeta {
+  category?: RouteCategory;
+  /**
+   * from app.router.json
+   */
+  title?: string;
+  icon?: string;
+  /**
+   * from app.router.json
+   *
+   * @default 'common'
+   */
+  localNamespace?: string;
+}
+
+export type RouteType = RouteObject & {
+  meta?: RouteMeta;
+};
+
+export type RouteConfig = {
+  routes: RouteType[];
+};
+
+export type PagesMaps = Record<
+  string,
+  | (() => LazyExoticComponent<React.ComponentType<unknown>>)
+  | (() => React.ComponentType<unknown>)
+>;
+
+export type LoadProps = {
+  pagesMaps: PagesMaps;
+  componentPath: string;
+  route: RouteType;
+  Provider?: React.ComponentType<PropsWithChildren<RouteMeta>>;
+};
+
+
+type ComponentValue = React.ComponentType<unknown> | LazyExoticComponent<React.ComponentType<unknown>>;
+
+export type ComponentMaps = {
+  /**
+   * key: ./xxx/bbb.(jsx,js,tsx,ts)
+   */
+  [key: string]: ComponentValue | (() => Promise<ComponentValue>) | (() => ComponentValue);
+}
+
+// new RouterManager({
+//   routes: [],
+//   componentMaps:
+// });

package/templates/react-app/lib/router-loader/RouterLoader.ts

@@ -0,0 +1,90 @@
+import { RouteObject } from 'react-router-dom';
+import isString from 'lodash/isString';
+import type { ComponentType, LazyExoticComponent, ReactNode } from 'react';
+
+type ComponentValue = Record<string, () => unknown>;
+
+type RouteComponentType<T = unknown> =
+  | ComponentType<T>
+  | LazyExoticComponent<ComponentType<T>>;
+
+export type RouteConfigValue = Omit<RouteObject, 'element' | 'children'> & {
+  /**
+   * 路径
+   * 
+   * FIXME: support `ReactNode`
+   */
+  element?: string;
+  children?: RouteConfigValue[];
+  meta?: Record<string, unknown>;
+};
+
+export type RouterLoaderRender = (
+  route: Omit<RouteConfigValue, 'element'> & {
+    element: () => RouteComponentType;
+  }
+) => ReactNode;
+
+export type RouterLoaderOptions = {
+  /**
+   * 路由配置
+   */
+  routes?: RouteConfigValue[];
+
+  /**
+   * 组件映射表
+   */
+  componentMaps?: ComponentValue;
+
+  /**
+   * 渲染路由
+   */
+  render: RouterLoaderRender;
+};
+
+export class RouterLoader {
+  constructor(private readonly options: RouterLoaderOptions) {
+    if (!options.render) {
+      throw new Error('RouterLoader render is required');
+    }
+  }
+
+  getComponentMaps(): ComponentValue {
+    const { componentMaps = {} } = this.options;
+
+    return componentMaps;
+  }
+
+  getComponent(element: string): () => RouteComponentType {
+    const maps = this.getComponentMaps();
+
+    const component = maps[element];
+
+    if (!component) {
+      throw new Error(`Component not found: ${element}`);
+    }
+
+    return component as () => RouteComponentType;
+  }
+
+  toRoute(route: RouteConfigValue): RouteObject {
+    const { render } = this.options;
+    const { element, children, ...rest } = route;
+
+    if (!element || !isString(element)) {
+      console.warn(
+        `Invalid route, path is: ${route.path}, element is: ${element}`
+      );
+    }
+
+    const componet = this.getComponent(element || '404');
+    const Element = render({ ...rest, element: componet });
+
+    // @ts-expect-error
+    return {
+      ...rest,
+      element: Element,
+      children: children?.map((child) => this.toRoute(child))
+    };
+  }
+}

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/App.tsx

@@ -1,14 +1,35 @@
 import '@/uikit/styles/css/index.css';
 import { createBrowserRouter, RouterProvider } from 'react-router-dom';
-import { createFeReactRoutes } from './pages';
-import { useMemo } from 'react';
-import { IOC } from './core';
-import { RouterController } from './uikit/controllers/RouterController';
+import { lazy, useMemo } from 'react';
+import { RouterLoader } from '@lib/router-loader/RouterLoader';
+import appConfig from '@config/app.router.json';
+import { RouterRenderComponent } from './components/RouterRenderComponent';
+import { PagesMaps } from './base/types/Page';
+
+function getAllPages() {
+  const modules = import.meta.glob('./pages/**/*.tsx');
+  return Object.keys(modules).reduce((acc, path) => {
+    const componentName = path.replace(/^\.\/pages\/(.*)\.tsx$/, '$1');
+    acc[componentName] = () =>
+      lazy(
+        modules[path] as () => Promise<{
+          default: React.ComponentType<unknown>;
+        }>
+      );
+    return acc;
+  }, {} as PagesMaps);
+}
+
+const routerLoader = new RouterLoader({
+  componentMaps: getAllPages(),
+  render: RouterRenderComponent
+});
 
 function App() {
   const routerBase = useMemo(() => {
-    const routerController = IOC(RouterController);
-    const routes = createFeReactRoutes(routerController.getRoutes());
+    const routes = appConfig.base.routes.map((route) =>
+      routerLoader.toRoute(route)
+    );
     const router = createBrowserRouter(routes);
     return router;
   }, []);

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,8 +1,7 @@
-import { LazyExoticComponent, PropsWithChildren } from 'react';
-import { RouteObject } from 'react-router-dom';
-
-import { TFunction } from 'i18next';
-import { UseTranslationResponse } from 'react-i18next';
+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;
@@ -27,12 +26,8 @@ export interface RouteMeta {
   localNamespace?: string;
 }
 
-export type RouteType = RouteObject & {
-  meta?: RouteMeta;
-};
-
 export type RouteConfig = {
-  routes: RouteType[];
+  routes: RouteConfigValue[];
 };
 
 export type PagesMaps = Record<
@@ -40,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>;
   }
 }