svelteesp32 2.4.0 → 3.0.0

package/README.md

@@ -56,7 +56,7 @@ npm install -D svelteesp32
 After building your frontend (Vite/Rollup/Webpack):
 
 ```bash
-npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h --etag=true
+npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h --etag=always
 ```
 
 Include in your ESP32 project:
@@ -79,7 +79,7 @@ void setup() {
 >
 > ```bash
 > npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h \
->   --etag=true --gzip=true --cachetime-html=0 --cachetime-assets=31536000
+>   --etag=always --gzip=always --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.
@@ -88,10 +88,8 @@ void setup() {
 
 ## What's New
 
+- **v3.0.0** — **Vite plugin** (`import { svelteESP32 } from 'svelteesp32/vite'`) generates the header automatically after every build; `npx svelteesp32 init` interactive RC file wizard; Node.js >= 22 required
 - **v2.4.0** — `--analyze` for CI size budget checks (per-file table, exits 1 on over-budget); `--manifest` to write a companion JSON manifest alongside the header
-- **v2.3.3** — TypeScript 6 upgrade; `module`/`moduleResolution` updated to `Node16`, target raised to `ES2023`
-- **v2.3.2** — Security hardening: symlink traversal blocked, RC file CWD warning, absolute `outputfile` rejected in RC files, per-file 50 MB size limit
-- **v2.3.1** — Fixes: `--version` and `--basepath` input validation, `formatConfiguration` newline safety
 - **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.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
@@ -107,8 +105,8 @@ void setup() {
 
 ## Requirements
 
-- Node.js >= 20
-- npm >= 9
+- Node.js >= 22
+- npm >= 10
 
 ---
 
@@ -120,22 +118,84 @@ void setup() {
 npm install -D svelteesp32
 ```
 
-### Generate Header File
+### Quick Setup with `init`
+
+The `init` command creates a `.svelteesp32rc.json` configuration file interactively so you never have to remember CLI flags:
+
+```bash
+npx svelteesp32 init
+```
+
+It asks for engine, source path, output path, and ETag preference, writes the RC file, and optionally runs the tool immediately.
+
+### Vite Plugin
+
+For Vite-based projects (SvelteKit, React, Vue, Vanilla) you can skip the manual CLI step entirely — the plugin hooks into the build pipeline and regenerates the C++ header automatically after every `vite build`.
+
+**`vite.config.ts`**
+
+```ts
+import { svelteKit } from '@sveltejs/kit/vite';
+import { svelteESP32 } from 'svelteesp32/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    svelteKit(),
+    svelteESP32({
+      output: '../firmware/include/svelteesp32.h',
+      engine: 'psychic',
+      etag: 'always',
+      gzip: 'always',
+      cachetimeHtml: 0,
+      cachetimeAssets: 31536000
+    })
+  ]
+});
+```
+
+The `output` path is required; all other options mirror the CLI flags and have the same defaults. `sourcepath` defaults to Vite's `build.outDir` when omitted.
+
+**Plugin options**
+
+| Option            | Type                                        | Default                   | Description                                        |
+| ----------------- | ------------------------------------------- | ------------------------- | -------------------------------------------------- |
+| `output`          | `string`                                    | (required)                | Output `.h` file path                              |
+| `sourcepath`      | `string`                                    | Vite's `build.outDir`     | Source directory (compiled web files)              |
+| `engine`          | `'psychic'\|'async'\|'espidf'\|'webserver'` | `'psychic'`               | Target web server engine                           |
+| `etag`            | `'always'\|'never'\|'compiler'`             | `'never'`                 | ETag generation mode                               |
+| `gzip`            | `'always'\|'never'\|'compiler'`             | `'always'`                | Gzip compression mode                              |
+| `cachetime`       | `number`                                    | `0`                       | `Cache-Control: max-age` in seconds (all files)    |
+| `cachetimeHtml`   | `number`                                    | (unset)                   | max-age for HTML files (overrides `cachetime`)     |
+| `cachetimeAssets` | `number`                                    | (unset)                   | max-age for non-HTML files (overrides `cachetime`) |
+| `exclude`         | `string[]`                                  | `[]`                      | Glob patterns to exclude                           |
+| `basepath`        | `string`                                    | (none)                    | URL prefix for all routes                          |
+| `espmethod`       | `string`                                    | `'initSvelteStaticFiles'` | Generated init function name                       |
+| `define`          | `string`                                    | `'SVELTEESP32'`           | C++ `#define` prefix                               |
+| `version`         | `string`                                    | (none)                    | Version string embedded in header                  |
+| `created`         | `boolean`                                   | `false`                   | Include creation timestamp                         |
+| `spa`             | `boolean`                                   | `false`                   | Serve `index.html` for unmatched routes            |
+| `manifest`        | `boolean`                                   | `false`                   | Write companion `.manifest.json`                   |
+| `noIndexCheck`    | `boolean`                                   | `false`                   | Skip `index.html` validation                       |
+| `maxSize`         | `number`                                    | (none)                    | Max total uncompressed size in bytes               |
+| `maxGzipSize`     | `number`                                    | (none)                    | Max total gzip size in bytes                       |
+
+### Generate Header File (CLI)
 
 Choose your web server engine:
 
 ```bash
 # PsychicHttpServer (recommended for ESP32)
-npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h --etag=true
+npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h --etag=always
 
 # ESPAsyncWebServer (ESP32 + ESP8266)
-npx svelteesp32 -e async -s ./dist -o ./esp32/svelteesp32.h --etag=true
+npx svelteesp32 -e async -s ./dist -o ./esp32/svelteesp32.h --etag=always
 
 # Arduino WebServer (ESP32, synchronous, no dependencies)
-npx svelteesp32 -e webserver -s ./dist -o ./esp32/svelteesp32.h --etag=true
+npx svelteesp32 -e webserver -s ./dist -o ./esp32/svelteesp32.h --etag=always
 
 # Native ESP-IDF
-npx svelteesp32 -e espidf -s ./dist -o ./esp32/svelteesp32.h --etag=true
+npx svelteesp32 -e espidf -s ./dist -o ./esp32/svelteesp32.h --etag=always
 ```
 
 ### Build Output
@@ -230,7 +290,7 @@ The generated header file includes everything your ESP needs:
 
 ```c
 //engine:   PsychicHttpServer V2
-//config:   engine=psychic sourcepath=./dist outputfile=./output.h etag=true gzip=true cachetime=0 espmethod=initSvelteStaticFiles define=SVELTEESP32
+//config:   engine=psychic sourcepath=./dist outputfile=./output.h etag=always gzip=always cachetime=0 espmethod=initSvelteStaticFiles define=SVELTEESP32
 //
 #define SVELTEESP32_COUNT 5
 #define SVELTEESP32_SIZE 468822
@@ -314,20 +374,20 @@ void initSvelteStaticFiles(PsychicHttpServer * server) {
 
 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.
 
-- **Enabled by default** — disable with `--gzip=false`
+- **Enabled by default** — disable with `--gzip=never`
 - **Compiler mode** — use `--gzip=compiler` and control via `-D SVELTEESP32_ENABLE_GZIP` in PlatformIO
 
 ### Smart ETag Caching
 
 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.
 
-- **Enable with** `--etag=true` (recommended)
+- **Enable with** `--etag=always` (recommended)
 - **Minimal overhead** — adds ~1-3% code size for significant bandwidth savings
 - **Compiler mode** — use `--etag=compiler` and control via `-D SVELTEESP32_ENABLE_ETAG`
 
 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 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=never` and `--cachetime=0` to force full downloads on every request.
 
 ### Browser Cache Control
 
@@ -341,7 +401,7 @@ Vite and webpack produce content-hashed filenames for JS/CSS (e.g., `app.a1b2c3.
 
 ```bash
 npx svelteesp32 -e psychic -s ./dist -o ./output.h \
-  --etag=true --cachetime-html=0 --cachetime-assets=31536000
+  --etag=always --cachetime-html=0 --cachetime-assets=31536000
 ```
 
 This emits `Cache-Control: no-cache` for every `text/html` file and `Cache-Control: max-age=31536000` for all other assets in the same header, with no per-file configuration needed.
@@ -468,8 +528,8 @@ The manifest records build metadata and per-file details for tooling and dashboa
 {
   "generated": "2026-04-26T12:00:00.000Z",
   "engine": "psychic",
-  "etag": "false",
-  "gzip": "true",
+  "etag": "never",
+  "gzip": "always",
   "filecount": 4,
   "size": 104960,
   "gzipSize": 51507,
@@ -539,8 +599,8 @@ Called for every response (200 = content served, 304 = cache hit).
 | `-s`                 | Source folder with compiled web files                                                  | (required)              |
 | `-e`                 | Web server engine (psychic/async/espidf/webserver)                                     | `psychic`               |
 | `-o`                 | Output header file path                                                                | `svelteesp32.h`         |
-| `--etag`             | ETag caching (true/false/compiler)                                                     | `false`                 |
-| `--gzip`             | Gzip compression (true/false/compiler)                                                 | `true`                  |
+| `--etag`             | ETag caching (always/never/compiler)                                                   | `never`                 |
+| `--gzip`             | Gzip compression (always/never/compiler)                                               | `always`                |
 | `--created`          | Include creation timestamp in header                                                   | `false`                 |
 | `--exclude`          | Exclude files by glob pattern                                                          | (none)                  |
 | `--basepath`         | URL prefix for all routes                                                              | (none)                  |
@@ -571,8 +631,8 @@ Store your settings in `.svelteesp32rc.json` for zero-argument builds:
   "engine": "psychic",
   "sourcepath": "./dist",
   "outputfile": "./esp32/svelteesp32.h",
-  "etag": "true",
-  "gzip": "true",
+  "etag": "always",
+  "gzip": "always",
   "exclude": ["*.map", "*.md"],
   "basepath": "/ui",
   "maxsize": "400k",
@@ -588,6 +648,8 @@ Store your settings in `.svelteesp32rc.json` for zero-argument builds:
 }
 ```
 
+Boolean fields (`noindexcheck`, `dryrun`, `analyze`, `spa`, `manifest`, `created`) accept native JSON booleans (`true`/`false`) or their string equivalents (`"true"`/`"false"`), matching the existing behaviour of `etag` and `gzip`.
+
 Then just run:
 
 ```bash
@@ -631,10 +693,10 @@ npm run build
 
 # 2. Generate the header
 npx svelteesp32 -e webserver -s ./dist -o ./MyProject/svelteesp32.h \
-  --gzip=true --etag=false
+  --gzip=always --etag=never
 ```
 
-> **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()`.
+> **Note:** The Arduino `WebServer` library does not support ETag validation, so `--etag=never` is the correct setting here. Remember to call `server.handleClient()` in your `loop()`.
 
 ```c
 #include <WebServer.h>
@@ -686,7 +748,7 @@ def build_frontend(source, target, env):
         "-e", "async",
         "-s", "frontend/dist",
         "-o", "src/svelteesp32.h",
-        "--etag=true", "--gzip=true",
+        "--etag=always", "--gzip=always",
         "--cachetime-html=0", "--cachetime-assets=31536000"
     ], check=True)
 
