@degreesign/webapp 1.6.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DegreeSign
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# DegreeSign webpack setup for WebApps
+The progressive web application template built with Webpack and TypeScript. Leverage `@degreesign/webapp` package for streamlined configuration and deployment. In addition to server bundling.
+
+## Features
+- **Webpack-powered**: Optimised bundling for production-ready applications.
+- **TypeScript Support**: Ensures type safety and modern JavaScript features.
+- **Modular Structure**: Organised folder layout for scalability.
+- **SEO & PWA Ready**: Configurable metadata and manifest for progressive web apps.
+- **Customisable**: Flexible Webpack configuration via `@degreesign/webapp`.
+
+## Recommended Setup
+1. **Node.js**: Version 18.x or higher.
+2. **Package Manager**: npm or Yarn.
+3. **Dependencies**:
+   - Install the `@degreesign/webapp` package: `npm install @degreesign/webapp`.
+   - Install Webpack and TypeScript: `npm install webpack webpack-cli typescript ts-loader`.
+4. **Environment**:
+   - Create a `.env` file in the root directory with for any keys used in ts code.
+   - Ensure a TypeScript configuration (`tsconfig.json`) is set up.
+5. **IDE**: Use VS Code or any TypeScript-compatible editor for best experience.
+
+## Package File
+Add file `package.json` as following
+```json
+{
+  "license": "MIT",
+  "scripts": {
+    "build": "webpack --config webpack.web.ts",
+    "start": "webpack serve --config webpack.web.ts",
+    "build_server": "webpack --config webpack.server.ts",
+    "start_server": "webpack serve --config webpack.server.ts"
+  },
+  "devDependencies": {
+    "@degreesign/webapp": "latest"
+  }
+}
+```
+
+## WebApp FrontEnd
+WebApp front-end website configuration
+
+### Folder Structure
+```
+app_folder/
+├── public_html/                 # Output directory for production build
+├── src/                         # Source files
+│   ├── assets/                  # Static assets
+│   │   ├── images/              # Image assets
+│   │   │   ├── favicon.ico      # Favicon
+│   │   │   ├── app_icon.png     # App icon for PWA
+│   │   │   └── app_cover_image.webp  # Cover image for SEO
+│   ├── code/                    # Utility scripts
+│   │   └── utils.ts             # Shared TypeScript utilities (optional)
+│   ├── pages/                   # Page-specific files
+│   │   ├── home/                # Home page
+│   │   │   ├── home.ts          # Home page logic
+│   │   │   └── home.html        # Home page template
+│   └── styles.css               # Global styles
+├── webpack.web.ts            # Webpack configuration
+├── .env                         # Environment variables
+├── tsconfig.json                # TypeScript configuration
+└── package.json                 # Project metadata and scripts
+```
+
+### Configuration
+Add `webpack.web.ts` file as the core of the webapp build process as following
+```typescript
+import { build } from "@degreesign/webapp";
+
+module.exports = build({
+  type: "webapp",
+  websiteDomain: "example.com",
+  websiteName: "Your App Name",
+  appShortName: "AppName",
+  twitterUserName: "YourApp",
+  publishedTime: "2025-01-01T00:00:00+00:00",
+  author: "Your Name",
+  websiteTitle: "Your App Slogan",
+  websiteDescription: "A brief description of your app.",
+  coverImage: "app_cover_image.webp",
+  coverImageDescription: "A descriptive alt text for the cover image.",
+  background_color: "#ffffff",
+  theme_color: "#000000",
+  appIcon: "app_icon.png",
+  appIconMaskable: "app_icon_maskable.png",
+  fav_icon: "favicon.ico",
+  orientation: "portrait",
+  pagesList: [{
+    uri: `home`,
+    name: `HomePage`,
+    description: `Progressive Web App (PWA) HomePage`,
+  }],
+  htmlCommonElements: [],
+  obfuscateON: false,
+  srcDir: "src",
+  assetsDir: "assets",
+  commonDir: "code",
+  imagesDir: "images",
+  pagesDir: "pages",
+  pageHome: "home",
+  productionDir: "public_html",
+  htaccessCustom: "",
+  startURI: "/",
+  language: "en_GB",
+  port: 3210,
+});
+```
+
+## WebApp BackEnd
+WebApp back-end server configuration
+
+### Folder Structure
+```
+app_folder/
+├── server_build/                # Output directory for production build
+├── server/                      # Source files
+│   ├── code/                    # Utility scripts
+│   │   └── utils.ts             # Shared TypeScript utilities (optional)
+│   └── main.ts                  # Main server file
+├── webpack.server.ts            # Webpack configuration
+├── .env                         # Environment variables
+├── tsconfig.json                # TypeScript configuration
+└── package.json                 # Project metadata and scripts
+```
+
+### Configuration
+Add `webpack.server.ts` file as the core of the server build process as following
+```typescript
+import { build } from "@degreesign/webapp";
+
+module.exports = build({
+    type: `server`,
+    obfuscateON: true,
+    srcDir: `server`,
+    productionDir: `server_build`,
+    filesList: [`main`],
+    port: 3211,
+});
+```
+
+## Key Configuration Notes
+- **Environment Variables**: Use `.env` to securely store sensitive data.
+- **Development Server**: Runs on `port: 3210` by default.
+- **PWA Support**: Customise `app_icon`, `fav_icon`, and `orientation` for a native-like experience.
+- **SEO Optimisation**: Set `websiteTitle`, `websiteDescription`, and `coverImage` for better search visibility.
+- **Pages**: Add all pages to `pagesList`.
+
+## Getting Started
+1. **Clone the Repository**:
+   ```bash
+   git clone https://github.com/DegreeSign/ds_webapp.git
+   cd ds_webapp
+   ```
+2. **Install Dependencies**:
+   ```bash
+   yarn install
+   ```
+3. **Create Folders Structure**:
+   Create folder structure for webapp, server, or both and add necessary files as explained above.
+4. **Run Development Server**:
+   *For WebApp*
+   ```bash
+   yarn start
+   ```
+   *For Server*
+   ```bash
+   yarn start_server
+   ```
+5. **Build for Production**:
+   *For WebApp*
+   ```bash
+   yarn build
+   ```
+   Output will be in the `public_html/` directory.
+   *For Server*
+   ```bash
+   yarn build_server
+   ```
+   Output will be in the `server_build/` directory.
+
+## Contributing
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feature-name`.
+3. Commit changes: `git commit -m "Add feature"`.
+4. Push to the branch: `git push origin feature-name`.
+5. Submit a pull request.
+
+## License
+This project is licensed under the MIT License. See the `LICENSE` file for details.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { build } from "./src/main";
+import { Page } from "./src/types";
+import { readData, readJSON, writeData, writeJSON } from "./src/utils";
+export { build, writeData, writeJSON, readData, readJSON, Page, };

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readJSON = exports.readData = exports.writeJSON = exports.writeData = exports.build = void 0;
+const main_1 = require("./src/main");
+Object.defineProperty(exports, "build", { enumerable: true, get: function () { return main_1.build; } });
+const utils_1 = require("./src/utils");
+Object.defineProperty(exports, "readData", { enumerable: true, get: function () { return utils_1.readData; } });
+Object.defineProperty(exports, "readJSON", { enumerable: true, get: function () { return utils_1.readJSON; } });
+Object.defineProperty(exports, "writeData", { enumerable: true, get: function () { return utils_1.writeData; } });
+Object.defineProperty(exports, "writeJSON", { enumerable: true, get: function () { return utils_1.writeJSON; } });

package/dist/src/main.d.ts

@@ -0,0 +1,4 @@
+import { Configuration } from "webpack";
+import { ConfigBuild } from "./types";
+declare const build: (params: ConfigBuild) => Configuration;
+export { build };

package/dist/src/main.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.build = void 0;
+const path_1 = __importDefault(require("path"));
+const webpack_1 = __importDefault(require("webpack"));
+const clean_webpack_plugin_1 = require("clean-webpack-plugin");
+const terser_webpack_plugin_1 = __importDefault(require("terser-webpack-plugin"));
+const webpack_node_externals_1 = __importDefault(require("webpack-node-externals"));
+const webpack_bundle_analyzer_1 = require("webpack-bundle-analyzer");
+const dotenv_1 = __importDefault(require("dotenv"));
+const web_1 = require("./web");
+const obfuscate_1 = require("./obfuscate");
+dotenv_1.default.config();
+const build = (params) => {
+    const isWebApp = params.type != `server`, { mode = `production`, obfuscateON = false, minimiseON = true, srcDir = `src`, productionDir = `public_html`, port = 3210, maxFileSizeMB = 2, resolveOptions = {}, licenseText = ``, } = params, { filesList = [], } = isWebApp ? {} : params, { entryPoints = {}, customWebRules = [], configWebPlugins = [], cssMinimise = [] } = isWebApp ? (0, web_1.webConfig)(params) : {}, fileSize = maxFileSizeMB * 1024 ** 2, envKeys = {};
+    // Environment keys
+    for (const key in process.env)
+        envKeys[`process.env.${key}`] = JSON.stringify(process.env[key]);
+    // entry points
+    if (!isWebApp)
+        for (let i = 0; i < filesList.length; i++) {
+            const fileName = filesList[i];
+            entryPoints[fileName] =
+                `./${srcDir}/${fileName}.ts`;
+        }
+    ;
+    return {
+        entry: entryPoints,
+        performance: {
+            maxAssetSize: fileSize,
+            maxEntrypointSize: fileSize,
+        },
+        output: {
+            path: path_1.default.resolve(process.cwd(), productionDir),
+            ...isWebApp ? {
+                filename: `code/[name].[contenthash].js`,
+                publicPath: '/', // Ensures assets are referenced with absolute paths starting from the root
+            } : {
+                filename: `[name].js`,
+                libraryTarget: `commonjs`, // CommonJS for Node.js
+                globalObject: `typeof globalThis !== 'undefined' ? globalThis : (typeof self !== 'undefined' ? self : this)`,
+            },
+        },
+        ...isWebApp ? {} : {
+            target: 'node18', // Target Node.js environment
+            node: {
+                __dirname: false, // Prevent Webpack from mocking __dirname
+                __filename: false, // Prevent Webpack from mocking __filename
+            },
+            externals: [(0, webpack_node_externals_1.default)()], // Externalize all node_modules
+        },
+        resolve: {
+            extensions: [`.tsx`, `.ts`, `.js`, `.json`], // Resolve files
+            ...isWebApp ? {} : {
+                mainFields: [`module`, `main`],
+                conditionNames: [`import`, `default`],
+                aliasFields: [],
+                preferRelative: true,
+            },
+            ...resolveOptions,
+        },
+        module: {
+            rules: [
+                {
+                    test: /\.ts$/,
+                    exclude: /node_modules/,
+                    use: `ts-loader`,
+                },
+                ...isWebApp ? [] : [{
+                        test: /\.node$/,
+                        loader: 'node-loader',
+                        options: {
+                            name: '[name].[ext]',
+                        },
+                    }],
+                ...customWebRules
+            ],
+        },
+        plugins: [
+            new webpack_bundle_analyzer_1.BundleAnalyzerPlugin({
+                analyzerMode: params.openAnalyzer == undefined ? `disabled` : `server`,
+                openAnalyzer: params.openAnalyzer || false, // Prevents auto-opening the browser
+            }),
+            new webpack_1.default.DefinePlugin(envKeys),
+            ...licenseText ? [new webpack_1.default.BannerPlugin({
+                    banner: licenseText,
+                    raw: true,
+                })] : [],
+            new clean_webpack_plugin_1.CleanWebpackPlugin({
+                cleanOnceBeforeBuildPatterns: ['code/*.js', 'code/*.js.LICENSE.txt'],
+            }),
+            ...obfuscateON ? [obfuscate_1.obfuscationSettings] : [],
+            ...configWebPlugins,
+        ],
+        optimization: {
+            minimize: minimiseON, // Enable minimization
+            minimizer: [
+                new terser_webpack_plugin_1.default({
+                    terserOptions: {
+                        compress: {
+                            drop_console: false, // Do not remove console logs
+                        },
+                    },
+                    ...isWebApp ? {} : {
+                        extractComments: false, // Prevent duplicate comments for external modules
+                    },
+                }),
+                ...cssMinimise,
+            ],
+            ...isWebApp ? {} : {
+                usedExports: true, // Enable tree-shaking
+                sideEffects: false, // Mark the project as free of side effects
+            },
+        }, // @ts-ignore
+        devServer: {
+            static: {
+                directory: path_1.default.join(process.cwd(), productionDir),
+            },
+            port, // Specify your desired port
+            open: true, // Automatically open the browser
+            compress: true, // Enable gzip compression for files served
+        },
+        mode
+    };
+};
+exports.build = build;

package/dist/src/obfuscate.d.ts

@@ -0,0 +1,2 @@
+import WebpackObfuscator from "webpack-obfuscator";
+export declare const obfuscationSettings: WebpackObfuscator;

package/dist/src/obfuscate.js

@@ -0,0 +1,35 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.obfuscationSettings = void 0;
+const webpack_obfuscator_1 = __importDefault(require("webpack-obfuscator"));
+exports.obfuscationSettings = new webpack_obfuscator_1.default({
+    compact: true, // Minify the output
+    controlFlowFlattening: false, // Disable control flow flattening to avoid errors
+    deadCodeInjection: false, // Disable dead code injection
+    debugProtection: false, // Disable debug protection
+    debugProtectionInterval: 0,
+    disableConsoleOutput: false, // Allow console output
+    identifierNamesGenerator: 'hexadecimal', // Use hexadecimal names for identifiers
+    log: false,
+    numbersToExpressions: false, // Disable numbers to expressions to reduce bloat
+    renameGlobals: false, // Avoid renaming global variables
+    selfDefending: false, // Disable self-defending code
+    simplify: true, // Simplify code structure
+    splitStrings: true, // Split strings into chunks
+    splitStringsChunkLength: 8, // chunk length
+    stringArray: true, // Enable string array transformation
+    stringArrayCallsTransform: false,
+    stringArrayEncoding: [], // No encoding for string array
+    stringArrayIndexShift: false, // Disable index shifting
+    stringArrayRotate: false, // Disable rotation to avoid potential issues
+    stringArrayShuffle: false, // Disable shuffling for stability
+    stringArrayWrappersCount: 1, // Match wrapper count
+    stringArrayWrappersChainedCalls: false, // Disable chained calls
+    stringArrayWrappersParametersMaxCount: 2, // Match max parameters
+    stringArrayWrappersType: `variable`, // Use variable wrappers
+    stringArrayThreshold: 1, // Obfuscate all strings
+    unicodeEscapeSequence: false // Disable unicode escape sequences
+});

package/dist/src/sw.d.ts

@@ -0,0 +1,7 @@
+declare const DomainName: string, CACHE_NAME: string, ROOT_URI = "APP_URL", NOTIFICATION_ICON = "APP_ICON", NOTIFICATION_BADGE = "APP_BADGE", DEFAULT_NOTIFICATION_DATA: {
+    title: string;
+    body: string;
+    url: string;
+}, 
+/** Check internet connectivity */
+isOnline: () => Promise<boolean>;

package/dist/src/sw.js

@@ -0,0 +1,173 @@
+"use strict";
+const DomainName = self.location.origin?.split(`.`)?.[0], CACHE_NAME = `cache_${DomainName}`, ROOT_URI = `APP_URL`, NOTIFICATION_ICON = `APP_ICON`, NOTIFICATION_BADGE = `APP_BADGE`, DEFAULT_NOTIFICATION_DATA = {
+    title: `New Notification`,
+    body: `You have a new notification!`,
+    url: `NOTIFICATION_URI`
+}, 
+/** Check internet connectivity */
+isOnline = async () => {
+    try {
+        // Attempt to fetch a small resource to check connectivity
+        await fetch(`REFERENCE_FILE`, {
+            method: `HEAD`,
+            mode: `no-cors`,
+            cache: `no-store`
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    ;
+};
+// // Install event: Activate immediately, no pre-caching
+// (self as unknown as ServiceWorkerGlobalScope).addEventListener(`install`, (event: ExtendableEvent) => {
+//     event.waitUntil(
+//         (self as unknown as ServiceWorkerGlobalScope).skipWaiting()
+//     );
+// });
+// // Activate event: Clean up old caches
+// (self as unknown as ServiceWorkerGlobalScope).addEventListener(`activate`, (event: ExtendableEvent) => {
+//     event.waitUntil(
+//         caches.keys().then(cacheNames =>
+//             Promise.all(
+//                 cacheNames.map(name => {
+//                     if (name !== CACHE_NAME) {
+//                         return caches.delete(name);
+//                     }
+//                     return null;
+//                 })
+//             )
+//         ).then(() =>
+//             (self as unknown as ServiceWorkerGlobalScope)
+//                 ?.clients
+//                 ?.claim()
+//         )
+//     );
+// });
+// Fetch event: Check isOnline only for .html files, others load from cache if available
+self.addEventListener(`fetch`, (event) => {
+    // event.respondWith(
+    //     (async () => {
+    //     const isHtmlRequest = event.request.url.endsWith('.html') || event.request.url.endsWith('/');
+    //     if (event.request.method !== `GET`) {
+    //         // Non-GET requests are not cached
+    //         if (isHtmlRequest) {
+    //             const online = await isOnline();
+    //             if (online) {
+    //                 return fetch(event.request).catch(() => {
+    //                     return new Response(`Network unavailable`, {
+    //                         status: 503,
+    //                         statusText: `Service Unavailable`
+    //                     });
+    //                 });
+    //             }
+    //             return new Response(`Offline and non-GET request`, {
+    //                 status: 503,
+    //                 statusText: `Service Unavailable`
+    //             });
+    //         }
+    //         return new Response(`Non-GET request not supported`, {
+    //             status: 503,
+    //             statusText: `Service Unavailable`
+    //         });
+    //     }
+    //     // For non-.html files, try cache first
+    //     if (!isHtmlRequest) {
+    //         const cachedResponse = await caches.match(event.request);
+    //         if (cachedResponse) {
+    //             return cachedResponse;
+    //         }
+    //         // If not in cache, fetch from network
+    //         try {
+    //             const networkResponse = await fetch(event.request);
+    //             if (networkResponse.ok) {
+    //                 const cache = await caches.open(CACHE_NAME);
+    //                 cache.put(event.request, networkResponse.clone());
+    //             }
+    //             return networkResponse;
+    //         } catch {
+    //             return new Response(`Network unavailable and no cached response found`, {
+    //                 status: 503,
+    //                 statusText: `Service Unavailable`
+    //             });
+    //         }
+    //     }
+    //     // For .html files, check online status
+    //     const online = await isOnline();
+    //     if (online) {
+    //         // When online, always fetch from network
+    //         try {
+    //             const networkResponse = await fetch(event.request);
+    //             if (networkResponse.ok) {
+    //                 const cache = await caches.open(CACHE_NAME);
+    //                 cache.put(event.request, networkResponse.clone());
+    //             }
+    //             return networkResponse;
+    //         } catch {
+    //             // Network failed, try cache
+    //             const cachedResponse = await caches.match(event.request);
+    //             if (cachedResponse) {
+    //                 return cachedResponse;
+    //             }
+    //             return new Response(`Network unavailable and no cached response found`, {
+    //                 status: 503,
+    //                 statusText: `Service Unavailable`
+    //             });
+    //         }
+    //     } else {
+    //         // When offline, serve from cache
+    //         const cachedResponse = await caches.match(event.request);
+    //         if (cachedResponse) {
+    //             return cachedResponse;
+    //         }
+    //         return new Response(`Offline and no cached response found`, {
+    //             status: 503,
+    //             statusText: `Service Unavailable`
+    //         });
+    //     }
+    // })()
+    // );
+});
+// Notification click: Open or focus window
+self.addEventListener(`notificationclick`, (event) => {
+    event.notification.close();
+    const url = new URL(ROOT_URI, self.location.origin).href;
+    event.waitUntil(self
+        ?.clients
+        ?.matchAll({ type: `window`, includeUncontrolled: true })
+        ?.then(clients => {
+        for (const client of clients) {
+            if (client.url === url && `focus` in client)
+                return client.focus();
+        }
+        ; // @ts-ignore
+        if (self?.clients.openWindow)
+            return self.clients.openWindow(url);
+    }));
+});
+// Notification close: Log event
+self.addEventListener(`notificationclose`, (event) => {
+    // console.log(`Notification closed:`, event.notification);
+});
+// Push event: Show notification
+self.addEventListener(`push`, (event) => {
+    let data = DEFAULT_NOTIFICATION_DATA;
+    if (event.data) {
+        try {
+            data = event.data.json();
+        }
+        catch (e) {
+            console.warn(`Invalid push data, using default: ${e}`);
+        }
+        ;
+    }
+    ;
+    const options = {
+        body: data.body,
+        icon: NOTIFICATION_ICON,
+        badge: NOTIFICATION_BADGE,
+        data: { url: new URL(data.url || ROOT_URI, self.location.origin).href }
+    };
+    event.waitUntil(self.registration.showNotification(data.title, options));
+});

package/dist/src/sw_register.js

@@ -0,0 +1,10 @@
+"use strict";
+if ('serviceWorker' in navigator) {
+    const serviceWorker = navigator.serviceWorker;
+    serviceWorker?.getRegistrations?.()?.then((registrations) => {
+        for (let registration of registrations)
+            registration.unregister();
+        serviceWorker.register(`/sw.js?updated=TIME_UPDATED`);
+    });
+}
+;