Filen Public Express

Serve static files publicly via filen.io buckets

   

🔗 Table of Contents

• 📍 Overview
• 👾 Features
• 🚀 Getting Started
  • ☑️ Prerequisites
  • ⚙️ Installation
  • 🤖 Usage
• 🔧 Configuration
  • config Options
  • corsOptions
  • .filen-public.json Configuration
• ⌨️ Examples
• 🛠️ Troubleshooting
• ❕ Disclaimer
• 🎗 License
• 🙌 Acknowledgments

📍 Overview

A lightweight, unofficial static file server powered by the Filen.io SDK. Designed for public, read-only access to files such as images, PDFs, and videos.

👾 Features

• Serve files from either all public buckets — or via one specific master bucket¹
• Supports server-wide CORS configuration, and JSON CORS configurations²³ inside each bucket - mimics AWS S3 CORS configuration structure (example)
• Supports file downloads⁴ via search parameters in GET requests (e.g. .../file.jpg?dl=1)
• Supports file ignores⁵ (e.g. ["secret.json", { endsWith: ".key" }])

🚀 Getting Started

☑️ Prerequisites

Node.js version:

• Minimum: v22.6.0
• Preferred: v23.7.0

⚙️ Installation

In your project, install using NPM:

npm install filen-public-express

🤖 Usage

1. Create a bucket on Filen.io starting with public_ (e.g. public_myimages)
2. Initialize the server:

import { FilenPublicExpress } from "filen-public-express";

const server = new FilenPublicExpress({
  user: {
    sdkConfig: {
      email: "[email protected]",
      password: "yourfilenpassword"
    }
  }
});

await server.start();

3. Start the server:

node server.js

You should now be able to access the files in your public buckets in your browser. (e.g. http://localhost:1700/myimages/mydog.jpg)

Note

Only files in public buckets (with public_ prefix) can be accessed. (e.g. public_myimages) The prefix is omitted in the URL pathname.

🔧 Configuration

config Options

Option	Type	Default	Description
downloadFileParam	string | null | undefined | false	"dl"	4Used as query param (e.g. .../file.pdf?dl=1) that allows downloading files instead of displaying them inline
masterBucket	string | undefined	-	1Name of the singular bucket that the server will expose publicly (setting this value will remove the ability for the server to expose other buckets)
ignoreList	IgnoreRule[]	-	5List of ignore rules for files/keys (e.g. ["secret.json", { endsWith: ".key" }])
corsBucketFileName	string | undefined	.filen-public.json	2Name for individual JSON CORS configurations inside the bucket
corsBucketCacheTTLMinutes	number | undefined	10	Cache duration for CORS configurations
corsBucketCachePurgeUrl	string | undefined	-	URL to purge CORS cache (e.g. "/purge-cors-cache")
expressTrustProxy	boolean | number | string | string[]	false	Express.js trust proxy setting

corsOptions

Option	Type	Default	Description
methods	"GET"	"GET"	Only GET method is supported
origin	string | string[]	"*"	Allowed Origins/Referers

.filen-public.json Configuration

³Place this file inside your bucket to configure CORS settings:

[
  {
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["https://example.com"]
  }
]

Important

Must be an array, only "GET" method supported, origin "*" is used to allow all. Mimics AWS S3 CORS configuration structure.

⌨️ Examples

Examples can be found in the examples folder.

🛠️ Troubleshooting

.mp4 not playing inline/directly on iPhone/iPad browsers when using Cloudflare CDN

If you're serving .mp4 files through Cloudflare and they are not playing inline in iOS browsers, this is likely due to Cloudflare's caching or compression settings. Follow these steps to bypass .mp4 Cloudflare cache for User Agents that include iPhone/iPad:

1. Go to Caching > Cache Rules.
2. Add the following condition:

(http.request.uri.path.extension in {"mp4"}) and (http.user_agent contains "iPad" or http.user_agent contains "iPhone" or http.user_agent contains "Macintosh")

3. Set the action to "Bypass cache".

(visual config example)

❕ Disclaimer

This project is not affiliated with or endorsed by Filen.io. It is provided as is, without any warranties or guarantees. The author assumes no responsibility for any issues, including but not limited to data privacy, security risks, or legal compliance arising from the use of this software. Use at your own risk.

🎗 License

Distributed under the AGPL-3.0 License. See LICENSE for more information.

🙌 Acknowledgments

This project:

• Uses filen-sdk-ts - The official Filen.io TypeScript SDK
• Incorporates code from filen-s3