From db1e2f6101f21845b79318a97ec73e1c02f01fb8 Mon Sep 17 00:00:00 2001 From: ambergristle <101149854+ambergristle@users.noreply.github.com> Date: Tue, 24 Feb 2026 13:11:57 -0800 Subject: [PATCH 1/2] docs(getting-started): add basic vite + vike info --- .vitepress/config.ts | 2 ++ docs/getting-started/vike.md | 59 ++++++++++++++++++++++++++++++++++++ docs/getting-started/vite.md | 56 ++++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 docs/getting-started/vike.md create mode 100644 docs/getting-started/vite.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 85f32757..16922058 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -79,6 +79,8 @@ const sidebars = (): DefaultTheme.SidebarItem[] => [ link: '/docs/getting-started/service-worker', }, { text: 'Node.js', link: '/docs/getting-started/nodejs' }, + { text: 'Vite', link: '/docs/getting-started/vite' }, + { text: 'Vike', link: '/docs/getting-started/vike' }, ], }, { diff --git a/docs/getting-started/vike.md b/docs/getting-started/vike.md new file mode 100644 index 00000000..c8b01bbb --- /dev/null +++ b/docs/getting-started/vike.md @@ -0,0 +1,59 @@ +# Vike + +[Vike](https://vike.dev/why) is a flexible full-stack framework that replaces Next/Nuxt/etc. It lets you combine Hono with popular UI frameworks, while providing QOL features like SSR, file-based routing, data loaders. + +::: warning +Vike does **not** support file-based routing for API endpoints by design. For more, see [API Routes and Middleware](/docs/getting-started/vike#api-routes-and-middleware) +::: + +## Quick Start + +Use the `create vike` CLI to quickly set up a new Vike project with Hono. The following example uses [Solid](https://docs.solidjs.com/). Check out [Vike's scaffolder](https://vike.dev/new) for a full list of supported UI frameworks (and other tooling). + +::: code-group + +```sh [npm] +npm create vike@latest --- --solid --hono +``` + +```sh [yarn] +yarn create vike@latest --solid --hono +``` + +```sh [pnpm] +pnpm create vike@latest --solid --hono +``` + +```sh [bun] +bun create vike@latest --solid --hono +``` + +```sh [deno] +deno run -A npm:create-vike@latest --solid --hono +``` + +::: + +## API Routes and Middleware + +Vike has file-based data loaders to server-render pages, but API tooling is outside the project's scope. API routes can be added using an [integrated Hono app](https://vike.dev/api-routes#api-routes), but currently only `GET` and `POST` requests are supported. + +To add API routes or middleware, use the Vike CLI to set up a Vike project with Hono, or [add it manually](https://vike.dev/vike-photon). Then, just add to your Hono app as you would normally. + +```ts +// /server/entry.ts + +import { Hono } from 'hono' +import { apply, serve } from '@photonjs/hono' +import { routes } from './routes' + +function startServer() { + const app = new Hono() + app.route('/api', routes) // [!code ++] + + apply(app) + return serve(app) +} + +export default startServer() +``` \ No newline at end of file diff --git a/docs/getting-started/vite.md b/docs/getting-started/vite.md new file mode 100644 index 00000000..152c09a8 --- /dev/null +++ b/docs/getting-started/vite.md @@ -0,0 +1,56 @@ +# Vite + +[Vite](https://vite.dev/guide/) is a highly extensible frontend build system that makes it easier to use UI frameworks with Hono. It supports TypeScript and ES modules natively, and offers: + +- Extremely fast **dev server** with [ESBuild](https://esbuild.github.io/) +- Optimized **build process** using [Rollup](https://rollupjs.org/) + +If you need SSR or a more full-stack solution, [Vike](/docs/getting-started/vike) may be what you're looking for. + +Vite uses official and community **plugins** to support integration with [most mainstream UI frameworks](https://vite.dev/guide/#trying-vite-online). **Plugins are also necessary to integrate with Hono's fetch-based API.** + +## Hono Plugins + +There are a number of [official](https://github.com/honojs/vite-plugins) and community plugins for working with Hono and Vite. + +- The [Dev Server](/docs/getting-started/vite.md#dev-server) is required to run Hono + Vite projects locally. +- The [Build](/docs/getting-started/vite.md#build) plugin bundles code for production. +- The [SSG](/docs/getting-started/vite.md#ssg) plugin allows you to build a static site from your Hono app. +- [SSR Components](/docs/getting-started/vite.md#ssr-components) and Vite plugins. See [Vike](/docs/getting-started/vike) for a preconfigured solution. + +::: warning +Vite brings its own CORS protection. [Disable it](https://hono.dev/docs/middleware/builtin/cors#using-with-vite) to avoid conflicts if using `hono/cors`. +::: + +### Dev Server + +The [Dev Server plugin](https://github.com/honojs/vite-plugins/blob/main/packages/dev-server) is an adapter for Hono's fetch-based API. It makes key features (e.g., hot module replacement on the client) available, and includes adapters for Node and Bun. *If you are using Cloudflare, [`@cloudflare/vite-plugin`](https://developers.cloudflare.com/workers/vite-plugin/) is recommended instead.* + +::: info +Vite will take over serving static files. You can override this behavior to [serve static files from a Hono app](https://github.com/honojs/vite-plugins/tree/main/packages/dev-server#importing-asset-as-url-is-not-working). +::: + +### Build + +To build your app for production, use the [Build plugin](https://github.com/honojs/vite-plugins/tree/main/packages/build). + +### SSG + +Generate a static site from your Hono app with the [SSG plugin](https://github.com/honojs/vite-plugins/blob/main/packages/ssg). + +### SSR + +[Vite SSR Components](https://github.com/yusukebe/vite-ssr-components) replaces [`hono-vite-react-stack`](https://github.com/yusukebe/hono-vite-react-stack) as the recommended approach for directly integrating Hono with Vite. + +## Vitest + +[Vitest](https://vitest.dev/) is recommended for running tests. For basic examples, check out the [Testing guide](/docs/helpers/testing.md). + +::: info +Cloudflare provides a test environment and database mocking through [`@cloudflare/vitest-pool-workers`](https://developers.cloudflare.com/workers/testing/vitest-integration/). +::: + +## Examples +- [With Hono JSX/DOM](https://github.com/honojs/examples/tree/main/hono-vite-jsx) for a pure Hono stack +- [With React](https://github.com/yusukebe/hono-vite-react-stack-example) +- [Vitest + Cloudflare](https://github.com/yusukebe/vitest-pool-workers-hono) From f6cb08867173bf9c763439fa04d5bcca99b452b6 Mon Sep 17 00:00:00 2001 From: ambergristle <101149854+ambergristle@users.noreply.github.com> Date: Tue, 24 Feb 2026 13:13:42 -0800 Subject: [PATCH 2/2] docs(getting-started): lint --- docs/getting-started/vike.md | 2 +- docs/getting-started/vite.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/vike.md b/docs/getting-started/vike.md index c8b01bbb..a764da98 100644 --- a/docs/getting-started/vike.md +++ b/docs/getting-started/vike.md @@ -56,4 +56,4 @@ function startServer() { } export default startServer() -``` \ No newline at end of file +``` diff --git a/docs/getting-started/vite.md b/docs/getting-started/vite.md index 152c09a8..93a97cdb 100644 --- a/docs/getting-started/vite.md +++ b/docs/getting-started/vite.md @@ -24,7 +24,7 @@ Vite brings its own CORS protection. [Disable it](https://hono.dev/docs/middlewa ### Dev Server -The [Dev Server plugin](https://github.com/honojs/vite-plugins/blob/main/packages/dev-server) is an adapter for Hono's fetch-based API. It makes key features (e.g., hot module replacement on the client) available, and includes adapters for Node and Bun. *If you are using Cloudflare, [`@cloudflare/vite-plugin`](https://developers.cloudflare.com/workers/vite-plugin/) is recommended instead.* +The [Dev Server plugin](https://github.com/honojs/vite-plugins/blob/main/packages/dev-server) is an adapter for Hono's fetch-based API. It makes key features (e.g., hot module replacement on the client) available, and includes adapters for Node and Bun. _If you are using Cloudflare, [`@cloudflare/vite-plugin`](https://developers.cloudflare.com/workers/vite-plugin/) is recommended instead._ ::: info Vite will take over serving static files. You can override this behavior to [serve static files from a Hono app](https://github.com/honojs/vite-plugins/tree/main/packages/dev-server#importing-asset-as-url-is-not-working). @@ -32,7 +32,7 @@ Vite will take over serving static files. You can override this behavior to [ser ### Build -To build your app for production, use the [Build plugin](https://github.com/honojs/vite-plugins/tree/main/packages/build). +To build your app for production, use the [Build plugin](https://github.com/honojs/vite-plugins/tree/main/packages/build). ### SSG @@ -51,6 +51,7 @@ Cloudflare provides a test environment and database mocking through [`@cloudflar ::: ## Examples + - [With Hono JSX/DOM](https://github.com/honojs/examples/tree/main/hono-vite-jsx) for a pure Hono stack - [With React](https://github.com/yusukebe/hono-vite-react-stack-example) - [Vitest + Cloudflare](https://github.com/yusukebe/vitest-pool-workers-hono)