svelteesp32 1.13.0 → 1.13.1

package/README.md

@@ -12,6 +12,23 @@ In order to be able to easily update OTA, it is important - from the users' poin
 
 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**.
 
+**Quick Comparison:**
+
+| 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
 
 > Starting with version v1.12.0, you can use RC file for configuration
@@ -309,6 +326,18 @@ At the same time, it can be an advantage that the content is cached by the brows
 
 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.
 
+**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:
+
+```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.
@@ -418,21 +447,22 @@ You can use the following c++ directives at the project level if you want to con
 
 ### 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`   |
-| `-h`          | Show help                                                                            |                         |
+| 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
 
@@ -479,19 +509,20 @@ npx svelteesp32 --config=.svelteesp32rc.prod.json
 
 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"]`                              |
+| 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
 

package/dist/commandLine.d.ts

@@ -10,6 +10,7 @@ interface ICopyFilesArguments {
     created: boolean;
     version: string;
     exclude: string[];
+    noIndexCheck?: boolean;
     help?: boolean;
 }
 interface IRcFileConfig {

package/dist/commandLine.js

@@ -12,6 +12,7 @@ const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = __importDefault(require("node:path"));
 const consoleColor_1 = require("./consoleColor");
+const errorMessages_1 = require("./errorMessages");
 function showHelp() {
     console.log(`
 svelteesp32 - Svelte JS to ESP32 converter
@@ -57,7 +58,8 @@ RC File:
 function validateEngine(value) {
     if (value === 'psychic' || value === 'psychic2' || value === 'async' || value === 'espidf')
         return value;
-    throw new Error(`Invalid engine: ${value}`);
+    console.error((0, errorMessages_1.getInvalidEngineError)(value));
+    process.exit(1);
 }
 function validateTriState(value, name) {
     if (value === 'true' || value === 'false' || value === 'compiler')
@@ -349,6 +351,10 @@ function parseArguments() {
             result.created = true;
             continue;
         }
+        if (argument === '--no-index-check') {
+            result.noIndexCheck = true;
+            continue;
+        }
         if (argument.startsWith('-') && !argument.startsWith('--')) {
             const flag = argument.slice(1);
             const nextArgument = arguments_[index + 1];
@@ -465,8 +471,12 @@ function formatConfiguration(cmdLine) {
     return parts.join(' ');
 }
 exports.cmdLine = parseArguments();
-if (!(0, node_fs_1.existsSync)(exports.cmdLine.sourcepath) || !(0, node_fs_1.statSync)(exports.cmdLine.sourcepath).isDirectory()) {
-    console.error(`Directory ${exports.cmdLine.sourcepath} not exists or not a directory`);
+if (!(0, node_fs_1.existsSync)(exports.cmdLine.sourcepath)) {
+    console.error((0, errorMessages_1.getSourcepathNotFoundError)(exports.cmdLine.sourcepath, 'not_found'));
+    process.exit(1);
+}
+if (!(0, node_fs_1.statSync)(exports.cmdLine.sourcepath).isDirectory()) {
+    console.error((0, errorMessages_1.getSourcepathNotFoundError)(exports.cmdLine.sourcepath, 'not_directory'));
     process.exit(1);
 }
 console.log(`[SvelteESP32] Generate code for ${exports.cmdLine.engine} engine`);

package/dist/errorMessages.d.ts

@@ -0,0 +1,4 @@
+export declare function getMissingIndexError(engine: string): string;
+export declare function getInvalidEngineError(attempted: string): string;
+export declare function getSourcepathNotFoundError(sourcepath: string, reason: 'not_found' | 'not_directory'): string;
+export declare function getMaxUriHandlersHint(engine: string, routeCount: number): string;

package/dist/errorMessages.js

@@ -0,0 +1,146 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMissingIndexError = getMissingIndexError;
+exports.getInvalidEngineError = getInvalidEngineError;
+exports.getSourcepathNotFoundError = getSourcepathNotFoundError;
+exports.getMaxUriHandlersHint = getMaxUriHandlersHint;
+const node_path_1 = __importDefault(require("node:path"));
+const consoleColor_1 = require("./consoleColor");
+function getEngineName(engine) {
+    const names = {
+        psychic: 'PsychicHttpServer',
+        psychic2: 'PsychicHttpServer V2',
+        async: 'ESPAsyncWebServer',
+        espidf: 'ESP-IDF'
+    };
+    return names[engine] ?? engine;
+}
+function getMissingIndexError(engine) {
+    const hints = {
+        psychic: `  1. Add an index.html file to your source directory
+  2. The file will automatically be set as the default route ("/")
+  3. PsychicHttpServer uses: server->defaultEndpoint = ...`,
+        psychic2: `  1. Add an index.html file to your source directory
+  2. The file will automatically be set as the default route ("/")
+  3. PsychicHttpServer V2 uses: server->defaultEndpoint = ...`,
+        async: `  1. Add an index.html file to your source directory
+  2. The file will automatically create a "/" route handler
+  3. ESPAsyncWebServer uses: server.on("/", HTTP_GET, ...)`,
+        espidf: `  1. Add an index.html file to your source directory
+  2. The file will register both "/" and "/index.html" routes
+  3. ESP-IDF uses: httpd_register_uri_handler(server, &route_def_...)`
+    };
+    const hint = hints[engine] ?? hints['psychic'];
+    return ((0, consoleColor_1.redLog)('[ERROR] No index.html or index.htm found in source files') +
+        `
+
+Why this matters:
+  Web applications typically need a default entry point. Without index.html,
+  users visiting http://your-esp32/ will get a 404 error.
+
+How to fix (for ${getEngineName(engine)}):
+${hint}
+
+Alternative:
+  If you use a different entry point (e.g., main.html), you can add --no-index-check flag,
+  but users must navigate to http://your-esp32/main.html explicitly.`);
+}
+function getInvalidEngineError(attempted) {
+    return ((0, consoleColor_1.redLog)(`[ERROR] Invalid engine: '${attempted}'`) +
+        `
+
+Valid engines are:
+  ${(0, consoleColor_1.cyanLog)('• psychic')}    - PsychicHttpServer (ESP32 only, fastest performance)
+  ${(0, consoleColor_1.cyanLog)('• psychic2')}   - PsychicHttpServer V2 (ESP32 only, modern API)
+  ${(0, consoleColor_1.cyanLog)('• async')}      - ESPAsyncWebServer (ESP32/ESP8266 compatible)
+  ${(0, consoleColor_1.cyanLog)('• espidf')}     - Native ESP-IDF web server (ESP32 only, no Arduino)
+
+How to fix:
+  npx svelteesp32 --engine=psychic --sourcepath=./dist
+
+Example RC file (.svelteesp32rc.json):
+  {
+    "engine": "psychic",
+    "sourcepath": "./dist"
+  }
+
+Documentation: https://github.com/hpieroni/svelteesp32#readme`);
+}
+function getSourcepathNotFoundError(sourcepath, reason) {
+    if (reason === 'not_directory')
+        return ((0, consoleColor_1.redLog)(`[ERROR] Source path is not a directory: '${sourcepath}'`) +
+            `
+
+The --sourcepath option must point to a directory containing your built web files,
+not an individual file.
+
+How to fix:
+  npx svelteesp32 --sourcepath=./dist --engine=psychic`);
+    const resolvedPath = node_path_1.default.resolve(sourcepath);
+    const currentDirectory = process.cwd();
+    return ((0, consoleColor_1.redLog)(`[ERROR] Source directory not found: '${sourcepath}'`) +
+        `
+
+Why this matters:
+  SvelteESP32 needs your compiled web assets (HTML, CSS, JS) to convert them
+  into C++ header files for the ESP32.
+
+How to fix:
+  1. Build your frontend application first:
+     • Svelte:  npm run build
+     • React:   npm run build
+     • Vue:     npm run build
+     • Angular: ng build
+
+  2. Verify the build output directory exists:
+     ${(0, consoleColor_1.cyanLog)(`ls -la ${sourcepath}`)}
+
+  3. Check your build tool configuration:
+     • Vite:    vite.config.js → build.outDir
+     • Webpack: webpack.config.js → output.path
+     • Rollup:  rollup.config.js → output.dir
+
+  4. Update your svelteesp32 command to match:
+     ${(0, consoleColor_1.cyanLog)(`npx svelteesp32 --sourcepath=./build --engine=psychic`)}
+
+Current directory: ${currentDirectory}
+Attempted path: ${resolvedPath} (resolved)`);
+}
+function getMaxUriHandlersHint(engine, routeCount) {
+    const recommended = routeCount + 5;
+    const hints = {
+        psychic: `PsychicHttpServer server;
+  server.config.max_uri_handlers = ${recommended};  // Default is 8, you need at least ${routeCount}
+  initSvelteStaticFiles(&server);
+  server.listen(80);`,
+        psychic2: `PsychicHttpServer server;
+  server.config.max_uri_handlers = ${recommended};  // Default is 8, you need at least ${routeCount}
+  initSvelteStaticFiles(&server);
+  server.listen(80);`,
+        espidf: `httpd_config_t config = HTTPD_DEFAULT_CONFIG();
+  config.max_uri_handlers = ${recommended};  // Default is 8, you need at least ${routeCount}
+  httpd_handle_t server = NULL;
+  httpd_start(&server, &config);
+  initSvelteStaticFiles(server);`
+    };
+    const hint = hints[engine];
+    if (!hint)
+        return '';
+    return ((0, consoleColor_1.yellowLog)('[CONFIG TIP] max_uri_handlers configuration') +
+        `
+
+Your generated code includes ${routeCount} routes. Make sure your server can handle them:
+
+For ${getEngineName(engine)}:
+  ${hint}
+
+Recommended formula: max_uri_handlers = file_count + 5 (safety margin)
+
+Runtime symptoms if too low:
+  • Routes not registered (HTTP 404 errors)
+  • ESP_ERR_HTTPD_HANDLERS_FULL error in logs
+  • Some files load, others don't (random behavior)`);
+}

package/dist/file.js

@@ -11,6 +11,7 @@ const picomatch_1 = __importDefault(require("picomatch"));
 const tinyglobby_1 = require("tinyglobby");
 const commandLine_1 = require("./commandLine");
 const consoleColor_1 = require("./consoleColor");
+const errorMessages_1 = require("./errorMessages");
 const findSimilarFiles = (files) => {
     const contentComparer = new Map();
     for (const [filename, content] of files.entries()) {
@@ -79,6 +80,11 @@ const getFiles = () => {
     const duplicates = findSimilarFiles(result);
     for (const sameFiles of duplicates)
         console.log((0, consoleColor_1.yellowLog)(` ${sameFiles.join(', ')} files look like identical`));
+    const hasIndex = [...result.keys()].some((f) => f === 'index.html' || f === 'index.htm' || f.endsWith('/index.html') || f.endsWith('/index.htm'));
+    if (!hasIndex && !commandLine_1.cmdLine.noIndexCheck) {
+        console.error('\n' + (0, errorMessages_1.getMissingIndexError)(commandLine_1.cmdLine.engine));
+        process.exit(1);
+    }
     return result;
 };
 exports.getFiles = getFiles;

package/dist/index.js

@@ -11,6 +11,7 @@ const mime_types_1 = require("mime-types");
 const commandLine_1 = require("./commandLine");
 const consoleColor_1 = require("./consoleColor");
 const cppCode_1 = require("./cppCode");
+const errorMessages_1 = require("./errorMessages");
 const file_1 = require("./file");
 const GZIP_MIN_SIZE = 1024;
 const GZIP_MIN_REDUCTION_RATIO = 0.85;
@@ -82,3 +83,5 @@ const cppFile = (0, cppCode_1.getCppCode)(sources, filesByExtension);
 (0, node_fs_1.writeFileSync)(commandLine_1.cmdLine.outputfile, cppFile, { flush: true, encoding: 'utf8' });
 console.log(`${summary.filecount} files, ${Math.round(summary.size / 1024)}kB original size, ${Math.round(summary.gzipsize / 1024)}kB gzip size`);
 console.log(`${commandLine_1.cmdLine.outputfile} ${Math.round(cppFile.length / 1024)}kB size`);
+if (commandLine_1.cmdLine.engine === 'psychic' || commandLine_1.cmdLine.engine === 'psychic2' || commandLine_1.cmdLine.engine === 'espidf')
+    console.log('\n' + (0, errorMessages_1.getMaxUriHandlersHint)(commandLine_1.cmdLine.engine, sources.length));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelteesp32",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "Convert Svelte (or any frontend) JS application to serve it from ESP32 webserver (PsychicHttp)",
   "author": "BCsabaEngine",
   "license": "ISC",
@@ -61,10 +61,10 @@
   ],
   "devDependencies": {
     "@types/mime-types": "^3.0.1",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.0.0",
     "@types/picomatch": "^4.0.2",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
-    "@typescript-eslint/parser": "^8.48.1",
+    "@typescript-eslint/eslint-plugin": "^8.49.0",
+    "@typescript-eslint/parser": "^8.49.0",
     "@vitest/coverage-v8": "^4.0.15",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",