svelteesp32 2.3.0 → 2.3.2

package/README.md

@@ -75,13 +75,20 @@ void setup() {
 
 **That's it.** Your entire web app is now embedded and ready to serve.
 
+> **Just want production-safe defaults?**
+>
+> ```bash
+> npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h \
+>   --etag=true --gzip=true --cachetime-html=0 --cachetime-assets=31536000
+> ```
+>
+> ETags for instant 304s, gzip for smaller transfers, `no-cache` for HTML so updates are always picked up, and 1-year caching for content-hashed JS/CSS assets.
+
 ---
 
 ## What's New
 
 - **v2.3.0** — `--cachetime-html` and `--cachetime-assets` for per-type cache control (e.g. `no-cache` for HTML, 1-year for content-hashed JS/CSS)
-- **v2.2.2** — `static const` data/ETag arrays prevent multi-TU linker collisions; `SVELTEESP32_MAX_URI_HANDLERS` define added for psychic engine; default exclude patterns removed (now explicit-only)
-- **v2.2.1** — Enhanced `--dryrun` output: engine/ETag/gzip/SPA summary header + aligned route table with MIME types, sizes, and tags (`[default]`, `[no gzip]`, `[SPA catch-all]`)
 - **v2.2.0** — SPA routing catch-all (`--spa`) for client-side routers on all four engines
 - **v2.1.0** — New Arduino WebServer engine (`-e webserver`), dependency updates
 - **v2.0.0** — **BREAKING**: PsychicHttpServer V2 is now the default `psychic` engine. The `psychic2` engine has been removed. Dry run mode, C++ identifier validation, improved MIME type warnings
@@ -316,6 +323,8 @@ Reduce bandwidth dramatically with HTTP 304 "Not Modified" responses. When a bro
 
 All four engines support full ETag validation.
 
+> **Browser compatibility note:** ETags and `Cache-Control: max-age` are universally supported in all modern browsers. Very old clients (IE6/7, early Android 2.x WebViews) may ignore `must-revalidate` or mishandle 304 responses. If you target these environments, set `--etag=false` and `--cachetime=0` to force full downloads on every request.
+
 ### Browser Cache Control
 
 Fine-tune how browsers cache your content:
@@ -540,6 +549,134 @@ npx svelteesp32 --config=.svelteesp32rc.prod.json
 
 CLI arguments always override RC file values.
 
+> **Security note:** When svelteesp32 auto-loads an RC file from the current directory it prints a warning. If you cloned a project that includes `.svelteesp32rc.json`, review it before running. `outputfile` in RC files must be a relative path — use `--output` on the CLI for absolute paths.
+
+---
+
+## Common Recipes
+
+### Recipe A — Arduino IDE + Built-in WebServer
+
+No PlatformIO required. Build your frontend, run svelteesp32 manually, then compile in Arduino IDE.
+
+```bash
+# 1. Build your frontend
+npm run build
+
+# 2. Generate the header
+npx svelteesp32 -e webserver -s ./dist -o ./MyProject/svelteesp32.h \
+  --gzip=true --etag=false
+```
+
+> **Note:** The Arduino `WebServer` library does not support ETag validation, so `--etag=false` is the correct setting here. Remember to call `server.handleClient()` in your `loop()`.
+
+```c
+#include <WebServer.h>
+#include "svelteesp32.h"
+
+WebServer server(80);
+
+void setup() {
+    WiFi.begin("ssid", "password");
+    while (WiFi.status() != WL_CONNECTED) delay(500);
+    initSvelteStaticFiles(&server);
+    server.begin();
+}
+
+void loop() {
+    server.handleClient();
+}
+```
+
+---
+
+### Recipe B — PlatformIO + Vite/SvelteKit, Auto-Generated Header on `pio run`
+
+Run svelteesp32 automatically as a PlatformIO pre-build step so your header is always up to date.
+
+**`platformio.ini`**
+
+```ini
+[env:esp32dev]
+platform = espressif32
+board = esp32dev
+framework = arduino
+lib_deps =
+    ESP Async WebServer
+extra_scripts = pre:scripts/build_frontend.py
+```
+
+**`scripts/build_frontend.py`**
+
+```python
+Import("env")
+import subprocess
+
+def build_frontend(source, target, env):
+    print("Building frontend...")
+    subprocess.run(["npm", "run", "build"], cwd="frontend", check=True)
+    subprocess.run([
+        "npx", "svelteesp32",
+        "-e", "async",
+        "-s", "frontend/dist",
+        "-o", "src/svelteesp32.h",
+        "--etag=true", "--gzip=true",
+        "--cachetime-html=0", "--cachetime-assets=31536000"
+    ], check=True)
+
+env.AddPreAction("buildprog", build_frontend)
+```
+
+This ensures the C++ header is regenerated from the latest frontend build every time you run `pio run`.
+
+---
+
+### Recipe C — ESP-IDF CMake, 1-Year Cached Content-Hashed Assets
+
+Integrate svelteesp32 into a CMake build so the header is regenerated automatically.
+
+**`CMakeLists.txt` (component or top-level)**
+
+```cmake
+add_custom_command(
+    OUTPUT ${CMAKE_CURRENT_SOURCE_DIR}/main/svelteesp32.h
+    COMMAND npm run build
+    COMMAND npx svelteesp32
+        -e espidf
+        -s ${CMAKE_CURRENT_SOURCE_DIR}/frontend/dist
+        -o ${CMAKE_CURRENT_SOURCE_DIR}/main/svelteesp32.h
+        --etag=true --gzip=true
+        --cachetime-html=0 --cachetime-assets=31536000
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    COMMENT "Generating svelteesp32.h from frontend build"
+    VERBATIM
+)
+
+add_custom_target(frontend_header
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/main/svelteesp32.h
+)
+
+# Make your main component depend on the generated header
+add_dependencies(${COMPONENT_LIB} frontend_header)
+```
+
+**`main/app_main.c`**
+
+```c
+#include <esp_http_server.h>
+#include "svelteesp32.h"
+
+void app_main(void) {
+    // ... WiFi init ...
+    httpd_config_t config = HTTPD_DEFAULT_CONFIG();
+    httpd_handle_t server = NULL;
+    httpd_start(&server, &config);
+    initSvelteStaticFiles(server);
+}
+```
+
+The `--cachetime-html=0 --cachetime-assets=31536000` combination gives you `no-cache` for `index.html` (so browser always checks for updates) and a 1-year `max-age` for content-hashed JS/CSS bundles.
+
 ---
 
 ## FAQ

package/dist/commandLine.js

@@ -94,6 +94,15 @@ function validateBasePath(value) {
         throw new Error(`basePath must not end with /: ${value}`);
     if (value.includes('//'))
         throw new Error(`basePath must not contain //: ${value}`);
+    if (value.includes('"'))
+        throw new Error(`basePath must not contain double quotes: ${value}`);
+    if (value.includes('\\'))
+        throw new Error(`basePath must not contain backslashes: ${value}`);
+    return value;
+}
+function validateVersion(value) {
+    if (!/^[\w+.-]+$/.test(value))
+        throw new Error(`version must only contain word characters, dots, hyphens, and plus signs: ${value}`);
     return value;
 }
 function parseSize(value, name) {
@@ -326,6 +335,8 @@ function validateRcConfig(config, rcPath) {
         throw new TypeError(`Invalid dryrun in RC file: ${configObject['dryrun']} (must be boolean)`);
     if (configObject['spa'] !== undefined && typeof configObject['spa'] !== 'boolean')
         throw new TypeError(`Invalid spa in RC file: ${configObject['spa']} (must be boolean)`);
+    if (configObject['outputfile'] !== undefined && node_path_1.default.isAbsolute(configObject['outputfile']))
+        throw new Error(`'outputfile' in RC file must be a relative path (use --output CLI flag for absolute paths): ${configObject['outputfile']}`);
     return configObject;
 }
 function parseArguments() {
@@ -346,8 +357,11 @@ function parseArguments() {
     }
     const rcPath = findRcFile(customConfigPath);
     const rcConfig = rcPath ? loadRcFile(rcPath) : {};
-    if (rcPath)
+    if (rcPath) {
         console.log((0, consoleColor_1.cyanLog)(`[SvelteESP32] Using config from: ${rcPath}`));
+        if (!customConfigPath && node_path_1.default.dirname(rcPath) === process.cwd())
+            console.warn((0, consoleColor_1.yellowLog)(`Warning: Loading config from current directory — verify this file is trusted before proceeding.`));
+    }
     const result = {
         engine: 'psychic',
         outputfile: 'svelteesp32.h',
@@ -420,7 +434,7 @@ function parseArguments() {
                 result.gzip = validateTriState(value, 'gzip');
                 break;
             case 'version':
-                result.version = value;
+                result.version = validateVersion(value);
                 break;
             case 'espmethod':
                 result.espmethod = validateCppIdentifier(value, 'espmethod');
@@ -576,7 +590,7 @@ function formatConfiguration(cmdLine) {
         parts.push(`spa=${cmdLine.spa}`);
     if (cmdLine.exclude.length > 0)
         parts.push(`exclude=[${cmdLine.exclude.join(', ')}]`);
-    return parts.join(' ');
+    return parts.join(' ').replace(/[\n\r]/g, ' ');
 }
 exports.cmdLine = parseArguments();
 if (!(0, node_fs_1.existsSync)(exports.cmdLine.sourcepath)) {

package/dist/file.js

@@ -51,7 +51,12 @@ const isExcluded = (filename, excludePatterns) => {
     return isMatch(normalizedFilename);
 };
 const getFiles = () => {
-    const allFilenames = (0, tinyglobby_1.globSync)('**/*', { cwd: commandLine_1.cmdLine.sourcepath, onlyFiles: true, dot: false });
+    const allFilenames = (0, tinyglobby_1.globSync)('**/*', {
+        cwd: commandLine_1.cmdLine.sourcepath,
+        onlyFiles: true,
+        dot: false,
+        followSymbolicLinks: false
+    });
     const withoutCompressed = allFilenames.filter((filename) => !shouldSkipFile(filename, allFilenames));
     const excludePatterns = commandLine_1.cmdLine.exclude || [];
     const excludedFiles = [];
@@ -73,9 +78,13 @@ const getFiles = () => {
     }
     else if (excludePatterns.length > 0)
         console.log((0, consoleColor_1.yellowLog)(`Warning: --exclude patterns matched no files: ${excludePatterns.join(', ')}`));
+    const MAX_FILE_SIZE = 50 * 1024 * 1024;
     const result = new Map();
     for (const filename of filenames) {
         const filePath = node_path_1.default.join(commandLine_1.cmdLine.sourcepath, filename);
+        const fileSize = (0, node_fs_1.statSync)(filePath).size;
+        if (fileSize > MAX_FILE_SIZE)
+            throw new Error(`File too large (${Math.round(fileSize / 1024)}kB): ${filename}. Maximum single-file size is 50MB.`);
         const content = (0, node_fs_1.readFileSync)(filePath, { flag: 'r' });
         const hash = (0, node_crypto_1.createHash)('sha256').update(content).digest('hex');
         result.set(filename, { content, hash });

package/dist/index.js

@@ -115,9 +115,10 @@ function main() {
     const longestFilename = [...files.keys()].reduce((p, c) => Math.max(c.length, p), 0);
     for (const [originalFilename, fileData] of files) {
         const { content, hash: sha256 } = fileData;
-        const mimeType = (0, mime_types_1.lookup)(originalFilename) || 'text/plain';
-        if (!(0, mime_types_1.lookup)(originalFilename))
+        const rawMime = (0, mime_types_1.lookup)(originalFilename);
+        if (!rawMime)
             console.log((0, consoleColor_1.yellowLog)(` [${originalFilename}] unknown MIME type for extension '${node_path_1.default.extname(originalFilename)}', using text/plain`));
+        const mimeType = rawMime || 'text/plain';
         summary.filecount++;
         const filename = originalFilename.replace(/\\/g, '/');
         let dataname = filename.replace(/\W/g, '_');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelteesp32",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Convert Svelte (or any frontend) JS application to serve it from ESP32 webserver (PsychicHttp)",
   "author": "BCsabaEngine",
   "license": "ISC",
@@ -64,25 +64,25 @@
     "@types/mime-types": "^3.0.1",
     "@types/node": "^25.5.0",
     "@types/picomatch": "^4.0.2",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "eslint": "^10.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint-plugin-unicorn": "^63.0.0",
-    "memfs": "^4.56.11",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "memfs": "^4.57.1",
     "nodemon": "^3.1.14",
     "prettier": "^3.8.1",
     "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.2"
   },
   "dependencies": {
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "mime-types": "^3.0.2",
-    "picomatch": "^4.0.3",
+    "picomatch": "^4.0.4",
     "tinyglobby": "^0.2.15"
   }
 }