Servercn Provider 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/provider-name
 
# Install dependencies
npm install
 
# Run workspaces
npm run dev:app
npm run dev:cli

Add Provider Registry

Each provider must follow this registry structure:

packages/
  registry/
    provider/
      provider-slug.json

Use this shape as a reference:

{
  "$schema": "https://servercn.vercel.app/schema/foundation.registry.json",
  "slug": "my-provider",
  "runtimes": {
    "node": {
      "frameworks": {
        "express": {
          "templates": {
            "mvc": "my-provider/mvc",
            "feature": "my-provider/feature"
          },
          "dependencies": {
            "runtime": ["@prisma/client@6"],
            "dev": ["prisma@6"]
          },
          "env": ["DATABASE_URL"]
        }
      }
    }
  }
}

I. $schema

• Use the same schema URL currently used by provider registry files in this repository.
• Keep it exactly aligned with existing provider entries to pass validation checks.

II. slug

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

npx servercn-cli add pr my-provider

III. runtimes and frameworks

• Declare only supported runtime/framework combinations.
• Most current providers target node + express.
• Add another framework only if templates are implemented for it.

IV. templates

Maps architecture types to template folders:

{
  "templates": {
    "mvc": "my-provider/mvc",
    "feature": "my-provider/feature"
  }
}

V. dependencies

Defines packages auto-installed when the provider is added.

{
  "dependencies": {
    "runtime": ["your-runtime-dependency"],
    "dev": ["your-dev-dependency"]
  }
}

VI. env

Defines required environment variables:

{
  "env": ["DATABASE_URL"]
}

Add Templates

Create provider templates in:

packages/
  templates/
    node/
      express/
        provider/
          provider-slug/
            mvc/
            feature/

Recommended conventions:

• Keep architecture mapping consistent (mvc vs feature).
• Include env.ts for validation (zod).
• Use db.ts for Drizzle/Mongoose connection helpers.
• Use prisma.ts + schema.prisma for Prisma providers.
• Add logger only when needed and keep it consistent with existing providers.

Test the Provider via CLI

Before submitting:

npm run dev:cli

Then test provider installation locally:

npx servercn-cli add pr provider-slug --local

• --local uses local registry/templates for validation.

Verify:

Register in Web Registry

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

{
  "slug": "provider-slug",
  "type": "provider",
  "status": "stable",
  "frameworks": ["express"],
  "title": "Provider Title",
  "description": "Provider short description",
  "docs": "/docs/providers/provider-slug",
  "meta": {
    "new": true
  }
}

This entry powers docs sidebar navigation and listing in the providers route.

Write Provider Documentation

Add docs at: apps/web/src/content/docs/express/providers/provider-slug.mdx

Recommended sections:

• Overview
• Features
• Installation command
• File structure (MVC + Feature)
• Core code snippets (env.ts, db.ts/prisma.ts)
• Usage example
• Example .env

Commit Properly

Use conventional commits:

feat(provider): add provider-slug provider

Example:

feat(provider): add pg-prisma provider templates and docs

Submit a Pull Request

Your PR should include: