Servercn Schema Contributing Guide

This guide explains how to contribute a Data Schema to Servercn. A Schema represents the data layer of an application, including models, entities, and validation logic for various databases (MongoDB, PostgreSQL, MySQL) and ORMs (Mongoose, Drizzle).

What Is a Schema?

A Schema in Servercn is:

A collection of related data models (e.g., User, Session, OTP)
Database-agnostic in concept but implementation-specific
Type-safe and production-ready
Designed to work with both MVC and Feature-based architectures

Includes:

Model/Entity definitions
Relationship mappings
Zod validation schemas (optional but recommended)
Seed data (optional)

Schemas are the building blocks of blueprints.

Some servercn schemas:

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 feat/schema-name
 
# Install dependencies
npm install
 
# Run a workspace
npm run dev:app 
npm run dev:cli

Add Registry

Each schema must follow the registry structure. Schemas are unique because they often contain multiple files (sub-items):

packages/
  registry/
    schema/
      schema-name.json

The example below references the registry structure for a schema:

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

I. $schema

Points to the official Servercn schema registry definition.

II. slug

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

npx servercn-cli add sc my-schema

III. templates (Sub-items)

Schemas use a nested templates object where each key represents a "sub-item" (like index, user, or post).

index: Usually represents the main entry point or combined models.
individual items: Large schemas should be broken down into individual files.

IV. Physical Path

Mapping strings (e.g., my-schema/user/postgresql/drizzle/mvc) must exist inside: packages/templates/node/express/schema/

Example structure:

packages/
  templates/
    node/
      express/
        schema/
          my-schema/
            user/
              postgresql/
                drizzle/
                  mvc/
                  feature/

Add Templates

Ensure your templates:

Provide clear types/interfaces.
Use appropriate database naming conventions (snake_case for SQL, camelCase for MongoDB).
Include index files for easy exporting.

Test the Schema via CLI

Before submitting:

npm run build:cli

npx servercn-cli add sc schema-name --local

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

Verify:

Files are generated in the correct project location
Types are correctly imported
Database drivers match the implementation

Build the Registry Items

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

npx servercn-cli build

Don't forget to run `npx servercn-cli build` before submitting your pull request.

Register in registry.json

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

{
  "slug": "schema-slug",
  "title": "Schema Title",
  "description": "Schema short description",
  "type": "schema",
  "status": "stable",
  "docs": "/docs/schemas/schema-slug",
  "meta": {
    "databases": [
      {
        "label": "PostgreSQL (Drizzle)",
        "slug": "schema-slug-postgresql"
      },
      {
        "label": "MongoDB (Mongoose)",
        "slug": "schema-slug-mongodb"
      }
    ]
  }
}

Write Documentation

Add mdx documentation inside: apps/web/src/content/docs/express/schemas/schema-slug.mdx

Explain:

Entity/Model fields
Relationships
Database-specific nuances

Commit Properly

Use conventional commit format:

feat(schema): add schema-name schema

Submit a Pull Request

Your PR must include:

Clear title and summary
Supported database/ORM combinations
Updated registry and templates

License

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

Thank you for contributing to Servercn schemas 🚀 Your work helps building consistent data layers across projects.