da-cli

@domoinc/da CLI - 应用脚手架与代码生成

DA CLI（@domoinc/da）是一个命令行工具，用于搭建 Domo 自定义应用脚手架并生成样板代码。它是创建新 Domo 应用和生成组件的推荐方式。

用途

DA CLI 提供：

• 项目脚手架 - 创建结构正确的全新 Domo 应用（Vite + React 18 + TypeScript）
• 代码生成 - 生成遵循正确 Domo 模式的组件、reducer 及其他样板代码
• Manifest 管理 - 管理针对不同环境的 manifest 配置
• 最佳实践 - 确保项目从一开始就遵循 Domo 约定

安装

# Install globally
pnpm add -g @domoinc/da

# Or with npm
npm install -g @domoinc/da

创建新应用

# Create new Domo app (recommended - Vite + React 18 + TypeScript)
da new my-app-name
cd my-app-name

# With custom template
da new my-app --template @myorg/custom-template
da new my-app --template github.com/user/repo
da new my-app --template ./local-template

创建的项目结构：

my-app/
├── public/
│   ├── manifest.json      # Domo app configuration
│   └── thumbnail.png      # App icon in Domo
├── src/
│   ├── components/        # React components
│   ├── reducers/          # Redux slices (if using)
│   ├── services/          # API service layers
│   ├── types/             # TypeScript definitions
│   └── index.tsx          # App entry point
├── package.json
└── vite.config.ts

代码生成

# Generate component with styles, tests, and Storybook
da generate component MyComponent
# Creates:
#   src/components/MyComponent/MyComponent.tsx
#   src/components/MyComponent/MyComponent.module.scss
#   src/components/MyComponent/MyComponent.test.tsx
#   src/components/MyComponent/MyComponent.stories.tsx

# Shorthand
da g component MyComponent

# Generate Redux slice (auto-imports to store)
da generate reducer myFeature
# Creates: src/reducers/myFeature/slice.ts

# Shorthand
da g reducer myFeature

Manifest 管理

DA CLI 可帮助管理多个 Domo 环境（dev、staging、prod）：

# Create environment-specific manifest overrides
da manifest instance.prod "Production on customer.domo.com"
da manifest instance.dev "Development on dev.domo.com"

# Apply an override before publishing
da apply-manifest instance.prod
yarn upload

覆盖文件结构：

{
  "instance.prod": {
    "description": "Production environment",
    "manifest": {
      "id": "prod-app-design-id",
      "proxyId": "prod-card-id"
    }
  }
}

---

将生成的应用（Lovable/v0）转换为 Domo

许多开发者使用 Lovable、v0 或类似的基于大模型的生成器来创建应用原型。然而，这些工具通常生成采用服务端渲染（SSR）的应用，与 Domo 仅客户端架构不兼容。

转换挑战

生成的应用通常包含：

• 服务端渲染（Next.js、Remix、SvelteKit、Nuxt）
• API 路由（pages/api/ 或 app/api/ 目录）
• 服务端数据获取（getServerSideProps、loader 等）
• 框架专属路由（Next.js App Router、Remix 路由）

Domo 应用必须是：

• 纯客户端 React - 无服务端渲染
• 基于静态文件 - Domo 仅提供静态文件
• 集成 Domo API - 使用 domo.get()、Query、AppDBClient 等，而非后端端点

推荐的转换模式

DA CLI 并非转换工具 - 它不会自动转换应用。不过，你可以将其用作参考结构和起点。

第 1 步：生成参考结构

# Create a fresh Domo app to use as reference
da new my-converted-app
cd my-converted-app

# This gives you the correct structure to compare against

第 2 步：检测并移除 SSR 代码

检查 SSR 迹象：

• getServerSideProps、getStaticProps（Next.js）
• loader、action 函数（Remix）
• +page.server.js、+server.js（SvelteKit）
• pages/api/ 或 app/api/ 目录
• 服务端 process.env 用法
• 组件中的数据库连接

操作： 移除所有服务端代码。Domo 应用完全在浏览器中运行。

第 3 步：替换数据获取

之前（Next.js 示例）：

