Platformatic Watt Skill for Claude Code

A Claude Code plugin for integrating and deploying Platformatic Watt in any Node.js project.

Features

• Automatic Framework Detection: Detects Next.js, Express, Fastify, Koa, Remix, Astro, NestJS, WordPress, Laravel, and PHP
• Configuration Generation: Creates optimized watt.json for your framework
• Deployment Automation: Generate Docker, Kubernetes, and cloud deployment configs
• Performance Optimization: Multi-worker SSR, distributed caching, and Kubernetes tuning
• Kafka Integration: Event-driven microservices with kafka-hooks webhooks (separate /kafka skill)
• Scheduled Jobs: Cron-based task scheduling with retry support
• CMS Integration: Headless CMS webhooks and cache invalidation (Contentful, Sanity, Strapi)
• Observability: Logging (Pino), tracing (OpenTelemetry), metrics (Prometheus)
• Status Checking: Verify your Watt setup with a single command

Installation

From Plugin Directory (Development)

# Clone the repository
git clone https://github.com/platformatic/watt-skill.git

# Use with Claude Code
claude --plugin-dir ./watt-skill

From npm (When Published)

# Install globally
npm install -g @platformatic/watt-skill

# Or use with Claude Code
/plugin install @platformatic/watt-skill

Usage

Initialize Watt in a Project

/watt

This will:

1. Detect your framework (Next.js, Express, Fastify, etc.)
2. Generate appropriate watt.json configuration
3. Install required dependencies (wattpm, @platformatic/*)
4. Update package.json scripts
5. Create .env file with defaults

Initialize with Framework Hint

/watt init nextjs
/watt init express
/watt init fastify

Check Watt Configuration Status

/watt status

Outputs:

Watt Configuration Status
=========================
Node.js Version:  v22.19.0       [OK]
watt.json:        Found          [OK]
Configuration:    Valid JSON     [OK]
wattpm:           v3.2.0         [OK]
Scripts:          Configured     [OK]

Status: Ready to run

Deploy with Docker

/watt deploy docker

Generates:

• Dockerfile (multi-stage, optimized)
• .dockerignore
• docker-compose.yml (optional)

Deploy to Kubernetes

/watt deploy k8s

Generates:

• k8s/deployment.yaml
• k8s/service.yaml
• k8s/configmap.yaml
• k8s/hpa.yaml (autoscaling)

Deploy to Cloud Platforms

/watt deploy cloud
/watt deploy fly
/watt deploy railway

Generates platform-specific configuration files.

Kafka Integration

/kafka
/kafka hooks
/kafka producer
/kafka consumer
/kafka monitoring

Migrate from KafkaJS

/kafka migrate
/kafka kafkajs

Guides through migrating from KafkaJS to @platformatic/kafka:

• API mapping (factory pattern → direct instantiation)
• Producer changes (topic per-message, built-in serializers)
• Consumer changes (callback → stream-based)
• Admin, transactions, error handling, and diagnostics

Sets up event-driven microservices with:

• @platformatic/kafka-hooks (webhooks, request/response, HTTP publishing)
• @platformatic/kafka (direct producer/consumer)
• Consumer lag monitoring and OpenTelemetry tracing

wattpm CLI Commands

/watt cli                   # overview of all wattpm commands
/watt create                # scaffold a new project
/watt inject                # test endpoints on a running app
/watt logs                  # stream application logs
/watt ps                    # list running instances
/watt admin                 # launch Watt admin UI
/watt resolve               # clone external applications

Multi-Service Enterprise Setup

/watt enterprise
/watt multi-service

Creates a multi-service architecture with:

• Platformatic Composer (API gateway)
• Multiple backend services
• Inter-service communication via {service-id}.plt.local

Migrate Existing Application

/watt migrate
/watt poc

Guides through migrating an existing Node.js app:

• Prerequisites checklist
• Entrypoint modification (create/close exports)
• watt.json configuration

Supported Frameworks

Framework	Package	Detection
Next.js	@platformatic/next	next.config.{js,ts,mjs}
Remix	@platformatic/remix	remix.config.js
Astro	@platformatic/astro	astro.config.{mjs,ts}
Express	@platformatic/node	express in dependencies
Fastify	@platformatic/node	fastify in dependencies
Koa	@platformatic/node	koa in dependencies
NestJS	@platformatic/node	nest-cli.json or @nestjs/core
WordPress	@platformatic/php	wp-config.php
Laravel	@platformatic/php	artisan + composer.json
PHP	@platformatic/php	composer.json + public/index.php

Requirements

• Node.js: v22.19.0 or higher
• Claude Code: Latest version

Configuration Reference

watt.json Structure

{
  "$schema": "https://schemas.platformatic.dev/@platformatic/{package}/3.0.0.json",
  "application": {
    "commands": {
      "development": "your-dev-command",
      "build": "your-build-command",
      "production": "your-start-command"
    }
  },
  "runtime": {
    "logger": {
      "level": "{PLT_SERVER_LOGGER_LEVEL}"
    },
    "server": {
      "hostname": "{PLT_SERVER_HOSTNAME}",
      "port": "{PORT}"
    }
  }
}

Environment Variables

Variable	Description	Default
PORT	Server port	3000
PLT_SERVER_HOSTNAME	Bind address	0.0.0.0
PLT_SERVER_LOGGER_LEVEL	Log level	info

Plugin Structure

watt-skill/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest
├── skills/
│   ├── watt/
│   │   ├── SKILL.md             # Main skill
│   │   └── references/
│   │       ├── frameworks/      # Framework-specific configs
│   │       ├── deployment/      # Deployment guides
│   │       └── troubleshooting.md
│   └── kafka/
│       ├── SKILL.md             # Kafka integration skill
│       └── references/
│           └── kafka.md         # Kafka reference docs
├── agents/
│   └── watt-analyzer.md         # Project analysis agent
├── commands/
│   └── watt-status.md           # Status check command
├── README.md
└── LICENSE

Development

Testing Locally

# Start Claude Code with plugin
claude --plugin-dir /path/to/watt-skill

# Test skill invocation
/watt:watt
/watt:watt-status

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Claude Code
5. Submit a pull request

Troubleshooting

See troubleshooting guide for common issues.

Quick Fixes

Node.js version too old:

nvm install 22 && nvm use 22

wattpm not found:

npm install wattpm

Port already in use:

PORT=3001 npm run dev

Resources

• Platformatic Watt Documentation
• Watt 3 Announcement
• Claude Code Skills Guide

License

Apache-2.0 - See LICENSE for details.

Support

• Issues: GitHub Issues
• Discord: Platformatic Community