1 files changed, 111 insertions, 0 deletions
diff --git a/docs/api/file-system-router.md b/docs/api/file-system-router.md
new file mode 100644
index 000000000..e55376446
--- /dev/null
+++ b/docs/api/file-system-router.md
@@ -0,0 +1,111 @@
+Bun provides a fast API for resolving routes against file-system paths. This API is primarily intended by library authors. At the moment only Next.js-style file-system routing is supported, but other styles may be added in the future.
+
+## Next.js-style
+
+The `FileSystemRouter` class can resolve routes against a `pages` directory. (The Next.js 13 `app` directory is not yet supported.) Consider the following `pages` directory:
+
+```txt
+pages
+├── index.tsx
+├── settings.tsx
+├── blog
+│   ├── [slug].tsx
+│   └── index.tsx
+└── [[...catchall]].tsx
+```
+
+The `FileSystemRouter` can be used to resolve routes against this directory:
+
+```ts
+const router = new Bun.FileSystemRouter({
+  style: "nextjs",
+  dir: "./pages",
+  origin: "https://mydomain.com",
+  assetPrefix: "_next/static/"
+});
+router.match("/");
+
+// =>
+{
+  filePath: "/path/to/pages/index.tsx",
+  kind: "exact",
+  name: "/",
+  pathname: "/",
+  src: "https://mydomain.com/_next/static/pages/index.tsx"
+}
+```
+
+Query parameters will be parsed and returned in the `query` property.
+
+```ts
+router.match("/settings?foo=bar");
+
+// =>
+{
+  filePath: "/Users/colinmcd94/Documents/bun/fun/pages/settings.tsx",
+  kind: "dynamic",
+  name: "/settings",
+  pathname: "/settings?foo=bar",
+  src: "https://mydomain.com/_next/static/pages/settings.tsx"
+  query: {
+    foo: "bar"
+  }
+}
+```
+
+The router will automatically parse URL parameters and return them in the `params` property:
+
+```ts
+router.match("/blog/my-cool-post");
+
+// =>
+{
+  filePath: "/Users/colinmcd94/Documents/bun/fun/pages/blog/[slug].tsx",
+  kind: "dynamic",
+  name: "/blog/[slug]",
+  pathname: "/blog/my-cool-post",
+  src: "https://mydomain.com/_next/static/pages/blog/[slug].tsx"
+  params: {
+    slug: "my-cool-post"
+  }
+}
+```
+
+The `.match()` method also accepts `Request` and `Response` objects. The `url` property will be used to resolve the route.
+
+```ts
+router.match(new Request("https://example.com/blog/my-cool-post"));
+```
+
+The router will read the directory contents on initialization. To re-scan the files, use the `.reload()` method.
+
+```ts
+router.reload();
+```
+
+## Reference
+
+```ts
+interface Bun {
+  class FileSystemRouter {
+    constructor(params: {
+      dir: string;
+      style: "nextjs";
+      origin?: string;
+      assetPrefix?: string;
+    });
+
+    reload(): void;
+
+    match(path: string | Request | Response): {
+      filePath: string;
+      kind: "exact" | "catch-all" | "optional-catch-all" | "dynamic";
+      name: string;
+      pathname: string;
+      src: string;
+      params?: Record<string, string>;
+      query?: Record<string, string>;
+    } | null
+  }
+}
+```