// ❌ Server-side data fetching
export async function getServerSideProps() {
  const res = await fetch('https://api.example.com/data');
  const data = await res.json();
  return { props: { data } };
}

// ❌ API route
// pages/api/users.ts
export default async function handler(req, res) {
  const users = await db.users.findMany();
  res.json(users);
}

之后（Domo）：

// ✅ Client-side with Domo APIs
import domo from 'ryuu.js';
import Query from '@domoinc/query';
import { AppDBClient } from '@domoinc/toolkit';

// Fetch from Domo dataset
const data = await domo.get('/data/v1/sales');

// Or use Query API for filtered/aggregated data
const summary = await new Query()
  .select(['region', 'sales'])
  .groupBy('region', { sales: 'sum' })
  .fetch('sales-dataset');

// Or use AppDB for document storage
const tasksClient = new AppDBClient.DocumentsClient('Tasks');
const tasks = await tasksClient.get();

第 4 步：更新路由

之前（Next.js）：

// ❌ Next.js routing
import Link from 'next/link';
<Link href="/dashboard">Dashboard</Link>

之后（Domo）：

// ✅ HashRouter for client-side routing
import { HashRouter, Routes, Route } from 'react-router-dom';
import domo from 'ryuu.js';

// Use HashRouter (works without server rewrites)
<HashRouter>
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="/dashboard" element={<Dashboard />} />
  </Routes>
</HashRouter>

// For Domo navigation, use domo.navigate()
domo.navigate('/page/123456789');

第 5 步：修复构建配置

之前（Next.js）：

// next.config.js
module.exports = {
  // Next.js config
}

之后（Domo - Vite）：

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  base: './',  // CRITICAL: Relative paths for Domo
  plugins: [react()],
});

第 6 步：移植组件

使用 DA CLI 生成结构正确的全新组件，然后移植逻辑：

# Generate component structure
da generate component SalesChart

# Copy component logic from generated app
# Replace data fetching with Domo APIs
# Update imports and dependencies

DA CLI 能提供哪些帮助

✅ 参考结构 - 展示正确的 Domo 应用组织方式
✅ 组件生成 - 创建结构规范的组件
✅ 模式示例 - 演示 Domo 约定
✅ 从零开始 - 如果转换过于复杂，可新建项目并移植逻辑

DA CLI 做不到的事

❌ 无自动转换 - 不会将 SSR 转换为客户端渲染
❌ 无迁移向导 - 没有分步转换工具
❌ 无代码转换 - 不会重写框架专属代码
❌ 无 API 迁移 - 不会自动替换后端调用

完整转换清单

• 检测并移除所有 SSR 代码
• 移除 API 路由（pages/api/、app/api/）
• 将调用后端的 fetch() 替换为 Domo API
• 将路由更新为 HashRouter
• 使用 base: './' 配置 Vite
• 替换环境变量（改用 Domo API）
• 更新导入（移除 Next.js/Remix 专属内容）
• 测试所有数据获取与 Domo API 正常工作
• 验证应用可在本地构建并运行
• 发布到 Domo 并在平台中测试

示例：转换一个简单的仪表板

原始（Lovable/Next.js）：

// pages/dashboard.tsx
export async function getServerSideProps() {
  const sales = await fetch('http://api.company.com/sales').then(r => r.json());
  return { props: { sales } };
}

export default function Dashboard({ sales }) {
  return <div>{/* Render sales data */}</div>;
}

转换后（Domo）：

// src/components/Dashboard/Dashboard.tsx
import { useEffect, useState } from 'react';
import domo from 'ryuu.js';

export default function Dashboard() {
  const [sales, setSales] = useState([]);

  useEffect(() => {
    // Fetch from Domo dataset instead of backend
    domo.get('/data/v1/sales').then(setSales);
  }, []);

  return <div>{/* Render sales data */}</div>;
}

---

附加参考：CODE_BLOCKS_DA_CLI.md

要添加的代码块：DA CLI 与转换指南

将本节添加到“构建与部署工作流”一节之后，“基础路径配置”之前。

---

@domoinc/da CLI - 应用脚手架与代码生成

DA CLI（@domoinc/da）是一个命令行工具，用于为 Domo 自定义应用搭建脚手架并生成样板代码。它是创建新 Domo 应用和生成组件的推荐方式。

