template: added cloudflare vite hybrid template

2026-03-16 04:27:21 +00:00 · 2025-11-21 17:55:24 +01:00
parent 9e7547e787
commit 000f8d20a8
27 changed files with 10092 additions and 0 deletions
--- a/examples/cloudflare-vite-hybrid/README.md
+++ b/examples/cloudflare-vite-hybrid/README.md
@@ -0,0 +1,249 @@
+# bknd starter: Cloudflare Vite Hybrid
+A fullstack React + Vite application with bknd integration, showcasing **hybrid mode** and Cloudflare Workers deployment.
+
+## Key Features
+
+This example demonstrates several advanced bknd features:
+
+### 🔄 Hybrid Mode
+Configure your backend **visually in development** using the Admin UI, then automatically switch to **code-only mode in production** for maximum performance. Changes made in the Admin UI are automatically synced to `bknd-config.json` and type definitions are generated in `bknd-types.d.ts`.
+
+### 📁 Filesystem Access with Vite Plugin
+Cloudflare's Vite plugin uses `unenv` which disables Node.js APIs like `fs`. This example uses bknd's `devFsVitePlugin` and `devFsWrite` to provide filesystem access during development, enabling automatic syncing of types and configuration.
+
+### ⚡ Split Configuration Pattern
+- **`config.ts`**: Shared configuration that can be safely imported in your worker
+- **`bknd.config.ts`**: Wraps the configuration with `withPlatformProxy` for CLI usage with Cloudflare bindings (should NOT be imported in your worker)
+
+This pattern prevents bundling `wrangler` into your worker while still allowing CLI access to Cloudflare resources.
+
+## Project Structure
+
+Inside of your project, you'll see the following folders and files:
+
+```text
+/
+├── src/
+│   ├── app/              # React frontend application
+│   │   ├── App.tsx
+│   │   ├── routes/
+│   │   │   ├── admin.tsx # bknd Admin UI route
+│   │   │   └── home.tsx  # Example frontend route
+│   │   └── main.tsx
+│   └── worker/
+│       └── index.ts      # Cloudflare Worker entry
+├── config.ts             # Shared bknd configuration (hybrid mode)
+├── bknd.config.ts        # CLI configuration with platform proxy
+├── bknd-config.json      # Auto-generated production config
+├── bknd-types.d.ts       # Auto-generated TypeScript types
+├── .env.example          # Auto-generated secrets template
+├── vite.config.ts        # Includes devFsVitePlugin
+├── package.json
+└── wrangler.json         # Cloudflare Workers configuration
+```
+
+## Cloudflare resources
+
+- **D1:** `wrangler.json` declares a `DB` binding. In production, replace `database_id` with your own (`wrangler d1 create <name>`).
+- **R2:** Optional `BUCKET` binding is pre-configured to show how to add additional services.
+- **Environment awareness:** `ENVIRONMENT` switch toggles hybrid behavior: production makes the database read-only, while development keeps `mode: "db"` and auto-syncs schema.
+- **Static assets:** The Assets binding points to `dist/client`. Run `npm run build` before `wrangler deploy` to upload the client bundle alongside the worker.
+
+## Admin UI & frontend
+
+- `/admin` mounts `<Admin />` from `bknd/ui` with `withProvider={{ user }}` so it respects the authenticated user returned by `useAuth`.
+- `/` showcases `useEntityQuery("todos")`, mutation helpers, and authentication state — demonstrating how the generated client types (`bknd-types.d.ts`) flow into the React code.
+
+
+## Configuration Files
+
+### `config.ts`
+The main configuration file that uses the `hybrid()` mode helper:
+
+  - Loads the generated config via an ESM `reader` (importing `./bknd-config.json`).
+  - Uses `devFsWrite` as the `writer` so the CLI/plugin can persist files even though Node's `fs` API is unavailable in Miniflare.
+  - Sets `typesFilePath`, `configFilePath`, and `syncSecrets` (writes `.env.example`) so config, types, and secret placeholders stay aligned.
+  - Seeds example data/users in `options.seed` when the database is empty.
+  - Disables the built-in admin controller because the React app renders `/admin` via `bknd/ui`.
+
+
+```typescript
+import { hybrid } from "bknd/modes";
+import { devFsWrite, type CloudflareBkndConfig } from "bknd/adapter/cloudflare";
+
+export default hybrid<CloudflareBkndConfig>({
+   // Special reader for Cloudflare Workers (no Node.js fs)
+   reader: async () => (await import("./bknd-config.json")).default,
+   // devFsWrite enables file writing via Vite plugin
+   writer: devFsWrite,
+   // Auto-sync these files in development
+   typesFilePath: "./bknd-types.d.ts",
+   configFilePath: "./bknd-config.json",
+   syncSecrets: {
+      enabled: true,
+      outFile: ".env.example",
+      format: "env",
+   },
+   app: (env) => ({
+      adminOptions: false, // Disabled - we render React app instead
+      isProduction: env.ENVIRONMENT === "production",
+      secrets: env,
+      // ... your configuration
+   }),
+});
+```
+
+### `bknd.config.ts`
+Wraps the configuration for CLI usage with Cloudflare bindings:
+
+```typescript
+import { withPlatformProxy } from "bknd/adapter/cloudflare/proxy";
+import config from "./config.ts";
+
+export default withPlatformProxy(config);
+```
+
+### `vite.config.ts`
+Includes the `devFsVitePlugin` for filesystem access:
+
+```typescript
+import { devFsVitePlugin } from "bknd/adapter/cloudflare";
+
+export default defineConfig({
+   plugins: [
+      // ...
+      devFsVitePlugin({ configFile: "config.ts" }),
+      cloudflare(),
+   ],
+});
+```
+
+## Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command            | Action                                                    |
+|:-------------------|:----------------------------------------------------------|
+| `npm install`      | Installs dependencies and generates wrangler types        |
+| `npm run dev`      | Starts local dev server with Vite at `localhost:5173`     |
+| `npm run build`    | Builds the application for production                     |
+| `npm run preview`  | Builds and previews the production build locally          |
+| `npm run deploy`   | Builds, syncs the schema and deploys to Cloudflare Workers|
+| `npm run bknd`     | Runs bknd CLI commands                                    |
+| `npm run bknd:types` | Generates TypeScript types from your schema             |
+| `npm run cf:types` | Generates Cloudflare Worker types from `wrangler.json`    |
+| `npm run check`    | Type checks and does a dry-run deployment                 |
+
+## Development Workflow
+
+1. **Install dependencies:**
+   ```sh
+   npm install
+   ```
+
+2. **Start development server:**
+   ```sh
+   npm run dev
+   ```
+
+3. **Visit the Admin UI** at `http://localhost:5173/admin` to configure your backend visually:
+   - Create entities and fields
+   - Configure authentication
+   - Set up relationships
+   - Define permissions
+
+4. **Watch for auto-generated files:**
+   - `bknd-config.json` - Production configuration
+   - `bknd-types.d.ts` - TypeScript types
+   - `.env.example` - Required secrets
+
+5. **Use the CLI** for manual operations:
+   ```sh
+   # Generate types manually
+   npm run bknd:types
+   
+   # Sync the production database schema (only safe operations are applied)
+   CLOUDFLARE_ENV=production npm run bknd -- sync --force
+   ```
+
+## Before you deploy
+
+If you're using a D1 database, make sure to create a database in your Cloudflare account and replace the `database_id` accordingly in `wrangler.json`:
+
+```sh
+npx wrangler d1 create my-database
+```
+
+Update `wrangler.json`:
+```json
+{
+   "d1_databases": [
+      {
+         "binding": "DB",
+         "database_name": "my-database",
+         "database_id": "your-database-id-here"
+      }
+   ]
+}
+```
+
+## Deployment
+
+Deploy to Cloudflare Workers:
+
+```sh
+npm run deploy
+```
+
+This will:
+1. Set `ENVIRONMENT=production` to activate code-only mode
+2. Build the Vite application
+3. Deploy to Cloudflare Workers using Wrangler
+
+In production, bknd will:
+- Use the configuration from `bknd-config.json` (read-only)
+- Skip config validation for better performance
+- Expect secrets to be provided via environment variables
+
+## Environment Variables
+
+Make sure to set your secrets in the Cloudflare Workers dashboard or via Wrangler:
+
+```sh
+# Example: Set JWT secret
+npx wrangler secret put auth.jwt.secret
+```
+
+Check `.env.example` for all required secrets after running the app in development mode.
+
+## How Hybrid Mode Works
+
+```mermaid
+graph LR
+    A[Development] -->|Visual Config| B[Admin UI]
+    B -->|Auto-sync| C[bknd-config.json]
+    B -->|Auto-sync| D[bknd-types.d.ts]
+    C -->|Deploy| E[Production]
+    E -->|Read-only| F[Code-only Mode]
+```
+
+1. **In Development:** `mode: "db"` - Configuration stored in database, editable via Admin UI
+2. **Auto-sync:** Changes automatically written to `bknd-config.json` and types to `bknd-types.d.ts`
+3. **In Production:** `mode: "code"` - Configuration read from `bknd-config.json`, no database overhead
+
+## Why devFsVitePlugin?
+
+Cloudflare's Vite plugin removes Node.js APIs for Workers compatibility. This breaks filesystem operations needed for:
+- Auto-syncing TypeScript types (`syncTypes` plugin)
+- Auto-syncing configuration (`syncConfig` plugin)
+- Auto-syncing secrets (`syncSecrets` plugin)
+
+The `devFsVitePlugin` + `devFsWrite` combination provides a workaround by using Vite's module system to enable file writes during development.
+
+## Want to learn more?
+
+- [Cloudflare Integration Documentation](https://docs.bknd.io/integration/cloudflare)
+- [Hybrid Mode Guide](https://docs.bknd.io/usage/introduction#hybrid-mode)
+- [Mode Helpers Documentation](https://docs.bknd.io/usage/introduction#mode-helpers)
+- [Discord Community](https://discord.gg/952SFk8Tb8)
+