@devisfuture/electron-modular 1.0.11 → 1.1.3

package/README.md

@@ -81,7 +81,9 @@ import { UserModule } from "./user/module.js";
 import { ResourcesModule } from "./resources/module.js";
 
 initSettings({
-  baseRestApi: process.env.BASE_REST_API ?? "",
+  cspConnectSources: process.env.BASE_REST_API
+    ? [process.env.BASE_REST_API]
+    : [],
   localhostPort: process.env.LOCALHOST_ELECTRON_SERVER_PORT ?? "",
   folders: {
     distRenderer: "dist-renderer",
@@ -100,6 +102,10 @@ app.on("ready", async () => {
 
 ---
 
+## Example App
+
+A small example app demonstrating how to use this package is available at [trae-op/quick-start_react_electron-modular](https://github.com/trae-op/quick-start_react_electron-modular). It contains a minimal React + Electron project that shows module registration, IPC handlers and window managers in action — check its README for setup and run instructions.
+
 ## Module Structure
 
 An example of each module's structure, but you can use your own:
@@ -266,6 +272,7 @@ export class UserService {
 Handle communication between main and renderer processes.
 
 ```typescript
+import { ipcMain, type IpcMainEvent } from "electron";
 import {
   IpcHandler,
   TIpcHandlerInterface,
@@ -280,7 +287,7 @@ export class UserIpc implements TIpcHandlerInterface {
   async onInit({ getWindow }: TParamOnInit<TWindows["main"]>) {
     const mainWindow = getWindow("window:main");
 
-    ipcMainOn("user:fetch", async (event, userId: string) => {
+    ipcMain.on("user:fetch", (event: IpcMainEvent, userId: string) => {
       const user = await this.userService.byId(userId);
       event.reply("user:fetch:response", user);
     });
@@ -370,6 +377,80 @@ Important implementation notes ⚠️
 - Handlers are attached per BrowserWindow instance and cleaned up automatically when the window is closed, so you don't have to manually remove listeners.
 - The same instance and set of handlers are tracked in a WeakMap internally; re-attaching the same `windowInstance` will not duplicate listeners.
 
+### Opening windows with URL params (dynamic routes) 🔗
+
+If your renderer uses dynamic routes (for example React Router) you can open a window that targets a specific route by passing a `hash` to `create`. The `hash` is merged with the window manager's defaults and can carry route segments or parameters (for example `window:items/<id>`).
+
+Renderer process
+
+```tsx
+<Route path="/window:items/:id" element={<ItemWindow />} />
+```
+
+Renderer (inside `ItemWindow`)
+
+```tsx
+import { useParams } from "react-router-dom";
+
+const ItemWindow = () => {
+  const { id } = useParams<{ id?: string }>();
+
+  if (!id) return null;
+
+  return <span>item id: {id}</span>;
+};
+
+export default ItemWindow;
+```
+
+Main process
+
+```typescript
+import { ipcMain, type IpcMainEvent } from "electron";
+import { IpcHandler, type TParamOnInit } from "@devisfuture/electron-modular";
+
+@IpcHandler()
+export class ItemsIpc {
+  constructor() {}
+
+  onInit({ getWindow }: TParamOnInit<TWindows["items"]>): void {
+    const window = getWindow("window:items");
+
+    ipcMain.on(
+      "itemWindow",
+      async (_: IpcMainEvent, payload: { id?: string }) => {
+        if (payload.id === undefined) {
+          return;
+        }
+
+        await window.create({
+          hash: `window:items/${payload.id}`,
+        });
+      },
+    );
+  }
+}
+```
+
+Default manager example
+
+```ts
+@WindowManager<TWindows['items']>({
+  hash: 'window:items',
+  isCache: true,
+  options: {
+    width: 350,
+    height: 300,
+  },
+})
+```
+
+Notes:
+
+- `await window.create({...})` merges the provided options with the manager's default `options`.
+- When `isCache: true`, `getWindow('window:items')` returns the cached manager and `create` will reuse (or re-create) the BrowserWindow as implemented by the manager.
+- Use a unique `hash` per route instance (for example `window:items/<id>`), so the renderer can read the route from the window URL and navigate to the correct route when the window loads.
+
 ---
 
 ## TypeScript types — `TWindows["myWindow"]`
@@ -482,13 +563,17 @@ Initializes framework configuration.
 
 **Parameters:**
 
-- `baseRestApi: string` - Base REST API URL
+- `cspConnectSources?: string[]` - Optional array of origins to include in the `connect-src` directive of the generated Content-Security-Policy header.
 - `localhostPort: string` - Development server port
 - `folders: { distRenderer: string; distMain: string }` - Build output folders
 
 ```typescript
 initSettings({
-  baseRestApi: process.env.BASE_REST_API ?? "",
+  cspConnectSources: [
+    "https://api.example.com",
+    "https://cdn.example.com",
+    "wss://websocket.example.com",
+  ],
   localhostPort: process.env.LOCALHOST_ELECTRON_SERVER_PORT ?? "",
   folders: {
     distRenderer: "dist-renderer",
@@ -497,6 +582,12 @@ initSettings({
 });
 ```
 
+> Note: When a cached window is created the framework will set a Content-Security-Policy header for renderer responses. The `connect-src` directive will include `'self'` plus any entries from `cspConnectSources`. For example:
+
+```
+connect-src 'self' https://api.example.com https://cdn.example.com wss://websocket.example.com;
+```
+
 #### `bootstrapModules(modules[])`
 
 Bootstraps all modules and initializes the DI container.
@@ -707,7 +798,9 @@ export class MyWindow implements TWindowManager {}
 
 ```typescript
 initSettings({
-  baseRestApi: process.env.BASE_REST_API ?? "",
+  cspConnectSources: process.env.BASE_REST_API
+    ? [process.env.BASE_REST_API]
+    : [],
   localhostPort: process.env.LOCALHOST_ELECTRON_SERVER_PORT ?? "",
   folders: { distRenderer: "dist-renderer", distMain: "dist-main" },
 });

package/dist/@core/bootstrap/settings.d.ts

@@ -3,7 +3,7 @@ export type TFolderSettings = {
     distMain: string;
 };
 export type TSettings = {
-    baseRestApi: string;
+    cspConnectSources?: string[];
     localhostPort: string;
     folders: TFolderSettings;
 };

package/dist/@core/control-window/create.js

@@ -3,8 +3,9 @@ import path from "node:path";
 import { cacheWindows } from "./cache.js";
 import { getWindow } from "./receive.js";
 import { getSettings } from "../bootstrap/settings.js";
-const setupCSP = (base, dev) => {
-    const csp = `default-src 'self'; connect-src 'self' ${base}; img-src * data:; style-src 'self' 'unsafe-inline'; script-src 'self' ${dev ? "'unsafe-inline'" : ""};`
+const setupCSP = (sources, dev) => {
+    const connectSrc = sources.length > 0 ? ` ${sources.join(" ")}` : "";
+    const csp = `default-src 'self'; connect-src 'self'${connectSrc}; img-src * data:; style-src 'self' 'unsafe-inline'; script-src 'self' ${dev ? "'unsafe-inline'" : ""};`
         .replace(/\s{2,}/g, " ")
         .trim();
     session.defaultSession.webRequest.onHeadersReceived((d, cb) => {
@@ -21,8 +22,6 @@ export const createWindow = ({ hash, options, isCache, loadURL, }) => {
     const isDev = process.env.NODE_ENV === "development";
     const ui = path.join(app.getAppPath(), `/${settings.folders.distRenderer}/index.html`);
     const preload = path.join(app.getAppPath(), isDev ? "." : "..", `/${settings.folders.distMain}/preload.cjs`);
-    if (!settings.baseRestApi)
-        console.warn('Warning: You have to add an environment variable called "process.env.BASE_REST_API"!');
     if (!settings.localhostPort)
         console.warn('Warning: You have to add an environment variable called "process.env.LOCALHOST_ELECTRON_SERVER_PORT"!');
     if (hash && isCache) {
@@ -41,8 +40,8 @@ export const createWindow = ({ hash, options, isCache, loadURL, }) => {
             ...options?.webPreferences,
         },
     });
-    if (isCache && !loadURL)
-        setupCSP(settings.baseRestApi, isDev);
+    if (isCache && !loadURL && settings.cspConnectSources)
+        setupCSP(settings.cspConnectSources, isDev);
     if (loadURL) {
         win.loadURL(loadURL);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devisfuture/electron-modular",
-  "version": "1.0.11",
+  "version": "1.1.3",
   "description": "Core module system, DI container, IPC handlers, and window utilities for Electron main process.",
   "type": "module",
   "main": "./dist/index.js",