Yellow Scaffold

A powerful scaffolding tool for building applications on the Yellow platform. Yellow Scaffold helps you quickly set up projects with Yellow's off-chain state channel functionality, supporting multiple frameworks and pre-built dApp templates.

Features

• 🚀 Quick Project Setup: Generate Yellow projects in seconds
• 🎯 Multiple Frameworks: Support for React, Vue, and Angular
• 💰 Pre-built dApps: Auction and Payment applications ready to deploy
• 📦 TypeScript Support: Full TypeScript support with proper type definitions
• 🔧 Configuration Management: Easy Yellow channel and ClearNode configuration
• 🛠️ Development Tools: Pre-configured with Vite, linting, and build tools
• 🎨 Interactive CLI: Vite-like interactive project creation experience
• 📚 Comprehensive Templates: Ready-to-use project templates with Yellow integration

Installation

Option 1: Global Installation (Recommended)

npm install -g yellow-scaffold

Option 2: Development Setup (npm link)

For local development and testing:

# Clone or navigate to the project
cd yellow-scaffold

# Install dependencies
npm install

# Build the project
npm run build

# Link globally
npm link

# Now you can use yellow-scaffold command anywhere
yellow-scaffold --help

Option 3: Using npx

npx yellow-scaffold create my-app

Quick Start

Interactive Mode (Recommended)

The easiest way to create a new project:

yellow-scaffold create my-yellow-app

You'll be prompted to:

1. Choose a project template (React App, Vue App, Angular App, Auction DApp, Payment DApp)
2. Enter a project description
3. Choose TypeScript or JavaScript
4. Select package manager (npm, yarn, pnpm)
5. Select supported blockchain chains
6. Enter Yellow Channel ID (optional)
7. Configure ClearNode URL

Non-Interactive Mode

Skip all prompts with the -y flag:

# Create with defaults
yellow-scaffold create my-app -y

# With specific template
yellow-scaffold create my-app -t auction-dapp -y

# With TypeScript disabled
yellow-scaffold create my-app --typescript false -y

List Available Templates

yellow-scaffold list-templates

Output:

Available templates:
- react-app: React App
- vue-app: Vue App
- angular-app: Angular App
- auction-dapp: Auction DApp
- payment-dapp: Payment DApp

Available Templates

React App

A modern React application with Yellow integration:

• React 18 with hooks
• Vite for blazing-fast development
• TypeScript support
• Yellow service integration
• Hot Module Replacement (HMR)
• Modern UI with responsive design

Use case: Building custom dApps with React

Vue App

A Vue.js application with Yellow integration:

• Vue 3 with Composition API
• Vite build system
• TypeScript support
• Yellow service integration
• Reactive state management
• Single File Components (SFC)

Use case: Building custom dApps with Vue

Angular App

An Angular application with Yellow integration:

• Angular 17
• TypeScript by default
• Yellow service integration
• Dependency injection
• RxJS for reactive programming
• Zone.js for change detection

Use case: Building enterprise-grade dApps with Angular

Auction DApp

A complete auction application built with Yellow state channels:

• Create and manage auctions
• Real-time bidding with Nitrolite SDK
• WebSocket-based live updates
• Bid history tracking
• Auction state management
• Demo mode for testing without Channel ID

Use case: NFT auctions, item bidding, time-limited sales

Payment DApp

A payment application leveraging Yellow's off-chain capabilities:

• Send and receive payments
• Transaction history
• Real-time payment status
• Session-based payments
• Low-latency transactions
• Demo mode for testing without Channel ID

Use case: Payment processing, peer-to-peer transfers, micropayments

Project Structure

Generated projects include:

my-yellow-app/
├── src/
│   ├── services/
│   │   └── YellowService.js/ts    # Yellow platform integration
│   ├── utils/
│   │   ├── config.js/ts           # Configuration loader
│   │   └── logger.js/ts           # Logging utility
│   └── index.js/ts                # Main entry point
├── yellow.config.json             # Yellow configuration
├── yellow.config.example.json     # Configuration template
├── package.json                   # Dependencies and scripts
├── tsconfig.json                  # TypeScript configuration (if applicable)
└── README.md                      # Project documentation

Configuration

Yellow Configuration

The yellow.config.json file contains your Yellow platform settings:

{
  "channelId": "your-channel-id",
  "clearNodeUrl": "wss://clearnet.yellow.com/ws",
  "chains": ["polygon", "celo", "base"],
  "features": ["websocket", "authentication", "session-management"],
  "privateKey": "your-private-key",
  "sessionKey": "your-session-key"
}

