watt

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Platformatic Watt Integration Skill

Platformatic Watt 集成技能

You are an expert in Platformatic Watt, the Node.js Application Server. Help users integrate, configure, and deploy Watt in their projects.

您是Node.js应用服务器Platformatic Watt的专家。请帮助用户在其项目中集成、配置并部署Watt。

Prerequisites Check

前置条件检查

Before any Watt operation, verify:

Node.js Version: Watt requires Node.js v22.19.0+
bash
```
node --version
```
If below v22.19.0, inform user they must upgrade Node.js first.
Existing Watt Config: Check if
```
watt.json
```
already exists
bash
```
ls watt.json 2>/dev/null
```

在执行任何Watt操作之前，请验证：

Node.js版本：Watt要求Node.js v22.19.0+
bash
```
node --version
```
如果版本低于v22.19.0，请告知用户必须先升级Node.js。
现有Watt配置：检查是否已存在
```
watt.json
```
bash
```
ls watt.json 2>/dev/null
```

Command Router

命令路由

Based on user input ($ARGUMENTS), route to the appropriate workflow:

Input Pattern	Action
`init` , `setup` , `integrate` , (empty)	Run Integration Workflow
`multi-service` , `enterprise` , `composer`	Run Multi-Service Setup
`migrate` , `port` , `onboard` , `poc`	Run Migration/POC Workflow
`observability` , `logging` , `tracing` , `metrics`	Run Observability Setup
`scheduler` , `cron` , `jobs`	Run Scheduler Setup
`cms` , `contentful` , `sanity` , `headless`	Run CMS Integration Setup
`deploy docker`	Run Docker Deployment
`deploy k8s` , `deploy kubernetes`	Run Kubernetes Deployment
`deploy cloud` , `deploy fly` , `deploy railway`	Run Cloud Deployment
`cli` , `wattpm` , `commands`	Run wattpm CLI Workflow
`create` , `scaffold`	Run wattpm CLI Workflow (create)
`inject` , `test endpoint`	Run wattpm CLI Workflow (inject)
`logs`	Run wattpm CLI Workflow (logs)
`ps` , `applications` , `services`	Run wattpm CLI Workflow (ps)
`admin` , `dashboard`	Run wattpm CLI Workflow (admin)
`resolve` , `import`	Run wattpm CLI Workflow (resolve/import)
`status` , `check`	Run Status Check

根据用户输入（$ARGUMENTS），路由到对应的工作流：

输入模式	操作
`init` , `setup` , `integrate` , (空)	执行集成工作流
`multi-service` , `enterprise` , `composer`	执行多服务设置
`migrate` , `port` , `onboard` , `poc`	执行迁移/POC工作流
`observability` , `logging` , `tracing` , `metrics`	执行可观测性设置
`scheduler` , `cron` , `jobs`	执行调度器设置
`cms` , `contentful` , `sanity` , `headless`	执行CMS集成设置
`deploy docker`	执行Docker部署
`deploy k8s` , `deploy kubernetes`	执行Kubernetes部署
`deploy cloud` , `deploy fly` , `deploy railway`	执行云部署
`cli` , `wattpm` , `commands`	执行wattpm CLI工作流
`create` , `scaffold`	执行wattpm CLI工作流（创建）
`inject` , `test endpoint`	执行wattpm CLI工作流（注入）
`logs`	执行wattpm CLI工作流（日志）
`ps` , `applications` , `services`	执行wattpm CLI工作流（进程查看）
`admin` , `dashboard`	执行wattpm CLI工作流（管理）
`resolve` , `import`	执行wattpm CLI工作流（解析/导入）
`status` , `check`	执行状态检查

Integration Workflow

集成工作流

Step 1: Framework Detection

步骤1：框架检测

Analyze the project to identify the framework. Use this priority order:

Priority 1 - Config Files:

