# Installation

## Requirements

- [Node.js](https://nodejs.org/) 22 for contributing to this repository
- [npm](https://www.npmjs.com/)
- A Cloudflare Workers project
- A GitHub classic personal access token with `read:packages` permission and access to the package

The published bundles target ES2020. Node.js 22 is the supported development version and matches continuous integration.

## Install the published package

The package is distributed through GitHub Packages. Add the scope and environment-backed authentication to the consuming
project's `.npmrc`:

```ini
@bayudwiyansatria:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_AUTH_TOKEN}
```

Set the token for your current shell, then install both libraries.

PowerShell:

```powershell
$env:NPM_AUTH_TOKEN = 'your-token'
npm install @bayudwiyansatria/core @bayudwiyansatria/cloudflare
```

POSIX shells:

```bash
export NPM_AUTH_TOKEN='your-token'
npm install @bayudwiyansatria/core @bayudwiyansatria/cloudflare
```

Do not write a literal token into `.npmrc` or commit one. Repository and package visibility are independent, so the
GitHub account associated with the token must have permission to download the package.

`@bayudwiyansatria/core` is a direct runtime dependency. It provides the capability interfaces implemented here and the
`configure()` function used during application startup.

### Peer dependencies

| Package                     | Required?                | Purpose                                                                       |
| --------------------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `@cloudflare/workers-types` | yes                      | Provides the binding types referenced by the declarations                     |
| `hono`                      | only for `./middlewares` | Provides the runtime types and API used by the optional Hono middleware entry |

## Published entries

```ts
import { cloudflareDefaults, KVService } from '@bayudwiyansatria/cloudflare'
import { SecurityMiddleware } from '@bayudwiyansatria/cloudflare/middlewares'
```

| Entry           | Contents                                           | Files under `lib/`                                               |
| --------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| `.`             | Bindings, services, configuration, `CloudflareEnv` | `index.min.cjs`, `index.min.mjs`, `index.d.ts`                   |
| `./middlewares` | `SecurityMiddleware`, `logToAnalytics`             | `middlewares.min.cjs`, `middlewares.min.mjs`, `middlewares.d.ts` |

Source maps are generated for the JavaScript bundles but excluded from the package archive.

### Module resolution

The `./middlewares` subpath is declared in `package.json#exports`. For a Worker bundled by Wrangler, use a modern
TypeScript resolution mode:

```jsonc
{
  "compilerOptions": {
    "moduleResolution": "Bundler"
  }
}
```

`typesVersions` also maps the middleware declarations for consumers using classic TypeScript resolution.

## Install for development

```bash
git clone https://github.com/bayudwiyansatria/nodejs-cloudflare.git
cd nodejs-cloudflare
```

Set `NPM_AUTH_TOKEN` as shown above, then run:

```bash
npm install
npm test
npm run build
```

See [Local Development](../guides/local-development.md) for the complete contributor workflow.

## Next

- [Quick Start](./quick-start.md) — configure the library, use a capability, and wire bindings
- [Bindings](../reference/bindings.md) — all supported bindings and their behavior