File

Server Source code Package

Serves static files from a store 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

npm install @walkeros/server-transformer-file

Integrated

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' },
  },
},
});

Bundled

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 | CLI reference

Configuration

This transformer uses the standard transformer config wrapper (consent, data, env, id, ...). For the shared fields see transformer configuration. Package-specific fields live under config.settings and are listed below.

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

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

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

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

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

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

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

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

• Cache - Add response caching before file serving (integrated collector mode)
• Stores - Configure store backends
• Docker: including files - Bake files into Docker images