svelteesp32 2.4.1 → 3.0.1

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,6 +88,8 @@ void setup() {
 
 ## What's New
 
+- **v3.0.1** — Vite plugin now reads RC file automatically; `output` is optional when `outputfile` is in the RC file; option names aligned to lowercase to match RC file keys (`cachetimehtml`, `cachetimeassets`, `noindexcheck`, `maxsize`, `maxgzipsize`); new `config` option to point at a custom RC file
+- **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.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
@@ -104,8 +106,8 @@ void setup() {
 
 ## Requirements
 
-- Node.js >= 20
-- npm >= 9
+- Node.js >= 22
+- npm >= 10
 
 ---
 
@@ -117,22 +119,85 @@ 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
+    })
+  ]
+});
+```
+
+`output` can be omitted when `outputfile` is set in an RC file. `sourcepath` defaults to Vite's `build.outDir`. All other options mirror CLI flags and fall back to the RC file before applying built-in defaults.
+
+**Plugin options**
+
+| Option            | Type                                        | Default                   | Description                                        |
+| ----------------- | ------------------------------------------- | ------------------------- | -------------------------------------------------- |
+| `output`          | `string`                                    | RC `outputfile`           | 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                       |
+| `config`          | `string`                                    | auto-discover             | Path to a custom RC file                           |
+
+### 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
@@ -227,7 +292,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
@@ -311,20 +376,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
 
@@ -338,7 +403,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.
@@ -465,8 +530,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,
@@ -536,8 +601,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)                  |
@@ -568,8 +633,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",
@@ -630,10 +695,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>
@@ -685,7 +750,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)
 
@@ -710,7 +775,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;
@@ -22,14 +22,14 @@ interface ICopyFilesArguments {
     manifest?: boolean;
     help?: boolean;
 }
-interface IRcFileConfig {
+export interface IRcFileConfig {
     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;
@@ -46,10 +46,12 @@ interface IRcFileConfig {
     manifest?: boolean | 'true' | 'false';
 }
 declare function validateCppIdentifier(value: string, name: string): string;
+export declare function validateBasePath(value: string): string;
 declare function parseSize(value: string, name: string): number;
 declare function getNpmPackageVariable(packageJson: Record<string, unknown>, variableName: string): string | undefined;
 declare function hasNpmVariables(config: IRcFileConfig): boolean;
 declare function interpolateNpmVariables(config: IRcFileConfig, rcFilePath: string): IRcFileConfig;
+export declare function loadRcFileConfig(configPath?: string): Partial<IRcFileConfig>;
+export declare function parseArguments(): ICopyFilesArguments;
 export { getNpmPackageVariable, hasNpmVariables, interpolateNpmVariables, parseSize, validateCppIdentifier };
 export declare function formatConfiguration(cmdLine: ICopyFilesArguments): string;
-export declare const cmdLine: ICopyFilesArguments;

package/dist/commandLine.js

@@ -3,7 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cmdLine = void 0;
+exports.validateBasePath = validateBasePath;
+exports.loadRcFileConfig = loadRcFileConfig;
+exports.parseArguments = parseArguments;
 exports.getNpmPackageVariable = getNpmPackageVariable;
 exports.hasNpmVariables = hasNpmVariables;
 exports.interpolateNpmVariables = interpolateNpmVariables;
@@ -19,6 +21,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 +32,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 +62,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 +83,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}`);
 }
@@ -252,6 +257,12 @@ function loadRcFile(rcPath) {
         throw error;
     }
 }
+function loadRcFileConfig(configPath) {
+    const rcPath = findRcFile(configPath);
+    if (!rcPath)
+        return {};
+    return loadRcFile(rcPath);
+}
 function validateSizeOption(configObject, key) {
     const value = configObject[key];
     if (value === undefined)
@@ -393,8 +404,8 @@ function parseArguments() {
     const result = {
         engine: 'psychic',
         outputfile: 'svelteesp32.h',
-        etag: 'false',
-        gzip: 'true',
+        etag: 'never',
+        gzip: 'always',
         created: false,
         version: '',
         espmethod: 'initSvelteStaticFiles',
@@ -522,8 +533,10 @@ function parseArguments() {
         const argument = arguments_[index];
         if (!argument)
             continue;
-        if (argument === '--help' || argument === '-h')
+        if (argument === '--help' || argument === '-h') {
             showHelp();
+            return result;
+        }
         if (argument.startsWith('--') && argument.includes('=')) {
             const parts = argument.split('=');
             const flag = parts[0];
@@ -636,13 +649,3 @@ function formatConfiguration(cmdLine) {
         parts.push(`exclude=[${cmdLine.exclude.join(', ')}]`);
     return parts.join(' ').replace(/[\n\r]/g, ' ');
 }
-exports.cmdLine = parseArguments();
-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/cppCode.d.ts

@@ -1,3 +1,4 @@
+import type { ICopyFilesArguments } from './commandLine';
 export type CppCodeSource = {
     filename: string;
     dataname: string;
@@ -14,4 +15,4 @@ export type ExtensionGroup = {
     count: number;
 };
 export type ExtensionGroups = ExtensionGroup[];
-export declare const getCppCode: (sources: CppCodeSources, filesByExtension: ExtensionGroups) => string;
+export declare const getCppCode: (sources: CppCodeSources, filesByExtension: ExtensionGroups, options: ICopyFilesArguments) => string;