用途

DA CLI 提供：

• 项目脚手架 - 创建结构正确的 Domo 新应用（Vite + React 18 + TypeScript）
• 代码生成 - 生成遵循 Domo 规范模式的组件、reducer 及其他样板代码
• 清单管理 - 管理特定环境的清单配置
• 最佳实践 - 确保项目从一开始就遵循 Domo 约定

安装

# Install globally
pnpm add -g @domoinc/da

# Or with npm
npm install -g @domoinc/da

创建新应用

# Create new Domo app (recommended - Vite + React 18 + TypeScript)
da new my-app-name
cd my-app-name

# With custom template
da new my-app --template @myorg/custom-template
da new my-app --template github.com/user/repo
da new my-app --template ./local-template

创建的项目结构：

my-app/
├── public/
│   ├── manifest.json      # Domo app configuration
│   └── thumbnail.png      # App icon in Domo
├── src/
│   ├── components/        # React components
│   ├── reducers/          # Redux slices (if using)
│   ├── services/          # API service layers
│   ├── types/             # TypeScript definitions
│   └── index.tsx          # App entry point
├── package.json
└── vite.config.ts

代码生成

# Generate component with styles, tests, and Storybook
da generate component MyComponent
# Creates:
#   src/components/MyComponent/MyComponent.tsx
#   src/components/MyComponent/MyComponent.module.scss
#   src/components/MyComponent/MyComponent.test.tsx
#   src/components/MyComponent/MyComponent.stories.tsx

# Shorthand
da g component MyComponent

# Generate Redux slice (auto-imports to store)
da generate reducer myFeature
# Creates: src/reducers/myFeature/slice.ts

# Shorthand
da g reducer myFeature

清单管理

DA CLI 可帮助管理多个 Domo 环境（dev、staging、prod）：

# Create environment-specific manifest overrides
da manifest instance.prod "Production on customer.domo.com"
da manifest instance.dev "Development on dev.domo.com"

# Apply an override before publishing
da apply-manifest instance.prod
yarn upload

覆盖文件结构：

{
  "instance.prod": {
    "description": "Production environment",
    "manifest": {
      "id": "prod-app-design-id",
      "proxyId": "prod-card-id"
    }
  }
}

---

将生成的应用（Lovable/v0）转换为 Domo

许多开发者使用 Lovable、v0 或类似的基于大模型的生成器来创建应用原型。然而，这些工具通常会生成带有服务端渲染（SSR）的应用，这与 Domo 仅客户端架构不兼容。

转换挑战

生成的应用通常包含：

• 服务端渲染（Next.js、Remix、SvelteKit、Nuxt）
• API 路由（pages/api/ 或 app/api/ 目录）
• 服务端数据获取（getServerSideProps、loader 等）
• 框架特定的路由（Next.js App Router、Remix 路由）

Domo 应用必须：

• 纯客户端 React - 没有服务端渲染
• 基于静态文件 - Domo 仅提供静态文件
• 集成 Domo API - 使用 domo.get()、Query、AppDBClient 等，而非后端端点

推荐的转换模式

DA CLI 不是转换工具 - 它不会自动转换应用。不过，你可以将其作为参考结构和起点。

第 1 步：生成参考结构

# Create a fresh Domo app to use as reference
da new my-converted-app
cd my-converted-app

# This gives you the correct structure to compare against

第 2 步：检测并移除 SSR 代码

检查 SSR 迹象：

• getServerSideProps、getStaticProps（Next.js）
• loader、action 函数（Remix）
• +page.server.js、+server.js（SvelteKit）
• pages/api/ 或 app/api/ 目录
• 服务端使用 process.env
• 组件中的数据库连接

操作： 移除所有服务端代码。Domo 应用完全在浏览器中运行。

第 3 步：替换数据获取

之前（Next.js 示例）：

// ❌ Server-side data fetching
export async function getServerSideProps() {
  const res = await fetch('https://api.example.com/data');
  const data = await res.json();
  return { props: { data } };
}

// ❌ API route
// pages/api/users.ts
export default async function handler(req, res) {
  const users = await db.users.findMany();
  res.json(users);
}