File	Framework	Package
`next.config.js` , `next.config.ts` , `next.config.mjs`	Next.js	`@platformatic/next`
`remix.config.js`	Remix	`@platformatic/remix`
`astro.config.mjs` , `astro.config.ts`	Astro	`@platformatic/astro`
`nest-cli.json`	NestJS	`@platformatic/node`
`wp-config.php`	WordPress	`@platformatic/php`
`artisan` + `composer.json`	Laravel	`@platformatic/php`
`composer.json` + `public/index.php`	PHP	`@platformatic/php`

Priority 2 - Dependencies (check package.json):

Dependency	Framework	Package
`@nestjs/core`	NestJS	`@platformatic/node`
`fastify`	Fastify	`@platformatic/node`
`express`	Express	`@platformatic/node`
`koa`	Koa	`@platformatic/node`

Priority 3 - Fallback: If no framework detected, use generic Node.js with

@platformatic/node

For framework-specific configuration, read the appropriate reference file:

references/frameworks/nextjs.md for Next.js
references/frameworks/express.md for Express
references/frameworks/fastify.md for Fastify
references/frameworks/koa.md for Koa
references/frameworks/remix.md for Remix
references/frameworks/astro.md for Astro
references/frameworks/nestjs.md for NestJS
references/frameworks/php.md for PHP, WordPress, and Laravel

分析项目以识别框架。使用以下优先级顺序：

优先级1 - 配置文件：

文件	框架	包
`next.config.js` , `next.config.ts` , `next.config.mjs`	Next.js	`@platformatic/next`
`remix.config.js`	Remix	`@platformatic/remix`
`astro.config.mjs` , `astro.config.ts`	Astro	`@platformatic/astro`
`nest-cli.json`	NestJS	`@platformatic/node`
`wp-config.php`	WordPress	`@platformatic/php`
`artisan` + `composer.json`	Laravel	`@platformatic/php`
`composer.json` + `public/index.php`	PHP	`@platformatic/php`

优先级2 - 依赖项（检查package.json）：

依赖项	框架	包
`@nestjs/core`	NestJS	`@platformatic/node`
`fastify`	Fastify	`@platformatic/node`
`express`	Express	`@platformatic/node`
`koa`	Koa	`@platformatic/node`

优先级3 - 备选方案： 如果未检测到框架，则使用通用Node.js搭配

@platformatic/node

。

针对框架的特定配置，请阅读对应的参考文档：

references/frameworks/nextjs.md 适用于Next.js
references/frameworks/express.md 适用于Express
references/frameworks/fastify.md 适用于Fastify
references/frameworks/koa.md 适用于Koa
references/frameworks/remix.md 适用于Remix
references/frameworks/astro.md 适用于Astro
references/frameworks/nestjs.md 适用于NestJS
references/frameworks/php.md 适用于PHP、WordPress和Laravel

Step 2: Generate watt.json

步骤2：生成watt.json

Create

watt.json

based on detected framework. Use the schema URL:

https://schemas.platformatic.dev/@platformatic/{package}/3.0.0.json

Where

{package}

is:

next

remix

astro

node

, or

php

Runtime placement rule:

For single-config application files (e.g.
```
@platformatic/node
```
,
```
@platformatic/next
```
, etc.), put runtime settings under
```
runtime
```
.
For multi-app/root orchestrator configs (
```
watt
```
/
```
@platformatic/runtime
```
with
```
services
```
/
```
web
```
/
```
autoload
```
), keep a top-level
```
runtime
```
block in the root
```
watt.json
```
.

根据检测到的框架创建

watt.json

。使用以下Schema URL：

https://schemas.platformatic.dev/@platformatic/{package}/3.0.0.json

其中

{package}

可为：

next

remix

astro

node

, 或

php

。

运行时放置规则：

对于单配置应用文件（如
```
@platformatic/node
```
,
```
@platformatic/next
```
等），将运行时设置放在
```
runtime
```
字段下。
对于多应用/根编排器配置（
```
watt
```
/
```
@platformatic/runtime
```
搭配
```
services
```
/
```
web
```
/
```
autoload
```
），在根
```
watt.json
```
中保留顶层
```
runtime
```
块。

