Servercn Foundation Contributing Guide

This guide explains how to contribute a Foundation to Servercn. A foundation represents a production-ready backend baseline (database, logging, security, env setup, tooling, etc.) that other foundations build upon.

What Is a Foundation?

A Foundation in Servercn is:

  • A complete backend starting structure
  • Opinionated but extensible
  • Runtime + framework scoped

Includes:

  • Templates (project structures)
  • Runtime dependencies
  • Dev dependencies
  • Required environment variables

It is not a single feature — it is the base architecture layer.

Some servercn foundations:


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 
npm run dev:cli

Add Registry

Each foundation must follow the registry structure:

packages/
  registry/
    foundation/
      foundation-name.json

The example below references the demo foundation:

{
  "$schema": "https://servercn.vercel.app/schema/foundation.registry.json",
  "slug": "express-starter",
  "runtimes": {
    "node": {
      "frameworks": {
        "express": {
          "templates": {
            "mvc": "express-starter/mvc",
            "feature": "express-starter/feature"
          },
          "dependencies": {
            "runtime": [
              "express",
              "cors",
              "helmet",
              "cookie-parser",
              "pino",
              "pino-pretty",
              "source-map-support",
              "zod"
            ],
            "dev": [
              "@types/express",
              "typescript",
              "dotenv",
              "tsx",
              "morgan",
              "@types/cors",
              "@types/cookie-parser",
              "prettier",
              "@commitlint/cli",
              "@commitlint/config-conventional",
              "@types/source-map-support",
              "lint-staged"
            ]
          },
          "env": ["LOG_LEVEL", "NODE_ENV", "PORT", "CORS_ORIGIN"]
        }
      }
    }
  }
}
  • Only include truly required variables.
  • Use clear naming conventions.
  • Avoid default secrets inside templates.
  • No hardcoded credentials.

Add Templates

Template must follow the folder structure below:

packages/
  templates/
    node/
      express/
        foundation/
          foundation-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 dev:cli
npx servercn-cli add fd foundation-name --local
  • --local: Used for testing in the local environment.

Verify:

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

Register in registry.json

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

{
  ...,
  "items": [
      {
        "slug": "foundation-slug",
        "title": "Foundation Title",
        "description": "foundation short description",
        "type": "foundation",
        "status": "stable",
        "docs": "/docs/foundations/foundation-slug"
      }
  ]
}

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

Write Minimal Documentation

Add mdx documentation inside:

apps/web/src/content/docs/express/foundations/foundation-slug.mdx

Keep documentation concise and technical.

Validation Checklist Before PR

  • Slug is unique
  • Schema URL correct
  • Templates exist physically
  • Dependencies match imports
  • No unused packages
  • Type definitions installed
  • Foundation builds without errors

Commit Properly

Use conventional commit format:

feat(foundation): add foundation-name foundation

Example:

feat(foundation): add drizzle-pg-starter for node/express with mvc and feature architecture

Submit a Pull Request

Your PR must include:

  • Clear title
  • Foundation summary
  • Supported stacks
  • Testing confirmation
  • Foundation registry entry
  • Template directories

License

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

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