# @flowfuse/file-server

> A basic Object Storage backend

Latest version **3.0.2** (published 2026-09-09) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @flowfuse/file-server
pnpm add @flowfuse/file-server
yarn add @flowfuse/file-server
bun add @flowfuse/file-server
```

Provides the command `ff-file-storage`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2026-09-09 |
| First published | 2023-11-28 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=24.x |
| Dependencies | 15 |
| Unpacked size | 83.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | FlowFuse Inc. |
| Maintainers | hardillb, knolleary, flowfuse-user |
| Keywords | flowfuse, object-store |

## Links

- npm: https://www.npmjs.com/package/@flowfuse/file-server
- Repository: https://github.com/FlowFuse/file-server
- Homepage: https://github.com/FlowFuse/file-server#readme
- Issues: https://github.com/FlowFuse/file-server/issues
- npm.io page: https://npm.io/package/@flowfuse/file-server

## Dependencies (15)

- [pg](https://npm.io/package/pg.md) ^8.11.2
- [got](https://npm.io/package/got.md) ^11.8.6
- [pino](https://npm.io/package/pino.md) ^8.15.1
- [yaml](https://npm.io/package/yaml.md) ^2.1.3
- [semver](https://npm.io/package/semver.md) ^7.5.4
- [fastify](https://npm.io/package/fastify.md) ^5.6.2
- [sqlite3](https://npm.io/package/sqlite3.md) ^6.0.1
- [sequelize](https://npm.io/package/sequelize.md) ^6.33.0
- [pino-pretty](https://npm.io/package/pino-pretty.md) ^10.2.0
- [@node-red/util](https://npm.io/package/@node-red/util.md) ^5.0.4
- [fastify-plugin](https://npm.io/package/fastify-plugin.md) ^5.1.0
- [@fastify/helmet](https://npm.io/package/@fastify/helmet.md) ^13.0.2
- [fastify-metrics](https://npm.io/package/fastify-metrics.md) ^12.1.0
- [@aws-sdk/client-s3](https://npm.io/package/@aws-sdk/client-s3.md) ^3.388.0
- [fastify-healthcheck](https://npm.io/package/fastify-healthcheck.md) ^5.1.0

## Recent versions

- 3.0.2 (latest) — 2026-09-09
- 3.0.3-15c2dc4-202609111055.0 (nightly) — 2026-09-11
- 3.0.3-ff0ba22-202609110916.0 — 2026-09-11
- 3.0.3-a724b5c-202609110910.0 — 2026-09-11
- 3.0.3-92a857b-202609110902.0 — 2026-09-11
- 3.0.3-d3741b0-202609110901.0 — 2026-09-11
- 3.0.3-acec240-202609090855.0 — 2026-09-09
- 3.0.2-ae321c9-202609090854.0 — 2026-09-09
- 3.0.2-c22ec53-202609021017.0 — 2026-09-02
- 3.0.1 — 2026-09-02
- 3.0.1-39e32e1-202608271317.0 — 2026-08-27
- 3.0.0 — 2026-08-27
- 2.33.3-b60d95f-202608241436.0 — 2026-08-24
- 2.33.3-6623e55-202608121503.0 — 2026-08-12
- 2.33.3-68e988a-202608120800.0 — 2026-08-12
- … 239 more at https://npm.io/package/@flowfuse/file-server/versions

## README

# A Basic Object Store for use with FlowFuse

## Authorisation

All requests should include a `Authorization` header with a Bearer token assigned by the FlowFuse platform to identify
## End Points

### File Storage

- Create/Replace

    **POST** */v1/files/:teamId/:projectId/[path and filename]*

    Content-Type: application/octet-stream

- Append

    **POST** */v1/files/:teamId/:projectId/[path and filename]*

    With Header `FF_MODE: append`

    Content-Type: application/octet-stream
- Read File

    **GET** */v1/files/:teamId/:projectId/[path and filename]*

    Content-Type: application/octet-stream

- Delete File

    **DELETE** */v1/files/:teamId/:projectId/[path and filename]*

- Check team quota usage

    **GET** */v1/quota/:teamId*

    Content-Type: application/json

### Context Store

- Set stored values

    **POST** */v1/context/:projectId/:scope*

    Content-Type: application/json

    Body:
    ```json
    [
        { "key": "x", "value": { "foo": "bar" } },
        { "key": "y.y", "value": 100 },
    ]
    ```

- Get stored values

    **GET** */v1/context/:projectId/:scope?key=x[&key=y.y]*

    Content-Type: application/json

    Response:
    ```json
    [
        { "key": "x", "value": { "foo": "bar" } },
        { "key": "y.y", "value": 100 }
    ]
    ```

- Get keys for a scope

    **GET** */v1/context/:projectId/:scope/keys*

    Content-Type: application/json

    Response:
    ```json
    [
        "x",
        "y"
    ]
    ```

- Delete scope

    **DELETE** */v1/context/:projectId/:scope*

- Clean unused scopes from the store

    **POST** */v1/context/:projectId/clean*

    Content-Type: application/json

    Body:
    ```json
    [
        "nodeId", "flowId"
    ]
    ```

## Configuration

Configuration is read from `etc/flowforge-storage.yml`

```yaml
host: 0.0.0.0
port: 3001
base_url: http://flowforge:3000
driver:
  type: localfs
  options:
    root: var/root
