> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# File

<!-- -->

[Server](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/server/transformers/file)

<!-- -->

[Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/transformers/file)[ ](https://www.npmjs.com/package/@walkeros/server-transformer-file)

<!-- -->

[Package](https://www.npmjs.com/package/@walkeros/server-transformer-file)

Serves static files from a [store](https://www.walkeros.io/docs/stores.md) backend. Reads the file by `ingest.path`, derives the Content-Type from the file extension, and responds directly. Returns `false` to stop the transformer chain so no further transformers or destinations run for the request.

## Installation[​](#installation "Direct link to Installation")

```
npm install @walkeros/server-transformer-file
```

* Integrated
* Bundled

```
import { startFlow } from '@walkeros/collector';
import { transformerFile } from '@walkeros/server-transformer-file';
import { storeFsInit } from '@walkeros/server-store-fs';

await startFlow({
  stores: {
    files: {
      code: storeFsInit,
      config: { settings: { basePath: './public' } },
    },
  },
  transformers: {
    file: {
      code: transformerFile,
      config: {
        settings: { prefix: '/static' },
      },
      env: { store: '$store.files' },
    },
  },
});
```

Add to your `flow.json`:

```
"stores": {
  "files": {
    "package": "@walkeros/server-store-fs",
    "config": { "settings": { "basePath": "./public" } }
  }
},
"transformers": {
  "file": {
    "package": "@walkeros/server-transformer-file",
    "config": { "settings": { "prefix": "/static" } },
    "env": { "store": "$store.files" }
  }
}
```

[See bundled mode setup](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This <!-- -->transformer<!-- --> uses the standard <!-- -->transformer<!-- --> config wrapper (consent, data, env, id, ...). For the shared fields see [transformer<!-- --> configuration](https://www.walkeros.io/docs/transformers.md#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property    | Type                     | Description                                                                                       | More |
| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------- | ---- |
| `prefix`    | `string`                 | URL prefix to strip before store lookup. E.g., "/static" → /static/walker.js looks up "walker.js" |      |
| `headers`   | `Record<string, string>` | Default response headers (e.g., Cache-Control, X-Frame-Options)                                   |      |
| `mimeTypes` | `Record<string, string>` | Extension → Content-Type overrides. Keys include dot: { ".wasm": "application/wasm" }             |      |

## Mapping[​](#mapping "Direct link to Mapping")

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

## Examples

### Serve static file

Serve a static JavaScript file from store. Config: prefix: "/static", headers: { "Cache-Control": "public, max-age=3600" }

Event

```
{
  "name": "page view",
  "data": {
    "path": "/static/walker.js"
  },
  "id": "ev-1700000600",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000600,
  "source": {
    "type": "express",
    "platform": "server"
  }
}
```

Out

```
respond({
  "status": 200,
  "headers": {
    "Content-Type": "application/javascript",
    "Cache-Control": "public, max-age=3600"
  }
})
```

## How it works[​](#how-it-works "Direct link to How it works")

1. Reads `ingest.path` from the request context
2. Strips the configured `prefix` (if set), e.g. `/static/image.png` becomes `image.png`
3. Looks up the remaining path in the store via `store.get(key)`
4. If found, derives the Content-Type from the file extension and responds with the content
5. Returns `false` to stop the chain. No further transformers or destinations run.
6. If the file is not found or the path doesn't match the prefix, the event passes through unchanged

## Environment[​](#environment "Direct link to Environment")

| Key     | Type             | Required | Description                                                                          |
| ------- | ---------------- | -------- | ------------------------------------------------------------------------------------ |
| `store` | `Store.Instance` | Yes      | Store providing file content. Without one, the transformer warns and passes through. |

## Cache and file chain[​](#cache-and-file-chain "Direct link to Cache and file chain")

Use native cache on the file transformer to serve cached files from memory, avoiding repeated store reads:

```
"sources": {
  "http": {
    "package": "@walkeros/server-source-express",
    "next": [
      {
        "match": { "key": "ingest.method", "operator": "eq", "value": "GET" },
        "next": "file"
      }
    ]
  }
},
"transformers": {
  "file": {
    "package": "@walkeros/server-transformer-file",
    "config": { "settings": { "prefix": "/static" } },
    "env": { "store": "$store.files" },
    "cache": {
      "rules": [
        { "match": "*", "key": ["ingest.method", "ingest.path"], "ttl": 300 }
      ]
    }
  }
}
```

## Custom MIME types[​](#custom-mime-types "Direct link to Custom MIME types")

```
{
  settings: {
    mimeTypes: {
      '.wasm': 'application/wasm',
      '.mjs': 'application/javascript',
    },
  },
}
```

## Behavior notes[​](#behavior-notes "Direct link to Behavior notes")

* **Requires a store**: without `env.store`, every request logs a warning and passes through
* **Prefix matching**: if `prefix` is set and the path doesn't start with it, the event passes through (not an error)
* **Returns `false`**: a served file stops the chain; no destinations receive the event
* **Content-Length**: automatically set for string and Buffer content

## Next steps[​](#next-steps "Direct link to Next steps")

* **[Cache](https://www.walkeros.io/docs/collector/cache.md)** - Add response caching before file serving (integrated collector mode)
* **[Stores](https://www.walkeros.io/docs/stores.md)** - Configure store backends
* **[Docker: including files](https://www.walkeros.io/docs/apps/docker.md#including-files)** - Bake files into Docker images