Free and simple Directory Listing with Vercel

Yik San Chan, webguide

What is directory listing, and why

Directories provide a natural way of organizing files. For example, in order to store course materials (mostly PDF) from 2 open courses in my local filesystem, I organize them using the directory hierarchy as shown below.

Local listing

What if we want to host the directory on the web for easier access and reference? Say you are away from your laptop but want to check the course materials real quick on your phone, or you are writing a blog post and want to reference some lecture slides using a URL.

Directory listing comes to the rescue. Basically, it allows you to put your directories on the web, and grants you access to your files via some URLs. At the end of the post, you will be able to use the URL to browse your directory like this:

Vercel listing

Directory listing solutions

There are multiple ways of doing this. I will comment on each of them based on these criteria:

File storage service: Google Drive and friends

Google Drive, Dropbox, AliyunDrive (阿里云盘) are popular file storage services that focus on UI (compared to API) users. After uploading your directory to the cloud, you can easily turn the resource into a publicly accessible URL. Note that it usually comes with built-in access control so that you can choose to share the resources with only a certain group of people.

GDrive get link

Users with the URL and the right permission can access your directory on the web,

GDrive listing

preview or download the PDF.

GDrive preview

According to our criteria:

Code hosting service: GitHub and friends

GitHub and GitLab host and version-control your code, but people do sometimes store non-code content (including PDF files) on the sites. Sharing the files to the public is nothing more than pushing your files to a public repository. An example can be found at

GitHub preview

According to our criteria:

Self hosting

Host a simple web app that serve static files on a HTTP server that you control. An example can be found at

Self-hosting listing

This approach is straightforward if you know how to run your own HTTP server, but that requires a good amount of knowledge and practice. You may need:

According to our criteria:


Vercel helps you to build the Next Web. It allows you to deploy your JS apps to Vercel's global CDN for free by simply pushing to GitHub. An example can be found at As you can see, it is exactly what we're looking for: a directory on the web.

Vercel listing

According to our criteria:


In summary, Vercel wins.

SolutionsFreeSimpleURL friendlyBrowsable
File storage service〰️
Code hosting service〰️〰️
Self hosting

I will walk through "how" in the following section.

Directory listing with Vercel

Step 1: In the project root directory, create a directory (I call it _serve, you can pick whatever name you like) and put all the files you want to serve in that directory. Also, run git init to version control the root directory.

|____ .git
|____ _serve
| |____open-courses
| | |____cmu15445_fa2020
| | | |____...
| | |____ucbcs186_fa2020
| | | |____05b-tree-indexes.pdf
| | | |____14-transactions-1.pdf
| | | |____09-sort-hash.pdf
| | | |____20-parallel-1.pdf
| | | |____...

Step 2: Run locally with serve by running npx serve _serve. See vercel/serve for more details. Then go to [localhost:5000](http://localhost:5000) and you should be able to see:

Local vercel root

Step 3: Run git push in the root directory to GitHub, and connect Vercel with your GitHub project. In my case, my GitHub project is named "fileserve", therefore the Vercel project is also called "fileserve". See the fileserve GitHub project.

Step 4: In Vercel dashboard, click into the fileserve project, go to Settings, and set Root Directory as "_serve". You need to input the directory name you gave.

Vercel settings root directory

Step 5: Still in Settings, toggle Directory Listing to "Enabled".

Vercel settings directory listing

Step 6: Go to the deployment URL and find the slides as I show in the beginning at All set!


Try Vercel! It provides a free and simple directory listing solution, that gives you friendly URLs and browsable PDFs!

© Yik San Chan. Built with Vercel and Nextra.