Skip to content

Contributing

Project Structure

jaduspine/
├── src/                    # SDK source
│   ├── index.ts            # Main exports
│   ├── types.ts            # Type definitions
│   ├── wsClient.ts         # WebSocket client
│   ├── httpPublisher.ts    # HTTP publisher
│   ├── backend.ts          # Backend singleton
│   ├── react.ts            # React exports
│   ├── useJaduSpine.tsx    # React provider & hook
│   ├── spineUtils.ts       # Utilities
│   ├── spineErrors.ts      # Error classes
│   └── ...
├── tests/                  # Test files
├── playground/
│   ├── be/                 # Express backend (port 3001)
│   └── fe/                 # Next.js frontend (port 3000)
└── dist/                   # Built output

Playground Setup

The playground demonstrates the SDK with a real-time plotter that streams random walk data from backend to frontend via Centrifugo. image

Prerequisites

1. Start Centrifugo

# Copy example config to your centrifugo directory
cp centrifugo.config.example.json /path/to/centrifugo/config.json

# Set env vars and run
export JADU_SPINE_JWT_SECRET=your-spine-jwt-secret
export CENTRIFUGO_API_KEY=your-api-key
export CENTRIFUGO_ADMIN_PASSWORD=admin
export CENTRIFUGO_ADMIN_SECRET=admin-secret

centrifugo --config=/path/to/centrifugo/config.json

2. Configure Environment

Backend (playground/be/.env):

PORT=3001
JWT_SECRET=your-jwt-secret
REFRESH_TOKEN_SECRET=your-refresh-token-secret
JADU_SPINE_JWT_SECRET=your-spine-jwt-secret    # Must match Centrifugo
CENTRIFUGO_API_URL=http://localhost:8000/api
CENTRIFUGO_API_KEY=your-api-key                # Must match Centrifugo

Frontend (playground/fe/.env.local):

NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_CENTRIFUGO_URL=ws://localhost:8000/connection/websocket

3. Install & Run

# Install playground dependencies
cd playground/be && npm install
cd ../fe && npm install
cd ../..

# Run everything (SDK watch + BE + FE)
npm run dev:all

Or run separately in 3 terminals:

npm run dev           # SDK watch
npm run dev:be        # Backend
npm run dev:fe        # Frontend

4. Access

Service URL
Frontend http://localhost:3000
Backend http://localhost:3001
Centrifugo http://localhost:8000

Login with any username/password, click Start to see real-time updates.

Deployment (AWS)

For a repeatable AWS deployment (ECS/Fargate + ALB + Cloudflare DNS + Terraform), see:

Message Format

All messages use SpineMessage:

interface SpineMessage<T = Record<string, unknown>> {
  topic: string; // Message topic
  data: T; // Payload
  timestamp?: number; // Auto-added by SDK
}

// Usage
await JaduSpineBackend.publish(channel, {
  topic: "plotter:point",
  data: { y: 42 },
});

Code Guidelines

  • Use Biome for linting/formatting
  • Add JSDoc comments with @public for public APIs
  • Follow conventional commits: feat(scope): message

Pull Requests

  1. Create feature branch
  2. Add tests for new functionality
  3. Run npm run test and npm run typecheck
  4. Update CHANGELOG.md for notable changes
  5. Submit PR with clear description