svelteesp32 1.0.3 → 1.0.4

package/README.md

@@ -1,31 +1,52 @@
-# [svelteesp32] Convert Svelte (or any frontend) JS application to serve it from ESP32 webserver (PsychicHttp)
+# `svelteesp32` ![image](https://badges.github.io/stability-badges/dist/stable.svg)
+
+# Convert Svelte (or React/Angular/Vue) JS application to serve it from ESP32 webserver
 
 ### Forget SPIFFS and LittleFS now
 
-I often make small to medium-sized microcontroller solutions that run on ESP32. If a web interface is needed, I will create a Svelte application. The Svelte application is practically served by the ESP32.
+I often make small to medium-sized microcontroller solutions that run on ESP32. If a web interface is needed, I create a Svelte application. The Svelte application is practically served by the ESP32.
 
-In order to be able to easily update OTA, it is important - from the users' point of view - that the update file **consists of one file**. I can't use the SPIFFS/LittleFS solution for this. It is necessary that the Svelte files are included inline in the Arduino/PlatformIO code.
+In order to be able to easily update OTA, it is important - from the users' point of view - that the update file **consists of one file**. I can't use the SPIFFS/LittleFS solution for this. It is necessary that the WebUI files are included inline in the Arduino or PlatformIO c++ code.
 
-This npm package provides a solution for **inserting any JS client application into the ESP32 web server** (PsychicHttp is my favorite, faster than ESPAsyncWebServer). For this, JS, html, css, font, etc. files must be converted to binary. npm is easy to use and easy to **integrate into your CI/CD pipeline**.
+This npm package provides a solution for **inserting any JS client application into the ESP32 web server** (PsychicHttp is my favorite, faster than ESPAsyncWebServer). 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**.
 
 ### Usage
 
-Install package as devDependency (it is practical if the package is part of the project so that you always receive updates)
+**Install package** as devDependency (it is practical if the package is part of the project so that you always receive updates)
 
 ```bash
 npm install -D svelteesp32
 ```
 
-After a successful Svelte build create az includeable cpp file
+After a successful Svelte build (rollup/webpack/vite) **create an includeable c++ header** file
 
 ```bash
 npx svelteesp32 -s ../svelteapp/dist -o ../esp32project/svelteesp32.h
+```
+
+During the **translation process**, the processed file details are visible, and at the end, the result shows the ESP32's memory allocation (gzip size)
+
+```
+[assets/index-KwubEIf-.js]
+✓ gzip used (38850 -> 12547)
+
+[assets/index-Soe6cpLA.css]
+✓ gzip used (32494 -> 5368)
 
-// compress files and serve as gzip
-npx svelteesp32 -s ../svelteapp/dist -o ../esp32project/svelteesp32.h -g
+[favicon.png]
+x gzip unused (33249 -> 33282)
+
+[index.html]
+✓ gzip used (472 -> 308)
+
+[roboto_regular.json]
+✓ gzip used (363757 -> 93567)
+
+5 files, 458kB original size, 142kB gzip size
+../../../Arduino/EspSvelte/svelteesp32.h 842kB size
 ```
 
-Include svelteesp32.h into yout Arduino cpp project (copy it next to the ino file)
+**Include svelteesp32.h** into your Arduino or PlatformIO c++ project (copy it next to the main c++ file)
 
 ```c
 ...
@@ -47,32 +68,65 @@ void setup()
 }
 ```
 
-The content of generated file (do not edit, just use)
+The content of **generated file** (do not edit, just use)
 
 ```c
+const uint8_t data0[12547] = {0x1f, 0x8b, 0x8, 0x0, ...
+const uint8_t data1[5368] = {0x1f, 0x8b, 0x8, 0x0, 0x0, ...
+
 void initSvelteStaticFiles(PsychicHttpServer * server) {
-    server->on("assets/index-KwubEIf-.js", HTTP_GET, [](PsychicRequest * request)
-    {
-        const uint8_t data[] = {0x1f, 0x8b, 0x8, 0x0, 0x0, ...}
-
-        PsychicStreamResponse response(request, "application/javascript");
-        response.addHeader("Content-Encoding", "gzip");
-        response.beginSend();
-        for (int i = 0; i < sizeof(data); i++) response.write(data[i]);
-        return response.endSend();
-    });
-
-    server->on("assets/index-Soe6cpLA.css", HTTP_GET, [](PsychicRequest * request)
-    {
-        const uint8_t data[] = {0x1f, 0x8b, 0x8, 0x0, 0x0, ...}
-
-        PsychicStreamResponse response(request, "text/css");
-        response.addHeader("Content-Encoding", "gzip");
-        response.beginSend();
-        for (int i = 0; i < sizeof(data); i++) response.write(data[i]);
-        return response.endSend();
-    });
+  server->on("/assets/index-KwubEIf-.js", HTTP_GET, [](PsychicRequest * request)
+  {
+    PsychicResponse response(request);
+    response.setContentType("application/javascript");
+    response.addHeader("Content-Encoding", "gzip");
+    response.setContent(data0, sizeof(data0));
+    return response.send();
+  });
+
+  server->on("/assets/index-Soe6cpLA.css", HTTP_GET, [](PsychicRequest * request)
+  {
+    PsychicResponse response(request);
+    response.setContentType("text/css");
+    response.addHeader("Content-Encoding", "gzip");
+    response.setContent(data1, sizeof(data1));
+    return response.send();
+  });
 
     ...
 }
 ```