Step 3: Install Dependencies

步骤3：安装依赖项

Install wattpm:

bash

npm install wattpm

For Next.js, Remix, Astro, or PHP, also install the specific stackable:

bash

npm install @platformatic/next    # for Next.js
npm install @platformatic/remix   # for Remix
npm install @platformatic/astro   # for Astro
npm install @platformatic/php     # for PHP/WordPress/Laravel

安装wattpm：

bash

npm install wattpm

对于Next.js、Remix、Astro或PHP，还需安装对应的特定栈包：

bash

npm install @platformatic/next    # 适用于Next.js
npm install @platformatic/remix   # 适用于Remix
npm install @platformatic/astro   # 适用于Astro
npm install @platformatic/php     # 适用于PHP/WordPress/Laravel

Step 4: Update package.json Scripts

步骤4：更新package.json脚本

Add or update these scripts in package.json:

json

{
  "scripts": {
    "dev": "wattpm dev",
    "build": "wattpm build",
    "start": "wattpm start"
  }
}

在package.json中添加或更新以下脚本：

json

{
  "scripts": {
    "dev": "wattpm dev",
    "build": "wattpm build",
    "start": "wattpm start"
  }
}

Step 5: Create Environment File

步骤5：创建环境文件

Create

.env

if it doesn't exist:

PLT_SERVER_HOSTNAME=0.0.0.0
PLT_SERVER_LOGGER_LEVEL=info
PORT=3000

如果不存在

.env

文件则创建：

PLT_SERVER_HOSTNAME=0.0.0.0
PLT_SERVER_LOGGER_LEVEL=info
PORT=3000

Step 6: Verify Setup

步骤6：验证设置

Run a quick verification:

bash

wattpm --version

Inform the user they can now run:

```
npm run dev
```
for development
```
npm run build && npm run start
```
for production

执行快速验证：

bash

wattpm --version

告知用户现在可以运行：

```
npm run dev
```
用于开发环境
```
npm run build && npm run start
```
用于生产环境

Multi-Service Setup

多服务设置

When user requests enterprise/multi-service setup:

Read references/enterprise.md
Create project structure with:
- Root
```
watt.json
```
  with service definitions
- ```
web/composer/
```
  - API gateway (Platformatic Composer)
- ```
web/frontend/
```
  - Next.js or other frontend
- ```
web/api/
```
  - Fastify API service
- ```
web/db/
```
  - Platformatic DB service (optional)
Configure Composer for path-based routing
Set up inter-service communication via
```
{service-id}.plt.local
```

当用户要求企业级/多服务设置时：

阅读references/enterprise.md
创建项目结构，包含：
- 根目录
```
watt.json
```
  ，含服务定义
- ```
web/composer/
```
  - API网关（Platformatic Composer）
- ```
web/frontend/
```
  - Next.js或其他前端
- ```
web/api/
```
  - Fastify API服务
- ```
web/db/
```
  - Platformatic DB服务（可选）
配置Composer以实现基于路径的路由
通过
```
{service-id}.plt.local
```
设置服务间通信

Service Communication

服务通信

Services communicate internally without network overhead:

javascript

// From api service, call db service
const response = await fetch('http://db.plt.local/users');

服务内部通信无需网络开销：

javascript

// 从api服务调用db服务
const response = await fetch('http://db.plt.local/users');

Migration / POC Workflow

迁移 / POC工作流

When user wants to migrate an existing app or prepare for a POC:

Read references/poc-checklist.md
Verify prerequisites:
- Node.js 22.19.0+
- Application runs locally
- Database/API access available
Install:
```
npm install wattpm
```
(or use
```
npx wattpm
```
)
Create
```
watt.json
```
with application entrypoint
Modify entrypoint to export
```
create
```
function (returns server) or
```
close
```
function
Test with
```
npx wattpm dev
```
and
```
npx wattpm start
```

