NerdSec Cloudflare Monorepo

A monorepo using pnpm workspaces containing shared TypeScript types and Cloudflare Workers.

📁 Project Structure

ns-cf/
├── packages/
│   └── nerdsec/                 # Shared types and utilities
│       ├── src/
│       │   ├── types/           # TypeScript type definitions
│       │   ├── utils/           # Utility functions
│       │   └── index.ts         # Main export file
│       ├── package.json
│       └── tsconfig.json
├── workers/
│   └── dev-api/                 # Cloudflare Worker API
│       ├── src/
│       │   └── index.ts         # Worker entry point
│       ├── package.json
│       ├── tsconfig.json
│       └── wrangler.toml        # Cloudflare configuration
├── package.json                 # Root package.json
├── pnpm-workspace.yaml         # Workspace configuration
├── tsconfig.json               # Root TypeScript config
└── README.md

🚀 Getting Started

Prerequisites

• Node.js 18+
• pnpm 8+
• Cloudflare account (for deployment)

Installation

1. Install dependencies:

   pnpm install

2. Build the shared package:

   cd packages/nerdsec
   pnpm build

Development

Working with the NerdSec Package

The @nerdsec/core package contains shared types and utilities:

• Types: User management, security events, API responses, pagination
• Utils: Response helpers, validation, sanitization, ID generation

To add new types or utilities:

1. Edit files in packages/nerdsec/src/
2. Run pnpm build to compile TypeScript
3. The compiled package will be available to workers

Developing the Cloudflare Worker

1. Start development server:

   cd workers/dev-api
   pnpm dev

2. The worker will be available at: http://localhost:8787

Available API Endpoints

• GET / - Health check
• GET /health - Detailed health status
• GET /users - List users (paginated)
• POST /users - Create a new user
• GET /security/events - List security events (paginated)
• POST /security/events - Create a security event

Example API Usage

Create a user:

curl -X POST http://localhost:8787/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Test User",
    "role": "user"
  }'

Get users:

curl http://localhost:8787/users?page=1&limit=10

Building and Type Checking

• Build all packages: pnpm build
• Type check all packages: pnpm type-check
• Clean build artifacts: pnpm clean

Deployment

Deploy to Cloudflare

1. Login to Cloudflare:

   cd workers/dev-api
   npx wrangler login

2. Deploy:

   pnpm deploy

Environment Configuration

The worker supports multiple environments:

• development - For local development
• staging - For staging environment
• production - For production environment

Deploy to specific environment:

npx wrangler deploy --env staging

🏗️ Architecture

Workspace Benefits

• Shared Types: Common TypeScript definitions across all projects
• Code Reuse: Utilities and helpers available to all workers
• Consistent APIs: Standardized response formats and error handling
• Type Safety: Full TypeScript support with shared interfaces

Package Dependencies

The dev-api worker depends on @nerdsec/core using workspace protocol:

{
  "dependencies": {
    "@nerdsec/core": "workspace:*"
  }
}

This ensures the worker always uses the local version of the shared package.

📝 Adding New Workers

1. Create worker directory:

   mkdir workers/new-worker
   cd workers/new-worker

2. Create package.json:

   {
     "name": "@nerdsec/new-worker",
     "dependencies": {
       "@nerdsec/core": "workspace:*"
     }
   }

3. Add to workspace: The worker will be automatically included due to the workers/* pattern in pnpm-workspace.yaml

🔧 Scripts

From the root directory:

• pnpm build - Build all packages
• pnpm dev - Start development for all packages
• pnpm type-check - Type check all packages
• pnpm clean - Clean all build artifacts

📚 Key Features

• Type-safe APIs using shared TypeScript definitions
• Standardized responses with consistent error handling
• Input validation and sanitization for security
• Pagination support for list endpoints
• CORS enabled for cross-origin requests
• Environment-specific deployments (dev/staging/prod)

🤝 Contributing

1. Make changes to shared types in packages/nerdsec/src/
2. Build the package: pnpm build
3. Test changes in workers
4. Ensure type checking passes: pnpm type-check

The monorepo structure ensures that changes to shared types are immediately available to all workers while maintaining type safety throughout the codebase.