Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .vitepress/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
],
},
{
Expand Down
59 changes: 59 additions & 0 deletions docs/getting-started/vike.md
Original file line number Diff line number Diff line change
@@ -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()
```
57 changes: 57 additions & 0 deletions docs/getting-started/vite.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# 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)