Static Files#
Static files are served by the app from predefined locations. To configure static file serving, either pass an
instance of StaticFilesConfig
or a list
thereof to Litestar
using the static_files_config
kwarg.
For example, lets say our Litestar app is going to serve regular files from the my_app/static
folder and html
documents from the my_app/html
folder, and we would like to serve the static files on the /files
path,
and the html files on the /html
path:
from litestar import Litestar
from litestar.static_files.config import StaticFilesConfig
app = Litestar(
route_handlers=[...],
static_files_config=[
StaticFilesConfig(directories=["static"], path="/files"),
StaticFilesConfig(directories=["html"], path="/html", html_mode=True),
],
)
Matching is done based on filename, for example, assume we have a request that is trying to retrieve the path
/files/file.txt
, the directory for the base path /files
will be searched for the file file.txt
. If it is
found, the file will be sent, otherwise a 404 response will be sent.
If html_mode
is enabled and no specific file is requested, the application will fall back to serving index.html
. If
no file is found the application will look for a 404.html
file in order to render a response, otherwise a 404
NotFoundException
will be returned.
You can provide a name
parameter to StaticFilesConfig
to identify the given config and generate links to files in
folders belonging to that config. name
should be a unique string across all static configs and
Route handlers.
from litestar import Litestar
from litestar.static_files.config import StaticFilesConfig
app = Litestar(
route_handlers=[...],
static_files_config=[
StaticFilesConfig(
directories=["static"], path="/some_folder/static/path", name="static"
),
],
)
url_path = app.url_for_static_asset("static", "file.pdf")
# /some_folder/static/path/file.pdf
Sending files as attachments#
By default, files are sent “inline”, meaning they will have a Content-Disposition: inline
header.
To send them as attachments, use the send_as_attachment=True
flag, which will add a
Content-Disposition: attachment
header:
from litestar import Litestar
from litestar.static_files.config import StaticFilesConfig
app = Litestar(
route_handlers=[...],
static_files_config=[
StaticFilesConfig(
directories=["static"],
path="/some_folder/static/path",
name="static",
send_as_attachment=True,
),
],
)
File System support and Cloud Files#
The StaticFilesConfig
class accepts a value called file_system
,
which can be any class adhering to the Litestar FileSystemProtocol
.
This protocol is similar to the file systems defined by fsspec,
which cover all major cloud providers and a wide range of other use cases (e.g. HTTP based file service, ftp
, etc.).
In order to use any file system, simply use fsspec or one of
the libraries based upon it, or provide a custom implementation adhering to the
FileSystemProtocol
.