Calendink/Provider/Documentation/build_frontend.md

Building and Flashing the Frontend

The Calendink Provider uses a modern Svelte 5 frontend, built with Vite and TailwindCSS. The frontend is served directly from the ESP32's www_0 or www_1 LittleFS partition, allowing the user interface to be updated completely independently from the underlying firmware.

1. Prerequisites

Before you can build the frontend, make sure you have Node.js installed on your machine. All frontend code is located inside the frontend/ directory.

cd frontend
npm install

2. Development Mode

During development, you don't need to rebuild and reflash the ESP32 every time you change a button color! You can run the Vite development server on your PC, and it will proxy API requests to the ESP32 over WiFi.

1. Ensure the ESP32 is powered on and connected to your local network.
2. Update frontend/.env.development with the IP address of your ESP32 (e.g., VITE_API_BASE=http://192.168.50.216).
3. Start the dev server:

npm run dev

3. Building for Production (ESP32)

When you are ready to deploy your frontend changes to the ESP32, you must package everything into a single file and compress it. Our custom build script handles this for you.

Run the following command inside the frontend/ folder:

npm run build:esp32

What this does:

1. Runs Vite's production build.
2. Inlines all CSS and JS into index.html (thanks to vite-plugin-singlefile).
3. Runs scripts/gzip.js to heavily compress index.html down to an index.html.gz file (~15-20KB).
4. Outputs the final files to the frontend/dist/ directory.

4. Flashing the Filesystem

Now that frontend/dist/ contains your compressed web app, you must tell the ESP-IDF build system to turn that folder into a LittleFS binary image and flash it.

In your standard ESP-IDF terminal (from the project root, not the frontend/ folder):

1. Enable Web Deployment via Menuconfig (if not already done):

   idf.py menuconfig
   # Navigate to: Calendink Configuration -> Deploy Web Pages
   # Make sure it is checked (Y)
   

2. Build and Flash:

   idf.py build
   idf.py flash
   

Because CONFIG_CALENDINK_DEPLOY_WEB_PAGES is enabled, CMake will automatically:

1. Detect your frontend/dist/ folder.
2. Run mklittlefs to package it into www.bin.
3. Flash www.bin directly to the active www_0 partition on the ESP32!

5. Over-The-Air (OTA) Updates

Once the backend supports it (Phase 2+), you can update the frontend without using USB or idf.py.

1. Build the assets: npm run build:esp32
2. Package the image: npm run ota:package
   • This generates a versioned binary in frontend/bin/ (e.g., www_v1.0.5.bin).
   • Configuration: If the tool is not in your PATH, add its path to frontend/.env:

     MKLITTLEFS_PATH=C:\path\to\mklittlefs.exe
     

     (Note: The script also supports littlefs-python.exe usually found in the build/littlefs_py_venv/Scripts/ folder).
3. Upload via Dashboard:
   • Open the dashboard in your browser.
   • Go to the Frontend Update section.
   • Select the www.bin file and click Flash.
   • The device will automatically write to the inactive partition and reboot.

6. Universal OTA Bundle

For a safer and more convenient update experience, you can bundle both the Firmware and Frontend into a single file.

See the Universal OTA Bundle Guide for details.