telemetry:
  backend:
    prometheus:
      enabled: true
```

- base_url - Where to reach the core FlowForge platform
- driver
    - type - can be `s3`, `localfs` or `memory` (for testing)
    - options - will vary by driver
- telemetry
    - backend
         - prometheus
             - enabled - turns on the `/metrics` endpoint to track resource usage

### File Storage
#### S3

The following can be any of the options for the S3Client Contructor, see [here](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/interfaces/s3clientconfig.html)

- options
    - bucket - name of S3 Bucket (required)
    - region - AWS Region
    - endpoint - S3 ObjectStore Endpoint (if not using AWS S3)
    - forcePathStyle: true/false
    - credential
        - accessKeyId - AccountID/Username
        - secretAccessKey - SecretKey/Password

```yaml
host: '0.0.0.0'
port: 3001
base_url: http://forge.default
driver:
  type: s3
  options:
    bucket: flowforge-files
    credentials:
      accessKeyId: XXXXXXXXXXXXXXXXXXX
      secretAccessKey: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
    forcePathStyle: true
    region: us-east-1
```

#### LocalFS

- options
    - root - path to store team files, relative path will apply to FLOWFORGE_HOME

#### Memory

This driver is purely to make testing easier, it has no configuration
options.

### Context Storage

#### Database

This driver can use either PostgreSQL or SQLite to hold context values.

To use with PostgreSQL configure as follows:

```yaml
context:
  type: db
  options:
    type: postgres
    host: 127.0.0.1
    port: 5432
    ssl: true
    database: ff-context
    username: user
    password: password
```

To use with SQLite configure as follows:

```yaml
context:
  type: db
  options:
    type: sqlite
    storage: ff-context.db
```

Where `context.options.storage` is the filename of the SQLite database, by default it will be written to 
the `var` directory if a fully qualified path is not provided.

### Environment variables

- FLOWFORGE_HOME default `/opt/flowforge-file-storage`
- PORT overrides value in config file, default 3001

## Development

### Testing

```bash
npm run test
```

NOTE: This will run all tests for all backends and requires a running postgres database

To prepare postgres for the tests, use the following procedure (tested on Linux and WSL2 ubuntu + docker)...

```bash
docker run --rm --name postgres -e POSTGRES_PASSWORD=secret -e POSTGRES_USER=postgres -p 5432:5432 postgres:14
```


### Testing (without postgres)

```
npm run test:nopg
```

Alternatively, you can set env variable TEST_POSTGRES=false
```
export TEST_POSTGRES=false
npm run test
```

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