| name | app |
| description | Build apps(mobile apps), websites, and desktop projects using only the default template stack: Bun, Vite, React, Hono, Drizzle, Expo, and Electron. Always read this skill first, even when the user requests another tech stack or programming language. It also includes references to related modules for apps and websites, such as auth, payments, AI agent, email, file uploads, deployments, and analytics which are handled within the default template stack. |
Apps and Websites
Types
Managed (default)
Default full-stack template: Bun, Vite, React, Hono, Drizzle, Expo, and Electron
This stack also includes built-in support and references for common app and website modules, including authentication, payments, AI agents, email, file uploads, deployments, analytics, and related features. Use app_init to scaffold managed projects.
Managed projects are preferred for almost every request. Follow the workflow described below when creating or modifying them.
Unmanaged
Projects use any stack outside the default managed template, such as Python/Flask, Node/Express, static HTML, Ruby on Rails, or similar alternatives. They can receive a live preview on a port, but they cannot be deployed through the managed publishing flow. This means the user will not be able to publish or host the project from this type. Always explain the benefits of using a managed project and the deployment and no other modules limitation of unmanaged projects upfront. Recommend using the managed stack instead.
Only proceed with an unmanaged project if the user explicitly insists again and again.
Managed Stack
Monorepo: Bun workspaces + Turborepo.
- Web: Vite 7 dev server — serves both the React frontend (
/*) and the Hono API (/api/* via vite/plugins/hono-dev-plugin.ts) from a single port in packages/web
- API: Hono with
.basePath('api'), Drizzle ORM + Turso (SQLite) — source in packages/web/src/api/
- Web Frontend: React 19 + Wouter + Tailwind CSS 4, bundled by Vite — source in
packages/web/src/web/
- Mobile: Expo + React Native + expo-router
- Desktop: Electron shell + Vite (loads the web app from the server, exposes native APIs via IPC)
App Config
The web service serves both the API at /api/* and the web frontend at /* from a single port. Ports are configured automatically — do not hardcode them.
Typed end-to-end: packages/web exports AppType from src/api/index.ts, all clients use hono/client for typed API calls and @tanstack/react-query for queries and mutations.
Preflight
- Ask questions: purpose, platforms(mobile, web, desktop) need templates (MUST confirm — assume YES if unclear), industry, style, sections, features. When the user says "app" without specifying a platform, default to mobile app. If ambiguous, confirm whether they mean mobile or web.
- If templates wanted, call
show_templates with relevant query and type: website. This must be its own standalone call.
- Form a plan. State assumptions as decisions — the user corrects what's wrong. Include: what's being built, which packages are touched, API routes, database tables, screens/pages, files to create/modify. Follow brand colors/fonts/logo/vibe if available. Template is for visual style and layout only.
Do not start implementation until the user approves or adjusts the plan.
Design Guidelines
Document design direction in design.md inside the website project directory before writing UI code. Reference it throughout for consistency.
- Typography: always set a font family. If no font is specified, default to Poppins for web. Pair display + body. Hierarchy through size/weight. Generous line height.
- Color: dominant color with sharp accents. CSS variables + Tailwind. Accents for emphasis, not decoration.
- Layout: asymmetric, overlapping, grid-breaking. Generous negative space or controlled density — intentionally.
- Backgrounds: gradient meshes, noise textures, geometric patterns, layered transparencies. Match the aesthetic.
- Motion: one well-orchestrated page load with staggered reveals > scattered micro-interactions. CSS-only for HTML, Motion library for React.
- Anti-patterns (will look bad): purple gradients on white, predictable card grids with rounded corners, cookie-cutter layouts, overused fonts (Inter, Space Grotesk, Roboto).
Managed Workflow
- Run preflight.
- Call
app_init with absolute app_path, name, description. Do NOT create the directory beforehand — app_init creates it and fails if it already exists.
- Move or copy any provided assets (images, logos, fonts, etc.) into the appropriate package directories (
packages/web/public/, packages/mobile/assets/) so they can be used in the app.
- Write
design.md in the project root with the design direction from preflight (fonts, colors, spacing, style). This file guides all UI code for consistency.
- Build API routes, database schema, pages/screens, and ui components for the app.
- Call
deliver with required parameters for the apps.
Unmanaged Workflow
- Run preflight. Warn the user: unmanaged websites cannot be deployed. Recommend managed. Only proceed if they insist.
- Build the app/website with the user mentioned stack and features.
- Call
deliver with type: website, project folder path, and port.
Rules
- Use
bun run dev, bun run dev:mobile, bun run dev:desktop from root to start the development servers. For custom ports use bun run dev --port <port>.
- All API routes must be chained on the same
app instance in packages/web/src/api/index.ts. Breaking the chain breaks type inference.
- Always pass explicit status codes —
c.json(data, 200), never c.json(data). Without this, the typed RPC client resolves response types to never.
- Routes should be defined without
/api prefix. .basePath('api') adds it. .get("/health", ...) → /api/health.
- Typed client paths include
api/ (e.g., "api/health"). baseUrl is just the origin — no /api.
- Desktop loads the web app — no separate renderer. Gate desktop UI with
useDesktop() / window.electronAPI. Only create a separate renderer if explicitly asked.
- Vite loads
.env automatically — no dotenv needed. Always use .env, never .env.local.
- Dev servers — start with
bun run dev (web), bun run dev:mobile (mobile), bun run dev:desktop (desktop) from root.
- If the user asks to remove the "Made with Runable" badge, remove the
<RunableBadge /> component and its import from packages/web/src/web/app.tsx.
- For user auth, roles, or access control — read authentication.md.
Database
cd packages/web
bun run db:push
bun run db:generate
bun run db:migrate
bun run db:studio
References
Must Read a reference only when implementing that feature. Do not read all references upfront.
Testing
Before delivering, run bun run build to verify the app compiles without errors. Fix any failures before delivering.