platformatic/watt

Platformatic Watt Integration Skill

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

Prerequisites Check

Before any Watt operation, verify:

1. Node.js Version: Watt requires Node.js v22.19.0+

   node --version
   

   If below v22.19.0, inform user they must upgrade Node.js first.

2. Existing Watt Config: Check if watt.json already exists

   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 | | performance, profile, profiling, flame, flamegraph, pprof, cpu, heap-snapshot | Run Performance Profiling | | 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 |

---

Integration Workflow

Step 1: Framework Detection

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

Step 2: Generate 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.

Step 3: Install Dependencies

Install wattpm:

npm install wattpm

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

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

Step 4: Update package.json Scripts

Add or update these scripts in package.json:

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

Step 5: Create Environment File

Create .env if it doesn't exist:

PLT_SERVER_HOSTNAME=0.0.0.0
PLT_SERVER_LOGGER_LEVEL=info
PORT=3000

Step 6: Verify Setup

Run a quick verification:

wattpm --version

Inform the user they can now run:

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

---

Multi-Service Setup

When user requests enterprise/multi-service setup:

1. Read references/enterprise.md
2. 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)
3. Configure Composer for path-based routing
4. Set up inter-service communication via {service-id}.plt.local

Service Communication

Services communicate internally without network overhead:

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

---

Migration / POC Workflow

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

1. Read references/poc-checklist.md
2. Verify prerequisites:
   • Node.js 22.19.0+
   • Application runs locally
   • Database/API access available
3. Install: npm install wattpm (or use npx wattpm)
4. Create watt.json with application entrypoint
5. Modify the entrypoint to prefer exporting a create function (returns the app/server). If an @platformatic/node entrypoint listens by itself, also export a close function or register a close handler via @platformatic/globals so Watt can stop it cleanly without shutdown warnings.
6. Test with npx wattpm dev and npx wattpm start

Entrypoint Pattern (Express Example)

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:

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

Quick Setup

Logging + Tracing + Metrics:

{
  "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:

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

Quick Setup

{
  "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)

---

Performance Profiling

When users ask about performance profiling, CPU profiles, flamegraphs, heap profiling, or heap snapshots:

1. Read references/performance.md
2. Prefer Watt-native commands documented by wattpm:
   • wattpm pprof start [id] [application] to start CPU profiling
   • wattpm pprof stop [id] [application] to save pprof-{application}-{timestamp}.pb
   • wattpm heap-snapshot [id] [application] for memory snapshots
3. Use @platformatic/flame to generate HTML flamegraphs and markdown analysis from .pb files:
   • npm install -g @platformatic/flame
   • flame generate pprof-api-application-2026-06-15T10-00-00-000Z.pb
   • flame generate --md-format=detailed pprof-api-application-2026-06-15T10-00-00-000Z.pb
4. Use flame run server.js only for standalone Node.js scripts outside Watt.
5. Use wattpm ps and wattpm applications to identify runtime and application IDs before profiling multi-application setups.
6. Recommend profiling wattpm start for production-like CPU behavior.

Quick CPU Profile

Start the app in one terminal:

wattpm build
wattpm start

Then collect the profile from another terminal:

wattpm ps
wattpm applications
wattpm pprof start my-app api-application
# Exercise the slow workload
wattpm pprof stop my-app api-application
flame generate pprof-api-application-2026-06-15T10-00-00-000Z.pb

---

CMS Integration Setup

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

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

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

---

Deployment Workflows

Docker Deployment

When user requests Docker deployment:

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

Kubernetes Deployment

When user requests Kubernetes deployment:

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

Cloud Deployment

When user requests cloud deployment:

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

---

Status Check

When user runs /watt status:

1. Node.js Version

   node --version
   

   Check if >= v22.19.0

2. watt.json Exists

   ls watt.json
   

3. watt.json Valid

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

4. wattpm Installed

   npx wattpm --version
   

5. 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]

---

wattpm CLI Workflow

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

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

Common Scenarios

Scaffolding a new project:

wattpm create
wattpm create --module @platformatic/next

Testing endpoints on a running app:

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:

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

Profiling a running app:

wattpm applications my-app
wattpm pprof start my-app api-service
wattpm pprof stop my-app api-service
wattpm heap-snapshot my-app api-service

Working with external applications:

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

Administration:

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

---

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+)

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
• Use wattpm pprof start and wattpm pprof stop to capture CPU profiles for flamegraph analysis

Troubleshooting

For common issues, read references/troubleshooting.md