之后（Domo）：

// ✅ Client-side with Domo APIs
import domo from 'ryuu.js';
import Query from '@domoinc/query';
import { AppDBClient } from '@domoinc/toolkit';

// Fetch from Domo dataset
const data = await domo.get('/data/v1/sales');

// Or use Query API for filtered/aggregated data
const summary = await new Query()
  .select(['region', 'sales'])
  .groupBy('region', { sales: 'sum' })
  .fetch('sales-dataset');

// Or use AppDB for document storage
const tasksClient = new AppDBClient.DocumentsClient('Tasks');
const tasks = await tasksClient.get();

第 4 步：更新路由

之前（Next.js）：

// ❌ Next.js routing
import Link from 'next/link';
<Link href="/dashboard">Dashboard</Link>

之后（Domo）：

// ✅ HashRouter for client-side routing
import { HashRouter, Routes, Route } from 'react-router-dom';
import domo from 'ryuu.js';

// Use HashRouter (works without server rewrites)
<HashRouter>
  <Routes>
    <Route path="/" element={<Home />} />
    <Route path="/dashboard" element={<Dashboard />} />
  </Routes>
</HashRouter>

// For Domo navigation, use domo.navigate()
domo.navigate('/page/123456789');

第 5 步：修复构建配置

之前（Next.js）：

// next.config.js
module.exports = {
  // Next.js config
}

之后（Domo - Vite）：

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  base: './',  // CRITICAL: Relative paths for Domo
  plugins: [react()],
});

第 6 步：移植组件

使用 DA CLI 生成结构正确的新组件，然后移植逻辑：

# Generate component structure
da generate component SalesChart

# Copy component logic from generated app
# Replace data fetching with Domo APIs
# Update imports and dependencies

DA CLI 能帮上什么

✅ 参考结构 - 展示正确的 Domo 应用组织方式
✅ 组件生成 - 创建结构正确的组件
✅ 模式示例 - 演示 Domo 约定
✅ 从头开始 - 如果转换过于复杂，可新建项目并移植逻辑

DA CLI 不做什么

❌ 不自动转换 - 不会将 SSR 转换为客户端渲染
❌ 没有迁移向导 - 没有分步转换工具
❌ 不做代码转换 - 不会重写框架特定的代码
❌ 不迁移 API - 不会自动替换后端调用

完整转换清单

• 检测并移除所有 SSR 代码
• 移除 API 路由（pages/api/、app/api/）
• 将对后端的 fetch() 调用替换为 Domo API
• 将路由更新为 HashRouter
• 配置 Vite，设置 base: './'
• 替换环境变量（改用 Domo API）
• 更新导入（移除 Next.js/Remix 专有内容）
• 测试所有数据获取在 Domo API 下正常工作
• 验证应用可在本地构建并运行
• 发布到 Domo 并在平台中测试

示例：转换一个简单的仪表盘

原始版本（Lovable/Next.js）：

// pages/dashboard.tsx
export async function getServerSideProps() {
  const sales = await fetch('http://api.company.com/sales').then(r => r.json());
  return { props: { sales } };
}

export default function Dashboard({ sales }) {
  return <div>{/* Render sales data */}</div>;
}

转换后（Domo）：

// src/components/Dashboard/Dashboard.tsx
import { useEffect, useState } from 'react';
import domo from 'ryuu.js';

export default function Dashboard() {
  const [sales, setSales] = useState([]);

  useEffect(() => {
    // Fetch from Domo dataset instead of backend
    domo.get('/data/v1/sales').then(setSales);
  }, []);

  return <div>{/* Render sales data */}</div>;
}

---

---

附加参考：PR_DA_CLI_DESCRIPTION.md

添加 DA CLI 文档与 Lovable/v0 转换指南

概要

本 PR 添加了 @domoinc/da CLI 工具的完整文档，以及一份将 Lovable/v0（或类似 LLM 生成的）应用转换为可运行的 Domo 应用的指南。

新增内容

1. DA CLI 文档

   • DA CLI 的用途与能力
   • 安装与设置
   • 代码生成命令（组件、reducer）
   • 多环境的 manifest 管理
   • 项目结构概览