Setting Up Your Yellow Channel

All templates work in Demo Mode without a Channel ID for development and testing.

For production deployment:

1. Visit apps.yellow.com
2. Create a new channel
3. Copy your channel ID
4. Update yellow.config.json with your channel details

Demo Mode: Applications will run locally without connecting to Yellow's network. Perfect for UI development and testing.

Production Mode: With a valid Channel ID, applications connect to Yellow's state channel network for real-time off-chain transactions.

Yellow Service

The generated YellowService class provides:

• WebSocket Connection: Connect to Yellow's ClearNode
• Authentication: Handle JWT-based authentication
• Session Management: Create and manage application sessions
• Message Handling: Process Yellow platform messages
• State Channel Operations: Interact with Yellow's Nitrolite SDK

Basic Usage

import { YellowService } from './services/YellowService';

const yellowService = new YellowService();

// Connect to Yellow
await yellowService.connect();

// Create a session
const sessionId = await yellowService.createAppSession({
  // session data
});

// Close session
await yellowService.closeAppSession(sessionId);

// Disconnect
yellowService.disconnect();

Demo Mode vs Production Mode

Demo Mode (no Channel ID):

• Application runs without connecting to Yellow network
• UI and components work normally
• Connection attempts will fail gracefully
• Perfect for development and testing

Production Mode (with Channel ID):

• Connects to Yellow's state channel network
• Real-time WebSocket communication
• Off-chain transactions with low latency
• Full Yellow platform functionality

Development

Prerequisites

• Node.js 16 or later
• npm, yarn, or pnpm
• A Yellow channel (create at apps.yellow.com)

Running the Development Server

npm run dev

Building for Production

npm run build

Framework-Specific Features

React

• Custom hooks for Yellow integration
• Context providers for state management
• Component examples with Yellow service

Vue

• Composables for Yellow functionality
• Reactive state management
• Component examples

Angular

• Injectable services
• RxJS observables
• Component examples

Node.js

• Express.js integration
• WebSocket server setup
• API endpoints for Yellow functionality

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.

Support

• 📖 Yellow Platform Documentation
• 💬 Discord Community
• 🐛 Issue Tracker

Publishing to npm

To publish this package to npm and make it available globally:

Step 1: Prepare Your Package

1. Update package.json:

   • Set a unique name (check availability on npmjs.com)
   • Update version (start with 1.0.0)
   • Add author information
   • Verify repository URL
   • Add keywords for discoverability

2. Create npm account (if you don't have one):

   npm signup

3. Login to npm:

   npm login

   Enter your username, password, and email when prompted.

Step 2: Build the Project

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Verify dist/ folder contains compiled files
ls dist/

Step 3: Test Locally

Before publishing, test the package locally:

# Link the package globally
npm link

# Test the command
yellow-scaffold --help
yellow-scaffold list-templates

# Create a test project
yellow-scaffold create test-app

Step 4: Publish to npm

# Publish as public package
npm publish --access public

# Or for first-time publish
npm publish

Step 5: Verify Publication

1. Visit https://www.npmjs.com/package/yellow-scaffold
2. Check that your package appears
3. Test installation:

   npm install -g yellow-scaffold

Updating the Package

When you make changes:

# Update version in package.json (e.g., 1.0.0 -> 1.0.1)
npm version patch  # for bug fixes
# or
npm version minor  # for new features
# or
npm version major  # for breaking changes

# Rebuild
npm run build

# Publish update
npm publish

Best Practices

1. Semantic Versioning: Follow semver (MAJOR.MINOR.PATCH)
2. Test Before Publishing: Always test with npm link first
3. Update README: Keep documentation current
4. Add .npmignore: Exclude unnecessary files from package
5. Changelog: Document changes in README or CHANGELOG.md

.npmignore Example

Create a .npmignore file to exclude development files:

src/
tests/
*.test.js
*.spec.js
.git/
.github/
node_modules/
.env
.DS_Store
tsconfig.json
.eslintrc
.prettierrc

Troubleshooting

Package name taken:

• Choose a scoped package: @yourusername/yellow-scaffold
• Or pick a different unique name

Permission errors:

• Run npm login again
• Check npm account permissions

Version conflicts:

• Increment version in package.json
• Cannot republish same version

Changelog

v1.0.0

• Initial release
• Support for React, Vue, and Angular apps
• Auction and Payment dApp templates
• Interactive CLI with Vite-like experience
• TypeScript support
• Yellow service integration with Nitrolite SDK
• Demo mode for development
• Non-interactive mode with -y flag