Write a file server

A file server listens for incoming HTTP requests and serves files from the local file system. This tutorial demonstrates how to create a simple file server using Deno's built-in file system APIs.

Write a simple File Server Jump to heading#

To start, create a new file called file-server.ts.

We'll use Deno's built in HTTP server to listen for incoming requests. In your new file-server.ts file, add the following code:

Deno.serve(
  { hostname: "localhost", port: 8080 },
  (request) => {
    const url = new URL(request.url);
    const filepath = decodeURIComponent(url.pathname);
  },
);

If you're not familiar with the URL object, you can learn more about it in the URL API documentation. The decodeURIComponent function is used to decode the URL-encoded path, in the case that characters have been percent-encoded.)

Open a file and stream its contents Jump to heading#

When a request is received, we'll attempt to open the file specified in the request URL with Deno.open.

If the requested file exists, we'll convert it into a readable stream of data with the ReadableStream API, and stream its contents to the response. We don't know how large the requested file might be, so streaming it will prevent memory issues when serving large files or multiple requests concurrently.

If the file does not exist, we'll return a "404 Not Found" response.

In the body of the request handler, below the two variables, add the following code:

try {
  const file = await Deno.open("." + filepath, { read: true });
  return new Response(file.readable);
} catch {
  return new Response("404 Not Found", { status: 404 });
}

Run the file server Jump to heading#

Run your new file server with the deno run command, allowing read access and network access:

deno run --allow-read=. --allow-net file-server.ts

Using the file server provided by the Deno Standard Library Jump to heading#

Writing a file server from scratch is a good exercise to understand how Deno's HTTP server works. However, writing production ready file server from scratch can be complex and error-prone. It's better to use a tested and reliable solution.

The Deno Standard Library provides you with a file server so that you don't have to write your own.

To use it, first install the remote script to your local file system:

# Deno 1.x
deno install --allow-net --allow-read jsr:@std/http@1/file-server
# Deno 2.x
deno install --global --allow-net --allow-read jsr:@std/http@1/file-server

This will install the script to the Deno installation root's bin directory, e.g. /home/user/.deno/bin/file-server.

You can now run the script with the simplified script name:

$ file-server .
Listening on:
- Local: http://0.0.0.0:8000

To see the complete list of options available with the file server, run file-server --help.

If you visit http://0.0.0.0:8000/ in your web browser you will see the contents of your local directory.

Using the @std/http file server in a Deno project Jump to heading#

To use the file-server in a Deno project, you can add it to your deno.json file with:

deno add jsr:@std/http

And then import it in your project:

import { serveDir } from "@std/http/file-server";

Deno.serve((req) => {
  const pathname = new URL(req.url).pathname;
  if (pathname.startsWith("/static")) {
    return serveDir(req, {
      fsRoot: "path/to/static/files/dir",
    });
  }
  return new Response();
});

This code will set up an HTTP server with Deno.serve. When a request comes in, it checks if the requested path starts with “/static”. If so, it serves files from the specified directory. Otherwise, it responds with an empty response.

🦕 Now you know how to write your own simple file server, and how to use the file-server utility provided by the Deno Standard Library. You're equipped to tackle a whole variety of tasks - whether it’s serving static files, handling uploads, transforming data, or managing access control - you're ready to serve files with Deno.