+
+### Gzip
+
+All modern browsers have been able to handle gzip-compressed content for years. For this reason, there is no question that the easily compressed JS and CSS files are stored compressed in the ESP32 and sent to the browser.
+
+During the translation process, data in gzip format is generated and will be used if the size is greater than 100 bytes and we experience a reduction of at least 15%. In such a case, the compressed data is unconditionally sent to the browser with the appropriate header information.
+
+Automatic compression can be turned off with the `--no-gzip` option.
+
+### Main entry point - index.html
+
+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://esp32_xxx.local` or just entering the `http://x.y.w.z/` IP address will serve this main file.
+
+### Command line options
+
+| Option        | Mandatory | Description                                    | default                 |
+| ------------- | :-------: | ---------------------------------------------- | ----------------------- |
+| `-s`          |     x     | Source dist folder contains compiled web files |                         |
+| `-o`          |     x     | Generated output file with path                | `svelteesp32.h`         |
+| `--no-gzip`   |           | Do not compress content with gzip              |                         |
+| `--espmethod` |     x     | Name of generated method                       | `initSvelteStaticFiles` |
+| `-h`          |           | Show help                                      |                         |
+
+### Q&A
+
+- **How big a frontend application can be placed?** If you compress the content with gzip, even a 3-4Mb assets directory can be placed. This is a serious enough amount to serve a complete application.
+
+- **How fast is cpp file compilation?** The cpp file can be large, but it can be compiled in a few seconds on any machine. If you don't modify your svelte/react app, it will use the already compiled cpp file (not recompile). This does not increase the speed of ESP32 development.
+
+- **Does the solution use PROGMEM?** No and yes. ESP32 no longer has PROGMEM. (Exists, but does not affect the translation). Instead, if we use a const array in the global namespace, its content will be placed in the code area, i.e. it will not be used from the heap or the stack, so the content of the files to be served will be placed next to the code.
+
+- **Is this safe to use in production?** I suggest you give it a try! If you find it useful and safe in several different situations, feel free to use it, just like any other free library.
+
+- **Will you develop it further?** Since I use it myself, I will do my best to make the solution better and better.

package/dist/commandLine.d.ts

@@ -1,8 +1,8 @@
 interface ICopyFilesArguments {
-    sourcePath: string;
-    outputFile: string;
-    espMethodName: string;
-    gzip: boolean;
+    sourcepath: string;
+    outputfile: string;
+    espmethod: string;
+    'no-gzip': boolean;
     help?: boolean;
 }
 export declare const cmdLine: ICopyFilesArguments;

package/dist/commandLine.js

