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"]
        }
      }
    }
  }
}

I. $schema

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

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

II. slug

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

npx servercn-cli add fd express-starter

{
 "slug": "express-starter"
}

III. runtimes

Defines which runtime environments support this foundation.

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

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

IV. frameworks

Specifies which frameworks the foundation 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. dependencies

Defines packages automatically installed when the foundation is added.

{
  "dependencies": {
      "runtime": [...],
      "dev": [...]
  }
}

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

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

VI. templates

Templates define project structure variants.

{
  "templates": {
    "mvc": "express-starter/mvc",
    "feature": "express-starter/feature"
  }
}

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

Example:

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

VII. env

Defines required environment variables.

{
  "env": [
    "LOG_LEVEL",
    "NODE_ENV",
    "PORT",
    "CORS_ORIGIN",
    "DATABASE_URL"
  ]
}

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 build: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

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

{
  ...,
  "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.

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

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.