svelteesp32 3.0.1 → 3.1.0

package/README.md

@@ -79,7 +79,7 @@ void setup() {
 >
 > ```bash
 > npx svelteesp32 -e psychic -s ./dist -o ./esp32/svelteesp32.h \
->   --etag=always --gzip=always --cachetime-html=0 --cachetime-assets=31536000
+>   --etag=always --gzip=always --cachetimehtml=0 --cachetimeassets=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,10 @@ 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
+- **v3.1.0** — Removed `handlebars` dependency; C++ generation is now pure TypeScript. `--cachetime-html` → `--cachetimehtml`, `--cachetime-assets` → `--cachetimeassets` (CLI now matches RC file keys); `--dry-run` alias removed — use `--dryrun`
+- **v3.0.0** — **Vite plugin** (`import { svelteESP32 } from 'svelteesp32/vite'`) generates the header automatically after every build — call with no argument for RC file mode or pass an options object for plugin-options mode; `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.3.0** — `--cachetimehtml` and `--cachetimeassets` 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
 - **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
@@ -133,13 +133,27 @@ It asks for engine, source path, output path, and ETag preference, writes the RC
 
 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`**
+The plugin has two exclusive modes — pick one:
+
+**RC file mode** — call with no argument (or a string path to a custom RC file). All settings come from `.svelteesp32rc.json`; `outputfile` in the RC file is required.
 
 ```ts
 import { svelteKit } from '@sveltejs/kit/vite';
 import { svelteESP32 } from 'svelteesp32/vite';
 import { defineConfig } from 'vite';
 
+export default defineConfig({
+  plugins: [
+    svelteKit(),
+    svelteESP32() // auto-discover .svelteesp32rc.json
+    // svelteESP32('/path/to/custom.rc.json')  // or specify path explicitly
+  ]
+});
+```
+
+**Plugin options mode** — call with an options object. The RC file is completely ignored; `output` is required.
+
+```ts
 export default defineConfig({
   plugins: [
     svelteKit(),
@@ -155,7 +169,7 @@ export default defineConfig({
 });
 ```
 
-`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.
+`sourcepath` defaults to Vite's `build.outDir` in both modes.
 
 **Plugin options**
 
@@ -180,7 +194,6 @@ export default defineConfig({
 | `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)
 
@@ -397,22 +410,22 @@ Fine-tune how browsers cache your content:
 
 - **Default:** `no-cache` — browsers always validate with server (ETag check)
 - **Long-term caching:** `--cachetime=86400` — cache for 24 hours without any server requests
-- **Per-type caching:** Use `--cachetime-html` and `--cachetime-assets` independently
+- **Per-type caching:** Use `--cachetimehtml` and `--cachetimeassets` independently
 
 Vite and webpack produce content-hashed filenames for JS/CSS (e.g., `app.a1b2c3.js`). Those can be cached for up to a year because the hash changes with every build, but `index.html` must stay `no-cache` since it's the entry point that references them:
 
 ```bash
 npx svelteesp32 -e psychic -s ./dist -o ./output.h \
-  --etag=always --cachetime-html=0 --cachetime-assets=31536000
+  --etag=always --cachetimehtml=0 --cachetimeassets=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.
 
-| Option               | Applies to                       | Falls back to  |
-| -------------------- | -------------------------------- | -------------- |
-| `--cachetime-html`   | `text/html` only                 | `--cachetime`  |
-| `--cachetime-assets` | everything else                  | `--cachetime`  |
-| `--cachetime`        | all files (when no override set) | `0` (no-cache) |
+| Option              | Applies to                       | Falls back to  |
+| ------------------- | -------------------------------- | -------------- |
+| `--cachetimehtml`   | `text/html` only                 | `--cachetime`  |
+| `--cachetimeassets` | everything else                  | `--cachetime`  |
+| `--cachetime`       | all files (when no override set) | `0` (no-cache) |
 
 ### Automatic Index Handling
 
@@ -596,31 +609,31 @@ Called for every response (200 = content served, 304 = cache hit).
 
 ## CLI Reference
 
-| Option               | Description                                                                            | Default                 |
-| -------------------- | -------------------------------------------------------------------------------------- | ----------------------- |
-| `-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 (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)                  |
-| `--maxsize`          | Max total uncompressed size (e.g., `400k`, `1m`)                                       | (none)                  |
-| `--maxgzipsize`      | Max total gzip size (e.g., `150k`, `500k`)                                             | (none)                  |
-| `--cachetime`        | Cache-Control max-age in seconds (all files)                                           | `0`                     |
-| `--cachetime-html`   | max-age for HTML files (overrides `--cachetime`)                                       | (unset)                 |
-| `--cachetime-assets` | max-age for non-HTML files (overrides `--cachetime`)                                   | (unset)                 |
-| `--version`          | Version string in header                                                               | (none)                  |
-| `--define`           | C++ define prefix                                                                      | `SVELTEESP32`           |
-| `--espmethod`        | Init function name                                                                     | `initSvelteStaticFiles` |
-| `--config`           | Custom RC file path                                                                    | `.svelteesp32rc.json`   |
-| `--dryrun`           | Show route table + summary without writing output                                      | `false`                 |
-| `--analyze`          | Print per-file size table and budget status, no output written; exits 1 if over budget | `false`                 |
-| `--manifest`         | Write companion `.manifest.json` alongside the header                                  | `false`                 |
-| `--spa`              | Serve index.html for unmatched routes (SPA routing)                                    | `false`                 |
-| `--noindexcheck`     | Skip index.html validation                                                             | `false`                 |
-| `-h`                 | Show help                                                                              |                         |
+| Option              | Description                                                                            | Default                 |
+| ------------------- | -------------------------------------------------------------------------------------- | ----------------------- |
+| `-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 (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)                  |
+| `--maxsize`         | Max total uncompressed size (e.g., `400k`, `1m`)                                       | (none)                  |
+| `--maxgzipsize`     | Max total gzip size (e.g., `150k`, `500k`)                                             | (none)                  |
+| `--cachetime`       | Cache-Control max-age in seconds (all files)                                           | `0`                     |
+| `--cachetimehtml`   | max-age for HTML files (overrides `--cachetime`)                                       | (unset)                 |
+| `--cachetimeassets` | max-age for non-HTML files (overrides `--cachetime`)                                   | (unset)                 |
+| `--version`         | Version string in header                                                               | (none)                  |
+| `--define`          | C++ define prefix                                                                      | `SVELTEESP32`           |
+| `--espmethod`       | Init function name                                                                     | `initSvelteStaticFiles` |
+| `--config`          | Custom RC file path                                                                    | `.svelteesp32rc.json`   |
+| `--dryrun`          | Show route table + summary without writing output                                      | `false`                 |
+| `--analyze`         | Print per-file size table and budget status, no output written; exits 1 if over budget | `false`                 |
+| `--manifest`        | Write companion `.manifest.json` alongside the header                                  | `false`                 |
+| `--spa`             | Serve index.html for unmatched routes (SPA routing)                                    | `false`                 |
+| `--noindexcheck`    | Skip index.html validation                                                             | `false`                 |
+| `-h`                | Show help                                                                              |                         |
 
 ---
 
@@ -751,7 +764,7 @@ def build_frontend(source, target, env):
         "-s", "frontend/dist",
         "-o", "src/svelteesp32.h",
         "--etag=always", "--gzip=always",
-        "--cachetime-html=0", "--cachetime-assets=31536000"
+        "--cachetimehtml=0", "--cachetimeassets=31536000"
     ], check=True)
 
 env.AddPreAction("buildprog", build_frontend)
@@ -776,7 +789,7 @@ add_custom_command(
         -s ${CMAKE_CURRENT_SOURCE_DIR}/frontend/dist
         -o ${CMAKE_CURRENT_SOURCE_DIR}/main/svelteesp32.h
         --etag=always --gzip=always
-        --cachetime-html=0 --cachetime-assets=31536000
+        --cachetimehtml=0 --cachetimeassets=31536000
     WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
     COMMENT "Generating svelteesp32.h from frontend build"
     VERBATIM
@@ -805,7 +818,7 @@ void app_main(void) {
 }
 ```
 
-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.
+The `--cachetimehtml=0 --cachetimeassets=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.
 
 ---
 

package/dist/commandLine.d.ts

@@ -21,6 +21,7 @@ export interface ICopyFilesArguments {
     spa?: boolean;
     manifest?: boolean;
     help?: boolean;
+    configSource: 'cli' | 'rcfile' | 'vite';
 }
 export interface IRcFileConfig {
     engine?: 'psychic' | 'async' | 'espidf' | 'webserver';

package/dist/commandLine.js

@@ -39,8 +39,8 @@ Options:
   --espmethod <name>         Name of generated method (default: "initSvelteStaticFiles")
   --define <prefix>          Prefix of c++ defines (default: "SVELTEESP32")
   --cachetime <seconds>      max-age cache time in seconds (default: 0)
-  --cachetime-html <sec>     Cache-Control max-age for HTML files (overrides --cachetime)
-  --cachetime-assets <sec>   Cache-Control max-age for non-HTML assets (overrides --cachetime)
+  --cachetimehtml <sec>      Cache-Control max-age for HTML files (overrides --cachetime)
+  --cachetimeassets <sec>    Cache-Control max-age for non-HTML assets (overrides --cachetime)
   --exclude <pattern>        Exclude files matching glob pattern (repeatable or comma-separated)
                              Examples: --exclude="*.map" --exclude="test/**/*.ts"
   --basepath <path>          URL prefix for all routes (e.g., "/ui") (default: "")
@@ -412,7 +412,8 @@ function parseArguments() {
         define: 'SVELTEESP32',
         cachetime: 0,
         exclude: [],
-        basePath: ''
+        basePath: '',
+        configSource: 'cli'
     };
     if (rcConfig.engine)
         result.engine = rcConfig.engine;
@@ -492,20 +493,20 @@ function parseArguments() {
                 if (result.cachetime < 0)
                     throw new TypeError(`Invalid cachetime: ${value} (must be non-negative)`);
                 break;
-            case 'cachetime-html': {
+            case 'cachetimehtml': {
                 result.cachetimeHtml = Number.parseInt(value, 10);
                 if (Number.isNaN(result.cachetimeHtml))
-                    throw new TypeError(`Invalid cachetime-html: ${value}`);
+                    throw new TypeError(`Invalid cachetimehtml: ${value}`);
                 if (result.cachetimeHtml < 0)
-                    throw new TypeError(`Invalid cachetime-html: ${value} (must be non-negative)`);
+                    throw new TypeError(`Invalid cachetimehtml: ${value} (must be non-negative)`);
                 break;
             }
-            case 'cachetime-assets': {
+            case 'cachetimeassets': {
                 result.cachetimeAssets = Number.parseInt(value, 10);
                 if (Number.isNaN(result.cachetimeAssets))
-                    throw new TypeError(`Invalid cachetime-assets: ${value}`);
+                    throw new TypeError(`Invalid cachetimeassets: ${value}`);
                 if (result.cachetimeAssets < 0)
-                    throw new TypeError(`Invalid cachetime-assets: ${value} (must be non-negative)`);
+                    throw new TypeError(`Invalid cachetimeassets: ${value} (must be non-negative)`);
                 break;
             }
             case 'exclude': {
@@ -554,7 +555,7 @@ function parseArguments() {
             result.noIndexCheck = true;
             continue;
         }
-        if (argument === '--dryrun' || argument === '--dry-run') {
+        if (argument === '--dryrun') {
             result.dryRun = true;
             continue;
         }
@@ -615,10 +616,12 @@ function parseArguments() {
     return result;
 }
 function formatConfiguration(cmdLine) {
+    const relativeOutput = node_path_1.default.relative(process.cwd(), cmdLine.outputfile);
     const parts = [
+        `source=${cmdLine.configSource}`,
         `engine=${cmdLine.engine}`,
         `sourcepath=${cmdLine.sourcepath}`,
-        `outputfile=${cmdLine.outputfile}`,
+        `outputfile=${relativeOutput}`,
         `etag=${cmdLine.etag}`,
         `gzip=${cmdLine.gzip}`,
         `cachetime=${cmdLine.cachetime}`

package/dist/cppCode.d.ts

@@ -15,4 +15,53 @@ export type ExtensionGroup = {
     count: number;
 };
 export type ExtensionGroups = ExtensionGroup[];
+export declare const sw: (value: string, cases: Partial<Record<"always" | "never" | "compiler", string>>) => string;
+declare const transformSourceToTemplateData: (s: CppCodeSource, etag: string, effectiveCacheTime: number) => {
+    length: number;
+    bytes: string;
+    lengthGzip: number;
+    bytesGzip: string;
+    isDefault: boolean;
+    gzipSizeForManifest: number;
+    etagForManifest: string;
+    cacheTime: {
+        value: number;
+    } | undefined;
+    filename: string;
+    dataname: string;
+    datanameUpperCase: string;
+    mime: string;
+    content: Buffer;
+    contentGzip: Buffer;
+    isGzip: boolean;
+    sha256: string;
+};
+export type TransformedSource = ReturnType<typeof transformSourceToTemplateData>;
+export type TemplateData = {
+    config: string;
+    now: string;
+    fileCount: string;
+    fileSize: string;
+    fileGzipSize: string;
+    sources: TransformedSource[];
+    filesByExtension: ExtensionGroups;
+    etag: string;
+    gzip: string;
+    created: boolean | undefined;
+    version: string | undefined;
+    methodName: string;
+    definePrefix: string;
+    basePath: string;
+    spa: boolean;
+    spaSource: TransformedSource | undefined;
+    isPsychic: boolean;
+    maxUriHandlers: string;
+};
+export declare const cacheCtrl: (source: TransformedSource) => string;
+export declare const genCommonHeader: (d: TemplateData) => string;
+export declare const genDataArrays: (d: TemplateData, progmem: boolean) => string;
+export declare const genEtagArrays: (d: TemplateData) => string;
+export declare const genManifest: (d: TemplateData) => string;
+export declare const genHook: (d: TemplateData) => string;
 export declare const getCppCode: (sources: CppCodeSources, filesByExtension: ExtensionGroups, options: ICopyFilesArguments) => string;
+export {};