ESP32 Web Server using SPIFFS (SPI Flash File System)

In this tutorial we’ll show you how to build a web server that serves HTML and CSS files stored on the ESP32 filesystem. Instead of having to write the HTML and CSS text into the Arduino sketch, we’ll create separated HTML and CSS files.
For demonstration purposes, the web server we’ll build controls an ESP32 output, but it can be easily adapted for other purposes like displaying sensor readings.
Recommended reading:
ESP8266 Web Server using SPIFFS
ESP32 Filesystem Uploader Plugin
To follow this tutorial you should have the ESP32 Filesystem Uploader plugin installed in your Arduino IDE. If you haven’t, follow the next tutorial to install it first:
Install ESP32 Filesystem Uploader on Arduino IDE
Note:
make sure you have the latest Arduino IDE installed, as well as the ESP32 add-on for the Arduino IDE. If you don’t, follow one of the next tutorials to install it:
Windows
instructions – Installing the ESP32 Board in Arduino IDE
Mac and Linux
instructions – Installing the ESP32 Board in Arduino IDE
Project Overview
Before going straight to the project, it’s important to outline what our web server will do, so that it is easier to understand.
The web server you’ll build controls an LED connected to the ESP32 GPIO 2. This is the ESP32 on-board LED. You can control any other GPIO;
The web server page shows two buttons: ON and OFF – to turn GPIO 2 on and off;
The web server page also shows the current GPIO state.
The following figure shows a simplified diagram to demonstrate how everything works.
The ESP32 runs a web server code based on the
ESPAsyncWebServer library
;
The HTML and CSS files are stored on the ESP32 SPIFFS (Serial Peripheral Interface Flash File System);
When you make a request on a specific URL using your browser, the ESP32 responds with the requested files;
When you click the ON button, you are redirected to the root URL followed by
/on
and the LED is turned on;
When you click the OFF button, you are redirected to the root URL followed by
/off
and the LED is turned off;
On the web page, there is a placeholder for the GPIO state. The placeholder for the GPIO state is written directly in the HTML file between % signs, for example
%STATE%
Installing Libraries
In most of our projects we’ve created the HTML and CSS files for the web server as a String directly on the Arduino sketch. With SPIFFS, you can write the HTML and CSS in separated files and save them on the ESP32 filesystem.
One of the easiest ways to build a web server using files from the filesystem is by using the ESPAsyncWebServer library. The ESPAsyncWebServer library is well documented on its GitHub page. For more information about that library, check the following link:
https://github.com/me-no-dev/ESPAsyncWebServer
Installing the ESPAsyncWebServer library
Follow the next steps to install the
ESPAsyncWebServer
library:
Click here to download
the ESPAsyncWebServer library. You should have a .zip folder in your Downloads folder
Unzip the .zip folder and you should get ESPAsyncWebServer-master folder
Rename your folder from
ESPAsyncWebServer-master
to ESPAsyncWebServer
Move the ESPAsyncWebServer folder to your Arduino IDE installation libraries folder
Installing the Async TCP Library for ESP32
The
ESPAsyncWebServer
library requires the
AsyncTCP
library to work. Follow the next steps to install that library:
Click here to download
the AsyncTCP library. You should have a .zip folder in your Downloads folder
Unzip the .zip folder and you should get AsyncTCP-master folder
Rename your folder from
AsyncTCP-master
to AsyncTCP
Move the AsyncTCPfolder to your Arduino IDE installation libraries folder
Finally, re-open your Arduino IDE
Organizing your Files
To build the web server you need three different files. The Arduino sketch, the HTML file and the CSS file. The HTML and CSS files should be saved inside a folder called
data
inside the Arduino sketch folder, as shown below:
Creating the HTML File
The HTML for this project is very simple. We just need to create a heading for the web page, a paragraph to display the GPIO state and two buttons.
Create an
index.html
file with the following content or
download all the project files here
:
<!DOCTYPE html>
<html>
<head>
<title>ESP32 Web Server</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" href="data:,">
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body>
<h1>ESP32 Web Server</h1>
<p>GPIO state: <strong> %STATE%</strong></p>
<p><a href="/on"><button class="button">ON</button></a></p>
<p><a href="/off"><button class="button button2">OFF</button></a></p>
</body>
</html>
Because we’re using CSS and HTML in different files, we need to reference the CSS file on the HTML text. The following line should be added between the <head> </head> tags:
<link rel="stylesheet" type="text/css" href="style.css">
The <link> tag tells the HTML file that you’re using an external style sheet to format how the page looks. The
rel
attribute specifies the nature of the external file, in this case that it is a
stylesheet
—the CSS file—that will be used to alter the appearance of the page.
The
type
attribute is set to
“text/css”
to indicate that you’re using a CSS file for the styles. The
href
attribute indicates the file location; since both the CSS and HTML files will be in the same folder, you just need to reference the filename:
style.css
In the following line, we write the first heading of our web page. In this case we have “ESP32 Web Server”. You can change the heading to any text you want:
<h1>ESP32 Web Server</h1>
Then, we add a paragraph with the text “GPIO state: ” followed by the GPIO state. Because the GPIO state changes accordingly to the state of the GPIO, we can add a placeholder that will then be replaced for whatever value we set on the Arduino sketch.
To add placeholder we use
%
signs. To create a placeholder for the state, we can use
%STATE%
, for example.
<p>GPIO state: <strong>%STATE%</strong></p>
Attributing a value to the
STATE
placeholder is done in the Arduino sketch.
Then, we create an ON and an OFF buttons. When you click the on button, we redirect the web page to to root followed by
/on
url. When you click the off button you are redirected to the
/off
url.
<p><a href="/on"><button class="button">ON</button></a></p>
<p><a href="/off"><button class="button button2">OFF</button></a></p>
Creating the CSS file
Create the
style.css file
with the following content or
download all the project files here
:
html {
font-family: Helvetica;
display: inline-block;
margin: 0px auto;
text-align: center;
}
h1{
color: #0F3376;
padding: 2vh;
}
p{
font-size: 1.5rem;
}
.button {
display: inline-block;
background-color: #008CBA;
border: none;
border-radius: 4px;
color: white;
padding: 16px 40px;
text-decoration: none;
font-size: 30px;
margin: 2px;
cursor: pointer;
}
.button2 {
background-color: #f44336;
}
This is just a basic CSS file to set the font size, style and color of the buttons and align the page. We won’t explain how CSS works. A good place to learn about CSS is the
W3Schools website
Arduino Sketch
Copy the following code to the Arduino IDE or
download all the project files here
. Then, you need to type your network credentials (SSID and password) to make it work.

// Import required libraries
#include "WiFi.h"
#include "ESPAsyncWebServer.h"
#include "SPIFFS.h"

// Replace with your network credentials
const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";

// Set LED GPIO
const int ledPin = 2;
// Stores LED state
String ledState;

// Create AsyncWebServer object on port 80
AsyncWebServer server(80);

// Replaces placeholder with LED state value
String processor(const String& var){
Serial.println(var);
if(var