imbytecat/fullstack-starter
1
1
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: imbytecat:58d7a453b64c66ad70acd2eff6959464ab171b86
Branches Tags
imbytecat:main imbytecat:ux imbytecat:backup/legacy imbytecat:backup/ux
..
compare: imbytecat:9d8a38a4c49a3379aa8d19b43bc40ae6ee270042
Branches Tags
imbytecat:main imbytecat:ux imbytecat:backup/legacy imbytecat:backup/ux

2 Commits
58d7a453b6 ... 9d8a38a4c4

Author SHA1 Message Date
imbytecat
9d8a38a4c4 fix: 修正 ORPC handler 语义、加固 Electron 安全、优化构建与运行时配置 
- todo.router: create 错误码 NOT_FOUND → INTERNAL_SERVER_ERROR，remove 增加存在性检查
- __root: devtools 仅在 DEV 环境渲染
- Electron: 添加 will-navigate 导航拦截、显式安全 webPreferences、deny-all 权限请求
- sidecar: 空 catch 块补充意图注释，新增 lastResolvedUrl getter
- todo.contract: 硬编码 omit 改用 generatedFieldKeys
- router: QueryClient 添加 staleTime/retry 默认值
- turbo: build 任务精细化 inputs 提升缓存命中率
- fields: id() 改为模块私有
 2026-03-05 14:06:43 +08:00
imbytecat
cd7448c3b3 docs: 统一使用 bun run <script> 避免与 Bun 内置子命令冲突 
bun build 会调用 Bun 内置 bundler 而非 package.json script，
将所有文档中的 bun <script> 改为 bun run <script> 以避免歧义。
bun test 保留不变（直接使用 Bun 内置 test runner）。
 2026-03-05 12:57:26 +08:00
12 changed files with 155 additions and 123 deletions
Expand all files Collapse all files

92
AGENTS.md
View File

