Skip to content

Commit e6bdef1

Browse files
BCsabaEngineBCsabaEngine
committed
fix: update readme
1 parent cf828f9 commit e6bdef1

File tree

1 file changed

+59
-28
lines changed

1 file changed

+59
-28
lines changed

‎README.md‎

Lines changed: 59 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,23 @@ In order to be able to easily update OTA, it is important - from the users' poin
1212

1313
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**.
1414

15+
**Quick Comparison:**
16+
17+
| Feature | SvelteESP32 | Traditional Filesystem (SPIFFS/LittleFS) |
18+
| --------------------- | --------------------------------------- | ---------------------------------------- |
19+
| **Single Binary OTA** | ✓ Everything embedded in firmware | ✗ Requires separate partition upload |
20+
| **Gzip Compression** | ✓ Automatic build-time (>15% reduction) | Manual or runtime compression |
21+
| **ETag Support** | ✓ Built-in MD5 ETags with 304 responses | Manual implementation required |
22+
| **CI/CD Integration** | ✓ npm package, simple build step | Complex with upload_fs tools |
23+
| **Memory Efficiency** | Flash only (PROGMEM/const arrays) | Flash partition + filesystem overhead |
24+
| **Performance** | Direct byte array serving | Filesystem read overhead |
25+
| **Setup Complexity** | Include header, call init function | Partition setup, upload tools, handlers |
26+
27+
**When to use:**
28+
29+
- **SvelteESP32**: Single-binary OTA updates, CI/CD pipelines, static web content that doesn't change at runtime
30+
- **SPIFFS/LittleFS**: Dynamic content, user-uploadable files, configuration that changes at runtime
31+
1532
> Starting with version v1.13.0, RC files support npm package variable interpolation
1633
1734
> 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
309326

310327
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.
311328

329+
**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.
330+
331+
**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:
332+
333+
```bash
334+
# API-only application (no web UI)
335+
npx svelteesp32 -e psychic -s ./dist -o ./output.h --no-index-check
336+
337+
# Custom entry point (users must visit /main.html explicitly)
338+
npx svelteesp32 -e psychic -s ./dist -o ./output.h --no-index-check
339+
```
340+
312341
### File Exclusion
313342

314343
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
418447

419448
### Command line options
420449

421-
| Option | Description | default |
422-
| ------------- | ------------------------------------------------------------------------------------ | ----------------------- |
423-
| `-s` | **Source dist folder contains compiled web files** | (required) |
424-
| `-e` | The engine for which the include file is created (psychic/psychic2/async/espidf) | psychic |
425-
| `-o` | Generated output file with path | `svelteesp32.h` |
426-
| `--exclude` | Exclude files matching glob pattern (repeatable or comma-separated) | Default system files |
427-
| `--etag` | Use ETag header for cache (true/false/compiler) | false |
428-
| `--cachetime` | Override no-cache response with a max-age=\<cachetime\> response (seconds) | 0 |
429-
| `--gzip` | Compress content with gzip (true/false/compiler) | true |
430-
| `--created` | Include creation time in generated header | false |
431-
| `--version` | Include a version string in generated header, e.g. `--version=v$npm_package_version` | '' |
432-
| `--espmethod` | Name of generated initialization method | `initSvelteStaticFiles` |
433-
| `--define` | Prefix of c++ defines (e.g., SVELTEESP32_COUNT) | `SVELTEESP32` |
434-
| `--config` | Use custom RC file path | `.svelteesp32rc.json` |
435-
| `-h` | Show help | |
450+
| Option | Description | default |
451+
| ------------------ | ------------------------------------------------------------------------------------ | ----------------------- |
452+
| `-s` | **Source dist folder contains compiled web files** | (required) |
453+
| `-e` | The engine for which the include file is created (psychic/psychic2/async/espidf) | psychic |
454+
| `-o` | Generated output file with path | `svelteesp32.h` |
455+
| `--exclude` | Exclude files matching glob pattern (repeatable or comma-separated) | Default system files |
456+
| `--etag` | Use ETag header for cache (true/false/compiler) | false |
457+
| `--cachetime` | Override no-cache response with a max-age=\<cachetime\> response (seconds) | 0 |
458+
| `--gzip` | Compress content with gzip (true/false/compiler) | true |
459+
| `--created` | Include creation time in generated header | false |
460+
| `--version` | Include a version string in generated header, e.g. `--version=v$npm_package_version` | '' |
461+
| `--espmethod` | Name of generated initialization method | `initSvelteStaticFiles` |
462+
| `--define` | Prefix of c++ defines (e.g., SVELTEESP32_COUNT) | `SVELTEESP32` |
463+
| `--config` | Use custom RC file path | `.svelteesp32rc.json` |
464+
| `--no-index-check` | Skip validation for index.html/index.htm (for API-only or custom entry points) | false |
465+
| `-h` | Show help | |
436466

437467
### Configuration File
438468

@@ -479,19 +509,20 @@ npx svelteesp32 --config=.svelteesp32rc.prod.json
479509

480510
All CLI options can be specified in the RC file using long-form property names:
481511

482-
| RC Property | CLI Flag | Type | Example |
483-
| ------------ | ------------- | ------- | ------------------------------------------------ |
484-
| `engine` | `-e` | string | `"psychic"`, `"psychic2"`, `"async"`, `"espidf"` |
485-
| `sourcepath` | `-s` | string | `"./dist"` |
486-
| `outputfile` | `-o` | string | `"./output.h"` |
487-
| `etag` | `--etag` | string | `"true"`, `"false"`, `"compiler"` |
488-
| `gzip` | `--gzip` | string | `"true"`, `"false"`, `"compiler"` |
489-
| `cachetime` | `--cachetime` | number | `86400` |
490-
| `created` | `--created` | boolean | `true`, `false` |
491-
| `version` | `--version` | string | `"v1.0.0"` |
492-
| `espmethod` | `--espmethod` | string | `"initSvelteStaticFiles"` |
493-
| `define` | `--define` | string | `"SVELTEESP32"` |
494-
| `exclude` | `--exclude` | array | `["*.map", "*.md"]` |
512+
| RC Property | CLI Flag | Type | Example |
513+
| -------------- | ------------------ | ------- | ------------------------------------------------ |
514+
| `engine` | `-e` | string | `"psychic"`, `"psychic2"`, `"async"`, `"espidf"` |
515+
| `sourcepath` | `-s` | string | `"./dist"` |
516+
| `outputfile` | `-o` | string | `"./output.h"` |
517+
| `etag` | `--etag` | string | `"true"`, `"false"`, `"compiler"` |
518+
| `gzip` | `--gzip` | string | `"true"`, `"false"`, `"compiler"` |
519+
| `cachetime` | `--cachetime` | number | `86400` |
520+
| `created` | `--created` | boolean | `true`, `false` |
521+
| `version` | `--version` | string | `"v1.0.0"` |
522+
| `espmethod` | `--espmethod` | string | `"initSvelteStaticFiles"` |
523+
| `define` | `--define` | string | `"SVELTEESP32"` |
524+
| `exclude` | `--exclude` | array | `["*.map", "*.md"]` |
525+
| `noIndexCheck` | `--no-index-check` | boolean | `true`, `false` |
495526

496527
#### CLI Override
497528

0 commit comments

Comments
 (0)