Servercn Blueprint Contributing Guide

Fork & Clone the Repository

Fork the Servercn repository and clone it locally: GitHub Link

# Clone on your local machine
git clone https://github.com/<your-username>/servercn.git
 
# Navigate to project directory
cd servercn
 
# Create a new Branch
git checkout -b feat/blueprint-name
 
# Install dependencies
npm install
 
# Run a workspace
npm run dev:app 
npm run dev:cli

Add Registry

Each blueprint must follow the registry structure. Blueprints have a more nested structure because they support multiple databases and ORMs:

packages/
  registry/
    blueprint/
      blueprint-name.json

The example below references the registry structure for a blueprint:

{
  "$schema": "https://servercn.vercel.app/schema/blueprint.registry.json",
  "slug": "my-blueprint",
  "runtimes": {
    "node": {
      "frameworks": {
        "express": {
          "databases": {
            "postgresql": {
              "orms": {
                "drizzle": {
                  "templates": {
                    "mvc": "my-blueprint/postgresql/drizzle/mvc",
                    "feature": "my-blueprint/postgresql/drizzle/feature"
                  },
                  "dependencies": {
                    "runtime": ["pg", "drizzle-orm"],
                    "dev": ["@types/pg", "drizzle-kit"]
                  },
                  "env": ["DATABASE_URL"]
                }
              }
            }
          }
        }
      }
    }
  }
}

I. $schema

• Points to the official Servercn blueprint schema.
• Ensures your configuration is validated automatically.

II. slug

• Unique identifier of the blueprint.
• Must be kebab-case.
• Used internally by CLI commands:

pnpmnpmyarnbun

npx servercn-cli add bp my-blueprint

III. databases & orms

Blueprints are designed to be flexible. You should ideally provide implementations for:

• Databases: PostgreSQL, MySQL, MongoDB.
• ORMs: Drizzle (for SQL), Mongoose (for MongoDB).

IV. templates

Templates define the physical location of the code for each combination. Template folder paths must exist inside: packages/templates/node/express/blueprint/blueprint-name/database/orm/architecture/

Example:

packages/
  templates/
    node/
      express/
        blueprint/
          my-blueprint/
            postgresql/
              drizzle/
                mvc/
                feature/

Add Templates

Ensure your templates:

• Follow clean separation of concerns.
• Are production-ready with proper error handling and logging.
• Use components where possible instead of duplicating code.

Test the Blueprint via CLI

Before submitting:

npm run build:cli

pnpmnpmyarnbun

npx servercn-cli add bp blueprint-name --local

• --local: Used for testing in the local environment.

Verify:

Build the Registry Items

Before opening your pull request, ensure the registry output is generated and up to date.

pnpmnpmyarnbun

npx servercn-cli build

What This Does:

Register in registry.json

Add your blueprint entry to: apps/web/src/data/registry.json

{
  "slug": "blueprint-slug",
  "title": "Blueprint Title",
  "description": "Blueprint short description",
  "type": "blueprint",
  "status": "stable",
  "docs": "/docs/blueprints/blueprint-slug",
  "meta": {
    "databases": [
      {
        "label": "PostgreSQL (Drizzle)",
        "slug": "blueprint-slug-postgresql"
      }
    ]
  }
}

Write Documentation

Add mdx documentation inside: apps/web/src/content/docs/express/blueprints/blueprint-slug.mdx

Explain:

• Key features
• How the logic works
• Installation steps
• Environment variables required

Commit Properly

Use conventional commit format:

feat(blueprint): add blueprint-name blueprint

Submit a Pull Request

Your PR must include: