On this page

Quick Start

Using Bun? See the Bun Quick Start for @joint-ops/hitlimit-bun.

Get up and running with hitlimit in under 5 minutes.

Basic Usage

The simplest way to add rate limiting to your Express app:

app.ts
import express from 'express'
import { hitlimit } from '@joint-ops/hitlimit'

const app = express()

// 100 requests per minute per IP
app.use(hitlimit({ limit: 100, window: '1m' }))

app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello World!' })
})

app.listen(3000)

Fastify

Using Fastify? Register hitlimit as a plugin:

app.ts
import Fastify from 'fastify'
import { hitlimit } from '@joint-ops/hitlimit/fastify'

const app = Fastify()

// 100 requests per minute per IP
await app.register(hitlimit, { limit: 100, window: '1m' })

app.get('/', () => 'Hello!')
await app.listen({ port: 3000 })

Hono

Using Hono? Use hitlimit as middleware:

app.ts
import { Hono } from 'hono'
import { hitlimit } from '@joint-ops/hitlimit/hono'

const app = new Hono()

// 100 requests per minute per IP
app.use(hitlimit({ limit: 100, window: '1m' }))

app.get('/', (c) => c.text('Hello!'))

Time Windows

Use human-readable time strings:

hitlimit({ limit: 100, window: '1m' })   // 100 per minute
hitlimit({ limit: 1000, window: '1h' })  // 1000 per hour
hitlimit({ limit: 10000, window: '1d' }) // 10000 per day

Custom Key

Rate limit by user ID, API key, or any identifier:

// By user ID
hitlimit({
  limit: 100,
  window: '1m',
  key: (req) => req.user?.id || req.ip
})

Using Stores

Choose the right store for your use case:

import { hitlimit, memoryStore } from '@joint-ops/hitlimit'
import { sqliteStore } from '@joint-ops/hitlimit/stores/sqlite'

// Memory (default, single instance)
hitlimit({ limit: 100, window: '1m' })

// SQLite (persistent)
hitlimit({
  limit: 100,
  window: '1m',
  store: sqliteStore({ path: './rate-limits.db' })
})

Response Headers

hitlimit automatically adds rate limit headers:

RateLimit-Limit: 100
RateLimit-Remaining: 73
RateLimit-Reset: 1640000000
Retry-After: 27  (only when rate limited)

Next Steps