@degreesign/webapp 1.7.4 → 1.7.6

package/README.md

@@ -1,29 +1,78 @@
-# 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
+# @degreesign/webapp
+
+**A TypeScript-first development standard for building a webapp — production-ready Progressive Web Apps and Node.js servers in pure HTML, CSS and TypeScript, engineered for the fastest possible renders and sub-second page loads; one config generates optimized bundles, SEO meta tags, a PWA manifest, service worker, `sitemap.xml`, `robots.txt`, `.htaccess` and optional JavaScript obfuscation.**
+
+[![npm version](https://img.shields.io/npm/v/@degreesign/webapp.svg)](https://www.npmjs.com/package/@degreesign/webapp)
+[![npm downloads](https://img.shields.io/npm/dm/@degreesign/webapp.svg)](https://www.npmjs.com/package/@degreesign/webapp)
+[![license](https://img.shields.io/npm/l/@degreesign/webapp.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6.svg)](https://www.typescriptlang.org/)
+[![Webpack 5](https://img.shields.io/badge/webpack-5-8dd6f9.svg)](https://webpack.js.org/)
+[![Node.js 18+](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](https://nodejs.org/)
+
+## Table of Contents
+
+- [What is @degreesign/webapp?](#what-is-degreesignwebapp)
+- [Why @degreesign/webapp?](#why-degreesignwebapp)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Build API](#build-api)
+- [File Utilities](#file-utilities)
+- [Types](#types)
+- [Configuration Options](#configuration-options)
+- [FAQ](#faq)
+- [Keywords](#keywords)
+- [License](#license)
+
+## What is @degreesign/webapp?
+
+`@degreesign/webapp` defines a **TypeScript-first development standard** for shipping **Progressive Web Apps (PWAs)** and **Node.js server bundles** from a single `build()` call: it is a small, dependency-light Webpack and TypeScript toolkit for building a webapp from **pure HTML, CSS and TypeScript**, with no framework runtime to ship or hydrate, so first render is immediate and page loads stay sub-second. Instead of hand-writing hundreds of lines of Webpack config, you pass one typed config object and get a production-ready build: TypeScript compilation, CSS extraction and inlining, asset copying, HTML templating, SEO and Open Graph/Twitter meta tags, `app.json` manifest, auto-registered service worker, sitemap, `robots.txt`, `.htaccess` security policies, bundle analysis and optional code obfuscation. It is a build-time developer tool — it runs in Node.js during your build, not in the browser.
+
+## Why @degreesign/webapp?
+
+- **One config, whole build** — a single typed object replaces a full `webpack.config.ts` with plugins, loaders and rules.
+- **PWA out of the box** — generates the web app manifest, service worker, icons, orientation and install metadata automatically.
+- **SEO built in** — per-page title, description, canonical URL, Open Graph, Twitter Cards, `robots.txt` and `sitemap.xml`.
+- **Typed configuration** — ships type definitions and typed configuration (`ConfigBuild`, `Page`, `PreconnectLink`).
+- **Web and server bundling** — build the front-end to `public_html/` and the Node.js back-end to `server_build/` from the same package.
+- **Performance defaults** — Terser minification, CSS minification, tree-shaking, content hashing and a 2 MB asset budget (configurable).
+- **Optional obfuscation** — toggle `obfuscateON` to protect shipped JavaScript with `webpack-obfuscator`.
+- **Secure by default** — emits `.htaccess` with HSTS, `X-Frame-Options`, Referrer-Policy, Permissions-Policy and HTTPS redirects.
+- **Pure HTML + CSS + TypeScript** — no framework runtime, hydration or virtual DOM to download; pages are generated as real markup at build time for the fastest possible first paint and sub-second page loads.
+- **MIT licensed and free forever.**
+
+## Installation
+
+Requires **Node.js 18 or higher**.
+
+```bash
+# npm
+npm install --save-dev @degreesign/webapp webpack webpack-cli typescript ts-loader
+
+# yarn
+yarn add --dev @degreesign/webapp webpack webpack-cli typescript ts-loader
+
+# pnpm
+pnpm add -D @degreesign/webapp webpack webpack-cli typescript ts-loader
+```
+
+### CDN
+
+The package is a Node.js build tool, so it is normally installed via a package manager. For quick inspection or utilities in a bundler that supports ESM CDNs, load it directly:
+
+```html
+<script type="module">
+  import { readJSON, writeJSON } from "https://esm.sh/@degreesign/webapp";
+</script>
+```
+
+> **Note:** the file utilities and `build()` rely on Node.js `fs`/`path`, so CDN usage is only suitable for Node-targeted environments, not the browser runtime.
+
+## Quick Start
+
+**1. Add build scripts to `package.json`:**
+
 ```json
 {
-  "license": "MIT",
   "scripts": {
     "build": "webpack --config webpack.web.ts",
     "start": "webpack serve --config webpack.web.ts",
@@ -36,34 +85,8 @@ Add file `package.json` as following
 }
 ```
 
-## WebApp FrontEnd
-WebApp front-end website configuration
+**2. Create `webpack.web.ts` — a complete, copy-paste PWA build:**
 
-### 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";
 
@@ -86,9 +109,9 @@ module.exports = build({
   fav_icon: "favicon.ico",
   orientation: "portrait",
   pagesList: [{
-    uri: `home`,
-    name: `HomePage`,
-    description: `Progressive Web App (PWA) HomePage`,
+    uri: "home",
+    name: "HomePage",
+    description: "Progressive Web App (PWA) HomePage",
   }],
   htmlCommonElements: [],
   obfuscateON: false,
@@ -110,85 +133,188 @@ module.exports = build({
 });
 ```
 
-## WebApp BackEnd
-WebApp back-end server configuration
+**3. Create `webpack.server.ts` — a Node.js back-end bundle:**
+
+```typescript
+import { build } from "@degreesign/webapp";
+
+module.exports = build({
+  type: "server",
+  obfuscateON: true,
+  srcDir: "server",
+  productionDir: "server_build",
+  filesList: ["main"],
+  port: 3211,
+});
+```
+
+**4. Add the expected source layout:**
 
-### 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
+├── public_html/                  # Web output
+├── server_build/                 # Server output
+├── src/
+│   ├── assets/images/            # favicon.ico, app_icon.png, cover images
+│   ├── code/                     # common HTML + ts utils
+│   ├── pages/home/
+│   │   ├── home.ts
+│   │   └── home.html
+│   └── styles.css
+├── server/
+│   └── main.ts
+├── webpack.web.ts
+├── webpack.server.ts
+├── .env
+└── tsconfig.json
+```
+
+**5. Build and run:**
+
+```bash
+npm start          # web dev server on port 3210
+npm run build      # web build → public_html/
+npm run start_server
+npm run build_server  # server build → server_build/
 ```
 
-### Configuration
-Add `webpack.server.ts` file as the core of the server build process as following
+### Use the file helper API
+
 ```typescript
-import { build } from "@degreesign/webapp";
+import { readJSON, writeJSON, readData, writeData } from "@degreesign/webapp";
 
-module.exports = build({
-    type: `server`,
-    obfuscateON: true,
-    srcDir: `server`,
-    productionDir: `server_build`,
-    filesList: [`main`],
-    port: 3211,
-});
+const config = readJSON("./config.json");         // parse a JSON file
+writeJSON("./dist/output.json", { built: true }); // serialize + write JSON
+const html = readData("./src/pages/home/home.html"); // read a text file
+writeData("./dist/robots.txt", "User-agent: *");     // write a text file
 ```
 
-## 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.
-- **Preconnect**: `preconnectLinks` adds `<link rel="preconnect">` entries (e.g. your server base URL) to the page head, so the browser starts DNS/TCP/TLS for those origins early. Each entry is a URL string or an object with `href` and optional `crossorigin`. `crossorigin` is on by default; set `crossorigin: false` per link to disable.
-- **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.
+## Build API
+
+### `build(params)`
+
+Creates and returns a Webpack `Configuration` object. Pass `type: "webapp"` for a front-end PWA build, or `type: "server"` for a Node.js bundle.
+
+| Export | Type | Returns | Description |
+| --- | --- | --- | --- |
+| `build` | `(params: ConfigBuild) => webpack.Configuration` | Webpack configuration | Central entry point. Accepts `ConfigWebApp` or `ConfigServer` (discriminated by `type`) and returns a ready-to-export Webpack config for `--config webpack.web.ts` / `webpack.server.ts`. |
+
+## File Utilities
+
+Small, dependency-free Node.js helpers used internally and exported for reuse in your own build scripts.
+
+| Export | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `writeData` | `(file: string, code: string) => boolean` | `true` on success, `false` on empty data or failure | Writes a UTF-8 string to `file` resolved against `process.cwd()`. |
+| `writeJSON` | `(file: string, code: any) => boolean` | `true` on success, `false` on empty data or failure | Serializes a value with `JSON.stringify` and writes it via `writeData`. |
+| `readData` | `(file: string, internal?: boolean) => string` | File contents or `""` on failure | Reads a UTF-8 file. When `internal` is `true`, the path is resolved relative to the package directory instead of `process.cwd()`. |
+| `readJSON` | `(file: string, internal?: boolean) => any` | Parsed JSON or `undefined` on failure | Reads a file via `readData` and parses it as JSON. |
+
+## Types
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `Page` | `interface` | A page in `pagesList`: `uri`, `name`, `description`, plus optional `short_name`, `icon`, `iconMaskable`, `shortcut`, `noindex`, `publishDate`, `coverImage`, `coverImageDescription`, `headerHTML`, `menuHTML`, `footerHTML`, `customHTML`, `isPHP`, `keywords` and `canonicalURL`. Drives per-page HTML, SEO tags, shortcuts and sitemap entries. |
+| `PreconnectLink` | `interface` | A `<link rel="preconnect">` entry: `{ href: string; crossorigin?: boolean }`. `crossorigin` defaults to `true`; `preconnectLinks` also accepts a plain URL string. |
+
+Additional public types `ConfigBuild`, `ConfigBase`, `ConfigWebApp`, `ConfigServer`, `MetaTags`, `MetaTagsInput` and `WebManifest` are exported from the package source for advanced typing.
+
+## Configuration Options
+
+### Base options (`ConfigBase`)
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `srcDir` | `string` | `src` | Source directory. |
+| `productionDir` | `string` | `public_html` | Build output directory. |
+| `mode` | `"development" \| "production"` | `production` | Webpack mode. |
+| `obfuscateON` | `boolean` | `false` | Enable JavaScript obfuscation. |
+| `minimiseON` | `boolean` | `true` | Enable JS/CSS minification. |
+| `port` | `number` | `3210` | Dev server port. |
+| `maxFileSizeMB` | `number` | `2` | Asset/entry performance budget in MB. |
+| `resolveOptions` | `ResolveOptions` | `{}` | Extra Webpack resolve options. |
+| `licenseText` | `string` | `""` | Banner text prepended to bundles. |
+| `openAnalyzer` | `boolean` | `false` | Open the bundle analyzer window. |
+| `includeServerModules` | `boolean` | `false` | Bundle `node_modules` into server output instead of externalizing. |
+
+### Web app options (`ConfigWebApp`)
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `websiteName` | `string` | yes | Application name. |
+| `websiteDomain` | `string` | yes | Domain used for canonical URLs, sitemap and Open Graph. |
+| `appShortName` | `string` | yes | Manifest short name. |
+| `twitterUserName` | `string` | yes | Twitter handle for `twitter:site`. |
+| `publishedTime` | `string` | yes | Publication timestamp (ISO 8601). |
+| `author` | `string` | yes | Site author meta tag. |
+| `websiteTitle` | `string` | yes | Default title / slogan. |
+| `websiteDescription` | `string` | yes | Default meta description. |
+| `coverImage` | `string` | yes | Social cover image (Open Graph / Twitter). |
+| `coverImageDescription` | `string` | yes | Cover image alt text. |
+| `background_color` | `string` | yes | Manifest background color. |
+| `theme_color` | `string` | yes | Manifest/`theme-color`. |
+| `appIcon` | `string` | yes | App icon path. |
+| `appIconMaskable` | `string` | yes | Maskable icon path. |
+| `fav_icon` | `string` | yes | Favicon path. |
+| `orientation` | `"portrait" \| "landscape"` | yes | Screen orientation. |
+| `pagesList` | `Page[]` | yes | Pages to generate. |
+| `htmlCommonElements` | `("header"\|"footer"\|"menu")[]` | no | Shared HTML partials to inject. |
+| `assetsDir` | `string` | yes | Assets directory. |
+| `commonDir` | `string` | yes | Shared code/HTML directory. |
+| `imagesDir` | `string` | yes | Images directory. |
+| `pagesDir` | `string` | yes | Pages directory. |
+| `pageHome` | `string` | yes | Home page identifier. |
+| `htaccessCustom` | `string` | yes | Appended to generated `.htaccess`. |
+| `startURI` | `string` | no | PWA `start_url`. |
+| `language` | `string` | no | Open Graph locale. |
+| `preconnectLinks` | `(string \| PreconnectLink)[]` | no | Origins to `preconnect`, CORS on by default. |
+| `cssDiscardUnused` | `boolean` | no | Discard unused CSS. |
+| `updateServiceWorker` | `boolean` | no | Re-version the service worker on build. |
+| `onlineIndicatorFile` | `string` | no | Reference file used by the service worker. |
+
+### Server options (`ConfigServer`)
+
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `"server"` | yes | Selects the Node.js target. |
+| `srcDir` | `string` | yes | Server source directory (e.g. `server`). |
+| `productionDir` | `string` | yes | Server output directory (e.g. `server_build`). |
+| `filesList` | `string[]` | yes | Entry names, each compiled from `./<srcDir>/<name>.ts`. |
+| `includeServerModules` | `boolean` | no | Bundle dependencies instead of externalizing them. |
+
+## FAQ
+
+**What is `@degreesign/webapp`?**
+A TypeScript-first Webpack + TypeScript build toolkit that turns one typed config object into a production-ready webapp — a Progressive Web App built from pure HTML, CSS and TypeScript — and/or a Node.js server bundle, including SEO metadata, a PWA manifest, service worker, sitemap and security headers.
+
+**Is it free?**
+Yes. It is open source under the MIT License and free to use in personal and commercial projects.
+
+**Does it work with Node.js and the browser?**
+It is a Node.js build-time tool. `build()` and the file helpers run in Node.js (18+) during your build. The generated output — HTML, JS, CSS, manifest and service worker — is what runs in the browser.
+
+**Does it have dependencies?**
+Yes. It wraps and configures Webpack plugins such as `terser-webpack-plugin`, `clean-webpack-plugin`, `copy-webpack-plugin`, `html-webpack-plugin`, `mini-css-extract-plugin`, `css-minimizer-webpack-plugin`, `sitemap-webpack-plugin`, `webpack-obfuscator` and `webpack-bundle-analyzer`. Install it alongside `webpack`, `webpack-cli`, `typescript` and `ts-loader`.
+
+**Does it support TypeScript?**
+Yes. It ships type definitions, compiles TypeScript via `ts-loader`, and exposes fully typed configuration (`ConfigBuild`, `ConfigWebApp`, `ConfigServer`, `Page`, `PreconnectLink`).
+
+**How are pages built?**
+Each page is an `.html` fragment plus a same-named `.ts` entry, styled by CSS, compiled to real markup at build time. There is no UI runtime to ship or hydrate, so first render is immediate. The package handles bundling, assets, PWA and SEO concerns rather than UI.
+
+**Can I use it for a Node.js back-end?**
+Yes. Set `type: "server"` with `filesList` to bundle one or more Node.js entry files, with `node_modules` externalized by default.
+
+**Can I disable minification or enable obfuscation?**
+Yes. Toggle `minimiseON` and `obfuscateON` in the config.
+
+**Where does the build output go?**
+Web builds default to `public_html/` and server builds to `server_build/`; both are configurable via `productionDir`.
+
+## Keywords
+
+webpack, webpack config, webpack 5, typescript, ts-loader, progressive web app, PWA, webapp, web app, webapp boilerplate, PWA boilerplate, web app template, build tool, bundler, node.js server bundling, SEO, meta tags, open graph, twitter cards, sitemap, robots.txt, service worker, web manifest, app manifest, code obfuscation, webpack-bundle-analyzer, static site, front-end build, degreesign.
 
 ## License
-This project is licensed under the MIT License. See the `LICENSE` file for details.
+
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

package/package.json

@@ -1,7 +1,7 @@
 {
   "license": "MIT",
   "name": "@degreesign/webapp",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,8 +10,39 @@
   },
   "keywords": [
     "webpack",
-    "webdev",
-    "development"
+    "webpack-config",
+    "webpack-5",
+    "typescript",
+    "ts-loader",
+    "progressive-web-app",
+    "pwa",
+    "web-app",
+    "pwa-boilerplate",
+    "web-app-template",
+    "build-tool",
+    "bundler",
+    "nodejs",
+    "server-bundling",
+    "seo",
+    "meta-tags",
+    "open-graph",
+    "twitter-cards",
+    "sitemap",
+    "robots-txt",
+    "service-worker",
+    "web-manifest",
+    "app-manifest",
+    "code-obfuscation",
+    "webpack-bundle-analyzer",
+    "static-site",
+    "front-end-build",
+    "webapp",
+    "webapp-template",
+    "webapp-boilerplate",
+    "typescript-first",
+    "development-standard",
+    "performance",
+    "degreesign"
   ],
   "repository": {
     "type": "git",
@@ -19,7 +50,7 @@
   },
   "author": "DegreeSign",
   "homepage": "https://degreesign.com",
-  "description": "DegreeSign webpack setup for WebApps",
+  "description": "TypeScript-first development standard for building a webapp — production-ready Progressive Web Apps (PWA) and Node.js servers from pure HTML, CSS and TypeScript, engineered for the fastest possible renders and sub-second page loads, generating SEO meta tags, manifest, service worker, sitemap and obfuscation from one config.",
   "bugs": {
     "url": "https://github.com/DegreeSign/ds_webapp/issues"
   },