当用户希望迁移现有应用或准备POC时：

阅读references/poc-checklist.md
验证前置条件：
- Node.js 22.19.0+
- 应用可在本地运行
- 可访问数据库/API
安装：
```
npm install wattpm
```
（或使用
```
npx wattpm
```
）
创建包含应用入口点的
```
watt.json
```
修改入口点以导出
```
create
```
函数（返回服务器）或
```
close
```
函数
使用
```
npx wattpm dev
```
和
```
npx wattpm start
```
进行测试

Entrypoint Pattern (Express Example)

入口点模式（Express示例）

javascript

async function create() {
  const app = express()
  app.get('/health', (req, res) => res.json({ status: 'ok' }))
  return app
}
module.exports = { create }

javascript

async function create() {
  const app = express()
  app.get('/health', (req, res) => res.json({ status: 'ok' }))
  return app
}
module.exports = { create }

Observability Setup

可观测性设置

When user requests logging, tracing, or metrics setup:

Read references/observability.md
Determine observability needs:
- Logging: Pino configuration, file transport, redaction
- Tracing: OpenTelemetry with OTLP exporter
- Metrics: Prometheus endpoint on port 9090
Configure based on backend:
- Jaeger, Datadog, New Relic, Grafana Stack, AWS, GCP, Azure
Set up log-trace correlation for debugging

当用户要求设置日志、追踪或指标时：

阅读references/observability.md
确定可观测性需求：
- 日志：Pino配置、文件传输、脱敏
- 追踪：搭配OTLP导出器的OpenTelemetry
- 指标：端口9090上的Prometheus端点
根据后端进行配置：
- Jaeger、Datadog、New Relic、Grafana Stack、AWS、GCP、Azure
设置日志-追踪关联以方便调试

Quick Setup

快速设置

Logging + Tracing + Metrics:

json

{
  "logger": {
    "level": "{PLT_SERVER_LOGGER_LEVEL}"
  },
  "telemetry": {
    "serviceName": "my-service",
    "exporter": {
      "type": "otlp",
      "options": { "url": "{OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces" }
    }
  },
  "metrics": {
    "port": 9090
  }
}

日志 + 追踪 + 指标：

json

{
  "logger": {
    "level": "{PLT_SERVER_LOGGER_LEVEL}"
  },
  "telemetry": {
    "serviceName": "my-service",
    "exporter": {
      "type": "otlp",
      "options": { "url": "{OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces" }
    }
  },
  "metrics": {
    "port": 9090
  }
}

Scheduler Setup

调度器设置

When user requests cron/scheduled jobs setup:

Read references/scheduler.md
Add
```
scheduler
```
array to
```
watt.json
```
Configure jobs with cron expressions, callback URLs, and retry settings
Create endpoint handlers in target services

当用户要求设置cron/定时任务时：

阅读references/scheduler.md
向
```
watt.json
```
添加
```
scheduler
```
数组
使用cron表达式、回调URL和重试设置配置任务
在目标服务中创建端点处理器

Quick Setup

快速设置

json

{
  "scheduler": [
    {
      "name": "daily-cleanup",
      "cron": "0 0 3 * * *",
      "callbackUrl": "http://api.plt.local/cron/cleanup",
      "method": "POST",
      "maxRetries": 3
    }
  ]
}

json

{
  "scheduler": [
    {
      "name": "daily-cleanup",
      "cron": "0 0 3 * * *",
      "callbackUrl": "http://api.plt.local/cron/cleanup",
      "method": "POST",
      "maxRetries": 3
    }
  ]
}

Key Points

关键点

Uses standard cron format with optional seconds field
Internal URLs:
```
http://{service-id}.plt.local
```
Jobs retry on failure (default: 3 attempts)
State is in-memory only (not persisted across restarts)

使用标准cron格式，可选秒字段
内部URL：
```
http://{service-id}.plt.local
```
任务失败时会重试（默认：3次）
状态仅在内存中存储（重启后不持久化）

CMS Integration Setup

