Skip to content

force-download.md

Latest commit

 

History

History
94 lines (70 loc) · 3.14 KB

force-download.md

File metadata and controls

94 lines (70 loc) · 3.14 KB
Raw

Force Download Extensions

The --force-download-extensions flag allows you to specify file extensions or exact filenames that should always be downloaded when accessed through the server, rather than being displayed in the browser.

Usage

You can specify multiple extensions or filenames in one of these ways:

  1. Comma-separated list:
# Simple extensions
http-server --force-download-extensions jpg,pdf,zip

# Compound extensions
http-server --force-download-extensions min.js,min.css

# Exact filenames (case-insensitive)
http-server --force-download-extensions Dockerfile,.env
  1. Multiple flag occurrences:
http-server --force-download-extensions jpg --force-download-extensions min.js
  1. In a configuration file (.http-server.yaml):
force-download-extensions:
  - jpg
  - min.js
  - Dockerfile
  - .env
  1. As environment variables:
export FILE_SERVER_FORCE_DOWNLOAD_EXTENSIONS="jpg,min.js,Dockerfile,.env"

How it works

When a client requests a file, the server checks if the file's extension or full filename matches any in the force download list (--force-download-extensions). If a match is found, the server adds a Content-Disposition: attachment; filename="filename.ext" header to the response. This tells the browser to download the file rather than attempting to display it.

Supported patterns

  • Simple extensions: .jpg, .pdf, .zip

    • Matches any file with that extension (case-insensitive)
    • Example: image.jpg, document.PDF

  • Compound extensions: .min.js, .bundle.css

    • Matches the exact extension sequence (case-insensitive)
    • Example: app.min.js, styles.MIN.CSS

  • Exact filenames: Dockerfile, .env

    • Matches files with exactly the same name (case-insensitive)
    • Example: Dockerfile, .env, dockerfile

Use cases

  • Force download of image files instead of displaying them in the browser
  • Ensure PDF documents are saved locally rather than opened in the browser
  • Handle minified or bundled assets with compound extensions
  • Control download behavior for files without extensions like Dockerfile

Limitations

  • Markdown in directory listing: When using the directory listing feature, Markdown files (like README.md) that are rendered as part of the page won't be affected by this flag, since they're processed before the file serving logic is applied.
  • Direct markdown links: If a user directly accesses a Markdown file and the directory listing is enabled, then Markdown files will not be force downloaded.
  • Case sensitivity: All matches are case-insensitive for consistency across different operating systems.

Examples

  1. Force download of common media files:

    http-server --force-download-extensions jpg,png,gif,mp4,pdf

  2. Handle minified JavaScript and CSS:

    http-server --force-download-extensions min.js,min.css

  3. Force download CSS files but exclude specific ones:

    http-server --force-download-extensions css --skip-force-download-files styles.css,themes/dark.css

  4. Complex configuration in YAML:

    force-download-extensions:
  - css
  - js
  - png