@bayudwiyansatria/cloudflare

Cloudflare platform adapters for TypeScript: binding accessors, capability services, and optional Hono middleware.

This community-maintained project is not affiliated with or endorsed by Cloudflare.

Features

• Accessors for 18 Cloudflare bindings, including KV, D1, R2, Queues, Vectorize, Workflows, AI Search, and Workers VPC
• Ten capability services implementing interfaces from @bayudwiyansatria/core
• Lazy configuration resolution that is safe for module-scope service instances
• Optional Hono security and telemetry middleware through a separate subpath export
• ESM and CommonJS bundles with TypeScript declarations
• Explicit missing-binding behavior: each capability documents whether it degrades or throws

See the bindings reference for the complete list and behavior of each adapter.

Installation

The package is distributed through GitHub Packages. Configure the package scope and provide a classic personal access token with read:packages permission:

# .npmrc
@bayudwiyansatria:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}
Copy

Set NPM_AUTH_TOKEN in your shell, then install the package:

npm install @bayudwiyansatria/core @bayudwiyansatria/cloudflare
Copy

Do not commit a token to the repository. Package access is controlled independently from this repository's visibility, so your GitHub account must also have permission to download the package.

@cloudflare/workers-types is a peer dependency. hono is optional and is required only when importing the @bayudwiyansatria/cloudflare/middlewares subpath.

Quick start

Configure the library once, then reuse service instances across requests. Bindings are resolved from the request's environment on every call.

import { configure, systemDefaults } from '@bayudwiyansatria/core'
import { cloudflareDefaults, KVService, type CloudflareEnv } from '@bayudwiyansatria/cloudflare'

const defaults = {
  ...systemDefaults,
  ...cloudflareDefaults,
  logging: {
    ...systemDefaults.logging,
    ...cloudflareDefaults.logging
  }
}

configure(defaults)

const cache = new KVService()

export default {
  async fetch(_request: Request, env: CloudflareEnv): Promise<Response> {
    const value = await cache.remember(env, 'greeting', async () => ({ message: 'Hello' }))
    return Response.json(value)
  }
} satisfies ExportedHandler<CloudflareEnv>
Copy

For setup details and a complete Worker example, read the installation guide and quick start.

Middleware subpath

import { logToAnalytics, SecurityMiddleware } from '@bayudwiyansatria/cloudflare/middlewares'

app.use('*', logToAnalytics)
new SecurityMiddleware().apply(app)
Copy

Register logToAnalytics first so requests rejected by security middleware are still observed. Keeping middleware in a separate entry allows projects that do not use Hono to avoid installing it.

Documentation

• Developer documentation
• Bindings reference
• API overview
• Local development
• Changelog

The generated API reference is published at https://bayudwiyansatria.github.io/nodejs-cloudflare.

Contributing and support

Contributions are welcome. Read the contributing guide and Code of Conduct before opening a pull request.

Use the support guide for questions and the security policy for private vulnerability reports.

License

Licensed under the MIT License.