Creating a New PearDrop Project

This guide walks you through creating a new PearDrop-based application using the PearDrop CLI workflow.

Overview

Creating a PearDrop project involves:

Creating your project directory with PearDrop workspace setup
Installing the PearDrop CLI locally
Initializing the project structure via the setup script

The directory name you choose becomes your project name.

Workflow: Create Directory → Setup Workspace → Install + Initialize via Setup Script → Develop

Step 1: Create Your Project Directory

Create and navigate to your project directory. The directory name becomes your project name:

# Create project directory (use PascalCase)
mkdir MyApp
cd MyApp

# Initialize PearDrop workspace (creates .peardrop/ folder with documentation and setup scripts)
dotnet new peardrop

What this creates:

.peardrop/ folder with:
- setup.ps1 / setup.sh - Scripts to install PearDrop CLI
- nuget.config - Pre-configured NuGet feeds for PearDrop packages
- CLI-QUICK-START.md - Quick reference guide
- README.md - Setup and workflow documentation
- Additional guides for agents and teams

Important:

Use PascalCase for proper C# namespacing (e.g., TenToOne, MyEquipmentApp)
If your directory name has dashes or dots (e.g., ten-to-one), the CLI helper can auto-convert to PascalCase (TenToOne)

Step 2: Install CLI and Initialize Project (Recommended)

Run the setup script to install the PearDrop CLI locally and initialize your project in one flow:

# Windows - installs latest version and initializes project
./.peardrop/setup.ps1 -InitializeProject

# Or install specific version and initialize
./.peardrop/setup.ps1 -CliVersion "10.0.0-rc1" -InitializeProject

# Linux/Mac
chmod +x .peardrop/setup.sh
./.peardrop/setup.sh --initialize

What this does:

Installs PearDrop CLI to .config/dotnet-tools.json (local to this directory)
Auto-selects appropriate NuGet feed from pre-configured .peardrop/nuget.config:
- RC versions → Uses PearDropPublic
- Other pre-release → Uses PearDropPrivate
- Stable versions → Uses PearDropPublic
Records installed version in .peardrop/.cli-version for team consistency
Scaffolds the full project structure in the current directory

For automatic PascalCase conversion:

If your directory name has dashes, dots, or underscores (e.g., ten-to-one), use the setup script:

# Automatically converts "ten-to-one" → "TenToOne"
./.peardrop/setup.ps1 -InitializeProject

Important:

Use the setup script as your primary workflow.
Do not run dotnet tool run peardrop init directly in normal setup flows.

Setup Script Parameters

Use these options with setup scripts:

Purpose	PowerShell (`setup.ps1`)	Bash (`setup.sh`)
Set NuGet feed URL	`-NuGetFeed "https://..."`	`--nuget-feed "https://..."`
Pin CLI version	`-CliVersion "10.0.0-rc1"`	`--cli-version "10.0.0-rc1"`
Install and initialize project	`-InitializeProject`	`--initialize` or `--initialize-project`
Override project name	`-ProjectName "MyApp"`	`--project-name "MyApp"`
Run without prompts	`-NoInteractive`	`--no-interactive`
Skip restore during init	`-SkipRestore`	`--skip-restore`

Notes:

If NuGetFeed/--nuget-feed is omitted, setup auto-selects a feed from .peardrop/nuget.config when possible.
-InitializeProject / --initialize requires a valid feed (explicitly passed or auto-resolved from config).
If ProjectName/--project-name is omitted, setup derives a PascalCase name from the current directory.

Examples:

# Install CLI and initialize (Windows)
./.peardrop/setup.ps1 -InitializeProject

# Pin CLI version and run non-interactive initialization
./.peardrop/setup.ps1 -CliVersion "10.0.0-rc1" -InitializeProject -NoInteractive -SkipRestore

# Override project name
./.peardrop/setup.ps1 -InitializeProject -ProjectName "TenToOne"

# Install CLI and initialize (Linux/Mac)
./.peardrop/setup.sh --initialize

