ipfs-gateway-emulator

ipfs-gateway-emulator

Serves a directory the way an IPFS path gateway does, so that "works locally, breaks on IPFS" problems show up before you deploy.

A path gateway serves your site under /ipfs/<cid>/ rather than /. That difference breaks things a plain static server will happily let through:

• the /ipfs/<cid> prefix is invisible to your app, so it has to be stripped before a file is looked up
• a root-relative URL such as /app.js escapes the CID root and 404s, even though it works fine when the same site is served from /
• a directory has to redirect to a trailing slash, or relative URLs inside the page resolve against the wrong base

This tool reproduces all three locally, which makes it useful both for previewing a build and as the server behind an end-to-end test suite.

Install

npm install -g ipfs-gateway-emulator

Usage

ipfs-emulator -d build -p 8080

Then open either address; both serve the same directory:

• http://127.0.0.1:8080/ behaves like a normal static host
• http://127.0.0.1:8080/ipfs/<cid>/ behaves like a path gateway

The <cid> is not validated and nothing is fetched from IPFS. Any placeholder works, because the point is to reproduce the shape of gateway URLs.

Options

Option	Description
-d, --directory <path>	Directory to serve. Defaults to the current directory.
-p, --port <number>	Port to listen on. Defaults to 8080.
--only [root|hash]	Serve only one addressing scheme. hash serves only /ipfs/<cid>/...; any other value serves only root paths. Passing the flag with no value serves both.
--fail <status>:<dirs>	Make comma-separated directories fail with the given status, to exercise client error handling. For example --fail 503:api.
-h, --help	Print help.
-v, --version	Print the version.

Catching the root-relative trap

The most valuable behaviour is the referer check. A page served from /ipfs/<cid>/ that requests /app.css gets a 404, because on a real gateway that URL points outside the CID root:

curl -H 'referer: http://127.0.0.1:8080/ipfs/<cid>/' http://127.0.0.1:8080/app.css
# 404 Not Found (referer)

If your build works from / but 404s here, it is emitting root-relative URLs and will break on a real path gateway. Emit relative URLs instead.

Programmatic use

import {createApp, startServer} from 'ipfs-gateway-emulator';

// A running server
const server = startServer({directory: 'build', port: 8080});

// Or a plain fetch handler, useful in tests, with no port bound
const app = createApp({directory: 'build'});
const response = await app.request('/ipfs/<cid>/index.html');

The path helpers are exported too (stripIpfsPrefix, routeRequest, parseFailSpec, matchesFailFolder, needsTrailingSlash) if you want to assert on the routing rules directly.

Notes

Version 5 is a rewrite. Earlier versions were a fork of local-web-server and inherited the whole lws plugin stack; this version is built directly on Hono and depends only on hono and @hono/node-server.

That means the lws middleware options (--stack, basic auth, blacklist, compression, rewriting, logging, and so on) are gone. If you relied on those, stay on 4.x or use local-web-server itself, which is what they belong to. What remains is the part this package exists for: emulating a gateway.

License

MIT