Product Ready Boilerplate Markers

The Product Ready Boilerplate provides production-grade infrastructure for Next.js SaaS applications. This document describes the technical specification for marking and tracking apps based on this boilerplate.

Identification System

Apps based on Product Ready are marked with a productready field in their package.json. This provides a lightweight, maintainable way to track which apps derive from the boilerplate.

package.json Marker Structure

{
  "name": "@app/web",
  "productready": {
    "type": "derived",
    "baseVersion": "0.3.0",
    "features": {
      "auth": true,
      "database": true,
      "trpc": true,
      "openapi": true,
      "i18n": true,
      "documentation": true,
      "billing": true,
      "email": true,
      "ai": true,
      "demo": true,
      "testing": true
    },
    "aligned": true,
    "missingFeatures": []
  }
}

Field Descriptions

Core Fields:

• type - Either "original" (productready itself) or "derived" (apps based on it)
• baseVersion - The version of Product Ready the app is based on (e.g., "0.3.0")

Feature Tracking:

• features - Object tracking which of the 11 Product Ready features are implemented
  • auth - Authentication system (Better Auth)
  • database - Database layer (Drizzle ORM with PostgreSQL)
  • trpc - Type-safe API (tRPC v11)
  • openapi - OpenAPI documentation
  • i18n - Internationalization support
  • documentation - User documentation (Fumadocs)
  • billing - Billing integration
  • email - Email sending capability
  • ai - AI features integration
  • demo - Demo/example implementations
  • testing - Test infrastructure (Vitest)

Alignment Status:

• aligned - Boolean indicating if all features match the boilerplate
• missingFeatures - Array listing features not yet implemented (only when aligned: false)

Detection and Validation

Apps can be detected and validated using automated scripts:

# List all Product Ready apps with feature alignment status
node scripts/detect-productready-apps.mjs

# Validate markers match patterns (for CI)
node scripts/detect-productready-apps.mjs --validate

The detection system uses two methods:

1. Explicit markers - Checks for productready field in package.json
2. Pattern detection - Verifies dependencies, folder structure, and scripts

Common Patterns

Apps based on Product Ready typically share these patterns:

• Better Auth for authentication
• Drizzle ORM with PostgreSQL for database
• tRPC v11 for type-safe APIs
• Consistent folder structure (src/lib/auth, src/server/routers, etc.)
• Standard scripts (auth:generate, db:migrate, etc.)

Technical Alignment

Apps marked with Product Ready should reference the boilerplate as the canonical implementation for infrastructure patterns.

Best Practices:

1. Check the Product Ready reference implementation before implementing features
2. Align changes with established patterns
3. Only diverge when business requirements clearly differ

Adding Product Ready Marker to New Apps

If you create a new app based on Product Ready:

1. Add the marker to package.json:

   "productready": {
     "type": "derived",
     "baseVersion": "0.3.0",
     "features": {
       "auth": true,
       "database": true,
       // ... set based on what you've implemented
     },
     "aligned": true,
     "missingFeatures": []
   }

2. Run detection to verify:

   node scripts/detect-productready-apps.mjs

3. Update features as you implement them:

   • Set feature flags to true as you add capabilities
   • Update aligned to false if missing features
   • List missing features in missingFeatures array

Maintenance

Updating Feature Alignment

When you add or remove Product Ready features in an app:

1. Edit the productready field in package.json
2. Update feature flags accordingly
3. Run validation: node scripts/detect-productready-apps.mjs --validate

Tracking Boilerplate Updates

When Product Ready is updated:

1. Update baseVersion in derived apps if you migrate
2. Check for new features and update feature flags
3. Re-run detection to verify alignment

Benefits

• ✅ Low maintenance - package.json is already part of workflow
• ✅ Clear visibility - Easy to see which apps align with Product Ready
• ✅ Feature tracking - Know exactly what's implemented in each app
• ✅ Machine-readable - Can be queried programmatically for tooling
• ✅ Extensible - Easy to add new features as boilerplate evolves
• ✅ Single source of truth - All information in package.json