ipfs-gateway-emulator/README.md

A server emulating IPFS gateway behaviour, for local preview and end-to-end tests

[![view on npm](https://badgen.net/npm/v/ipfs-gateway-emulator)](https://www.npmjs.org/package/ipfs-gateway-emulator)
[![npm module downloads](https://badgen.net/npm/dt/ipfs-gateway-emulator)](https://www.npmjs.org/package/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

```sh
npm install -g ipfs-gateway-emulator
```

## Usage

```sh
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:

```sh
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

```js
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](https://github.com/lwsjs/local-web-server) and inherited the whole `lws` plugin stack; this version is built directly on [Hono](https://hono.dev) 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