Installation

This guide will help you install and set up ServerCN in your Node.js project.

Prerequisites

Before installing ServerCN, ensure you have:

  • Node.js version 18 or higher
  • npm, yarn, bun or pnpm package manager
  • An existing Node.js project (or create a new one)
  • TypeScript (recommended but not required)

Quick Start

The fastest way to get started with ServerCN:

1. Initialize ServerCN in your project

npx servercn init

2. Add your first component

npx servercn add error-handler

Step-by-Step Installation

1. Create a New Project (Optional)

If you're starting a new project, create a new directory and initialize it:

mkdir my-backend
cd my-backend
npm init -y

2. Install TypeScript (Recommended)

ServerCN works best with TypeScript:

npm install -D typescript @types/node @types/express
npx tsc --init

3. Initialize ServerCN

Run the initialization command in your project root:

npx servercn init

This will prompt you with a series of questions to configure your project:

Configuration Options

Project Root Directory

  • Default: . (current directory)
  • The root directory where your project lives

Source Directory

  • Default: src
  • Where your source code will be located

Architecture

  • MVC: Traditional Model-View-Controller structure
  • Feature-based: Feature-module architecture

Language

  • TypeScript: Recommended for type safety

Backend Framework

  • Express: Currently supported framework

Database

  • MongoDB: With Mongoose ORM
  • More databases coming soon

Package Manager

  • npm: Node Package Manager
  • pnpm: Fast, disk space efficient
  • yarn: Alternative package manager
  • bun: Superfast Node.js-compatible package manager

4. Configuration File

After initialization, ServerCN creates a servercn.json file in your project root:

{
  "$schema": "https://servercn.dev/schema/v1.json",
  "version": "1.0.0",
  "project": {
    "root": ".",
    "srcDir": "src",
    "type": "backend",
    "packageManager": "npm"
  },
  "stack": {
    "runtime": "node",
    "language": "typescript",
    "framework": "express",
    "architecture": "feature"
  },
  "database": {
    "type": "mongodb",
    "orm": "mongoose"
  },
  "overrides": {}
}

This file stores your project configuration and is used by ServerCN to generate components in the correct structure.

Adding Components

Once initialized, you can add components to your project:

# Add a component
npx servercn add <component-name>
 
# Examples
npx servercn add error-handler
npx servercn add jwt-utils
npx servercn add request-validator

Listing Available Components

To see all available components:

npx servercn list

Project Structure

After initialization, your project structure will look like this:

my-backend/
├── src/                    # Source directory
├── servercn.json          # ServerCN configuration
├── package.json           # Node.js dependencies
└── tsconfig.json          # TypeScript configuration

MVC Architecture

When using MVC architecture, components are organized as:

src/
├── configs/               # Configuration files
├── constants/            # Constants and enums
├── controllers/          # Route controllers
├── middlewares/          # Express middlewares
├── models/               # Database models
├── routes/               # Route definitions
├── services/             # Business logic
├── utils/                # Utility functions
└── validations/          # Validation schemas

Feature-Based Architecture

When using feature-based architecture, components are organized as:

src/
├── shared/               # Shared code
│   ├── configs/
│   ├── constants/
│   ├── errors/
│   ├── middlewares/
│   └── utils/
├── modules/              # Feature modules
│   └── user/
│       ├── controllers/
│       ├── routes/
│       ├── services/
│       └── validations/
└── routes/               # Main route index

Common Commands

Initialize ServerCN

npx servercn init

Add a Component

npx servercn add <component-name>

Or you can add multiple components like this:

npx servercn add jwt-utils http-status-codes logger-pino

List Available Components

npx servercn list

Add Component with Architecture Override

npx servercn add <component-name> --arch=feature

Installing Components

When you add a component, ServerCN will:

  1. Copy component files to your project following your architecture
  2. Install dependencies required by the component
  3. Update .env.example with required environment variables
  4. Create necessary directories if they don't exist

Example: Adding Error Handler

npx servercn add error-handler

This will:

  • Create src/middlewares/error-handler.ts (MVC) or src/shared/middlewares/error-handler.ts (Feature)
  • Create src/utils/api-error.ts or src/shared/errors/api-error.ts
  • Create src/constants/status-codes.ts or src/shared/constants/status-coes.ts
  • Install any required npm packages

Updating Configuration

You can manually edit servercn.json to change your project configuration:

{
  "stack": {
    "architecture": "feature" // Change from "mvc" to "feature"
  }
}

After updating, new components will use the updated configuration.

Verifying Installation

To verify ServerCN is properly installed:

  1. Check for servercn.json in your project root
  2. Run npx servercn list to see available components
  3. Try adding a component: npx servercn add error-handler

Troubleshooting

Already Initialized

If you see "ServerCN is already initialized":

  • Your project already has a servercn.json file
  • You can start adding components immediately
  • To reinitialize, delete servercn.json first

Component Not Found

If a component doesn't exist:

# List all available components
npx servercn list
 
# Check component name spelling
npx servercn add error-handler  # ✅ Correct
npx servercn add errorhandler   # ❌ Incorrect

TypeScript Errors

If you encounter TypeScript errors:

  1. Ensure TypeScript is installed: npm install -D typescript @types/node
  2. Check tsconfig.json exists and is properly configured
  3. Ensure component dependencies are installed

Architecture Mismatch

If components aren't appearing in the expected location:

  1. Check your servercn.json architecture setting
  2. Verify your srcDir configuration
  3. Ensure directories exist before adding components

Next Steps

After installation:

  1. Add your first component: npx servercn add error-handler
  2. Set up your Express app: Create src/app.ts
  3. Add more components: Explore available components with npx servercn list
  4. Read component docs: Each component has detailed documentation

Getting Help

  • Documentation: Check component-specific docs in /docs/components/
  • Issues: Report issues on GitHub
  • Community: Join our community discussions

Uninstalling

To remove ServerCN from your project:

  1. Delete servercn.json configuration file
  2. Remove any ServerCN components you've added
  3. Remove ServerCN-specific dependencies (if any)

Note: ServerCN doesn't install itself as a runtime dependency. Components are copied into your codebase, so you own the code completely.