# Pin CLI version and run non-interactive initialization
./.peardrop/setup.sh --cli-version "10.0.0-rc1" --initialize --no-interactive --skip-restore

# Override project name
./.peardrop/setup.sh --initialize --project-name "TenToOne"

What happens:

PearDrop CLI detects your directory name as the project name
Installs the PearDrop.Minimal.Template matching the CLI version
Scaffolds the entire project structure in the current directory
Configures your NuGet feed for PearDrop packages
Creates .peardrop/ folder with setup and configuration

Output structure:

MyApp/                                 # Your project root
├── .peardrop/                          # CLI configuration & scripts
│   ├── setup.ps1                       # Helper script for setup
│   ├── CLI-QUICK-START.md              # CLI quick reference
│   ├── README.md                       # Setup documentation
│   └── cli-version                     # Pinned CLI version
│
├── source/                             # Application code
│   ├── MyApp.App/                      # Main server application
│   │   ├── Infrastructure/
│   │   │   ├── Domain/                 # Domain aggregates & CQRS
│   │   │   ├── Data/                   # EF Core DbContexts
│   │   │   └── Module.cs               # DI registration
│   │   ├── Components/                 # Server Razor components
│   │   └── Program.cs                  # Server startup
│   │
│   └── MyApp.App.Client/               # Blazor WebAssembly client
│       ├── Infrastructure/
│       │   └── Module.cs               # [BluQubeRequester] setup
│       ├── Components/                 # Client components
│       └── Program.cs                  # Client startup
│
├── .config/                            # Local .NET tools
│   └── dotnet-tools.json               # Pinned CLI version
│
├── docker-compose.yml                  # Local development services
├── Documentation/                      # Generated docs
├── peardrop.json                       # CLI configuration
└── README.md                           # Project README

Step 3: Set Up Your Environment

Start Docker services for local development:

# Start Docker services (SQL Server, Redis, etc.)
docker-compose up -d

# Verify services are running
docker-compose ps

Expected output:

   NAME                STATUS              
─────────────────────────────────────────
   sqlserver          running            
   redis              running
   jaeger             running

Step 4: Build and Run

# Restore NuGet packages & build solution
dotnet build

# Run the application
dotnet run --project source/MyApp.App

# Or using VS Code task (Ctrl+Shift+B)

When ready, you'll see:

Now listening on: https://localhost:7001
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to stop.

Step 5: Open in Browser

Navigate to your application:

https://localhost:7001

You should see the PearDrop application with:

Authentication page (if configured)
Sample module
Ready to develop!

Handling Directory Name Edge Cases

If your directory name isn't PascalCase, the setup helper can convert it:

# Directory: ten-to-one → Project: TenToOne
cd ten-to-one
dotnet new peardrop
./.peardrop/setup.ps1

# Use helper to auto-convert during initialization
./.peardrop/setup.ps1 -InitializeProject

Automatic conversions:

ten-to-one → TenToOne
my.app.name → MyAppName
hello_world → HelloWorld

Understanding the Generated Structure

Project Structure

After running ./.peardrop/setup.ps1 -InitializeProject (or ./.peardrop/setup.sh --initialize), your project structure looks like:

MyApp/                                 # Your project root
├── .peardrop/                          # CLI configuration & documentation
│   ├── setup.ps1                       # Installation and helper script
│   ├── nuget.config                    # Pre-configured NuGet feeds
│   ├── CLI-QUICK-START.md              # CLI command reference
│   ├── README.md                       # Setup and troubleshooting
│   └── .cli-version                    # Pinned CLI version
│
├── .config/                            # Local .NET tools
│   └── dotnet-tools.json               # Pinned PearDrop CLI version
│
├── source/                             # Application code
│   ├── MyApp.App/                      # Server
│   └── MyApp.App.Client/               # Client
├── docker-compose.yml                  # Local development services
├── peardrop.json                       # Project configuration
└── README.md                           # Project-specific docs

Core Directories

.peardrop/ - CLI configuration and documentation

