Contributing Components to Servercn

Servercn is a backend component registry for Node.js and TypeScript projects.
This guide explains exactly how to create, structure, validate, and submit a reusable component to the registry.

This guide is strictly for contributing registry components — not core CLI or documentation changes.

Step-by-Step Contribution 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 my-new-branch
 
# Install dependencies
npm install
 
# Run a workspace
npm run dev:app # app
npm run dev:cli # cli

Understand Component Structure

Each component must follow the registry structure:

packages/
  registry/
    component/
      component-name.json

Add Registry

Each component must follow the registry structure:

1. Add Registry Without Variant

{
  "$schema": "https://servercn.vercel.app/schema/component.registry.json",
  "slug": "test-component",
  "runtimes": {
    "node": {
      "frameworks": {
        "express": {
          "dependencies": {
            "dev": ["express"],
            "runtime": ["@types/express"]
          },
          "templates": {
            "feature": "test-component/feature",
            "mvc": "test-component/mvc"
          },
          "env": ["TEST"]
        }
      }
    }
  }
}

2. Add Registry With Variant

{
  "$schema": "https://servercn.vercel.app/schema/component.registry.json",
  "slug": "test-component",
  "runtimes": {
    "node": {
      "frameworks": {
        "express": {
          "prompt": "Select the variant: ",
          "variants": {
            "test-variant": {
              "label": "Label that shown in the cli",
              "dependencies": {
                "dev": ["express"],
                "runtime": ["@types/express"]
              },
              "templates": {
                "feature": "test-component/feature",
                "mvc": "test-component/mvc"
              },
              "env": ["TEST"]
            }
          }
        }
      }
    }
  }
}

I. $schema

Points to the official Servercn component schema.
Ensures your configuration is validated automatically.
If this is missing or incorrect, the component will fail validation.
Always use the official schema URL.

{
  "$schema": "https://servercn.vercel.app/schema/component.registry.json",
}

II. slug

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

npx servercn-cli add test-component

{
 "slug": "test-component"
}

III. runtimes

Defines which runtime environments support this component.

"runtimes": {
  "node": { ... },
  "bun": { ... }
}

Currently, node is the primary runtime.
Future runtimes (e.g., bun, deno) may be added.
Your component must not assume compatibility with unsupported runtimes.

IV. frameworks

Specifies which frameworks the component supports.

"frameworks": {
  "express": { ... }
}

Only define frameworks your templates actually support.
If you declare express, you must provide valid Express-compatible templates.
Do not declare frameworks without implementation support.

V. prompt

{
  "prompt": "Select the variant: "
}

Displays a selection message in the CLI.
Used when your component has multiple variants.
Keep prompt concise.
Avoid explanations inside the prompt.
Prompt should describe a decision (library, strategy, mode).

Example CLI output:

? Select the variant:
> test-variant
  test-variant2

VI. variants

Each key under variants represents a selectable implementation option.

"variants": {
  "test-variant": { ... }
}

Key must be kebab-case.
Each variant must define: label, templates
Optional but recommended: dependencies, env

VII. label

{
  "label": "Label that shown in the cli"
}

Human-readable name shown in CLI.
Should clearly describe the variant.

Example for email-provider:

{
  "label": "Select an email provider: "
}

VIII. dependencies

Defines packages automatically installed when the component is added.

{
  "dependencies": {
    "dev": ["express"],
    "runtime": ["@types/express"]
  }
}

| Field     | Meaning                  |
| --------- | ------------------------ |
| `runtime` | Production dependencies  |
| `dev`     | Development dependencies |

Only include packages required by your templates.
Do not include unnecessary peer dependencies.

IX. templates

Maps architecture types to template folders.

{
  "templates": {
  "feature": "test-component/feature",
  "mvc": "test-component/mvc"
  }
}

If you declare both, you must implement both.
Template folder paths must exist inside:
packages/templates/node/express/component/test-component/

Example:

packages/
  templates/
    node/
      express/
        component/
          component-name/
            feature/
            mvc/

X. env

Defines required environment variables.

{
  "env": ["NODE_ENV"]
}

Only include truly required variables.
Use clear naming conventions.
Avoid default secrets inside templates.

Add Templates

Template must follow the folder structure below:

packages/
  templates/
    node/
      express/
        component/
          component-name
            feature/
            mvc/

Follow clean separation of concerns
Match selected architecture style
Avoid unnecessary dependencies
Be production-ready

Test the Component via CLI

Before submitting:

npm run build:cli

npx servercn-cli add test-component --local

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

Verify:

No runtime errors
Files generate correctly
Architecture mapping works
Stack selection works

Build the Registry Items

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

npx servercn-cli build

What This Does:

Compiles all registry items
Validates schema structure
Processes component metadata
Outputs generated files into: apps/web/public/sr/

Verification:

After running the build command:
Navigate to apps/web/public/sr/
Confirm your component/item appears
Ensure generated JSON reflects your changes

Only proceed with your pull request after confirming the registry output is correct.

Don't forget to run `npx servercn-cli build` before submitting your pull request to ensure the registry output is up to date.

Register in registry.json

Add registry inside: apps/web/src/data/registry.json

{
  "name": "Servercn",
  "homepage": "https://servercn.vercel.app",
  "author": "Akkal Dhami",
  "items": [
    ...
      {
        "slug": "component-slug",
        "title": "Component Title",
        "description": "Component short description",
        "type": "component",
        "status": "stable",
        "docs": "/docs/components/component-slug"
      },
      ....
  ]
}

This configuration is used to generate the docs sidebar and display components in the /components route.

Write Minimal Documentation

Add mdx documentation inside:

apps/web/src/content/docs/express/components/component-slug.mdx

Keep documentation concise and technical.

Don't forget to include `mvc_structure` and `feature_structure` in the front matter.

Commit Properly

Use conventional commit format:

feat(component): add password-hashing component

Example:

feat(security-header): add middleware for configuring security headers with Helmet and CORS

Submit a Pull Request

Your PR must include:

Clear title
Component summary
Supported stacks
Testing confirmation

PR checklist:

Schema valid
Templates structured correctly
CLI tested
No unrelated changes
Clean commit history

License

By contributing a component to Servercn, you agree that your contribution will be licensed under the MIT License.

Thank you for contributing to Servercn components 🚀 Your work helps strengthen the Node.js backend ecosystem.