2. 转换生成应用指南

   • 将 Lovable/v0 应用转换为 Domo 的分步流程
   • 以 DA CLI 作为参考的推荐模式
   • 常见不兼容问题及其修复方法
   • 数据获取迁移模式
   • 路由与构建配置更新

为什么这很重要

许多开发者使用 Lovable 或 v0 等 AI 工具生成应用原型，但这些工具会创建带有服务端渲染的 Next.js/Remix 应用，与 Domo 仅客户端运行的架构不兼容。本指南提供了清晰的转换路径。

重点亮点

• DA CLI 的用途：说明 DA CLI 是脚手架工具，而非转换工具，但可作为参考结构使用
• 转换模式：手动移植组件与逻辑的分步指南
• SSR 检测：强调检测并移除服务端代码的重要性
• API 迁移：用 Domo API 替换后端调用的清晰模式

位置

添加在 "Build & Deploy Workflow" 一节之后、"Base Path Configuration" 之前。

---

附加参考：PR_DA_CLI_SUGGESTIONS.md

PR 建议：DA CLI 文档与转换指南

概述

本 PR 添加了 @domoinc/da CLI 工具的文档，以及一份将 Lovable/v0（或类似 LLM 生成的）应用转换为可运行的 Domo 自定义应用的完整指南。

理由

DA CLI 文档缺口

当前 .cursorrules 文件简要提到了 DA CLI，但未说明：

• DA CLI 是什么以及为何存在
• 它的完整能力（代码生成、manifest 管理）
• 它与其他设置方法的区别
• 何时使用它、何时用手动设置

转换指南的需求

许多开发者使用 AI 工具（Lovable、v0 等）生成应用原型，但这些工具会创建：

• 带 SSR 的 Next.js 应用（与 Domo 不兼容）
• API 路由（Domo 中没有后端）
• 特定框架的模式（需要 Domo 的对应方案）

目前没有关于如何转换这些应用的指导。本 PR 填补了这一空白。

影响评估

高价值新增内容：

• DA CLI 文档 - 帮助开发者了解推荐的工具链
• 转换指南 - 为拥有生成应用的开发者节省大量试错时间
• 模式指导 - 提供从常见框架迁移的清晰路径

开发者收益：

• 了解何时以及如何使用 DA CLI
• 获得转换生成应用的清晰流程
• 避免常见陷阱（SSR、API 路由、路由）
• 清楚 DA CLI 能做什么、不能做什么

建议添加位置

插入在 "Build & Deploy Workflow" 一节之后、"Base Path Configuration" 之前。这一位置合理，因为：

1. 它涉及项目设置与工作流
2. 转换是开发过程的一部分
3. 它位于技术配置细节之前

内容结构

本次新增包括：

1. DA CLI - 用途与能力

• DA CLI 是什么（脚手架与代码生成工具）
• 安装与基本用法
• 代码生成命令
• Manifest 管理
• 它创建的项目结构

2. 将生成的 App 转换为 Domo

• 转换挑战（SSR、API 路由等）
• 推荐的转换模式
• 分步流程：
  1. 使用 DA CLI 生成参考结构
  2. 检测并移除 SSR 代码
  3. 将数据获取替换为 Domo API
  4. 更新路由（HashRouter）
  5. 修复构建配置
• DA CLI 能提供哪些帮助（参考结构、组件生成）
• DA CLI 不做什么（不会自动转换）

关键亮点

包含的关键信息：

• DA CLI 不是转换工具 - 重要澄清
• 将 DA CLI 用作参考 - 推荐的转换模式
• SSR 检测 - 强化了现有的关于服务端代码的警告
• API 迁移模式 - 替换后端调用的清晰示例
• 分步流程 - 可执行的转换工作流

代码示例：

• DA CLI 安装与用法
• 组件生成示例
• 面向各环境的 Manifest 管理
• 转换模式示例
• 数据获取迁移（Next.js → Domo API）

测试说明

本文档基于：

• 官方 DA CLI 文档模式
• 来自 Lovable/v0 App 的常见转换场景
• Domo App 架构的最佳实践
• 与现有 SSR 检测警告的集成

需要更新的文件

• .cursorrules - 添加 DA CLI 章节和转换指南