cowboy/guide/static_handlers.md

Static handlers

Purpose

Static handlers are a built-in REST handler for serving files. They are available as a convenience and provide fast file serving with proper cache handling.

It is recommended to use a Content Distribution Network (CDN) or at least a dedicated file server running on a dedicated cookie-less hostname for serving your application's static files in production.

Usage

Static handlers are pre-written REST handlers. They only need to be specified in the routing information with the proper options.

The following example routing serves all files found in the priv_dir/static/ directory of the application my_app.

Dispatch = [
	{'_', [
		{"/[...]", cowboy_static, [
			{directory, {priv_dir, my_app, [<<"static">>]}},
			{mimetypes, {fun mimetypes:path_to_mimes/2, default}}
		]}
	]}
].

You can also serve a single file specifically. A common example would be an index.html file to be served when the path / is requested. The following example will serve the priv/index.html file from the application my_app.

Dispatch = [
	{'_', [
		{"/", cowboy_static, [
			{directory, {priv_dir, my_app, []}},
			{file, "index.html"},
			{mimetypes, {fun mimetypes:path_to_mimes/2, default}}
		]}
	]}
].

MIME type

Cowboy does not provide any default for MIME types. This means that unless you specify the mimetypes option, all files will be sent as application/octet-stream, which the browser will not try to interpret, instead trying to make you download it.

In the examples above we used the mimetypes application to find the MIME type from the file's extension.