@@ -4,7 +4,7 @@ Guidelines for AI agents working in this Bun monorepo.
## Project Overview ## Project Overview
> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run` / `bun <script>` for scripts. Never use `npm`, `npx`, or `node`.** > **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.**
- **Monorepo**: Bun workspaces + Turborepo orchestration - **Monorepo**: Bun workspaces + Turborepo orchestration
- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js** - **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
@@ -18,57 +18,57 @@ Guidelines for AI agents working in this Bun monorepo.
### Root Commands (via Turbo) ### Root Commands (via Turbo)
```bash ```bash
bun dev # Start all apps in dev mode bun run dev # Start all apps in dev mode
bun build # Build all apps bun run build # Build all apps
bun compile # Compile server to standalone binary (current platform) bun run compile # Compile server to standalone binary (current platform)
bun compile:darwin # Compile server for macOS (arm64 + x64) bun run compile:darwin # Compile server for macOS (arm64 + x64)
bun compile:linux # Compile server for Linux (x64 + arm64) bun run compile:linux # Compile server for Linux (x64 + arm64)
bun compile:windows # Compile server for Windows x64 bun run compile:windows # Compile server for Windows x64
bun dist # Package desktop distributable (current platform) bun run dist # Package desktop distributable (current platform)
bun dist:linux # Package desktop for Linux (x64 + arm64) bun run dist:linux # Package desktop for Linux (x64 + arm64)
bun dist:mac # Package desktop for macOS (arm64 + x64) bun run dist:mac # Package desktop for macOS (arm64 + x64)
bun dist:win # Package desktop for Windows x64 bun run dist:win # Package desktop for Windows x64
bun fix # Lint + format (Biome auto-fix) bun run fix # Lint + format (Biome auto-fix)
bun typecheck # TypeScript check across monorepo bun run typecheck # TypeScript check across monorepo
``` ```
### Server App (`apps/server`) ### Server App (`apps/server`)
```bash ```bash
bun dev # Vite dev server (localhost:3000) bun run dev # Vite dev server (localhost:3000)
bun build # Production build -> .output/ bun run build # Production build -> .output/
bun compile # Compile to standalone binary (current platform) bun run compile # Compile to standalone binary (current platform)
bun compile:darwin # Compile for macOS (arm64 + x64) bun run compile:darwin # Compile for macOS (arm64 + x64)
bun compile:darwin:arm64 # Compile for macOS arm64 bun run compile:darwin:arm64 # Compile for macOS arm64
bun compile:darwin:x64 # Compile for macOS x64 bun run compile:darwin:x64 # Compile for macOS x64
bun compile:linux # Compile for Linux (x64 + arm64) bun run compile:linux # Compile for Linux (x64 + arm64)
bun compile:linux:arm64 # Compile for Linux arm64 bun run compile:linux:arm64 # Compile for Linux arm64
bun compile:linux:x64 # Compile for Linux x64 bun run compile:linux:x64 # Compile for Linux x64
bun compile:windows # Compile for Windows (default: x64) bun run compile:windows # Compile for Windows (default: x64)
bun compile:windows:x64 # Compile for Windows x64 bun run compile:windows:x64 # Compile for Windows x64
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
# Database (Drizzle) # Database (Drizzle)
bun db:generate # Generate migrations from schema bun run db:generate # Generate migrations from schema
bun db:migrate # Run migrations bun run db:migrate # Run migrations
bun db:push # Push schema (dev only) bun run db:push # Push schema (dev only)
bun db:studio # Open Drizzle Studio bun run db:studio # Open Drizzle Studio
``` ```
### Desktop App (`apps/desktop`) ### Desktop App (`apps/desktop`)
```bash ```bash
bun dev # electron-vite dev mode (requires server dev running) bun run dev # electron-vite dev mode (requires server dev running)
bun build # electron-vite build (main + preload) bun run build # electron-vite build (main + preload)
bun dist # Build + package for current platform bun run dist # Build + package for current platform
bun dist:linux # Build + package for Linux (x64 + arm64) bun run dist:linux # Build + package for Linux (x64 + arm64)
bun dist:linux:x64 # Build + package for Linux x64 bun run dist:linux:x64 # Build + package for Linux x64
bun dist:linux:arm64 # Build + package for Linux arm64 bun run dist:linux:arm64 # Build + package for Linux arm64
bun dist:mac # Build + package for macOS (arm64 + x64) bun run dist:mac # Build + package for macOS (arm64 + x64)
bun dist:mac:arm64 # Build + package for macOS arm64 bun run dist:mac:arm64 # Build + package for macOS arm64
bun dist:mac:x64 # Build + package for macOS x64 bun run dist:mac:x64 # Build + package for macOS x64
bun dist:win # Build + package for Windows x64 bun run dist:win # Build + package for Windows x64
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
``` ```
### Testing ### Testing
@@ -160,7 +160,7 @@ export const myTable = pgTable('my_table', {
## Critical Rules ## Critical Rules
**DO:** **DO:**
- Run `bun fix` before committing - Run `bun run fix` before committing
- Use `@/*` path aliases (not relative imports) - Use `@/*` path aliases (not relative imports)
- Include `createdAt`/`updatedAt` on all tables - Include `createdAt`/`updatedAt` on all tables
- Use `catalog:` for dependency versions - Use `catalog:` for dependency versions
@@ -178,9 +178,9 @@ export const myTable = pgTable('my_table', {
## Git Workflow ## Git Workflow
1. Make changes following style guide 1. Make changes following style guide
2. `bun fix` - auto-format and lint 2. `bun run fix` - auto-format and lint
3. `bun typecheck` - verify types 3. `bun run typecheck` - verify types
4. `bun dev` - test locally 4. `bun run dev` - test locally
5. Commit with descriptive message 5. Commit with descriptive message
## Directory Structure ## Directory Structure

36
apps/desktop/AGENTS.md
View File

@@ -4,7 +4,7 @@ Thin Electron shell hosting the fullstack server app.
## Tech Stack ## Tech Stack
> **⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Never use `npm`, `npx`, `yarn`, or `pnpm`.** > **⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, `yarn`, or `pnpm`.**
- **Type**: Electron desktop shell - **Type**: Electron desktop shell
- **Design**: Server-driven desktop (thin native window hosting web app) - **Design**: Server-driven desktop (thin native window hosting web app)
@@ -22,18 +22,18 @@ Thin Electron shell hosting the fullstack server app.
## Commands ## Commands
```bash ```bash
bun dev # electron-vite dev (requires server dev running) bun run dev # electron-vite dev (requires server dev running)
bun build # electron-vite build (main + preload) bun run build # electron-vite build (main + preload)
bun dist # Build + package for current platform bun run dist # Build + package for current platform
bun dist:linux # Build + package for Linux (x64 + arm64) bun run dist:linux # Build + package for Linux (x64 + arm64)
bun dist:linux:x64 # Build + package for Linux x64 bun run dist:linux:x64 # Build + package for Linux x64
bun dist:linux:arm64 # Build + package for Linux arm64 bun run dist:linux:arm64 # Build + package for Linux arm64
bun dist:mac # Build + package for macOS (arm64 + x64) bun run dist:mac # Build + package for macOS (arm64 + x64)
bun dist:mac:arm64 # Build + package for macOS arm64 bun run dist:mac:arm64 # Build + package for macOS arm64
bun dist:mac:x64 # Build + package for macOS x64 bun run dist:mac:x64 # Build + package for macOS x64
bun dist:win # Build + package for Windows x64 bun run dist:win # Build + package for Windows x64
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
``` ```
## Directory Structure ## Directory Structure
@@ -56,13 +56,13 @@ bun typecheck # TypeScript check
## Development Workflow ## Development Workflow
1. **Start server**: `bun dev` in `apps/server` (or use root `bun dev` via Turbo). 1. **Start server**: `bun run dev` in `apps/server` (or use root `bun run dev` via Turbo).
2. **Start desktop**: `bun dev` in `apps/desktop`. 2. **Start desktop**: `bun run dev` in `apps/desktop`.
3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow. 3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow.
## Production Build Workflow ## Production Build Workflow
From monorepo root, run `bun dist` to execute the full pipeline automatically (via Turbo task dependencies): From monorepo root, run `bun run dist` to execute the full pipeline automatically (via Turbo task dependencies):
1. **Build server**: `apps/server` → `vite build` → `.output/` 1. **Build server**: `apps/server` → `vite build` → `.output/`
2. **Compile server**: `apps/server` → `bun compile.ts --target ...` → `out/server-{os}-{arch}` 2. **Compile server**: `apps/server` → `bun compile.ts --target ...` → `out/server-{os}-{arch}`
@@ -70,8 +70,8 @@ From monorepo root, run `bun dist` to execute the full pipeline automatically (v
The `electron-builder.yml` `extraResources` config reads binaries directly from `../server/out/`, no manual copy needed. The `electron-builder.yml` `extraResources` config reads binaries directly from `../server/out/`, no manual copy needed.
To build for a specific platform explicitly, use `bun dist:linux` / `bun dist:mac` / `bun dist:win` in `apps/desktop`. To build for a specific platform explicitly, use `bun run dist:linux` / `bun run dist:mac` / `bun run dist:win` in `apps/desktop`.
For single-arch output, use `bun dist:linux:x64`, `bun dist:linux:arm64`, `bun dist:mac:x64`, or `bun dist:mac:arm64`. For single-arch output, use `bun run dist:linux:x64`, `bun run dist:linux:arm64`, `bun run dist:mac:x64`, or `bun run dist:mac:arm64`.
## Development Principles ## Development Principles

27
apps/desktop/src/main/index.ts
View File

@@ -1,5 +1,5 @@
import { join } from 'node:path' import { join } from 'node:path'
import { app, BrowserWindow, dialog, shell } from 'electron' import { app, BrowserWindow, dialog, session, shell } from 'electron'
import { createSidecarRuntime } from './sidecar' import { createSidecarRuntime } from './sidecar'
const DEV_SERVER_URL = 'http://localhost:3000' const DEV_SERVER_URL = 'http://localhost:3000'
@@ -61,6 +61,8 @@ const createWindow = async () => {
webPreferences: { webPreferences: {
preload: join(__dirname, '../preload/index.js'), preload: join(__dirname, '../preload/index.js'),
sandbox: true, sandbox: true,
contextIsolation: true,
nodeIntegration: false,
}, },
}) })
mainWindow = windowRef mainWindow = windowRef
@@ -78,6 +80,21 @@ const createWindow = async () => {
return { action: 'deny' } return { action: 'deny' }
}) })
windowRef.webContents.on('will-navigate', (event, url) => {
const allowed = [DEV_SERVER_URL, sidecar.lastResolvedUrl].filter((v): v is string => v != null)
const isAllowed = allowed.some((origin) => url.startsWith(origin))
if (!isAllowed) {
event.preventDefault()
if (canOpenExternally(url)) {
void shell.openExternal(url)
} else if (!app.isPackaged) {
console.warn(`Blocked navigation to: ${url}`)
}
}
})
windowRef.on('closed', () => { windowRef.on('closed', () => {
if (mainWindow === windowRef) { if (mainWindow === windowRef) {
mainWindow = null mainWindow = null
@@ -151,7 +168,13 @@ const handleWindowCreationError = (error: unknown, context: string) => {
app app
.whenReady() .whenReady()
.then(() => ensureWindow()) .then(() => {
session.defaultSession.setPermissionRequestHandler((_webContents, _permission, callback) => {
callback(false)
})
return ensureWindow()
})
.catch((error) => { .catch((error) => {
handleWindowCreationError(error, 'Failed to create window') handleWindowCreationError(error, 'Failed to create window')
}) })

9
apps/desktop/src/main/sidecar.ts
View File

@@ -27,6 +27,7 @@ type SidecarRuntimeOptions = {
type SidecarRuntime = { type SidecarRuntime = {
resolveUrl: () => Promise<string> resolveUrl: () => Promise<string>
stop: () => void stop: () => void
lastResolvedUrl: string | null
} }
const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms)) const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
@@ -72,7 +73,9 @@ const isServerReady = async (url: string): Promise<boolean> => {
return true return true
} }
} catch {} } catch {
// Expected: probe request fails while server is still starting up
}
} }
return false return false
@@ -239,11 +242,15 @@ export const createSidecarRuntime = (options: SidecarRuntimeOptions): SidecarRun
throw new Error('Dev server not responding. Run `bun dev` in apps/server first.') throw new Error('Dev server not responding. Run `bun dev` in apps/server first.')
} }
state.url = options.devServerUrl
return options.devServerUrl return options.devServerUrl
} }
return { return {
resolveUrl, resolveUrl,
stop, stop,
get lastResolvedUrl() {
return state.url
},
} }
} }

38
apps/server/AGENTS.md
View File

@@ -4,7 +4,7 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
## Tech Stack ## Tech Stack
> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.** > **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**
- **Framework**: TanStack Start (React 19 SSR, file-based routing) - **Framework**: TanStack Start (React 19 SSR, file-based routing)
- **Runtime**: Bun — **NOT Node.js** - **Runtime**: Bun — **NOT Node.js**
@@ -20,29 +20,29 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
```bash ```bash
# Development # Development
bun dev # Vite dev server (localhost:3000) bun run dev # Vite dev server (localhost:3000)
bun db:studio # Drizzle Studio GUI bun run db:studio # Drizzle Studio GUI
# Build # Build
bun build # Production build → .output/ bun run build # Production build → .output/
bun compile # Compile to standalone binary (current platform, depends on build) bun run compile # Compile to standalone binary (current platform, depends on build)
bun compile:darwin # Compile for macOS (arm64 + x64) bun run compile:darwin # Compile for macOS (arm64 + x64)
bun compile:darwin:arm64 # Compile for macOS arm64 bun run compile:darwin:arm64 # Compile for macOS arm64
bun compile:darwin:x64 # Compile for macOS x64 bun run compile:darwin:x64 # Compile for macOS x64
bun compile:linux # Compile for Linux (x64 + arm64) bun run compile:linux # Compile for Linux (x64 + arm64)
bun compile:linux:arm64 # Compile for Linux arm64 bun run compile:linux:arm64 # Compile for Linux arm64
bun compile:linux:x64 # Compile for Linux x64 bun run compile:linux:x64 # Compile for Linux x64
bun compile:windows # Compile for Windows (default: x64) bun run compile:windows # Compile for Windows (default: x64)
bun compile:windows:x64 # Compile for Windows x64 bun run compile:windows:x64 # Compile for Windows x64
# Code Quality # Code Quality
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
# Database # Database
bun db:generate # Generate migrations from schema bun run db:generate # Generate migrations from schema
bun db:migrate # Run migrations bun run db:migrate # Run migrations
bun db:push # Push schema directly (dev only) bun run db:push # Push schema directly (dev only)
# Testing (not yet configured) # Testing (not yet configured)
bun test path/to/test.ts # Run single test bun test path/to/test.ts # Run single test
@@ -257,7 +257,7 @@ export const env = createEnv({
## Critical Rules ## Critical Rules
**DO:** **DO:**
- Run `bun fix` before committing - Run `bun run fix` before committing
- Use `@/*` path aliases - Use `@/*` path aliases
- Include `createdAt`/`updatedAt` on all tables - Include `createdAt`/`updatedAt` on all tables
- Use `ORPCError` with proper codes - Use `ORPCError` with proper codes

9
apps/server/src/router.tsx
View File

@@ -5,7 +5,14 @@ import type { RouterContext } from './routes/__root'
import { routeTree } from './routeTree.gen' import { routeTree } from './routeTree.gen'
export const getRouter = () => { export const getRouter = () => {
const queryClient = new QueryClient() const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 30 * 1000,
retry: 1,
},
},
})
const router = createRouter({ const router = createRouter({
routeTree, routeTree,

2
apps/server/src/routes/__root.tsx
View File

@@ -46,6 +46,7 @@ function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
</head> </head>
<body> <body>
{children} {children}
{import.meta.env.DEV && (
<TanStackDevtools <TanStackDevtools
config={{ config={{
position: 'bottom-right', position: 'bottom-right',
@@ -61,6 +62,7 @@ function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
}, },
]} ]}
/> />
)}
<Scripts /> <Scripts />
</body> </body>
</html> </html>

13
apps/server/src/server/api/contracts/todo.contract.ts
View File

@@ -1,21 +1,14 @@
import { oc } from '@orpc/contract' import { oc } from '@orpc/contract'
import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-orm/zod' import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-orm/zod'
import { z } from 'zod' import { z } from 'zod'
import { generatedFieldKeys } from '@/server/db/fields'
import { todoTable } from '@/server/db/schema' import { todoTable } from '@/server/db/schema'
const selectSchema = createSelectSchema(todoTable) const selectSchema = createSelectSchema(todoTable)
const insertSchema = createInsertSchema(todoTable).omit({ const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
id: true,
createdAt: true,
updatedAt: true,
})
const updateSchema = createUpdateSchema(todoTable).omit({ const updateSchema = createUpdateSchema(todoTable).omit(generatedFieldKeys)
id: true,
createdAt: true,
updatedAt: true,
})
export const list = oc.input(z.void()).output(z.array(selectSchema)) export const list = oc.input(z.void()).output(z.array(selectSchema))

8
apps/server/src/server/api/routers/todo.router.ts
View File

@@ -15,7 +15,7 @@ export const create = os.todo.create.use(db).handler(async ({ context, input })
const [newTodo] = await context.db.insert(todoTable).values(input).returning() const [newTodo] = await context.db.insert(todoTable).values(input).returning()
if (!newTodo) { if (!newTodo) {
throw new ORPCError('NOT_FOUND') throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Failed to create todo' })
} }
return newTodo return newTodo
@@ -32,5 +32,9 @@ export const update = os.todo.update.use(db).handler(async ({ context, input })
}) })
export const remove = os.todo.remove.use(db).handler(async ({ context, input }) => { export const remove = os.todo.remove.use(db).handler(async ({ context, input }) => {
await context.db.delete(todoTable).where(eq(todoTable.id, input.id)) const [deleted] = await context.db.delete(todoTable).where(eq(todoTable.id, input.id)).returning({ id: todoTable.id })
if (!deleted) {
throw new ORPCError('NOT_FOUND')
}
}) })

2
apps/server/src/server/db/fields.ts
View File

@@ -4,7 +4,7 @@ import { v7 as uuidv7 } from 'uuid'
// id // id
export const id = (name: string) => uuid(name) const id = (name: string) => uuid(name)
export const pk = (name: string, strategy?: 'native' | 'extension') => { export const pk = (name: string, strategy?: 'native' | 'extension') => {
switch (strategy) { switch (strategy) {
// PG 18+ // PG 18+

1
apps/server/turbo.json
View File

@@ -4,6 +4,7 @@
"tasks": { "tasks": {
"build": { "build": {
"env": ["NODE_ENV", "VITE_*"], "env": ["NODE_ENV", "VITE_*"],
"inputs": ["src/**", "public/**", "package.json", "tsconfig.json", "vite.config.ts"],
"outputs": [".output/**"] "outputs": [".output/**"]
}, },
"compile": { "compile": {

7
turbo.json
View File

@@ -14,12 +14,7 @@
"cache": false "cache": false
}, },
"typecheck": { "typecheck": {
"inputs": [ "inputs": ["package.json", "tsconfig.json", "tsconfig.*.json", "**/*.{ts,tsx,d.ts}"],
"package.json",
"tsconfig.json",
"tsconfig.*.json",
"**/*.{ts,tsx,d.ts}"
],
"outputs": [] "outputs": []
} }
}, },