@@ -711,7 +773,7 @@ add_custom_command(
         -e espidf
         -s ${CMAKE_CURRENT_SOURCE_DIR}/frontend/dist
         -o ${CMAKE_CURRENT_SOURCE_DIR}/main/svelteesp32.h
-        --etag=true --gzip=true
+        --etag=always --gzip=always
         --cachetime-html=0 --cachetime-assets=31536000
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
     COMMENT "Generating svelteesp32.h from frontend build"

package/bin/index.js

@@ -1,2 +1,11 @@
 #! /usr/bin/env node
-const start = require('../dist/index.js');
+if (process.argv[2] === 'init') {
+  require('../dist/initCommand.js')
+    .runInit()
+    .catch((err) => {
+      console.error('Error:', err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    });
+} else {
+  require('../dist/index.js').main();
+}

package/dist/commandLine.d.ts

@@ -1,11 +1,11 @@
-interface ICopyFilesArguments {
+export interface ICopyFilesArguments {
     engine: 'psychic' | 'async' | 'espidf' | 'webserver';
     sourcepath: string;
     outputfile: string;
     espmethod: string;
     define: string;
-    gzip: 'true' | 'false' | 'compiler';
-    etag: 'true' | 'false' | 'compiler';
+    gzip: 'always' | 'never' | 'compiler';
+    etag: 'always' | 'never' | 'compiler';
     cachetime: number;
     cachetimeHtml?: number;
     cachetimeAssets?: number;
@@ -28,22 +28,22 @@ interface IRcFileConfig {
     outputfile?: string;
     espmethod?: string;
     define?: string;
-    gzip?: 'true' | 'false' | 'compiler';
-    etag?: 'true' | 'false' | 'compiler';
+    gzip?: 'always' | 'never' | 'compiler';
+    etag?: 'always' | 'never' | 'compiler';
     cachetime?: number;
     cachetimehtml?: number;
     cachetimeassets?: number;
-    created?: boolean;
+    created?: boolean | 'true' | 'false';
     version?: string;
     exclude?: string[];
     basepath?: string;
     maxsize?: number | string;
     maxgzipsize?: number | string;
-    noindexcheck?: boolean;
-    dryrun?: boolean;
-    analyze?: boolean;
-    spa?: boolean;
-    manifest?: boolean;
+    noindexcheck?: boolean | 'true' | 'false';
+    dryrun?: boolean | 'true' | 'false';
+    analyze?: boolean | 'true' | 'false';
+    spa?: boolean | 'true' | 'false';
+    manifest?: boolean | 'true' | 'false';
 }
 declare function validateCppIdentifier(value: string, name: string): string;
 declare function parseSize(value: string, name: string): number;
@@ -53,3 +53,4 @@ declare function interpolateNpmVariables(config: IRcFileConfig, rcFilePath: stri
 export { getNpmPackageVariable, hasNpmVariables, interpolateNpmVariables, parseSize, validateCppIdentifier };
 export declare function formatConfiguration(cmdLine: ICopyFilesArguments): string;
 export declare const cmdLine: ICopyFilesArguments;
+//# sourceMappingURL=commandLine.d.ts.map

package/dist/commandLine.js

@@ -19,6 +19,9 @@ function showHelp() {
     console.log(`
 svelteesp32 - Svelte JS to ESP32 converter
 
+Commands:
+  init                       Create .svelteesp32rc.json interactively
+
 Configuration:
   --config <path>            Use custom RC file (default: search for .svelteesp32rc.json)
 
@@ -27,8 +30,8 @@ Options:
                              (psychic|async|espidf|webserver) (default: "psychic")
   -s, --sourcepath <path>    Source dist folder with compiled web files (required)
   -o, --outputfile <path>    Generated output file with path (default: "svelteesp32.h")
-  --etag <value>             Use ETAG header for cache (true|false|compiler) (default: "false")
-  --gzip <value>             Compress content with gzip (true|false|compiler) (default: "true")
+  --etag <value>             Use ETAG header for cache (always|never|compiler) (default: "never")
+  --gzip <value>             Compress content with gzip (always|never|compiler) (default: "always")
   --created                  Include creation time in the output file (default: false)
   --version <value>          Include version info in the output file (default: "")
   --espmethod <name>         Name of generated method (default: "initSvelteStaticFiles")
@@ -57,8 +60,8 @@ RC File:
       "engine": "psychic",
       "sourcepath": "./dist",
       "outputfile": "./output.h",
-      "etag": "true",
-      "gzip": "true",
+      "etag": "always",
+      "gzip": "always",
       "exclude": ["*.map", "*.md"],
       "basepath": "/ui",
       "maxsize": "400k",
@@ -78,7 +81,7 @@ function validateEngine(value) {
     process.exit(1);
 }
 function validateTriState(value, name) {
-    if (value === 'true' || value === 'false' || value === 'compiler')
+    if (value === 'always' || value === 'never' || value === 'compiler')
         return value;
     throw new Error(`Invalid ${name}: ${value}`);
 }
@@ -333,15 +336,35 @@ function validateRcConfig(config, rcPath) {
     }
     validateSizeOption(configObject, 'maxsize');
     validateSizeOption(configObject, 'maxgzipsize');
-    if (configObject['noindexcheck'] !== undefined && typeof configObject['noindexcheck'] !== 'boolean')
+    if (configObject['created'] !== undefined &&
+        typeof configObject['created'] !== 'boolean' &&
+        configObject['created'] !== 'true' &&
+        configObject['created'] !== 'false')
+        throw new TypeError(`Invalid created in RC file: ${configObject['created']} (must be boolean)`);
+    if (configObject['noindexcheck'] !== undefined &&
+        typeof configObject['noindexcheck'] !== 'boolean' &&
+        configObject['noindexcheck'] !== 'true' &&
+        configObject['noindexcheck'] !== 'false')
         throw new TypeError(`Invalid noindexcheck in RC file: ${configObject['noindexcheck']} (must be boolean)`);
-    if (configObject['dryrun'] !== undefined && typeof configObject['dryrun'] !== 'boolean')
+    if (configObject['dryrun'] !== undefined &&
+        typeof configObject['dryrun'] !== 'boolean' &&
+        configObject['dryrun'] !== 'true' &&
+        configObject['dryrun'] !== 'false')
         throw new TypeError(`Invalid dryrun in RC file: ${configObject['dryrun']} (must be boolean)`);
-    if (configObject['analyze'] !== undefined && typeof configObject['analyze'] !== 'boolean')
+    if (configObject['analyze'] !== undefined &&
+        typeof configObject['analyze'] !== 'boolean' &&
+        configObject['analyze'] !== 'true' &&
+        configObject['analyze'] !== 'false')
         throw new TypeError(`Invalid analyze in RC file: ${configObject['analyze']} (must be boolean)`);
-    if (configObject['spa'] !== undefined && typeof configObject['spa'] !== 'boolean')
+    if (configObject['spa'] !== undefined &&
+        typeof configObject['spa'] !== 'boolean' &&
+        configObject['spa'] !== 'true' &&
+        configObject['spa'] !== 'false')
         throw new TypeError(`Invalid spa in RC file: ${configObject['spa']} (must be boolean)`);
-    if (configObject['manifest'] !== undefined && typeof configObject['manifest'] !== 'boolean')
+    if (configObject['manifest'] !== undefined &&
+        typeof configObject['manifest'] !== 'boolean' &&
+        configObject['manifest'] !== 'true' &&
+        configObject['manifest'] !== 'false')
         throw new TypeError(`Invalid manifest in RC file: ${configObject['manifest']} (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']}`);
@@ -373,8 +396,8 @@ function parseArguments() {
     const result = {
         engine: 'psychic',
         outputfile: 'svelteesp32.h',
-        etag: 'false',
-        gzip: 'true',
+        etag: 'never',
+        gzip: 'always',
         created: false,
         version: '',
         espmethod: 'initSvelteStaticFiles',
@@ -400,7 +423,7 @@ function parseArguments() {
     if (rcConfig.cachetimeassets !== undefined)
         result.cachetimeAssets = rcConfig.cachetimeassets;
     if (rcConfig.created !== undefined)
-        result.created = rcConfig.created;
+        result.created = rcConfig.created === true || rcConfig.created === 'true';
     if (rcConfig.version)
         result.version = rcConfig.version;
     if (rcConfig.espmethod)
@@ -414,15 +437,15 @@ function parseArguments() {
     if (rcConfig.maxgzipsize !== undefined)
         result.maxGzipSize = rcConfig.maxgzipsize;
     if (rcConfig.noindexcheck !== undefined)
-        result.noIndexCheck = rcConfig.noindexcheck;
+        result.noIndexCheck = rcConfig.noindexcheck === true || rcConfig.noindexcheck === 'true';
     if (rcConfig.dryrun !== undefined)
-        result.dryRun = rcConfig.dryrun;
+        result.dryRun = rcConfig.dryrun === true || rcConfig.dryrun === 'true';
     if (rcConfig.analyze !== undefined)
-        result.analyze = rcConfig.analyze;
+        result.analyze = rcConfig.analyze === true || rcConfig.analyze === 'true';
     if (rcConfig.spa !== undefined)
-        result.spa = rcConfig.spa;
+        result.spa = rcConfig.spa === true || rcConfig.spa === 'true';
     if (rcConfig.manifest !== undefined)
-        result.manifest = rcConfig.manifest;
+        result.manifest = rcConfig.manifest === true || rcConfig.manifest === 'true';
     if (rcConfig.exclude && rcConfig.exclude.length > 0)
         result.exclude = [...rcConfig.exclude];
     const cliExclude = [];

package/dist/consoleColor.d.ts

@@ -2,3 +2,4 @@ export declare const greenLog: (s: string) => string;
 export declare const yellowLog: (s: string) => string;
 export declare const redLog: (s: string) => string;
 export declare const cyanLog: (s: string) => string;
+//# sourceMappingURL=consoleColor.d.ts.map

package/dist/cppCode.d.ts

@@ -15,3 +15,4 @@ export type ExtensionGroup = {
 };
 export type ExtensionGroups = ExtensionGroup[];
 export declare const getCppCode: (sources: CppCodeSources, filesByExtension: ExtensionGroups) => string;
+//# sourceMappingURL=cppCode.d.ts.map