Malla文档
首页快速入门打开 Malla

本地开发

Monorepo 结构、在本地运行每个 Worker，以及质量门禁。

开发者指南

代码仓库是一个由 Turborepo 驱动的 pnpm workspace。每个应用都是一个可以用 Wrangler 在本地运行的 Worker。

目录结构

路径内容本地端口
apps/webNuxt 编辑器，Panda CSS 设计系统3000
apps/apiHono API4000
apps/realtimeYjs 房间8788
apps/sites已发布站点，<slug>.localhost:87908790
apps/runner服务端工作流、表、访客认证8791
apps/mcpMCP 服务器8792
packages/*共享库，直接从源码导入—
docs/架构、部署指南、智能体流程—

初始设置

  1. 安装

    使用 package.json 中固定的 pnpm 版本。

    bash
    pnpm install                      # also runs nuxt prepare + panda codegen for web
cp apps/api/.dev.vars.example apps/api/.dev.vars
cp apps/sites/.dev.vars.example apps/sites/.dev.vars
cp apps/realtime/.dev.vars.example apps/realtime/.dev.vars
cp apps/mcp/.dev.vars.example apps/mcp/.dev.vars
# fill in DATABASE_URL (a Neon dev branch) and the shared keys

  2. 迁移数据库

    设置好 DATABASE_URL 后，用 pnpm --filter @malla/db db:migrate 把 packages/db/migrations 应用到你的开发分支。

  3. 运行

    bash
    pnpm dev                          # every Worker and the editor through turbo
pnpm --filter web dev             # just the editor
pnpm --filter api dev             # just one Worker

本地沙箱

pnpm sandbox 会运行整套服务（Postgres、api、realtime、sites、runner 和编辑器），无需配置 .dev.vars 和 DATABASE_URL。Postgres 使用 PGlite，启动时会应用 packages/db/migrations 中的迁移，仅供开发用的密钥只生成一次。数据在多次运行之间保留；按 Ctrl+C 停止。

bash
pnpm sandbox                      # start; data persists between runs
pnpm sandbox --reset              # wipe the sandbox data first, then start
服务URL
编辑器http://localhost:3200/login
APIhttp://localhost:4200/health
Realtimews://localhost:8988
Siteshttp://<slug>.localhost:8990（发布之后）
Runnerhttp://localhost:8991/health
Postgrespostgres://postgres@127.0.0.1:5599/postgres

用 demo@malla.local 和密码 demo-password-123 登录。首次启动会创建该用户、它的工作区，以及一个名为 "Demo site"、slug 为 demo 的站点。这些端口与 pnpm dev 和 e2e 环境互不冲突，三者可以同时运行。沙箱不会启动 MCP Worker，也没有邮件或 AI 密钥：它不发送任何邮件（因此没有登录链接），内置 AI 也处于关闭状态。它生成的所有内容都在 scripts/sandbox/.data/ 中；端口覆盖和其他细节见 scripts/sandbox/README.md。

质量关卡

bash
pnpm check-types                  # TypeScript across the monorepo
pnpm test                         # Vitest unit tests in every package
pnpm --filter web build           # production build of the editor
pnpm e2e                          # Playwright against the full local stack
graphify update .                 # refresh the code knowledge graph

e2e 测试套件会在每个检出目录各自的状态目录中启动自己的服务，因此并行的 worktree 绝不会冲突；它还会在 apps/web/e2e/.screenshots/ 中为每个测试保留一张截图。

约定

  • Vue 3 <script setup lang="ts">、严格的 TypeScript、显式导入（自动导入已关闭）。
  • 编辑器 UI 用 Panda CSS 编写样式，只使用语义化令牌；动效统一通过 app/motion（GSAP）。
  • 所有文档改动都通过 ops 和 editor.document.transact 完成；绝不直接修改文档。
  • 小而精的 Conventional Commits，每次提交一个逻辑改动。完整规则见 docs/frontend-conventions.md。