Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

`void/kv` and `void/storage` for `target: 'node'`, backed by Redis and S3

Open
  • Is something wrong?
#454 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
postgresql, redis, typescript
Domain
backend, cloud, database

Research direction

Start with packages/void/src/plugin-node-target.ts and the Node route setup in packages/void/src/router/compile.ts, then read the existing remote KV and storage adapters. The proposal leaves core versus plugin placement and backend configuration format open, so first get maintainer direction before implementation. Done means configured Redis and S3-compatible bindings work through the existing APIs on Node, with a Compose example and guide updates.

Written by the indexing model from the issue text.

Description

Parts of the text were generated using an LLM, but the core purpose and intent of the proposal were written by a human.

Summary

I'd like to use void/kv and void/storage with target: 'node' (and bun / deno), backed by Redis and S3-compatible storage, so the same app code runs on Cloudflare and on our own servers.

This would extend what Void already does for databases. void/db isn't limited to D1: with database: 'pg' or 'mysql' and a DATABASE_URL, the same API works with your own PostgreSQL or MySQL server (Choosing a Dialect). This proposal applies the same idea to KV and Storage: the API stays the same, and the app brings its own Redis or S3-compatible service.

Since Void is built for Cloudflare Workers, I'd like to check the direction before writing code: would you accept this in Void core, or should it live in an external plugin or a fork?

"Self-hosting" here means running the app on a Node.js server or container, not the self-hosted Void Platform.

Motivation

I believe solid self-hosting is important for Void to become a first-class choice for full-stack apps. Many teams can't run everything on a single provider: they have existing infrastructure, data residency or compliance requirements, or want to avoid lock-in. Next.js, for comparison, supports all of its features on a Node.js server or in a Docker container (Deploying).

What sets Void apart from other frameworks is its built-in, typed server APIs: void/db, void/kv, void/storage, void/auth and void/env, with types carried from database queries to the UI. With target: 'node', none of these are available today. What remains is mostly routing and pages, which many frameworks already provide, so a self-hosted Void app loses most of its advantage as a full-stack framework.

void/ai and void/sandbox probably don't need self-hosted support. They wrap Cloudflare services (Workers AI and Containers), and a self-hosted app can call a model provider or run containers directly.

This issue starts with KV and Storage. If the direction works, void/db, void/auth and void/env could follow with the same approach.

Current behavior

  • void/kv and void/storage are in CF_ONLY_IMPORTS, so importing them with target: 'node' fails at build time (plugin-node-target.ts).
  • The docs suggest using an external provider through standard Node.js libraries instead (No Cloudflare bindings).

So an app that uses kv or storage can't move to target: 'node' by changing config. Every call site has to be rewritten against another client, and an app that also deploys to Cloudflare ends up with two code paths.

Proposal

1. Adapters behind the existing APIs
  • void/storage (R2Bucket) → S3 API: AWS S3, R2's S3 API, Garage, SeaweedFS, …
  • void/kv (the KVNamespace methods the kv client calls) → Redis protocol: Redis, Valkey, …

The generated Node entry creates them at startup and provides them as KV / STORAGE. kv, storage, createKV() and createStorage() keep their types, so app code stays the same on both targets.

remote: true already works this way: ProxyKVNamespace / ProxyR2Bucket implement these interfaces over another transport and throw a clear error for unsupported features (runtime/remote). Full parity with Cloudflare isn't a goal: differences such as list() ordering, consistency and size limits would be documented. Client libraries would be optional dependencies, so the Cloudflare target and its install size stay unchanged.

2. Config

This mirrors database: 'pg' + DATABASE_URL (config):

// void.config.ts
export default defineConfig({
  target: 'node',
  kv: 'redis', // KV_URL=redis://valkey:6379
  storage: 's3', // STORAGE_URL=s3://<key>:<secret>@object-store:8333/uploads (format TBD)
});

The server reads these URLs from the environment when it starts, not at build time. That keeps credentials out of dist/ and lets the same image run in several environments.

3. Docker Compose example

A playground app (e.g. playground/node-self-hosted/) with a compose.yaml that runs the app, Valkey and an S3-compatible server such as SeaweedFS or Garage, plus a short section in the Node.js, Bun, and Deno guide. The same setup could back integration tests for the adapters.

Cloudflare-target behavior and defaults don't change.

Where it would touch

  • plugin-node-target.ts: allow void/kv / void/storage when a backend is configured.
  • router/compile.ts: the Node route table uses a no-op withRuntimeEnv (L159-L163), and compileNodeApp adds only ASSETS to the env it passes to the routes (L1349). Both would need to provide KV / STORAGE.
  • New adapter modules, config schema and types, and docs.

Question: where should this live?

  1. Void core. The adapters ship with Void, either in void with optional peer dependencies or as @void/* packages in this repo. They're configured in void.config.ts, documented in the guides and tested in CI here.

  2. External plugin. The adapters live in a separate package, and core gets only the small extension points it needs. I'd send PRs for:

    • a supported way to give the generated Node, Bun and Deno entries bindings created at startup, for example a module path in void.config.ts that exports { KV, STORAGE };
    • letting the guard allow void/kv / void/storage when those bindings are provided.

    There's a similar precedent in void/database-provider, which lets third-party packages add providers to void db connect.

  3. Fork. Running these APIs outside Cloudflare is out of scope for Void, and this should be maintained separately.

If 1 or 2 works for you, I'd be happy to implement it, starting with Storage (S3), and I'll follow your preference on details such as config shape and which methods to support.

Dominant language
TypeScript
Stars
402
Forks
32
Avg merge
12h 1m
Merged PRs (30d)
80

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from voidzero-dev/void

All issues in voidzero-dev/void

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.