# file-fetch

> fetch for read and write access to the local file system

Latest version **2.0.1** (published 2025-04-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install file-fetch
pnpm add file-fetch
yarn add file-fetch
bun add file-fetch
```

## Health

**Score 53/100 (C)** — status: stable.

Positive: has types package; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2025-04-04 |
| First published | 2017-10-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/file-fetch) |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 24.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Thomas Bergwinkl |
| Maintainers | bergos |
| Keywords | fetch, readable, stream, file, fs |

## Links

- npm: https://www.npmjs.com/package/file-fetch
- Repository: https://github.com/bergos/file-fetch
- Issues: https://github.com/bergos/file-fetch/issues
- npm.io page: https://npm.io/package/file-fetch

## Dependencies (3)

- [mime-types](https://npm.io/package/mime-types.md) ^3.0.1
- [stream-chunks](https://npm.io/package/stream-chunks.md) ^1.0.0
- [readable-stream](https://npm.io/package/readable-stream.md) ^4.4.2

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 2.0.1 (latest) — 2025-04-04
- 2.0.0 — 2023-11-19
- 1.7.0 — 2021-06-09
- 1.6.1 — 2021-05-31
- 1.6.0 — 2021-05-10
- 1.5.0 — 2021-01-18
- 1.4.1 — 2020-01-03
- 1.4.0 — 2020-01-02
- 1.3.1 — 2019-11-27
- 1.3.0 — 2019-11-12
- 1.2.0 — 2019-03-27
- 1.1.1 — 2017-11-30
- 1.1.0 — 2017-10-23
- 1.0.1 — 2017-10-21
- 1.0.0 — 2017-10-18

## README

# file-fetch

[![build status](https://img.shields.io/github/actions/workflow/status/bergos/file-fetch/test.yaml?branch=master)](https://github.com/bergos/file-fetch/actions/workflows/test.yaml)
[![npm version](https://img.shields.io/npm/v/file-fetch.svg)](https://www.npmjs.com/package/file-fetch)

`file-fetch` is a [nodeify-fetch](https://www.npmjs.com/package/nodeify-fetch) compatible fetch for read and write access to the local file system using `file:` URLs and URIs (including
implicit ones using relative paths).

## Usage

### Read

Reading a file from the file system is as easy as fetching it on the Web.
Call `fetch` with the URL, and the content is provided as `Readable` stream in `res.body`.
The example below uses an absolute URL, but relative paths are also supported.
See the [Supported URLs and URIs](#supported-urls-and-uris) section for more details.

```js
import fetch from 'file-fetch'

const res = await fetch(new URL('example.js', import.meta.url))

res.body.pipe(process.stdout)
```

It's also possible to handle the content without streams.
The async `res.text()` method returns the whole content as a string.

```js
import fetch from 'file-fetch'

const res = await fetch(new URL('example.js', import.meta.url))

console.log(await res.text())
```

A similar method `res.json()` is available to parse JSON content and return the parsed result.

```js
import fetch from 'file-fetch'

const res = await fetch(new URL('example.js', import.meta.url))

console.log(await res.json())
```

### Write

Writing content to a file is done with the same function but with the `PUT` method.
The content must be provided as a `string` or a `Readable` stream object.

```js
import fetch from 'file-fetch'

await fetch('file:///tmp/example.log', {
  method: 'PUT',
  body: 'test'
})
```

```js
import fetch from 'file-fetch'
import { Readable } from 'readable-stream'

await fetch('file:///tmp/example.log', {
  method: 'PUT',
  body: Readable.from(['test'])
})
```

## Options

`file-fetch` supports the following non-standard options:

- `baseURL`: A `string` or `URL` used to resolve relative paths and URIs.
- `contentType`: A `string` or `function` to determine the media type based on the file extension or a fixed value.
  It can be useful if file extensions or media types not covered by [mime-db](https://www.npmjs.com/package/mime-db) are required.

## Custom fetch with fixed baseURL or contentType lookup

Custom fetch instances can be useful if requests should be processed with relative paths to a directory that is not the current working directory.
The `contentType` argument can also be predefined for the instance.
The example below shows how to set the `baseURL` to a relative path of the current script and how to use a custom `contentType` function: 

```js
import { factory as fetchFactory } from 'file-fetch'

const baseURL = new URL('examples', import.meta.url)
const contentType = ext => ext === 'json' ? 'application/ld+json' : 'application/octet-stream'

const fetch = fetchFactory({ baseURL, contentType })

const res = await fetch('example.js')
const text = await res.text()
```

## Supported URLs and URIs

Different styles of URLs and URIs are supported.

### Absolute URLs

An absolute URL for a `file` schema must start with `file:///`.
No further resolve logic is used.

Example:

```
file:///home/user/tmp/content.txt
```

### URIs

URIs are supported for use cases where a `file` scheme is required to distinguish identifiers by scheme and if relative paths are required.
The [relative paths](#relative-paths) logic is used to resolve the full URL.

Example:

```
file:tmp/content.txt
```

### Relative paths

Relative paths are resolved with the given `baseURL` or, if not given, with the working directory.

Example:

```
tmp/content.txt
```

---
_Source: https://npm.io/package/file-fetch · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._