bhvr

The shared package is the source of truth for data contracts used by both the client and server. By defining types in shared/src/types, you achieve end-to-end type safety.

Workflow

1. Define a type in shared/src/types/index.ts.
2. Export it from shared/src/index.ts using export * from "./types".
3. Import the type in either the client or server using the shared package alias.

When you run bun run dev or bun run build, the shared package is compiled so its exports are available to the other workspaces via TypeScript path aliases.

You can scaffold a new full-stack TypeScript project using the bun create command. This sets up a monorepo with a React client, a Hono server, and a shared types package.

Ensure Bun is installed on your system before proceeding.

bun create bhvr@latest my-app

# Navigate to the project and start development
cd my-app
bun dev

To improve code quality for React development, you can install and configure eslint-plugin-react-x and eslint-plugin-react-dom. These plugins provide specialized rules for React and React DOM components.

// eslint.config.js
import reactX from 'eslint-plugin-react-x'
import reactDom from 'eslint-plugin-react-dom'

export default tseslint.config({
  plugins: {
    // Add the react-x and react-dom plugins
    'react-x': reactX,
    'react-dom': reactDom,
  },
  rules: {
    // other rules...
    // Enable its recommended typescript rules
    ...reactX.configs['recommended-typescript'].rules,
    ...reactDom.configs.recommended.rules,
  },
})

The client workspace is a Vite + React TypeScript application. To consume the backend API with type safety, import the shared types and use the VITE_SERVER_URL environment variable to point to your Hono server.

import { useState } from 'react'
import { ApiResponse } from 'shared'

const SERVER_URL = import.meta.env.VITE_SERVER_URL || "http://localhost:3000"

function App() {
  const [data, setData] = useState<ApiResponse | undefined>()

  async function sendRequest() {
    try {
      const req = await fetch(`${SERVER_URL}/hello")
      const res: ApiResponse = await req.json()
      setData(res)
    } catch (error) {
      console.log(error)
    }
  }

  // ... render logic
}

The server workspace uses Hono to provide a lightweight API. It is designed to be familiar to Express users. You can use Hono middleware (like cors) and return JSON data that adheres to types defined in the shared package.

import { Hono } from 'hono'
import { cors } from 'hono/cors'
import type { ApiResponse } from 'shared'

const app = new Hono()

app.use(cors())

app.get('/hello', async (c) => {
  const data: ApiResponse = {
    message: "Hello BHVR!",
    success: true
  }

  return c.json(data, { status: 200 })
})

export default app

The server package exports a default Hono application instance. This instance comes pre-configured with CORS middleware and includes the following routes:

• GET /: Returns a plain text response 'Hello Hono!'.
• GET /hello: Returns a JSON response containing an ApiResponse object with a success message.

You can import this app instance to mount it on a Node.js or Bun server (e.g., using @hono/node-server or Bun.serve).

The ApiResponse type defines the standard structure for successful API responses within the bhvr ecosystem. It ensures that every successful response contains a descriptive message and a success flag set to true.

export type ApiResponse = {
  message: string;
  success: true;
}