Created by dotnet new peardrop
Contains setup scripts, guides, and NuGet feed configuration

source/ - Your application code

MyApp.App/ - ASP.NET Core server hosting Blazor
MyApp.App.Client/ - Blazor WebAssembly client

Documentation/ - Auto-generated docs (created during init, read-only)

peardrop.json - CLI configuration + project manifest

{
  "projectName": "MyApp",
  "projects": [
    {
      "name": "MyApp.App",
      "path": "source/MyApp.App",
      "role": "app",
      "moduleName": "Module",
      "registrationMethod": "AddMyAppAppModule"
    },
    {
      "name": "MyApp.App.Client",
      "path": "source/MyApp.App.Client",
      "role": "client"
    }
  ],
  "appProject": "source/MyApp.App",
  "clientProject": "source/MyApp.App.Client",
  "appRegistrationMethod": "AddMyAppAppModule",
  "frameworkVersion": "10.0.0",
  "usedModules": ["core"],
  "auth": {
    "configured": false,
    "mode": "none",
    "internalEnabled": false,
    "externalProviders": [],
    "externalProviderCount": 0
  }
}

Key Files

docker-compose.yml - Local development infrastructure

SQL Server 2022 database
Redis cache
Jaeger for distributed tracing (UI available at http://localhost:16686)

source/MyApp.App/Program.cs - Server startup

Registers PearDrop modules
Configures authentication
Sets up Blazor hosting

source/MyApp.App.Client/Program.cs - Client startup

Registers BluQube for CQRS
Sets up authentication state
Configures services

Troubleshooting

"Directory does not exist" error

Ensure you create and navigate to the directory before running setup:

mkdir MyApp
cd MyApp
./.peardrop/setup.ps1 -InitializeProject  # ✅ Correct

NOT:

./.peardrop/setup.ps1 -InitializeProject MyApp  # ❌ Wrong

"NuGet feed not found" error

Verify your NuGet feed URL is accessible:

# Check connectivity
Test-NetConnection -ComputerName "pkgs.dev.azure.com" -Port 443

# Or with file path
Test-Path "file:///c:/local-feed/index.json"

Then run setup with the correct feed:

./.peardrop/setup.ps1 -NuGetFeed "https://correct-feed-url" -InitializeProject

Docker services won't start

# Verify Docker is running
docker --version

# Check for port conflicts (SQL Server, Redis, Jaeger UI)
netstat -ano | findstr ":1433"  # SQL Server
netstat -ano | findstr ":6379"  # Redis
netstat -ano | findstr ":16686" # Jaeger UI

# Inspect container logs
docker logs sqlserver
docker logs redis
docker logs jaeger

Next Steps

Now that your project is initialized:

Your First Feature - Build your first domain feature
Project Structure - Understand the file layout
CQRS Operations - Implement commands and queries
Using the PearDrop CLI - Scaffold domain code with the CLI

Template Documentation

Detailed technical information is available in your project:

In .peardrop/ folder:

CLI-QUICK-START.md - CLI command reference
README.md - Setup and troubleshooting
AGENT-SETUP-GUIDE.md - Guide for developers
CLI-AGENT-GUIDE.md - Advanced patterns and decisions

In Documentation/ folder (auto-generated after init):

GETTING-STARTED.md - Feature development guide (read-only)

These files are kept in sync with your PearDrop framework version.

Overview​

Workflow: Create Directory → Setup Workspace → Install + Initialize via Setup Script → Develop​

Step 1: Create Your Project Directory​

Step 2: Install CLI and Initialize Project (Recommended)​

Setup Script Parameters​

Step 3: Set Up Your Environment​

Step 4: Build and Run​

Step 5: Open in Browser​

Handling Directory Name Edge Cases​

Understanding the Generated Structure​

Project Structure​

Core Directories​

Key Files​

Troubleshooting​

"Directory does not exist" error​

"NuGet feed not found" error​

Docker services won't start​

Next Steps​

Template Documentation​