Building blocks for REST APIs, built on industry standards
++ The web toolkit for full-stack connoisseurs. +
-## Overview
-
-Webroute is a set of building blocks which can combine to form a fully fledged web framework. Each tool is decoupled from the next, meaning they are all independently useful. But they can also be stacked, leaving you with a strong foundation for quickly building backend web apps that are future-proofed.
-
-**View the [documentation](https://webroute.vercel.app).**
-
-## Example Usage
-
-```ts
-import { route } from "@webroute/route";
-
-export const myRoute = route("/post/:id")
- .method("get")
- .use(isAuthed())
- .params(z.object({ id: z.string() }))
- .handle(async (req, c) => {
- const { params } = await c.parse();
- // ...
- return { title: "..." };
- });
-
-// myRoute: (req: Request) => Response
-```
-
-## Quick Start
-
-To get up and running quickly with a fully-fledged app, you can use the `create-webroute-app` command:
-
-```sh
-npx create-webroute-app ./my-app
-```
-
-## How is this different to X?
+
-Webroute is not a framework. Modern web apps are deployed to a range of different environments, runtimes and architectures. Webroute provides a handful of _independent_ libraries to help with common tasks like routing, route handling, middleware and client-side type-safety.
+## Overview
-Webroute was designed to get out of your way and to be minimally opinionated. We prefer requiring slightly more additional setup if it means much greater flexibility – and less lock-in – for the lifetime of an app.
+Webroute provides a few packages which make building and consuming HTTP APIs a breeze, both on the client- and server-side.
-## [Packages](https://webroute.vercel.app/docs/packages)
+As opposed to monolithic frameworks, webroute merely provides you with the tools to create powerful APIs alongside your favourite runtime, full-stack framework and/or platform.
-Webroute provides several packages that are entirely independent of one another. Combined, they can be used to create fully-fledged REST APIs.
+## Why?
-They will work with any framework or runtime that utilises web-standard `Request` and `Response` objects.
+Modern API development is extremely fragmented across vast combinations of frameworks, runtimes and platforms. Monolithic web frameworks are no longer suitable.
-| Package | Purpose |
-| ----------------------------------------------------------------------- | ------------------------------------------------------------- |
-| [**Route**](https://webroute.vercel.app/docs/route/overview) | Build powereful and atomic web-standard request handlers |
-| [**Client**](https://webroute.vercel.app/docs/client/overview) | Create type-safe clients for any REST API |
-| [**Middleware**](https://webroute.vercel.app/docs/middleware/overview) | Middleware compatible with any framework |
-| [**Schema**](https://webroute.vercel.app/docs/schema/overview) | Universal converters, parsers and infererence for any schema |
-| [**Router**](https://webroute.vercel.app/docs/router/overview) | Match incoming `Request`s to request handlers |
-| [**OpenAPI Spec (OAS)**](https://webroute.vercel.app/docs/oas/overview) | Define, generate and infer OpenAPI schema without any codegen |
+Instead, webroute has implemented the core elements you _might_ need in a web framework, and you can easily piece together those that suit your use case.
## Compatibility
-Webroute was built from the ground up to be friendly with most existing tools. It can be used standalone or alongside existing frameworks, and in various runtimes.
-
-### Frameworks:
-
-- ✅ Hono
-- ✅ NextJS
-- ✅ Remix
-- ✅ SolidStart
-
-### Runtimes:
-
-- ✅ Bun
-- ✅ Deno
-- ✅ Node (via adapter)
-- ✅ Cloudflare Workers
-- ✅ Vercel Edge
-
----
+Webroute works with all runtimes or frameworks that conform to the WinterCG Minimum Web Standard.
-## Contribution
+### Frameworks
-Feel free to [open any PRs or issues](https://github.com/sinclairnick/webroute/issues) or [start a discussion](https://github.com/sinclairnick/webroute/issues).
+- [x] `Hono`
+- [x] `Next.js`
+- [x] `Remix`
+- [x] `SolidStart`
+- [x] `SvelteKit`
-## Author
+### Runtimes
-Webroute was initially developed by [Nick Sinclair](https://github.com/sinclairnick)
+- [x] `Bun`
+- [x] `Deno`
+- [x] `Node` (via adapter)
+- [x] `Cloudflare Workes`
+- [x] `Vercel Edge`
diff --git a/docs/content/docs/comparisons.mdx b/docs/content/docs/comparisons.mdx
deleted file mode 100644
index f54ac0f..0000000
--- a/docs/content/docs/comparisons.mdx
+++ /dev/null
@@ -1,61 +0,0 @@
----
-title: Comparisons
-icon: GitCompareArrows
----
-
-`webroute` builds on lessons from previous libraries and frameworks, aiming to provide the best abstraction for building general purpose APIs.
-
-It was born out of a dissatisfaction with existing options being some combination of too simple, poorly designed, confusing or convoluted.
-
-Ultimately, `webroute` was designed to be as scalable as NestJS, simple as express and even more flexible than modern web frameworks.
-
-## Express
-
-Express is the go-to framework for Node-based APIs. While still a completely valid option, it suffers from several issues.
-
-Express is an old framework. This means it's both stable and battle-tested, hence its lingering popularity. However, express is reliant on node APIs that have since been succeeded by web standards. It makes heavy use of now-considered bad practices like monkey-patching and mutation of the request object. It has poor support for table-stakes like typescript and async support.
-
-All of these problems make it more difficult to create secure, testable, fast, reliable APIs.
-
-`webroute` aims to maintain the simplicity and intuitiveness of express, without the rough edges. Consequently `webroute` is if anything even simpler than express, yet behaves as one would expect and makes room for fundamental modern API requirements like validation, OpenAPI and testing.
-
-## tRPC
-
-The API for `webroute` is similar to [tRPC](https://trpc.io/) in many ways. The chained syntax allows for great composability and makes things like type-safe middleware possible.
-
-However tRPC is an RPC framework, whereas `webroute` is not a framework, and instead of RPC it is HTTP/REST-focused. While tRPC can be used with the `trpc-openapi` framework to work over REST, it is fundamentally not designed for REST, so rough edges abound.
-
-`webroute` is more primitive than tRPC and instead of shying away from HTTP/REST, it leans into it.
-
-## NestJS
-
-NestJS provides a huge amount of functionality and positions itself as the enterprise node solution. While it's true that express and other alternatives are likely insufficient for large-scale apps, NestJS has been rightly criticised for being overcomplicated.
-
-Enforcing dependency injection, class-decorators and other methods familiar to OOP languages like Java or C#, NestJS often leads to obscure errors around circular dependencies and typescript metadata issues, making otherwise simple tasks complicated and difficult to resolve.
-
-Like express, NestJS also utilises functionality at its core which is at odds with where the standards are going. For example, Typescript decorators which relied on, yet are only experimentally supported. Moreover, the JavaScript proposal for decorators is deviating from the experimental TypeScript version.
-
-`webroute` was designed to sit somewhere between the reliability of NestJS and the stability of express.
-
-## Web Frameworks
-
-> Hono, Elysia, etc.
-
-While similar to these frameworks in some ways, `webroute` inverts the responsibility of route and "app". Typically a central `app` is initialised, where routes are then registered on to this `app` instance.
-
-Contra to this approach, `webroute` defines the necessary functionality at the route-level, leaving the orchestration and routing decoupled and thus more flexible. Because `webroute`s are compatible with these frameworks, it can also be incrementally adopted or work alongside an existing app without adopting a new framework or methodology. An existing app with a single `webroute` shoehorned in is a completely valid use case and won't interfere negatively.
-
-
-
-## Other Node Frameworks
-
-> Fastify, Koa, etc.
-
-Similar to express, these frameworks have idiosyncratic APIs that are often hard to test, unreliable or complicated.
-
-
-## MVC Frameworks
-
-> Adonis, Sails, etc.
-
-`webroute` is not an MVC framework and has no opinions on rendering views. It can be used for such, but is not a fully-fledged framework for building web applications. Instead it is a simple abstraction for building APIs across web-compatible runtimes.
\ No newline at end of file
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
index 05c4094..ef1e31a 100644
--- a/docs/content/docs/index.mdx
+++ b/docs/content/docs/index.mdx
@@ -3,14 +3,25 @@ title: Overview
icon: Home
---
+Webroute is a toolkit for building and interacting with APIs in a type-safe, robust and ergonomic manner.
-**Webroute is a suite of independent tools for building server-side apps and APIs, based on the [WinterCG Minimum Common Web API](https://common-min-api.proposal.wintercg.org/).**
+It was designed to work with your existing stack, or be used standalone. As a result, webroute offers a selection of independent packages which you can mix-and-match as needed.
-Instead of a monolithic framework, Webroute provides a handful of independent packages. Boundaries between **routing**, **middleware**, **validation**, **routing** and **client** are clearly defined and separate. This means you're not tied down by framework or runtime.
+Additionally, industry standards are heavily leaned into so you can "learn the platform" instead of another bespoke framework API.
+
+## Get Started
+
+The fastest way to get started with webroute is via the `create-webroute-app` CLI.
+
+```sh
+npx create-webroute-app webroute-app
+```
+
+This will dynamically build an starter app with the features you require.
## Philosophy
-When building new web tools, the following principles are followed.
+To achieve a balance of flexibility, ease of use and interoperability, webroute adheres to a few principles.
| Concept | Description |
| ---------------- | :------------------------------------------------------------------------------------- |
@@ -19,5 +30,7 @@ When building new web tools, the following principles are followed.
| **Pure** | Preferring basic input/output functions over side-effectful ones |
| **Atomic** | Standalone functionality is better than requiring complex integration or orchestration |
| **Declarative** | When useful, prefer declarative over imperative approaches, enabling introspection |
-| **No magic** | No monkey-patching, wrapped `Request`/`Response` objects |
+| **No magic** | No monkey-patching, no wrapped `Request`/`Response` objects, no magical compilers |
| **Composable** | Prefer composition over orchestration so pipelines are traceable and reasonable |
+
+These principles, and their benefits will become clearer over the course of these docs.
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index f300051..780a3a7 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -3,7 +3,6 @@
"root": true,
"pages": [
"index",
- "comparisons",
"---Guides---",
"guides/quick-start",
"---Packages---",
@@ -17,4 +16,4 @@
"---About---",
"acknowledgements"
]
-}
\ No newline at end of file
+}