CMS集成设置

When user requests headless CMS integration (Contentful, Sanity, Strapi, etc.):

Read references/cms-integration.md
Recommend architecture with separate content-worker service
Set up webhook endpoint for CMS callbacks
Configure cache invalidation with Next.js
```
revalidateTag()
```
Create mock data pattern for development

当用户要求集成无头CMS（Contentful、Sanity、Strapi等）时：

阅读references/cms-integration.md
推荐使用独立内容工作者服务的架构
设置用于CMS回调的Webhook端点
搭配Next.js
```
revalidateTag()
```
配置缓存失效
为开发环境创建模拟数据模式

Key Components

核心组件

Content Worker: Fastify service handling webhooks
Cache Tags: Map CMS content types to Next.js cache tags
Revalidation API: Next.js endpoint called by content-worker

内容工作者：处理Webhook的Fastify服务
缓存标签：将CMS内容类型映射到Next.js缓存标签
重新验证API：由内容工作者调用的Next.js端点

Deployment Workflows

部署工作流

Docker Deployment

Docker部署

When user requests Docker deployment:

Read references/deployment/docker.md
Generate:
- Multi-stage
```
Dockerfile
```
  optimized for Watt
- ```
.dockerignore
```
  file
- Optional
```
docker-compose.yml
```
  for development
Provide build and run commands

当用户要求Docker部署时：

阅读references/deployment/docker.md
生成：
- 针对Watt优化的多阶段
```
Dockerfile
```
- ```
.dockerignore
```
  文件
- 可选的
```
docker-compose.yml
```
  （用于开发环境）
提供构建和运行命令

Kubernetes Deployment

Kubernetes部署

When user requests Kubernetes deployment:

Read references/deployment/kubernetes.md
Generate:
- ```
deployment.yaml
```
  with health checks
- ```
service.yaml
```
- ```
configmap.yaml
```
  for environment variables
- Optional
```
hpa.yaml
```
  for autoscaling
Provide kubectl apply commands

当用户要求Kubernetes部署时：

阅读references/deployment/kubernetes.md
生成：
- 含健康检查的
```
deployment.yaml
```
- ```
service.yaml
```
- 用于环境变量的
```
configmap.yaml
```
- 可选的
```
hpa.yaml
```
  （用于自动扩缩容）
提供kubectl应用命令

Cloud Deployment

云部署

When user requests cloud deployment:

Read references/deployment/cloud.md
Based on target platform, generate appropriate config:
- Fly.io:
```
fly.toml
```
- Railway:
```
railway.json
```
- Render:
```
render.yaml
```
Provide deployment commands

当用户要求云部署时：

阅读references/deployment/cloud.md
根据目标平台生成对应的配置：
- Fly.io:
```
fly.toml
```
- Railway:
```
railway.json
```
- Render:
```
render.yaml
```
提供部署命令

Status Check

状态检查

When user runs

/watt status

Node.js Version
bash
```
node --version
```
Check if >= v22.19.0
watt.json Exists
bash
```
ls watt.json
```

watt.json Valid

bash

node -e "JSON.parse(require('fs').readFileSync('watt.json'))"

wattpm Installed
bash
```
npx wattpm --version
```
package.json Scripts Check for dev, build, start scripts

Report findings in a clear format:

Watt Configuration Status
========================
Node.js Version: vX.X.X [OK/UPGRADE NEEDED]
watt.json: [Found/Missing]
Configuration: [Valid/Invalid]
wattpm: [Installed vX.X.X/Not installed]
Scripts: [Configured/Missing]

[Next steps if any issues found]

当用户运行

/watt status

时：

Node.js版本
bash
```
node --version
```
检查是否 >= v22.19.0
watt.json是否存在
bash
```
ls watt.json
```

watt.json是否有效

bash

node -e "JSON.parse(require('fs').readFileSync('watt.json'))"

wattpm是否已安装
bash
```
npx wattpm --version
```
package.json脚本 检查是否存在dev、build、start脚本

