From b9745e79c5e18a09bdc9e21c7941249d77dfb9d8 Mon Sep 17 00:00:00 2001 From: Yusuke Wada Date: Tue, 26 Apr 2022 07:58:08 +0900 Subject: [PATCH] docs: update readme --- README.md | 52 +++++++++++++++++++++++------ docs/README.ja.md | 63 ++++++++++++++++++++++++++++++++--- src/middleware/cors/README.md | 39 +++++++++++----------- 3 files changed, 119 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 785a2186..d269d397 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ [![GitHub commit activity](https://img.shields.io/github/commit-activity/m/yusukebe/hono)](https://github.com/yusukebe/hono/pulse) [![GitHub last commit](https://img.shields.io/github/last-commit/yusukebe/hono)](https://github.com/yusukebe/hono/commits/master) -Hono - _**[炎] means flame🔥 in Japanese**_ - is small, simple, and ultrafast web framework for Cloudflare Workers and Fastly Compute@Edge. +Hono - _**[炎] means flame🔥 in Japanese**_ - is a small, simple, and ultrafast web framework for Cloudflare Workers and Service Worker based serverless such as Fastly Compute@Edge. ```js import { Hono } from 'hono' @@ -37,7 +37,7 @@ app.fire() - **Zero-dependencies** - using only Service Worker and Web standard API. - **Middleware** - built-in middleware and ability to extend with your own middleware. - **TypeScript** - first-class TypeScript support. -- **Optimized** - for Cloudflare Workers. +- **Optimized** - for Cloudflare Workers and Fastly Compute@Edge. ## Benchmark @@ -58,7 +58,41 @@ A demonstration to create an application for Cloudflare Workers with Hono. ![Demo](https://user-images.githubusercontent.com/10682/151973526-342644f9-71c5-4fee-81f4-64a7558bb192.gif) -Now, the named path parameter has types. +## Not only fast + +Hono is fast. But not only fast. + +### Write Less, do more + +Built-in middleware make _"**Write Less, do more**"_ in reality. You can use a lot of middleware without writing code from scratch. Below are examples. + +- [Basic Authentication](https://github.com/yusukebe/hono/tree/master/src/middleware/basic-auth/) +- [Cookie parsing / serializing](https://github.com/yusukebe/hono/tree/master/src/middleware/cookie/) +- [CORS](https://github.com/yusukebe/hono/tree/master/src/middleware/cors/) +- [ETag](https://github.com/yusukebe/hono/tree/master/src/middleware/etag/) +- [GraphQL Server](https://github.com/yusukebe/hono/tree/master/src/middleware/graphql-server/) +- [Logger](https://github.com/yusukebe/hono/tree/master/src/middleware/logger/) +- [Mustache template engine](https://github.com/yusukebe/hono/tree/master/src/middleware/mustache/) (Only for Cloudflare Workers) +- [JSON pretty printing](https://github.com/yusukebe/hono/tree/master/src/middleware/pretty-json/) +- [Serving static files](https://github.com/yusukebe/hono/tree/master/src/middleware/serve-static/) (Only for Cloudflare Workers) + +You can enable logger and CORS middleware with just this code. + +```js +import { Hono } from 'hono' +import { cors } from 'hono/cors' +import { logger } from 'hono/logger' + +const app = new Hono() +app.use('*', cors()).use(logger()) +``` + +### Developer Experience + +And Hono provides fine _"**Developer Experience**"_. Easy access to Request/Response thanks to the `Context` object. +Above all, Hono is written in TypeScript. So, Hono has _"**Types**"_! + +For example, the named path parameters will be literal types. ![Demo](https://user-images.githubusercontent.com/10682/154179671-9e491597-6778-44ac-a8e6-4483d7ad5393.png) @@ -80,10 +114,10 @@ npm install hono An instance of `Hono` has these methods. -- app.**HTTP_METHOD**(path, handler) -- app.**all**(path, handler) +- app.**HTTP_METHOD**(\[path,\] handler) +- app.**all**(\[path,\] handler) - app.**route**(path) -- app.**use**(path, middleware) +- app.**use**(\[path,\] middleware) - app.**notFound**(handler) - app.**onError**(err, handler) - app.**fire**() @@ -507,7 +541,7 @@ npx wrangler@beta publish index.js ## Starter template -You can start making your Cloudflare Workers application with [the starter template](https://github.com/yusukebe/hono-minimal). It is really minimal using TypeScript, esbuild, and Miniflare. +You can start making your Cloudflare Workers application with [the starter template](https://github.com/yusukebe/hono-minimal). It is really minimal using TypeScript, esbuild, Miniflare, and Jest. To generate a project skelton, run this command. @@ -529,7 +563,7 @@ Implementation of the original router `TrieRouter` is inspired by [goblin](https ## Contributing -Contributions Welcome! You can contribute by the following way. +Contributions Welcome! You can contribute in the following ways. - Write or fix documents - Write code of middleware @@ -537,8 +571,6 @@ Contributions Welcome! You can contribute by the following way. - Refactor the code - etc. -Let's make Hono together! - ## Contributors Thanks to [all contributors](https://github.com/yusukebe/hono/graphs/contributors)! diff --git a/docs/README.ja.md b/docs/README.ja.md index 661297e5..24e8c77b 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -20,7 +20,7 @@ [![GitHub commit activity](https://img.shields.io/github/commit-activity/m/yusukebe/hono)](https://github.com/yusukebe/hono/pulse) [![GitHub last commit](https://img.shields.io/github/last-commit/yusukebe/hono)](https://github.com/yusukebe/hono/commits/master) -Hono - _日本語の\[炎\]に由来 🔥_ - はCloudflare WorkersやFastly Compute@Edge向けの小さくて、シンプルで、めちゃくちゃ速いWebフレームワークです。 +Hono - _日本語の\[炎\]に由来 🔥_ - はCloudflare WorkersやFastly Compute@Edgeなど、Service Workerベースのサーバーレス向けの小さくて、シンプルで、めちゃくちゃ速いWebフレームワークです。 ```js import { Hono } from 'hono' @@ -58,7 +58,42 @@ Honoを使って、Cloudflare Workersのアプリケーションを作ってい ![Demo](https://user-images.githubusercontent.com/10682/151973526-342644f9-71c5-4fee-81f4-64a7558bb192.gif) -名前付きパラメーターにも型がつきます。 +## 速いだけじゃない + +Honoは速いけど、速いだけではありません。 + +### Write Less, do more + +ビルトイン・ミドルウェアが「**_Write Less, do more_**」を実現します。 +たくさんのミドルウェアを１からコードを書くことなく、使えます。 +例えば、以下のミドルウェアがあります。 + +- [Basic認証](https://github.com/yusukebe/hono/tree/master/src/middleware/basic-auth/) +- [Cookieパース/シリアライゼーション](https://github.com/yusukebe/hono/tree/master/src/middleware/cookie/) +- [CORS](https://github.com/yusukebe/hono/tree/master/src/middleware/cors/) +- [ETag](https://github.com/yusukebe/hono/tree/master/src/middleware/etag/) +- [GraphQLサーバー](https://github.com/yusukebe/hono/tree/master/src/middleware/graphql-server/) +- [ロガー](https://github.com/yusukebe/hono/tree/master/src/middleware/logger/) +- [Mustacheを使ったテンプレート](https://github.com/yusukebe/hono/tree/master/src/middleware/mustache/) (Cloudflare Workersのみ) +- [JSON pretty](https://github.com/yusukebe/hono/tree/master/src/middleware/pretty-json/) +- [静的ファイルのサーブ](https://github.com/yusukebe/hono/tree/master/src/middleware/serve-static/) (Cloudflare Workersのみ) + +たったこれだけのコードでロガーとCORSミドルウェアを使うことができます。 + +```js +import { Hono } from 'hono' +import { cors } from 'hono/cors' +import { logger } from 'hono/logger' + +const app = new Hono() +app.use('*', cors()).use(logger()) +``` + +### Developer Experience + +そして、Honoは優れた「**_Developer Experience_**」を提供します。`Context` オブジェクトのおかげで、Request/Responseへのアクセスが簡単です。なにより、HonoはTypeScriptで書かれています。そう、Honoは「**_型_**」を持っているのです！ + +例えば、名前付きパラメーターにもリテラル型がつきます。 ![Demo](https://user-images.githubusercontent.com/10682/154179671-9e491597-6778-44ac-a8e6-4483d7ad5393.png) @@ -80,10 +115,10 @@ npm install hono `Hono`のインスタンスには以下のメソッドがあります。 -- app.**HTTP_METHOD**(path, handler) -- app.**all**(path, handler) +- app.**HTTP_METHOD**(\[path,\] handler) +- app.**all**(\[path,\] handler) - app.**route**(path) -- app.**use**(path, middleware) +- app.**use**(\[path,\] middleware) - app.**notFound**(handler) - app.**onError**(err, handler) - app.**fire**() @@ -127,6 +162,21 @@ app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => { }) ``` +### チェインされたルート + +```js +app + .get('/endpoint', (c) => { + return c.text('GET /endpoint') + }) + .post((c) => { + return c.text('POST /endpoint') + }) + .delete((c) => { + return c.text('DELETE /endpoint') + }) +``` + ### ネストされたルート ```js @@ -175,6 +225,9 @@ const app = new Hono() app.use('*', poweredBy()) app.use('*', logger()) +// もしくはこのようにも書けます。 +// app.use('*', poweredBy()).use(logger()) + app.use( '/auth/*', basicAuth({ diff --git a/src/middleware/cors/README.md b/src/middleware/cors/README.md index e27503c0..654b69a1 100644 --- a/src/middleware/cors/README.md +++ b/src/middleware/cors/README.md @@ -5,26 +5,25 @@ index.js: ```js -describe('CORS by Middleware', () => { - const app = new Hono() +const app = new Hono() - app.use('/api/*', cors()) - app.use( - '/api2/*', - cors({ - origin: 'http://example.com', - allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'], - allowMethods: ['POST', 'GET', 'OPTIONS'], - exposeHeaders: ['Content-Length', 'X-Kuma-Revision'], - maxAge: 600, - credentials: true, - }) - ) +app.use('/api/*', cors()) +app.use( + '/api2/*', + cors({ + origin: 'http://example.com', + allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'], + allowMethods: ['POST', 'GET', 'OPTIONS'], + exposeHeaders: ['Content-Length', 'X-Kuma-Revision'], + maxAge: 600, + credentials: true, + }) +) - app.all('/api/abc', (c) => { - return c.json({ success: true }) - }) - app.all('/api2/abc', (c) => { - return c.json({ success: true }) - }) +app.all('/api/abc', (c) => { + return c.json({ success: true }) +}) +app.all('/api2/abc', (c) => { + return c.json({ success: true }) +}) ```