← Back to Blog
nodejsengineeringvfsdeveloper

Could Node.js VFS Turn a Postal Code API Into a Single Executable?

The PostalDataPI Team··4 min read

Matteo Collina just opened a 14,000-line PR to add a virtual filesystem to Node.js core. The node:vfs module lets you write files to memory and have them be fully accessible through fs, import(), and require() — not as a mock, but as a real part of the module resolver.

We build PostalDataPI, a postal code API covering 70+ countries. Our data layer loads 261 compressed JSON files (~71 MB) into memory at startup. When we saw the VFS proposal, one question jumped out: could we ship the entire API as a single executable?

What Node.js VFS Actually Does

Today, if you generate JavaScript at runtime — say, from an AI agent or a plugin system — you write it to a temp file and import() it. Messy. With VFS:

import { create } from '@platformatic/vfs'

const vfs = create()
vfs.writeFileSync('/handler.mjs', generatedCode)
vfs.mount('/generated')


const { default: handler } = await import('/generated/handler.mjs')

No temp files. No cleanup. The code lives in memory and the module resolver finds it like any real file.

The key insight: VFS hooks into Node.js below the public API surface. Third-party code that calls fs.readFileSync() gets VFS content transparently. Express serving static files from a VFS mount just works.

The Single Executable Angle

Node.js already supports Single Executable Applications (SEA) — you can embed a blob of data into the Node.js binary. But accessing that data has always been awkward. Your application calls fs.readFileSync() expecting real paths, so you end up writing glue code.

VFS changes this. The SEAProvider automatically mounts embedded assets so they're accessible through standard fs calls. Your application code doesn't need to know it's running as an SEA.

For PostalDataPI, that could mean:

  • Bundle the API server + all 261 country data files into a single binary
  • User downloads one file
  • User runs it
  • Local postal code API on localhost, no installation, no dependencies

    • No Node.js. No npm. No configuration. Just a binary that speaks HTTP.

    Why This Is Interesting for API Products

    Most API products are cloud-only. You sign up, get a key, and call endpoints. That model works well — it's how PostalDataPI works today, and sub-10ms responses from our hosted API are hard to beat.

    But some use cases want local:

    • Air-gapped environments — government, defense, compliance-heavy industries
    • Edge deployment — IoT, embedded systems, CDN workers
    • Privacy requirements — postal code lookups that never leave the building
    • Development — a local API for testing without network calls or API key management
    A single executable postal code API serves all of these. Download 80 MB, run it, query localhost. Same API contract, same response format, works offline.

    What We're Exploring

    We haven't built this yet. The VFS module is experimental and the PR is still in review. But the pieces are aligning:

    • @platformatic/vfs is available today on npm for Node.js 22+
    • Node.js SEA is stable and supports embedded assets
    • Our data files are already compressed JSON — they'd bundle cleanly
    • Our API layer is standard HTTP — no database dependency for reads
    The technical question is whether a VFS-backed SEA can handle our data volume. 261 files at ~71 MB compressed, expanding to several hundred MB in memory. Node.js SEAs have been used for smaller payloads. Pushing 71 MB of embedded data through SEAProvider is uncharted territory.

    We'll be experimenting with @platformatic/vfs in the coming weeks. If it works, a self-hosted PostalDataPI binary could be an interesting offering alongside the hosted API.

    Try the Hosted API Today

    While we explore the self-hosted angle, the hosted PostalDataPI API is live and ready:

    curl -s -X POST https://postaldatapi.com/api/lookup \
  -H "Content-Type: application/json" \
  -d '{"zipcode": "90210", "apiKey": "YOUR_KEY"}'

    70+ countries, sub-10ms responses, 1,000 free queries on signup. Get started at postaldatapi.com.

    SDKs: pip install postaldatapi | npm install postaldatapi

    And if you use Claude, our MCP server lets you look up postal codes directly: pip install postaldatapi-mcp

    Could Node.js VFS Turn a Postal Code API Into a Single Executable? | PostalDataPI Blog