以清晰格式报告结果：

Watt配置状态
========================
Node.js版本: vX.X.X [正常/需要升级]
watt.json: [已找到/缺失]
配置: [有效/无效]
wattpm: [已安装 vX.X.X/未安装]
脚本: [已配置/缺失]

[如果存在问题，给出下一步建议]

wattpm CLI Workflow

wattpm CLI工作流

When users ask about wattpm commands, CLI usage, or managing running applications:

Read references/wattpm-cli.md
Based on the user's request, provide the relevant command with flags and examples
For general CLI questions, give an overview of available commands

当用户询问wattpm命令、CLI用法或管理运行中的应用时：

阅读references/wattpm-cli.md
根据用户请求，提供相关命令及参数示例
对于通用CLI问题，概述可用的命令

Common Scenarios

常见场景

Scaffolding a new project:

bash

wattpm create
wattpm create --module @platformatic/next

Testing endpoints on a running app:

bash

wattpm inject --path /health
wattpm inject my-app api-service --method POST --path /users \
  --header "Content-Type: application/json" \
  --data '{"name": "Alice"}'

Monitoring a running app:

bash

wattpm ps                        # list running instances
wattpm logs my-app               # stream all logs
wattpm logs my-app api-service   # stream logs from a sub-application
wattpm env my-app --table        # view environment variables
wattpm config my-app             # view configuration

Working with external applications:

bash

wattpm import . platformatic/acme-base --id base-app
wattpm resolve                   # clone all external apps defined in watt.json

Administration:

bash

wattpm admin                     # launch Watt admin UI
wattpm patch-config . patches/production.js  # apply config patches

搭建新项目：

bash

wattpm create
wattpm create --module @platformatic/next

测试运行中应用的端点：

bash

wattpm inject --path /health
wattpm inject my-app api-service --method POST --path /users \
  --header "Content-Type: application/json" \
  --data '{"name": "Alice"}'

监控运行中应用：

bash

wattpm ps                        # 列出运行实例
wattpm logs my-app               # 流式输出所有日志
wattpm logs my-app api-service   # 流式输出子应用的日志
wattpm env my-app --table        # 查看环境变量
wattpm config my-app             # 查看配置

处理外部应用：

bash

wattpm import . platformatic/acme-base --id base-app
wattpm resolve                   # 克隆watt.json中定义的所有外部应用

管理操作：

bash

wattpm admin                     # 启动Watt管理UI
wattpm patch-config . patches/production.js  # 应用配置补丁

Important Notes

重要说明

Watt 3.x runs applications in parallel for faster startup
Use internal hostname
```
{app-name}.plt.local
```
for inter-service communication
The unified
```
wattpm
```
CLI replaces older individual CLIs
Always recommend running
```
wattpm build
```
before production deployment
TypeScript is supported natively via Node.js type stripping (v22.6+)

Watt 3.x并行运行应用以加快启动速度
使用内部主机名
```
{app-name}.plt.local
```
进行服务间通信
统一的
```
wattpm
```
CLI替代了旧的独立CLI
始终建议在生产部署前运行
```
wattpm build
```
Node.js v22.6+原生支持TypeScript（通过类型剥离）

Performance Optimization

性能优化

For production performance tuning, read references/performance.md

Key optimizations:

Configure
```
PLT_NEXT_WORKERS
```
for multi-threaded SSR
Scale CPU limits proportionally (workers × 1000m)
Enable distributed caching with Valkey/Redis
Use
```
output: 'standalone'
```
for Next.js

如需生产环境性能调优，请阅读references/performance.md

关键优化点：

配置
```
PLT_NEXT_WORKERS
```
以实现多线程SSR
按比例扩展CPU限制（workers × 1000m）
启用基于Valkey/Redis的分布式缓存
对Next.js使用
```
output: 'standalone'
```

Troubleshooting

故障排除

For common issues, read references/troubleshooting.md

如需解决常见问题，请阅读references/troubleshooting.md