diff --git a/packages/ratelimit/README.md b/packages/ratelimit/README.md
new file mode 100644
index 0000000000..1aba4ecbbb
--- /dev/null
+++ b/packages/ratelimit/README.md
@@ -0,0 +1,91 @@
+<div align="center">
+    <h1 align="center">@unkey/ratelimit</h1>
+    <h5>@unkey/ratelimit is a library for fast global ratelimiting in serverless functions.</h5>
+</div>
+
+<div align="center">
+  <a href="https://www.unkey.com/docs/libraries/ts/ratelimit">Documentation</a>
+</div>
+<br/>
+
+## Installation
+
+```bash
+npm install @unkey/ratelimit
+```
+
+## Quickstart
+
+1.  Configure your ratelimiter:
+
+```ts
+import { Ratelimit } from "@unkey/ratelimit";
+
+const unkey = new Ratelimit({
+  rootKey: process.env.UNKEY_ROOT_KEY,
+  namespace: "my-app",
+  limit: 10,
+  duration: "30s",
+  async: true,
+});
+```
+
+2.  Use it:
+
+```ts
+async function handler(request) {
+  const identifier = request.getUserId(); // or IP or anything else you want
+
+  const ratelimit = await unkey.limit(identifier);
+  if (!ratelimit.success) {
+    return new Response("try again later", { status: 429 });
+  }
+
+  // handle the request here
+}
+```
+
+## Making it Bullet Proof
+
+To ensure reliability, you can configure timeout and error handling:
+
+```ts
+import { Ratelimit } from "@unkey/ratelimit";
+
+const fallback = (identifier: string) => ({
+  success: true,
+  limit: 0,
+  reset: 0,
+  remaining: 0,
+});
+
+const unkey = new Ratelimit({
+  // ... standard configuration
+  timeout: {
+    ms: 3000, // only wait 3s at most before returning the fallback
+    fallback,
+  },
+  onError: (err, identifier) => {
+    console.error(`${identifier} - ${err.message}`);
+    return fallback(identifier);
+  },
+});
+```
+
+## API Overview
+
+Create a new instance for ratelimiting by providing the necessary configuration.
+
+```ts
+new Ratelimit(config: RatelimitConfig)
+```
+
+Check whether a specific identifier is currently allowed to do something or if they have currently exceeded their limit.
+
+```ts
+.limit(identifier: string, opts: LimitOptions): Promise<RatelimitResponse>
+```
+
+### Documentation
+
+[Read the full documentation](https://www.unkey.com/docs/libraries/ts/ratelimit)
diff --git a/packages/ratelimit/package.json b/packages/ratelimit/package.json
index f318b817ff..459ce97791 100644
--- a/packages/ratelimit/package.json
+++ b/packages/ratelimit/package.json
@@ -14,7 +14,7 @@
     "url": "https://github.com/unkeyed/unkey/issues"
   },
   "homepage": "https://github.com/unkeyed/unkey#readme",
-  "files": ["./dist/**"],
+  "files": ["./dist/**","README.md"],
   "author": "Andreas Thomas <andreas@unkey.dev>",
   "scripts": {
     "build": "tsup"