git.stevedylan.dev

docs/pages/getting-started.mdx 9.6 K raw

# Get started

bhvr is a framework used to build apps that are not tied down to a single provider, and each piece can be deployed in multiple places.

## Quickstart

::::steps

### Create a New Project

To start using bhvr make sure you have [Bun](https://bun.sh) installed first, then run the following command.

```bash [terminal]
bun create bhvr@latest
```

The stack is composed of the following:

```
.
├── client/               # React frontend
├── server/               # Hono backend
├── shared/               # Shared TypeScript definitions
│   └── src/types/        # Type definitions used by both client and server
└── package.json          # Root package.json with workspaces
```

### Start Up Dev Server

Once you have created your project you can `cd` into it and run the dev server

```bash [terminal]
bun run dev
```

This will spin up dev servers for the `server`, `client`, and `shared` packages

Try updating the API endpoints in the `server` package

```typescript [server/src/index.ts]
import { Hono } from 'hono'
import { cors } from 'hono/cors'
import type { ApiResponse } from 'shared/dist'

const app = new Hono()

app.use(cors())

app.get('/', (c) => {
  return c.text('Hello Hono!')
})

app.get('/hello', async (c) => {

  const data: ApiResponse = {
    message: "Hello BHVR!",
    success: true
  }

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

export default app
```

Also try editing the React app in `client`

```tsx [client/src/App.tsx]
import { useState } from 'react'
import beaver from './assets/beaver.svg'
import { ApiResponse } from 'shared'
import './App.css'

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)
    }
  }

  return (
    <>
      <div>
        <a href="https://github.com/stevedylandev/bhvr" target="_blank">
          <img src={beaver} className="logo" alt="beaver logo" />
        </a>
      </div>
      <h1>bhvr</h1>
      <h2>Bun + Hono + Vite + React</h2>
      <p>A typesafe fullstack monorepo</p>
      <div className="card">
        <button onClick={sendRequest}>
          Call API
        </button>
        {data && (
          <pre className='response'>
            <code>
            Message: {data.message} <br />
            Success: {data.success.toString()}
            </code>
          </pre>
        )}
      </div>
      <p className="read-the-docs">
        Click the beaver to learn more
      </p>
    </>
  )
}

export default App
```

### Build Project

Once you have your project ready to go you can use the build command to build the `client` and `shared` packages

```bash [terminal]
bun run build
```

From there you can select multiple [deployment options](/deployment/client/orbiter)

::::

## Manual Setup

There are few other ways you can get started with bhvr outside of the CLI

### Clone or Use GitHub Template

If you visit the [bhvr repo](https://github.com/stevedylandev/bhvr) you can click the "Use This Template" button in the top right.

![screenshot](https://cdn.stevedylan.dev/ipfs/bafybeicf2phwxwkqwl7uhr4awdrd5h7a37mqd7eay3czbpaldozjze3noa)

Alternatively you can clone the template

```bash [terminal]
git clone https://github.com/stevedylandev/bhvr
```

### Create from Scratch

To recreate bhvr from scratch you can do the following

::::steps

#### Install Bun

```bash [terminal]
curl -fsSL https://bun.sh/install | bash
```

#### Setup Project

```bash [terminal]
mkdir bhvr
cd bhvr
bun init -y
rm index.ts
mkdir shared
```

#### Update Root Files

Update `tsconfig.json` with the following settings

```json
{
  "compilerOptions": {
    // Environment setup & latest features
    "lib": ["ESNext", "DOM", "DOM.Iterable"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "allowJs": true,

    // Path resolution
    "baseUrl": "./",
    "paths": {
      "@server/*": ["./server/src/*"],
      "@client/*": ["./client/src/*"],
      "@shared/*": ["./shared/src/*"]
    },

    // Module resolution
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "verbatimModuleSyntax": true,

    // Strictness and best practices
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "experimentalDecorators": true,

    // Output control
    "skipLibCheck": true,

    // Optional strict flags (disabled by default)
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noPropertyAccessFromIndexSignature": false
  }
}
```

Update the `package.json` with the following contents

```json
{
  "name": "bhvr",
  "version": "0.3.0",
  "description": "A monorepo template built with Bun, Hono, Vite, and React",
  "license": "MIT",
  "workspaces": [
    "./server",
    "./client",
    "./shared"
  ],
  "scripts": {
    "dev": "turbo dev",
    "dev:client": "turbo dev --filter=client",
    "dev:server": "turbo dev --filter=server",
    "build": "turbo build",
    "build:client": "turbo build --filter=client",
    "build:server": "turbo build --filter=server",
    "lint": "turbo lint",
    "type-check": "turbo type-check",
    "test": "turbo test",
    "postinstall": "turbo build --filter=shared --filter=server"
  },
  "keywords": [
    "bun",
    "hono",
    "react",
    "vite",
    "monorepo"
  ],
  "devDependencies": {
    "bun-types": "latest",
    "turbo": "^2.5.5"
  },
  "peerDependencies": {
    "typescript": "^5.0.0"
  }
}
```

#### Setup Client

Setup Vite with your preferences

```bash [terminal]
bun create vite@latest client
cd client
```

Update the `package.json` file

```json
{
  "name": "client",
  "private": true,
  "version": "0.0.1",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "shared": "workspace:*", // [!code focus]
    "server": "workspace:*" // [!code focus]
  },
  "devDependencies": {
    "@eslint/js": "^9.22.0",
    "@types/node": "^22.15.2", // [!code focus]
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "@vitejs/plugin-react": "^4.3.4",
    "eslint": "^9.22.0",
    "eslint-plugin-react-hooks": "^5.2.0",
    "eslint-plugin-react-refresh": "^0.4.19",
    "globals": "^16.0.0",
    "typescript": "~5.7.2",
    "typescript-eslint": "^8.26.1",
    "vite": "^6.3.1"
  }
}
```

Update the `tsconfig.json` file

```json
{
  "extends": "../tsconfig.json", // [!code focus]
  "files": [],
  "references": [{ "path": "./tsconfig.node.json" }, { "path": "./tsconfig.app.json"}]
}
```

Update the `vite.config.ts` file

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path' // [!code focus]

export default defineConfig({
  plugins: [react()],
  resolve: { // [!code focus]
    alias: { // [!code focus]
      "@client": path.resolve(__dirname, "./src"), // [!code focus]
      "@server": path.resolve(__dirname, "../server/src"), // [!code focus]
      "@shared": path.resolve(__dirname, "../shared/src") // [!code focus]
    }
  }
})
```

#### Setup Server

Create `server` repo with Hono

```bash [terminal]
bun create hono@latest server
cd server
```

Update the `tsconfig.json` file

```json
{
  "extends": "../tsconfig.json", // [!code focus]
  "compilerOptions": {
    // Environment settings
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "ESNext",
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx",

    // Types
    "types": ["bun-types"],

    // Output settings
    "declaration": true, // [!code focus]
    "outDir": "dist", // [!code focus]
    "noEmit": false, // [!code focus]
    "emitDecoratorMetadata": true, // [!code focus]

    // Module resolution
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": false
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

Update the `package.json` file

```json
{
  "name": "server",
  "version": "0.0.1",
  "main": "dist/index.js", // [!code focus]
  "types": "dist/index.d.ts", // [!code focus]
  "scripts": {
    "build": "tsc",
    "dev": "bun run --hot src/index.ts"
  },
  "dependencies": {
    "hono": "^4.7.7",
    "shared": "workspace:*" // [!code focus]
  },
  "devDependencies": {
    "@types/bun": "latest"
  }
}
```

#### Setup Shared

Initialize the directory

```bash [terminal]
cd shared
bun init -y
mkdir src
mv index.ts src/index.ts
```

Update the `tsconfig.json` file

```json
{
  "extends": "../tsconfig.json", // [!code focus]
  "compilerOptions": {
    // Environment setup
    "lib": ["ESNext"],
    "target": "ESNext",
    "module": "ESNext",

    // Output configuration
    "declaration": true, // [!code focus]
    "outDir": "./dist", // [!code focus]
    "noEmit": false, // [!code focus]

    // Type checking
    "strict": true,
    "skipLibCheck": true,

    // Additional checks
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true
  },
  "include": ["src/**/*"], // [!code focus]
  "exclude": ["node_modules", "**/*.test.ts", "dist"] // [!code focus]
}
```

Update the `package.json` file

```json
{
  "name": "shared",
  "version": "0.0.1",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  },
  "devDependencies": {
    "typescript": "^5.2.2"
  }
}
```

#### Start Up bhvr 🦫

```bash [terminal]
bun install
bun dev
```

::::

1	# Get started
2
3	bhvr is a framework used to build apps that are not tied down to a single provider, and each piece can be deployed in multiple places.
4
5	## Quickstart
6
7	::::steps
8
9	### Create a New Project
10
11	To start using bhvr make sure you have [Bun](https://bun.sh) installed first, then run the following command.
12
13	```bash [terminal]
14	bun create bhvr@latest
15	```
16
17	The stack is composed of the following:
18
19	```
20	.
21	├── client/ # React frontend
22	├── server/ # Hono backend
23	├── shared/ # Shared TypeScript definitions
24	│ └── src/types/ # Type definitions used by both client and server
25	└── package.json # Root package.json with workspaces
26	```
27
28	### Start Up Dev Server
29
30	Once you have created your project you can `cd` into it and run the dev server
31
32	```bash [terminal]
33	bun run dev
34	```
35
36	This will spin up dev servers for the `server`, `client`, and `shared` packages
37
38	Try updating the API endpoints in the `server` package
39
40	```typescript [server/src/index.ts]
41	import { Hono } from 'hono'
42	import { cors } from 'hono/cors'
43	import type { ApiResponse } from 'shared/dist'
44
45	const app = new Hono()
46
47	app.use(cors())
48
49	app.get('/', (c) => {
50	return c.text('Hello Hono!')
51	})
52
53	app.get('/hello', async (c) => {
54
55	const data: ApiResponse = {
56	message: "Hello BHVR!",
57	success: true
58	}
59
60	return c.json(data, { status: 200 })
61	})
62
63	export default app
64	```
65
66	Also try editing the React app in `client`
67
68	```tsx [client/src/App.tsx]
69	import { useState } from 'react'
70	import beaver from './assets/beaver.svg'
71	import { ApiResponse } from 'shared'
72	import './App.css'
73
74	const SERVER_URL = import.meta.env.VITE_SERVER_URL \|\| "http://localhost:3000"
75
76	function App() {
77	const [data, setData] = useState<ApiResponse \| undefined>()
78
79	async function sendRequest() {
80	try {
81	const req = await fetch(`${SERVER_URL}/hello`)
82	const res: ApiResponse = await req.json()
83	setData(res)
84	} catch (error) {
85	console.log(error)
86	}
87	}
88
89	return (
90	<>
91	<div>
92	<a href="https://github.com/stevedylandev/bhvr" target="_blank">
93	<img src={beaver} className="logo" alt="beaver logo" />
94	</a>
95	</div>
96	<h1>bhvr</h1>
97	<h2>Bun + Hono + Vite + React</h2>
98	<p>A typesafe fullstack monorepo</p>
99	<div className="card">
100	<button onClick={sendRequest}>
101	Call API
102	</button>
103	{data && (
104	<pre className='response'>
105	<code>
106	Message: {data.message} <br />
107	Success: {data.success.toString()}
108	</code>
109	</pre>
110	)}
111	</div>
112	<p className="read-the-docs">
113	Click the beaver to learn more
114	</p>
115	</>
116	)
117	}
118
119	export default App
120	```
121
122	### Build Project
123
124	Once you have your project ready to go you can use the build command to build the `client` and `shared` packages
125
126	```bash [terminal]
127	bun run build
128	```
129
130	From there you can select multiple [deployment options](/deployment/client/orbiter)
131
132	::::
133
134	## Manual Setup
135
136	There are few other ways you can get started with bhvr outside of the CLI
137
138	### Clone or Use GitHub Template
139
140	If you visit the [bhvr repo](https://github.com/stevedylandev/bhvr) you can click the "Use This Template" button in the top right.
141
142	![screenshot](https://cdn.stevedylan.dev/ipfs/bafybeicf2phwxwkqwl7uhr4awdrd5h7a37mqd7eay3czbpaldozjze3noa)
143
144	Alternatively you can clone the template
145
146	```bash [terminal]
147	git clone https://github.com/stevedylandev/bhvr
148	```
149
150	### Create from Scratch
151
152	To recreate bhvr from scratch you can do the following
153
154	::::steps
155
156	#### Install Bun
157
158	```bash [terminal]
159	curl -fsSL https://bun.sh/install \| bash
160	```
161
162	#### Setup Project
163
164	```bash [terminal]
165	mkdir bhvr
166	cd bhvr
167	bun init -y
168	rm index.ts
169	mkdir shared
170	```
171
172	#### Update Root Files
173
174	Update `tsconfig.json` with the following settings
175
176	```json
177	{
178	"compilerOptions": {
179	// Environment setup & latest features
180	"lib": ["ESNext", "DOM", "DOM.Iterable"],
181	"target": "ESNext",
182	"module": "ESNext",
183	"moduleDetection": "force",
184	"jsx": "react-jsx",
185	"allowJs": true,
186
187	// Path resolution
188	"baseUrl": "./",
189	"paths": {
190	"@server/": ["./server/src/"],
191	"@client/": ["./client/src/"],
192	"@shared/": ["./shared/src/"]
193	},
194
195	// Module resolution
196	"moduleResolution": "bundler",
197	"allowSyntheticDefaultImports": true,
198	"esModuleInterop": true,
199	"verbatimModuleSyntax": true,
200
201	// Strictness and best practices
202	"strict": true,
203	"forceConsistentCasingInFileNames": true,
204	"noFallthroughCasesInSwitch": true,
205	"noUncheckedIndexedAccess": true,
206	"experimentalDecorators": true,
207
208	// Output control
209	"skipLibCheck": true,
210
211	// Optional strict flags (disabled by default)
212	"noUnusedLocals": false,
213	"noUnusedParameters": false,
214	"noPropertyAccessFromIndexSignature": false
215	}
216	}
217	```
218
219	Update the `package.json` with the following contents
220
221	```json
222	{
223	"name": "bhvr",
224	"version": "0.3.0",
225	"description": "A monorepo template built with Bun, Hono, Vite, and React",
226	"license": "MIT",
227	"workspaces": [
228	"./server",
229	"./client",
230	"./shared"
231	],
232	"scripts": {
233	"dev": "turbo dev",
234	"dev:client": "turbo dev --filter=client",
235	"dev:server": "turbo dev --filter=server",
236	"build": "turbo build",
237	"build:client": "turbo build --filter=client",
238	"build:server": "turbo build --filter=server",
239	"lint": "turbo lint",
240	"type-check": "turbo type-check",
241	"test": "turbo test",
242	"postinstall": "turbo build --filter=shared --filter=server"
243	},
244	"keywords": [
245	"bun",
246	"hono",
247	"react",
248	"vite",
249	"monorepo"
250	],
251	"devDependencies": {
252	"bun-types": "latest",
253	"turbo": "^2.5.5"
254	},
255	"peerDependencies": {
256	"typescript": "^5.0.0"
257	}
258	}
259	```
260
261	#### Setup Client
262
263	Setup Vite with your preferences
264
265	```bash [terminal]
266	bun create vite@latest client
267	cd client
268	```
269
270	Update the `package.json` file
271
272	```json
273	{
274	"name": "client",
275	"private": true,
276	"version": "0.0.1",
277	"type": "module",
278	"scripts": {
279	"dev": "vite",
280	"build": "tsc -b && vite build",
281	"lint": "eslint .",
282	"preview": "vite preview"
283	},
284	"dependencies": {
285	"react": "^19.0.0",
286	"react-dom": "^19.0.0",
287	"shared": "workspace:*", // [!code focus]
288	"server": "workspace:*" // [!code focus]
289	},
290	"devDependencies": {
291	"@eslint/js": "^9.22.0",
292	"@types/node": "^22.15.2", // [!code focus]
293	"@types/react": "^19.0.10",
294	"@types/react-dom": "^19.0.4",
295	"@vitejs/plugin-react": "^4.3.4",
296	"eslint": "^9.22.0",
297	"eslint-plugin-react-hooks": "^5.2.0",
298	"eslint-plugin-react-refresh": "^0.4.19",
299	"globals": "^16.0.0",
300	"typescript": "~5.7.2",
301	"typescript-eslint": "^8.26.1",
302	"vite": "^6.3.1"
303	}
304	}
305	```
306
307	Update the `tsconfig.json` file
308
309	```json
310	{
311	"extends": "../tsconfig.json", // [!code focus]
312	"files": [],
313	"references": [{ "path": "./tsconfig.node.json" }, { "path": "./tsconfig.app.json"}]
314	}
315	```
316
317	Update the `vite.config.ts` file
318
319	```typescript
320	import { defineConfig } from 'vite'
321	import react from '@vitejs/plugin-react'
322	import path from 'path' // [!code focus]
323
324	export default defineConfig({
325	plugins: [react()],
326	resolve: { // [!code focus]
327	alias: { // [!code focus]
328	"@client": path.resolve(__dirname, "./src"), // [!code focus]
329	"@server": path.resolve(__dirname, "../server/src"), // [!code focus]
330	"@shared": path.resolve(__dirname, "../shared/src") // [!code focus]
331	}
332	}
333	})
334	```
335
336	#### Setup Server
337
338	Create `server` repo with Hono
339
340	```bash [terminal]
341	bun create hono@latest server
342	cd server
343	```
344
345	Update the `tsconfig.json` file
346
347	```json
348	{
349	"extends": "../tsconfig.json", // [!code focus]
350	"compilerOptions": {
351	// Environment settings
352	"lib": ["ESNext"],
353	"target": "ESNext",
354	"module": "ESNext",
355	"jsx": "react-jsx",
356	"jsxImportSource": "hono/jsx",
357
358	// Types
359	"types": ["bun-types"],
360
361	// Output settings
362	"declaration": true, // [!code focus]
363	"outDir": "dist", // [!code focus]
364	"noEmit": false, // [!code focus]
365	"emitDecoratorMetadata": true, // [!code focus]
366
367	// Module resolution
368	"moduleResolution": "bundler",
369	"allowImportingTsExtensions": false
370	},
371	"include": ["src/*/"],
372	"exclude": ["node_modules", "dist"]
373	}
374	```
375
376	Update the `package.json` file
377
378	```json
379	{
380	"name": "server",
381	"version": "0.0.1",
382	"main": "dist/index.js", // [!code focus]
383	"types": "dist/index.d.ts", // [!code focus]
384	"scripts": {
385	"build": "tsc",
386	"dev": "bun run --hot src/index.ts"
387	},
388	"dependencies": {
389	"hono": "^4.7.7",
390	"shared": "workspace:*" // [!code focus]
391	},
392	"devDependencies": {
393	"@types/bun": "latest"
394	}
395	}
396	```
397
398	#### Setup Shared
399
400	Initialize the directory
401
402	```bash [terminal]
403	cd shared
404	bun init -y
405	mkdir src
406	mv index.ts src/index.ts
407	```
408
409	Update the `tsconfig.json` file
410
411	```json
412	{
413	"extends": "../tsconfig.json", // [!code focus]
414	"compilerOptions": {
415	// Environment setup
416	"lib": ["ESNext"],
417	"target": "ESNext",
418	"module": "ESNext",
419
420	// Output configuration
421	"declaration": true, // [!code focus]
422	"outDir": "./dist", // [!code focus]
423	"noEmit": false, // [!code focus]
424
425	// Type checking
426	"strict": true,
427	"skipLibCheck": true,
428
429	// Additional checks
430	"noFallthroughCasesInSwitch": true,
431	"noUncheckedIndexedAccess": true
432	},
433	"include": ["src/*/"], // [!code focus]
434	"exclude": ["node_modules", "*/.test.ts", "dist"] // [!code focus]
435	}
436	```
437
438	Update the `package.json` file
439
440	```json
441	{
442	"name": "shared",
443	"version": "0.0.1",
444	"main": "dist/index.js",
445	"types": "dist/index.d.ts",
446	"scripts": {
447	"build": "tsc",
448	"dev": "tsc --watch"
449	},
450	"devDependencies": {
451	"typescript": "^5.2.2"
452	}
453	}
454	```
455
456	#### Start Up bhvr 🦫
457
458	```bash [terminal]
459	bun install
460	bun dev
461	```
462
463	::::