svelteesp32 1.13.1 → 1.15.0

package/README.md

@@ -1,135 +1,125 @@
-# `svelteesp32` ![image](https://badges.github.io/stability-badges/dist/stable.svg)
+# svelteesp32 ![image](https://badges.github.io/stability-badges/dist/stable.svg)
 
-[Changelog](CHANGELOG.md)
-
-# Convert Svelte (or React/Angular/Vue) JS application to serve it from ESP32/ESP8266 webserver
-
-### Forget SPIFFS and LittleFS now
-
-I often make small to medium-sized microcontroller solutions that run on ESP32 or ESP8266. If a web interface is needed, I create a Svelte application. The Svelte application is practically served by the ESP32/ESP8266.
-
-In order to be able to easily update OTA, it is important - from the users' point of view - that the update file **consists of one file**. I can't use the SPIFFS/LittleFS solution for this. It is necessary that the WebUI files are included inline in the Arduino or PlatformIO c++ code.
-
-This npm package provides a solution for **inserting any JS client application into the ESP web server** (PsychicHttp and also ESPAsyncWebServer (https://github.com/ESP32Async/ESPAsyncWebServer) and ESP-IDF available, PsychicHttp is the default). For this, JS, html, css, font, assets, etc. files must be converted to binary byte array. Npm mode is easy to use and easy to **integrate into your CI/CD pipeline**.
+### Embed Any Web App in Your ESP32 — One Binary, Zero Filesystem Hassle
 
-**Quick Comparison:**
+**Turn your Svelte, React, Angular, or Vue frontend into a single C++ header file.** Serve beautiful web interfaces directly from ESP32/ESP8266 flash memory with automatic gzip compression, ETag caching, and seamless OTA updates.
 
-| Feature               | SvelteESP32                             | Traditional Filesystem (SPIFFS/LittleFS) |
-| --------------------- | --------------------------------------- | ---------------------------------------- |
-| **Single Binary OTA** | ✓ Everything embedded in firmware       | ✗ Requires separate partition upload     |
-| **Gzip Compression**  | ✓ Automatic build-time (>15% reduction) | Manual or runtime compression            |
-| **ETag Support**      | ✓ Built-in MD5 ETags with 304 responses | Manual implementation required           |
-| **CI/CD Integration** | ✓ npm package, simple build step        | Complex with upload_fs tools             |
-| **Memory Efficiency** | Flash only (PROGMEM/const arrays)       | Flash partition + filesystem overhead    |
-| **Performance**       | Direct byte array serving               | Filesystem read overhead                 |
-| **Setup Complexity**  | Include header, call init function      | Partition setup, upload tools, handlers  |
-
-**When to use:**
-
-- **SvelteESP32**: Single-binary OTA updates, CI/CD pipelines, static web content that doesn't change at runtime
-- **SPIFFS/LittleFS**: Dynamic content, user-uploadable files, configuration that changes at runtime
-
-> Starting with version v1.13.0, RC files support npm package variable interpolation
+[Changelog](CHANGELOG.md)
 
-> Starting with version v1.12.0, you can use RC file for configuration
+---
 
-> Starting with version v1.11.0, you can exclude files by pattern
+## Why SvelteESP32?
 
-> Starting with version v1.10.0, we reduced npm dependencies
+**The problem:** Traditional approaches like SPIFFS and LittleFS require separate partition uploads, complex OTA workflows, and manual compression. Your users end up managing multiple files, and your CI/CD pipeline becomes a mess.
 
-> Starting with version v1.9.0, code generator for esp-idf is available
+**The solution:** SvelteESP32 compiles your entire web application into a single C++ header file. One firmware binary. One OTA update. Done.
 
-> Starting with version v1.8.0, use the new and maintained ESPAsyncWebserver available at https://github.com/ESP32Async/ESPAsyncWebServer
+### Key Benefits
 
-> Starting with version v1.7.0, with the cachetime command line option, you can set whether the browser can cache pages
+- **Single Binary OTA** — Everything embedded in firmware. No partition juggling, no separate uploads.
+- **Automatic Optimization** — Build-time gzip compression with intelligent thresholds (>1KB, >15% reduction).
+- **Smart Caching** — Built-in SHA256 ETags deliver HTTP 304 responses, slashing bandwidth on constrained devices.
+- **CI/CD Ready** — Simple npm package that slots into any build pipeline.
+- **Zero Runtime Overhead** — Data served directly from flash. No filesystem reads, no RAM allocation.
+- **4 Web Server Engines** — PsychicHttp V1/V2, ESPAsyncWebServer, and native ESP-IDF supported.
 
-> Starting with version v1.6.0, mime-types package properly handles MIME types (application/javascript -> text/javascript)
+---
 
-> Starting with version v1.5.0, PsychicHttp v2 is also supported.
+## SvelteESP32 vs Traditional Filesystem
 
-> Version v1.4.0 has a breaking change! --no-gzip changed to --gzip. Starting with this version c++ compiler directives are available to setup operation in project level.
+| Feature               | SvelteESP32                       | SPIFFS / LittleFS                        |
+| --------------------- | --------------------------------- | ---------------------------------------- |
+| **Single Binary OTA** | ✓ Everything in firmware          | ✗ Separate partition upload required     |
+| **Gzip Compression**  | ✓ Automatic at build time         | Manual or runtime compression            |
+| **ETag Support**      | ✓ Built-in SHA256 + 304 responses | Manual implementation required           |
+| **CI/CD Integration** | ✓ One npm command                 | Complex upload_fs tooling                |
+| **Memory Efficiency** | Flash only (PROGMEM/const arrays) | Filesystem partition + overhead          |
+| **Performance**       | Direct byte array serving         | Filesystem read latency                  |
+| **Setup Complexity**  | Include header, call one function | Partition tables, upload tools, handlers |
 
-> Starting with version v1.3.0, c++ defines can be used.
+**Best for:** Single-binary OTA, CI/CD pipelines, static web UIs that ship with firmware.
 
-> Starting with version v1.2.0, ESP8266/ESP8285 is also supported.
+**Consider SPIFFS/LittleFS for:** User-uploadable files, runtime-editable configs, dynamic content.
 
-> Starting with version v1.1.0, the ETag header is also supported.
+---
 
-### Requirements
+## Quick Start
 
-- Node.js >= 20
-- npm >= 9
+```bash
+npm install -D svelteesp32
+```
 
-### Development
+After building your frontend (Vite/Rollup/Webpack):
 
-#### Testing
+```bash
+npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h --etag=true
+```
 
-The project includes comprehensive unit tests using Vitest:
+Include in your ESP32 project:
 
-```bash
-# Run tests once
-npm run test
+```c
+#include <PsychicHttp.h>
+#include "svelteesp32.h"
 
-# Run tests in watch mode (for development)
-npm run test:watch
+PsychicHttpServer server;
 
-# Generate coverage report
-npm run test:coverage
+void setup() {
+    server.listen(80);
+    initSvelteStaticFiles(&server);
+}
 ```
 
-**Test Coverage:** ~68% overall with focus on core functionality:
-
-- `commandLine.ts`: 84.56% - CLI argument parsing and validation
-- `file.ts`: 100% - File operations and duplicate detection
-- `cppCode.ts`: 96.62% - C++ code generation and templates
-- `consoleColor.ts`: 100% - Console output utilities
+**That's it.** Your entire web app is now embedded and ready to serve.
 
-Coverage reports are generated in the `coverage/` directory and can be viewed by opening `coverage/index.html` in a browser.
+---
 
-#### Code Quality
+## What's New
 
-```bash
-# Check formatting
-npm run format:check
+- **v1.15.0** — `--base-path` for multiple frontends (e.g., `/admin`, `/app`)
+- **v1.13.0** — npm package variable interpolation in RC files
+- **v1.12.0** — RC file configuration support
+- **v1.11.0** — File exclusion patterns
+- **v1.9.0** — Native ESP-IDF engine
+- **v1.5.0** — PsychicHttp V2 support
 
-# Fix formatting
-npm run format:fix
+---
 
-# Check linting
-npm run lint:check
+## Requirements
 
-# Fix linting issues
-npm run lint:fix
+- Node.js >= 20
+- npm >= 9
 
-# Fix all formatting and linting issues
-npm run fix
-```
+---
 
-### Usage
+## Installation & Usage
 
-**Install package** as dev dependency (it is practical if the package is part of the project so that you always receive updates)
+### Install
 
 ```bash
 npm install -D svelteesp32
 ```
 
-After a successful Svelte build (rollup/webpack/vite) **create an includable c++ header** file
+### Generate Header File
+
+Choose your web server engine:
 
 ```bash
-// for PsychicHttpServer
-npx svelteesp32 -e psychic -s ../svelteapp/dist -o ../esp32project/svelteesp32.h --etag=true
+# PsychicHttpServer (recommended for ESP32)
+npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h --etag=true
 
-// for PsychicHttpServer V2
-npx svelteesp32 -e psychic2 -s ../svelteapp/dist -o ../esp32project/svelteesp32.h --etag=true
+# PsychicHttpServer V2
+npx svelteesp32 -e psychic2 -s ./dist -o ./esp32/svelteesp32.h --etag=true
 
-// for ESPAsyncWebServer
-npx svelteesp32 -e async -s ../svelteapp/dist -o ../esp32project/svelteesp32.h --etag=true
+# ESPAsyncWebServer (ESP32 + ESP8266)
+npx svelteesp32 -e async -s ./dist -o ./esp32/svelteesp32.h --etag=true
 
-// for native esp-idf
-npx svelteesp32 -e espidf -s ../svelteapp/dist -o ../esp32project/svelteesp32.h --etag=true
+# Native ESP-IDF
+npx svelteesp32 -e espidf -s ./dist -o ./esp32/svelteesp32.h --etag=true
 ```
 
-During the **translation process**, the processed file details are visible with compression ratios, and at the end, the result shows the ESP's memory allocation (gzip size)
+### Build Output
+
+Watch your files get optimized in real-time:
 
 ```
 [assets/index-KwubEIf-.js]  ✓ gzip used (38850 -> 12547 = 32%)
@@ -142,82 +132,62 @@ During the **translation process**, the processed file details are visible with
 ../../../Arduino/EspSvelte/svelteesp32.h 842kB size
 ```
 
-The tool automatically:
+**Automatic optimizations:**
 
-- Compresses files with gzip level 9 when beneficial (>1024 bytes and >15% reduction)
-- Detects and reports duplicate files using SHA256 hashing
-- Skips pre-compressed files (.gz, .br, .brottli) if the original exists
+- Gzip level 9 compression when beneficial (>1KB, >15% size reduction)
+- Duplicate file detection via SHA256 hashing
+- Smart skip of pre-compressed files (.gz, .br) when originals exist
 
-**Include svelteesp32.h** into your Arduino or PlatformIO c++ project (copy it next to the main c++ file)
+### ESP32 Integration
 
-```c
-...
+**PsychicHttpServer (Recommended)**
 
+```c
 #include <PsychicHttp.h>
 #include "svelteesp32.h"
 
 PsychicHttpServer server;
 
-...
-
-void setup()
-{
-    ...
-
+void setup() {
     server.listen(80);
-
-    initSvelteStaticFiles(&server);
+    initSvelteStaticFiles(&server);  // One line. Done.
 }
 ```
 
-or
+**ESPAsyncWebServer**
 
 ```c
-...
-
 #include <ESPAsyncWebServer.h>
 #include "svelteesp32.h"
 
 AsyncWebServer server(80);
 
-...
-
-void setup()
-{
-    ...
-
+void setup() {
     initSvelteStaticFiles(&server);
-
     server.begin();
 }
 ```
 
-or for ESP-IDF native:
+**Native ESP-IDF**
 
 ```c
-...
-
 #include <esp_http_server.h>
 #include "svelteesp32.h"
 
 httpd_handle_t server = NULL;
 
-...
-
-void app_main()
-{
-    ...
-
+void app_main() {
     httpd_config_t config = HTTPD_DEFAULT_CONFIG();
     httpd_start(&server, &config);
-
     initSvelteStaticFiles(server);
 }
 ```
 
-You can find minimal buildable example projects in [demo/esp32](demo/esp32) (Arduino/PlatformIO) and [demo/esp32idf](demo/esp32idf) (ESP-IDF native) folders.
+Working examples: [Arduino/PlatformIO](demo/esp32) | [ESP-IDF](demo/esp32idf)
+
+### What Gets Generated
 
-The content of **generated file** (do not edit, just use):
+The generated header file includes everything your ESP needs:
 
 ```c
 //engine:   PsychicHttpServer
@@ -240,14 +210,33 @@ const uint8_t datagzip_assets_index_KwubEIf__js[12547] = {0x1f, 0x8b, 0x8, 0x0,
 const uint8_t datagzip_assets_index_Soe6cpLA_css[5368] = {0x1f, 0x8b, 0x8, 0x0, 0x0, ...
 const char * etag_assets_index_KwubEIf__js = "387b88e345cc56ef9091...";
 const char * etag_assets_index_Soe6cpLA_css = "d4f23bc45ef67890ab12...";
+
+// File manifest for runtime introspection
+struct SVELTEESP32_FileInfo {
+  const char* path;
+  uint32_t size;
+  uint32_t gzipSize;
+  const char* etag;
+  const char* contentType;
+};
+const SVELTEESP32_FileInfo SVELTEESP32_FILES[] = {
+  { "/assets/index-KwubEIf-.js", 38850, 12547, etag_assets_index_KwubEIf__js, "text/javascript" },
+  { "/assets/index-Soe6cpLA.css", 32494, 5368, etag_assets_index_Soe6cpLA_css, "text/css" },
+  ...
+};
+const size_t SVELTEESP32_FILE_COUNT = sizeof(SVELTEESP32_FILES) / sizeof(SVELTEESP32_FILES[0]);
 ...
 
+// File served hook - override with your own implementation for metrics/logging
+extern "C" void __attribute__((weak)) SVELTEESP32_onFileServed(const char* path, int statusCode) {}
+
 void initSvelteStaticFiles(PsychicHttpServer * server) {
   server->on("/assets/index-KwubEIf-.js", HTTP_GET, [](PsychicRequest * request) {
     if (request->hasHeader("If-None-Match") &&
         request->header("If-None-Match").equals(etag_assets_index_KwubEIf__js)) {
       PsychicResponse response304(request);
       response304.setCode(304);
+      SVELTEESP32_onFileServed("/assets/index-KwubEIf-.js", 304);
       return response304.send();
     }
 
@@ -257,23 +246,7 @@ void initSvelteStaticFiles(PsychicHttpServer * server) {
     response.addHeader("Cache-Control", "no-cache");
     response.addHeader("ETag", etag_assets_index_KwubEIf__js);
     response.setContent(datagzip_assets_index_KwubEIf__js, 12547);
-    return response.send();
-  });
-
-  server->on("/assets/index-Soe6cpLA.css", HTTP_GET, [](PsychicRequest * request) {
-    if (request->hasHeader("If-None-Match") &&
-        request->header("If-None-Match").equals(etag_assets_index_Soe6cpLA_css)) {
-      PsychicResponse response304(request);
-      response304.setCode(304);
-      return response304.send();
-    }
-
-    PsychicResponse response(request);
-    response.setContentType("text/css");
-    response.addHeader("Content-Encoding", "gzip");
-    response.addHeader("Cache-Control", "no-cache");
-    response.addHeader("ETag", etag_assets_index_Soe6cpLA_css);
-    response.setContent(datagzip_assets_index_Soe6cpLA_css, 5368);
+    SVELTEESP32_onFileServed("/assets/index-KwubEIf-.js", 200);
     return response.send();
   });
 
@@ -281,393 +254,249 @@ void initSvelteStaticFiles(PsychicHttpServer * server) {
 }
 ```
 
-### Engines and ESP variants
-
-Four web server engines are supported:
-
-- **`-e psychic`** (default): PsychicHttpServer V1 - Fast ESP32-only server using ESP-IDF internally. Recommended for ESP32 projects.
-- **`-e psychic2`**: PsychicHttpServer V2 - Updated version with improved API
-- **`-e async`**: ESPAsyncWebServer (https://github.com/ESP32Async/ESPAsyncWebServer) - Popular async server supporting both ESP32 and ESP8266/ESP8285
-- **`-e espidf`**: Native ESP-IDF web server - For projects using ESP-IDF framework directly (not Arduino)
+---
 
-If you **only work on ESP32**, we recommend using PsychicHttpServer (`-e psychic` or `-e psychic2`), which uses the native ESP-IDF web server internally for significantly faster and more stable operation.
+## Supported Web Server Engines
 
-**Note for PsychicHttpServer users:** The generated header includes a comment suggesting to configure `server.config.max_uri_handlers` to match or exceed your file count to ensure all routes are properly registered.
+| Engine                | Flag          | Best For                     | Platform        |
+| --------------------- | ------------- | ---------------------------- | --------------- |
+| **PsychicHttp V1**    | `-e psychic`  | Maximum performance          | ESP32 only      |
+| **PsychicHttp V2**    | `-e psychic2` | Modern API + performance     | ESP32 only      |
+| **ESPAsyncWebServer** | `-e async`    | Cross-platform compatibility | ESP32 + ESP8266 |
+| **Native ESP-IDF**    | `-e espidf`   | Pure ESP-IDF projects        | ESP32 only      |
 
-### Gzip
+**Recommendation:** For ESP32-only projects, use PsychicHttpServer for the fastest, most stable experience.
 
-All modern browsers have been able to handle gzip-compressed content for years. For this reason, there is no question that the easily compressed JS and CSS files are stored compressed in the ESP32/ESP8266 and sent to the browser.
+**Note:** For PsychicHttp, configure `server.config.max_uri_handlers` to match your file count.
 
-During the translation process, data in gzip format is generated and will be used if the **size is greater than 1024 bytes** and we experience a **reduction of at least 15%**. In such a case, the compressed data is unconditionally sent to the browser with the appropriate **Content-Encoding** header information.
+---
 
-Automatic compression can be turned off with the `--gzip=false` option.
+## Features
 
-> This setting has three states: yes, no, and compiler mode is available. In compiler mode, you can disable/enable Gzip by setting the `SVELTEESP32_ENABLE_GZIP` c++ compiler directive. For example, if using platformio, just write `-D SVELTEESP32_ENABLE_GZIP`.
+### Automatic Gzip Compression
 
-### ETag
+Your JS, CSS, and HTML files are automatically compressed at build time — not on the ESP32. Files are gzipped when they're >1KB and achieve >15% size reduction.
 
-The ETag HTTP header can be used to significantly reduce network traffic. If the server sends ETag information, the client can check the integrity of the file by sending back this ETag (in `If-None-Match` header) without sending the data back again. All browsers use this function, the 304 HTTP response code is clearly visible in the network traffic.
+- **Enabled by default** — disable with `--gzip=false`
+- **Compiler mode** — use `--gzip=compiler` and control via `-D SVELTEESP32_ENABLE_GZIP` in PlatformIO
 
-Since microcontroller data traffic is moderately expensive, it is an individual decision whether to use the ETag or not. We **recommend using ETag**, which adds a bit more code (about 1-3%) but results in a much cleaner operation.
+### Smart ETag Caching
 
-The use of ETag is **not enabled by default**, this can be achieved with the `--etag=true` switch.
+Reduce bandwidth dramatically with HTTP 304 "Not Modified" responses. When a browser has a cached file, the ESP32 sends just a status code instead of the entire file — perfect for bandwidth-constrained IoT devices.
 
-All four engines (psychic, psychic2, async, espidf) fully support ETag validation with HTTP 304 Not Modified responses, reducing bandwidth usage when clients have valid cached content.
+- **Enable with** `--etag=true` (recommended)
+- **Minimal overhead** — adds ~1-3% code size for significant bandwidth savings
+- **Compiler mode** — use `--etag=compiler` and control via `-D SVELTEESP32_ENABLE_ETAG`
 
-> This setting has three states: yes, no, and compiler mode is available. In compiler mode, you can disable/enable ETag by setting the `SVELTEESP32_ENABLE_ETAG` c++ compiler directive. For example, if using platformio, just type `-D SVELTEESP32_ENABLE_ETAG`.
+All four engines support full ETag validation.
 
-### Cache-control
+### Browser Cache Control
 
-By default (when using the ETag), we send no-cache in the cache-control header of the HTTP response. Pages, subpages and other elements are downloaded every time. This is perfectly acceptable when serving small pages with ESP.
+Fine-tune how browsers cache your content:
 
-At the same time, it can be an advantage that the content is cached by the browser and not even the ETag check is performed. For this, you can specify how many seconds the max-age value sent instead of no-cache should be. In the case of `--cachetime=86400` (max-age=86400), the page (and other elements) will not be downloaded by the browser **for one day**.
+- **Default:** `no-cache` — browsers always validate with server (ETag check)
+- **Long-term caching:** `--cachetime=86400` — cache for 24 hours without any server requests
 
-### Main entry point - index.html
+### Automatic Index Handling
 
-Typically, the entry point for web applications is the **index.htm or index.html** file. This does not need to be listed in the browser's address bar because web servers know that this file should be served by default. Svelteesp32 also does this: if there is an index.htm or index.html file, it sets it as the main file to be served. So using `http://esp_xxx.local` or just entering the `http://x.y.w.z/` IP address will serve this main file.
+Your `index.html` is automatically served at the root URL — just like any web server. Visit `http://esp32.local/` and your app loads.
 
-**Validation**: By default, svelteesp32 validates that an `index.html` or `index.htm` file exists in your source directory (in the root or any subdirectory). This ensures users won't get a 404 error when visiting your ESP32's root URL.
-
-**Skipping Validation**: If you're building an API-only application (REST endpoints without a web UI) or using a different entry point (e.g., `main.html`), you can skip this validation with the `--no-index-check` flag:
+**API-only projects?** Skip index validation with `--no-index-check`:
 
 ```bash
-# API-only application (no web UI)
-npx svelteesp32 -e psychic -s ./dist -o ./output.h --no-index-check
-
-# Custom entry point (users must visit /main.html explicitly)
 npx svelteesp32 -e psychic -s ./dist -o ./output.h --no-index-check
 ```
 
 ### File Exclusion
 
-The `--exclude` option allows you to exclude files from being embedded in the ESP32 firmware using glob patterns. This is useful for excluding source maps, documentation, and test files that shouldn't be part of the deployed application.
-
-#### Basic Usage
+Keep source maps, docs, and test files out of your firmware:
 
 ```bash
-# Exclude source maps
-npx svelteesp32 -e psychic -s ./dist -o ./output.h --exclude="*.map"
-
-# Exclude documentation files
-npx svelteesp32 -e psychic -s ./dist -o ./output.h --exclude="*.md"
-
-# Exclude multiple file types (comma-separated)
-npx svelteesp32 -e psychic -s ./dist -o ./output.h --exclude="*.map,*.md,*.txt"
+# Single pattern
+npx svelteesp32 -s ./dist -o ./output.h --exclude="*.map"
 
-# Exclude using multiple flags
-npx svelteesp32 -e psychic -s ./dist -o ./output.h --exclude="*.map" --exclude="*.md"
-
-# Exclude entire directories
-npx svelteesp32 -e psychic -s ./dist -o ./output.h --exclude="test/**/*"
-
-# Combine multiple approaches
-npx svelteesp32 -e psychic -s ./dist -o ./output.h --exclude="*.map,*.md" --exclude="docs/**/*"
+# Multiple patterns
+npx svelteesp32 -s ./dist -o ./output.h --exclude="*.map,*.md,test/**/*"
 ```
 
-#### Pattern Syntax
-
-The exclude patterns use standard glob syntax:
-
-- `*.map` - Match all files ending with `.map`
-- `**/*.test.js` - Match all `.test.js` files in any directory
-- `test/**/*` - Match all files in the `test` directory and subdirectories
-- `.DS_Store` - Match specific filename
-
-#### Default Exclusions
-
-By default, the following system and development files are automatically excluded:
+**Default exclusions:** `.DS_Store`, `Thumbs.db`, `.git`, `.svn`, `*.swp`, `*~`, `.gitignore`, `.gitattributes`
 
-- `.DS_Store` (macOS system file)
-- `Thumbs.db` (Windows thumbnail cache)
-- `.git` (Git directory)
-- `.svn` (SVN directory)
-- `*.swp` (Vim swap files)
-- `*~` (Backup files)
-- `.gitignore` (Git ignore file)
-- `.gitattributes` (Git attributes file)
-
-Custom exclude patterns are added to these defaults.
-
-#### Exclusion Output
-
-When files are excluded, you'll see a summary in the build output:
+Build output shows exactly what's excluded:
 
 ```
-Excluded 5 file(s):
+Excluded 3 file(s):
   - assets/index.js.map
   - assets/vendor.js.map
   - README.md
-  - docs/guide.md
-  - test/unit.test.js
 ```
 
-This helps you verify that the correct files are being excluded from your build.
+### Multiple Frontends (Base Path)
 
-### C++ defines
+Serve multiple web apps from one ESP32 using URL prefixes:
 
-To make it easy to integrate into a larger c++ project, we have made a couple of variables available as c++ defines.
-
-You can use the COUNT and SIZE constants:
+```bash
+npx svelteesp32 -s ./admin-dist -o ./admin.h --base-path=/admin
+npx svelteesp32 -s ./user-dist -o ./user.h --base-path=/app
+```
 
 ```c
-...
-#include "svelteesp32.h"
+#include "admin.h"  // Serves at /admin/*
+#include "user.h"   // Serves at /app/*
 
-#if SVELTEESP32_COUNT != 5
-  #error Invalid file count
-#endif
-...
+void setup() {
+    server.listen(80);
+    initSvelteStaticFiles_admin(&server);
+    initSvelteStaticFiles_user(&server);
+    server.on("/api/data", HTTP_GET, handleApiData);
+}
 ```
 
-You can include a blocker error if a named file accidentally missing from the build:
-
-```c
-...
-#include "svelteesp32.h"
+**Rules:** Must start with `/`, no trailing slash, no double slashes.
 
-#ifndef SVELTEESP32_FILE_INDEX_HTML
-  #error Missing index file
-#endif
-...
-```
+### C++ Build-Time Validation
 
-...or if there are too many of a file type:
+Catch configuration issues at compile time with generated defines:
 
 ```c
-...
 #include "svelteesp32.h"
 
-#if SVELTEESP32_CSS_FILES > 1
-  #error Too many CSS files
+#if SVELTEESP32_COUNT != 5
+  #error Unexpected file count - check your build
 #endif
-...
-```
-
-You can use the following c++ directives at the project level if you want to configure the usage there: `SVELTEESP32_ENABLE_ETAG` and `SVELTEESP32_ENABLE_GZIP`. (Do not forget `--etag=compiler` or `--gzip=compiler` command line arg!)
-
-### Command line options
-
-| Option             | Description                                                                          | default                 |
-| ------------------ | ------------------------------------------------------------------------------------ | ----------------------- |
-| `-s`               | **Source dist folder contains compiled web files**                                   | (required)              |
-| `-e`               | The engine for which the include file is created (psychic/psychic2/async/espidf)     | psychic                 |
-| `-o`               | Generated output file with path                                                      | `svelteesp32.h`         |
-| `--exclude`        | Exclude files matching glob pattern (repeatable or comma-separated)                  | Default system files    |
-| `--etag`           | Use ETag header for cache (true/false/compiler)                                      | false                   |
-| `--cachetime`      | Override no-cache response with a max-age=\<cachetime\> response (seconds)           | 0                       |
-| `--gzip`           | Compress content with gzip (true/false/compiler)                                     | true                    |
-| `--created`        | Include creation time in generated header                                            | false                   |
-| `--version`        | Include a version string in generated header, e.g. `--version=v$npm_package_version` | ''                      |
-| `--espmethod`      | Name of generated initialization method                                              | `initSvelteStaticFiles` |
-| `--define`         | Prefix of c++ defines (e.g., SVELTEESP32_COUNT)                                      | `SVELTEESP32`           |
-| `--config`         | Use custom RC file path                                                              | `.svelteesp32rc.json`   |
-| `--no-index-check` | Skip validation for index.html/index.htm (for API-only or custom entry points)       | false                   |
-| `-h`               | Show help                                                                            |                         |
-
-### Configuration File
-
-You can store frequently-used options in a configuration file to avoid repeating command line arguments. This is especially useful for CI/CD pipelines and team collaboration.
-
-#### Quick Start
-
-Create `.svelteesp32rc.json` in your project directory:
-
-```json
-{
-  "engine": "psychic",
-  "sourcepath": "./dist",
-  "outputfile": "./esp32/include/svelteesp32.h",
-  "etag": "true",
-  "gzip": "true",
-  "cachetime": 86400,
-  "exclude": ["*.map", "*.md"]
-}
-```
-
-Then simply run:
-
-```bash
-npx svelteesp32
-```
-
-No command line arguments needed!
-
-#### Search Locations
-
-The tool automatically searches for `.svelteesp32rc.json` in:
-
-1. Current working directory
-2. User home directory
-
-Or specify a custom location:
-
-```bash
-npx svelteesp32 --config=.svelteesp32rc.prod.json
-```
-
-#### Configuration Reference
-
-All CLI options can be specified in the RC file using long-form property names:
-
-| RC Property    | CLI Flag           | Type    | Example                                          |
-| -------------- | ------------------ | ------- | ------------------------------------------------ |
-| `engine`       | `-e`               | string  | `"psychic"`, `"psychic2"`, `"async"`, `"espidf"` |
-| `sourcepath`   | `-s`               | string  | `"./dist"`                                       |
-| `outputfile`   | `-o`               | string  | `"./output.h"`                                   |
-| `etag`         | `--etag`           | string  | `"true"`, `"false"`, `"compiler"`                |
-| `gzip`         | `--gzip`           | string  | `"true"`, `"false"`, `"compiler"`                |
-| `cachetime`    | `--cachetime`      | number  | `86400`                                          |
-| `created`      | `--created`        | boolean | `true`, `false`                                  |
-| `version`      | `--version`        | string  | `"v1.0.0"`                                       |
-| `espmethod`    | `--espmethod`      | string  | `"initSvelteStaticFiles"`                        |
-| `define`       | `--define`         | string  | `"SVELTEESP32"`                                  |
-| `exclude`      | `--exclude`        | array   | `["*.map", "*.md"]`                              |
-| `noIndexCheck` | `--no-index-check` | boolean | `true`, `false`                                  |
-
-#### CLI Override
 
-Command line arguments always take precedence over RC file values:
-
-```bash
-# Use RC settings but override etag
-npx svelteesp32 --etag=false
-
-# Use RC settings but add different exclude pattern
-npx svelteesp32 --exclude="*.txt"
+#ifndef SVELTEESP32_FILE_INDEX_HTML
+  #error Missing index.html - frontend build failed?
+#endif
 ```
 
-#### Multiple Environments
+**Available defines:** `SVELTEESP32_COUNT`, `SVELTEESP32_SIZE`, `SVELTEESP32_SIZE_GZIP`, `SVELTEESP32_FILE_*`, `SVELTEESP32_*_FILES`
 
-Create different config files for different environments:
+### Runtime File Manifest
 
-```bash
-# Development build
-npx svelteesp32 --config=.svelteesp32rc.dev.json
+Query embedded files at runtime for logging, diagnostics, or API endpoints:
 
-# Production build
-npx svelteesp32 --config=.svelteesp32rc.prod.json
+```c
+// List all embedded files
+for (size_t i = 0; i < SVELTEESP32_FILE_COUNT; i++) {
+    const auto& f = SVELTEESP32_FILES[i];
+    Serial.printf("%s (%d bytes, gzip: %d)\n", f.path, f.size, f.gzipSize);
+}
 ```
 
-#### Exclude Pattern Behavior
+Each file entry includes: `path`, `size`, `gzipSize`, `etag`, `contentType`
 
-**Replace mode**: When you specify `exclude` patterns in RC file or CLI, they completely replace the defaults.
+### Request Hook (Metrics & Logging)
 
-- **No exclude specified**: Uses default system exclusions (`.DS_Store`, `Thumbs.db`, `.git`, etc.)
-- **RC file has exclude**: Replaces defaults with RC patterns
-- **CLI has --exclude**: Replaces RC patterns (or defaults if no RC)
+Track every request with zero overhead when unused (weak linkage):
 
-Example:
-
-```json
-// .svelteesp32rc.json
-{ "exclude": ["*.map"] }
+```c
+extern "C" void SVELTEESP32_onFileServed(const char* path, int statusCode) {
+    Serial.printf("[HTTP] %s -> %d\n", path, statusCode);
+    if (statusCode == 304) cacheHits++;
+}
 ```
 
-Result: Only `*.map` is excluded (default patterns are replaced)
-
-To keep defaults, explicitly list them in your RC file:
+Called for every response (200 = content served, 304 = cache hit).
 
-```json
-{
-  "exclude": [".DS_Store", "Thumbs.db", ".git", "*.map", "*.md"]
-}
-```
+---
 
-#### NPM Package Variable Interpolation
+## CLI Reference
 
-RC files support automatic variable interpolation from your `package.json`. This allows you to reference package.json fields in your RC configuration using npm-style variable syntax.
+| Option             | Description                                       | Default                 |
+| ------------------ | ------------------------------------------------- | ----------------------- |
+| `-s`               | Source folder with compiled web files             | (required)              |
+| `-e`               | Web server engine (psychic/psychic2/async/espidf) | `psychic`               |
+| `-o`               | Output header file path                           | `svelteesp32.h`         |
+| `--etag`           | ETag caching (true/false/compiler)                | `false`                 |
+| `--gzip`           | Gzip compression (true/false/compiler)            | `true`                  |
+| `--exclude`        | Exclude files by glob pattern                     | System files            |
+| `--base-path`      | URL prefix for all routes                         | (none)                  |
+| `--cachetime`      | Cache-Control max-age in seconds                  | `0`                     |
+| `--version`        | Version string in header                          | (none)                  |
+| `--define`         | C++ define prefix                                 | `SVELTEESP32`           |
+| `--espmethod`      | Init function name                                | `initSvelteStaticFiles` |
+| `--config`         | Custom RC file path                               | `.svelteesp32rc.json`   |
+| `--no-index-check` | Skip index.html validation                        | `false`                 |
+| `-h`               | Show help                                         |                         |
 
-**Syntax:** `$npm_package_<field_name>`
+---
 
-**Supported in:** All string fields (`version`, `define`, `sourcepath`, `outputfile`, `espmethod`, `exclude` patterns)
+## Configuration File
 
-**Example:**
+Store your settings in `.svelteesp32rc.json` for zero-argument builds:
 
 ```json
-// .svelteesp32rc.json
 {
   "engine": "psychic",
-  "version": "v$npm_package_version",
-  "define": "$npm_package_name",
   "sourcepath": "./dist",
-  "outputfile": "./output.h"
+  "outputfile": "./esp32/svelteesp32.h",
+  "etag": "true",
+  "gzip": "true",
+  "exclude": ["*.map", "*.md"]
 }
 ```
 
-With `package.json` containing:
+Then just run:
 
-```json
-{
-  "name": "my-esp32-app",
-  "version": "2.1.0"
-}
+```bash
+npx svelteesp32
 ```
 
-The variables are automatically interpolated to:
+### npm Variable Interpolation
+
+Sync versions and names automatically from your `package.json`:
 
 ```json
 {
-  "version": "v2.1.0",
-  "define": "my_esp32_app"
+  "version": "v$npm_package_version",
+  "define": "$npm_package_name"
 }
 ```
 
-**Nested Fields:**
-
-You can access nested package.json fields using underscores:
+With `package.json` containing `"version": "2.1.0"`, this becomes `"version": "v2.1.0"`.
 
-```json
-// package.json
-{
-  "name": "myapp",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/user/repo.git"
-  }
-}
+### Multiple Environments
 
-// .svelteesp32rc.json
-{
-  "version": "$npm_package_repository_type"
-}
-// Results in: "version": "git"
+```bash
+npx svelteesp32 --config=.svelteesp32rc.prod.json
 ```
 
-**Multiple Variables:**
-
-Combine multiple variables in a single field:
+CLI arguments always override RC file values.
 
-```json
-{
-  "version": "$npm_package_name-v$npm_package_version-release"
-}
-// Results in: "my-esp32-app-v2.1.0-release"
-```
+---
 
-**Requirements:**
+## FAQ
 
-- `package.json` must exist in the same directory as the RC file
-- If variables are used but `package.json` is not found, an error is thrown with details about which fields contain variables
-- Unknown variables are left unchanged (e.g., `$npm_package_nonexistent` stays as-is)
+**How large can my web app be?**
+With gzip compression, 3-4MB asset directories work comfortably. That's enough for a full-featured SPA.
 
-**Use Cases:**
+**Does this use RAM or Flash?**
+Flash only. Data is stored in program memory (PROGMEM on ESP8266, const arrays on ESP32), leaving your heap and stack free for application logic.
 
-- **Version Synchronization:** Keep header version in sync with npm package version
-- **Dynamic Naming:** Use package name for C++ defines automatically
-- **CI/CD Integration:** Reusable RC files across projects with different package names
+**Why is the .h file so large?**
+The text representation (comma-separated bytes) is larger than binary. Check `SVELTEESP32_SIZE_GZIP` for actual flash usage.
 
-### Q&A
+**Does compilation take forever?**
+No. Large headers compile in seconds, and incremental builds skip recompilation if your frontend hasn't changed.
 
-- **How big a frontend application can be placed?** If you compress the content with gzip, even a 3-4Mb assets directory can be placed. This is a serious enough amount to serve a complete application.
+**Can frontend and firmware teams work separately?**
+Absolutely. Frontend builds the app, runs svelteesp32, commits the header. Firmware team includes it and ships. Version sync via npm variables keeps everyone aligned.
 
-- **How fast is cpp file compilation?** The cpp (.h) file can be large, but it can be compiled in a few seconds on any machine. If you don't modify your svelte/react app, it will use the already compiled cpp file (not recompile). This does not increase the speed of ESP32/ESP8266 development.
+---
 
-- **Does the solution use PROGMEM?** It depends on the engine. For PsychicHttpServer (`psychic`, `psychic2`) and ESP-IDF (`espidf`) engines, const arrays are used which are automatically placed in program memory on ESP32. For ESPAsyncWebServer (`async`), PROGMEM directive is explicitly used to support ESP8266/ESP8285. In both cases, the file data is stored in flash memory, not RAM, so your heap and stack remain available for your application.
+## Development
 
-- **Why is the .h file so big?** The source files are always larger than the binary compiled from them. The .h file contains byte arrays in text format (comma-separated decimal numbers), which takes more space than the binary data itself. The actual memory allocation is shown in the header file defines (SVELTEESP32_SIZE for uncompressed, SVELTEESP32_SIZE_GZIP for compressed).
+```bash
+npm run build        # Build TypeScript
+npm run test         # Run unit tests
+npm run test:watch   # Watch mode
+npm run fix          # Fix formatting & linting
+```
 
-- **Is collaboration between groups supported?** Yes, the Frontend team produces the application, the use of svelteesp32 is part of the build process. Then, provided with a version number, the .h file is placed in git, which the ESP team translates into the platformio application.
+---
 
-- **Will you develop it further?** Since I use it myself, I will do my best to make the solution better and better.
+**Ready to ship your web UI in a single binary?**
 
-- **Is this safe to use in production?** I suggest you give it a try! If you find it useful and safe in several different situations, feel free to use it, just like any other free library.
+```bash
+npm install -D svelteesp32
+```