@@ -4,24 +4,23 @@ exports.cmdLine = void 0;
 const node_fs_1 = require("node:fs");
 const ts_command_line_args_1 = require("ts-command-line-args");
 exports.cmdLine = (0, ts_command_line_args_1.parse)({
-    sourcePath: {
+    sourcepath: {
         type: String,
         alias: 's',
         description: 'Source dist folder contains compiled web files'
     },
-    outputFile: {
+    outputfile: {
         type: String,
         alias: 'o',
         description: 'Generated output file with path',
         defaultValue: 'svelteesp32.h'
     },
-    gzip: {
+    'no-gzip': {
         type: Boolean,
-        alias: 'g',
-        description: 'Compress content with gzip',
+        description: 'Do not compress content with gzip',
         defaultValue: false
     },
-    espMethodName: {
+    espmethod: {
         type: String,
         description: 'Name of generated method',
         defaultValue: 'initSvelteStaticFiles'
@@ -31,7 +30,7 @@ exports.cmdLine = (0, ts_command_line_args_1.parse)({
     helpArg: 'help',
     headerContentSections: [{ header: 'svelteesp32', content: 'Svelte JS to ESP32 converter' }]
 });
-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) || !(0, node_fs_1.statSync)(exports.cmdLine.sourcepath).isDirectory()) {
+    console.error(`Directory ${exports.cmdLine.sourcepath} not exists or not a directory`);
     process.exit(1);
 }

package/dist/cppCode.js

@@ -43,7 +43,7 @@ const getCppCode = (sources) => {
     }
     let result = fileTemplate;
     result = replaceAll(result, '$arrays$', arrays.join('\n'));
-    result = replaceAll(result, '$method$', commandLine_1.cmdLine.espMethodName);
+    result = replaceAll(result, '$method$', commandLine_1.cmdLine.espmethod);
     result = replaceAll(result, '$code$', blocks.join(''));
     return result;
 };

package/dist/file.js

@@ -4,7 +4,7 @@ exports.getFiles = void 0;
 const node_path_1 = require("node:path");
 const glob_1 = require("glob");
 const commandLine_1 = require("./commandLine");
-const getFiles = () => (0, glob_1.globSync)((0, node_path_1.join)('**/*'), { cwd: commandLine_1.cmdLine.sourcePath, nodir: true })
+const getFiles = () => (0, glob_1.globSync)((0, node_path_1.join)('**/*'), { cwd: commandLine_1.cmdLine.sourcepath, nodir: true })
     .filter((filename) => !['.gz', '.brottli'].includes((0, node_path_1.extname)(filename)))
     .sort();
 exports.getFiles = getFiles;

package/dist/index.js

@@ -18,9 +18,19 @@ for (const file of (0, file_1.getFiles)()) {
     const mime = (0, mime_types_1.lookup)(file) || 'text/plain';
     summary.filecount++;
     console.log(`[${file}]`);
-    const rawContent = (0, node_fs_1.readFileSync)((0, node_path_1.join)(commandLine_1.cmdLine.sourcePath, file), { flag: 'r' });
+    const rawContent = (0, node_fs_1.readFileSync)((0, node_path_1.join)(commandLine_1.cmdLine.sourcepath, file), { flag: 'r' });
     summary.size += rawContent.length;
-    if (commandLine_1.cmdLine.gzip) {
+    if (commandLine_1.cmdLine['no-gzip']) {
+        sources.push({
+            index: sourceIndex++,
+            filename: file,
+            content: rawContent,
+            isGzip: false,
+            mime
+        });
+        console.log(`- gzip skipped (${rawContent.length})`);
+    }
+    else {
         const zipContent = (0, node_zlib_1.gzipSync)(rawContent, { level: 9 });
         summary.gzipsize += zipContent.length;
         if (rawContent.length > 100 && zipContent.length < rawContent.length * 0.85) {
@@ -44,22 +54,14 @@ for (const file of (0, file_1.getFiles)()) {
             console.log(`x gzip unused (${rawContent.length} -> ${zipContent.length})`);
         }
     }
-    else {
-        sources.push({
-            index: sourceIndex++,
-            filename: file,
-            content: rawContent,
-            isGzip: false,
-            mime
-        });
-        console.log(`- gzip skipped (${rawContent.length})`);
-    }
     console.log('');
 }
 const cppFile = (0, cppCode_1.getCppCode)(sources);
-(0, node_fs_1.writeFileSync)(commandLine_1.cmdLine.outputFile, cppFile);
-if (commandLine_1.cmdLine.gzip)
-    console.log(`${summary.filecount} files, ${Math.round(summary.size / 1024)}kB original size, ${Math.round(summary.gzipsize / 1024)}kB gzip size`);
-else
+(0, node_fs_1.writeFileSync)(commandLine_1.cmdLine.outputfile, cppFile);
+if (commandLine_1.cmdLine['no-gzip']) {
     console.log(`${summary.filecount} files, ${Math.round(summary.size / 1024)}kB original size`);
-console.log(`${commandLine_1.cmdLine.outputFile} ${Math.round(cppFile.length / 1024)}kB size`);
+}
+else {
+    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`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelteesp32",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Convert Svelte (or any frontend) JS application to serve it from ESP32 webserver (PsychicHttp)",
   "author": "BCsabaEngine",
   "license": "ISC",
@@ -28,7 +28,7 @@
   },
   "homepage": "https://github.com/BCsabaEngine/svelteesp32",
   "scripts": {
-    "dev": "nodemon src/index.ts -- -s ./svelte/dist -o ../../../Arduino/EspSvelte/svelteesp32.h -g",
+    "dev": "nodemon src/index.ts -- -s ./svelte/dist -o ../../../Arduino/EspSvelte/svelteesp32.h",
     "clean": "tsc --build --clean",
     "build": "tsc --build --clean && tsc --build --force",
     "format:check": "prettier --check .",
@@ -48,8 +48,8 @@
   "devDependencies": {
     "@types/mime-types": "^2.1.4",
     "@types/node": "^20.11.17",
-    "@typescript-eslint/eslint-plugin": "^6.21.0",
-    "@typescript-eslint/parser": "^6.21.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.1",
+    "@typescript-eslint/parser": "^7.0.1",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-simple-import-sort": "^12.0.0",