opsos

Zero-config, incremental git-branch deploy CLI for MERN, Next.js, and Vite projects.

opsos is a lightweight command-line tool designed to build your project and deploy the output to a dedicated Git branch on your remote repository. By pushing only build artifacts to a branch (like stage or prod), your VPS/server can pull updates in seconds — completely bypassing complex Docker setups or resource-heavy CI/CD pipelines.

⚡ Key Features

• 🚀 Smart Auto-Detection: Automatically identifies Next.js (Standalone, Static Export, or Standard), Vite, Create React App, and generic frontend setups.
• ⏱️ Incremental Syncing: Only copies new or modified assets, keeping filesystem operations minimal and lightning-fast.
• 📁 File & Folder Copies: Configure custom file transfers in deploy-config.json by copying entire directories or targeting individual files.
• 🚫 Advanced Exclusions: Exclude specific files, extensions, or subfolders relative to your destination root.
• 🔧 Standalone Injection: Patches Next.js server.js with automated .env loaders and starting diagnostics upon deployment.
• 💾 Git Caching: Retains a persistent .deploy Git environment locally to make subsequent deploys near-instant.

📦 Installation

Use npx to run it on-demand without installation:

npx opsos deploy prod

Or install it globally / locally as a dev dependency:

# Global installation
npm install -g opsos

# As a dev dependency (recommended)
npm install -D opsos

🛠️ CLI Usage

opsos deploy [branch]     # Build and deploy to target branch (default: stage)
opsos init                # Auto-detect project structure & generate deploy-config.json
opsos help                # Show command help

Recommended package.json Scripts

Easily integrate opsos into your development workflow:

{
  "scripts": {
    "deploy:stage": "opsos deploy stage",
    "deploy:prod":  "opsos deploy prod"
  }
}

⚙️ Configuration (deploy-config.json)

To customize your builds, place a deploy-config.json in your project root. If not present, opsos will auto-generate one during the first run.

Default Auto-Detection Rules

| Project Type | Detection Trigger | Target Copy Source | |---|---|---| | Next.js Standalone | output: 'standalone' in next.config | .next/standalone | | Next.js Static Export | output: 'export' in next.config | out/ (or customized distDir) | | Vite | vite.config.* present | dist/ | | Create React App | react-scripts in package.json | build/ | | Generic | Fallback | dist/ |

Configuration Examples

1. Next.js Standalone (Default)

Optimized for production Node.js servers running Next.js standalone builds:

{
  "buildCommand": "npm run build",
  "copySteps": [
    {
      "src": ".next/standalone",
      "dest": ".deploy",
      "excludes": ["public", ".next/static", ".git"]
    },
    { "src": ".next/static", "dest": ".deploy/.next/static" },
    { "src": "public",       "dest": ".deploy/public" }
  ]
}

2. Vite / Static Web Application

For static Single Page Applications (SPA) deploying to GitHub Pages, Netlify, or static servers:

{
  "buildCommand": "npm run build",
  "copySteps": [
    { "src": "dist", "dest": ".deploy" }
  ]
}

3. Custom Assets & File Copying

You can copy specific files and apply exclusions to keep your target deployment clean:

{
  "buildCommand": "npm run build",
  "copySteps": [
    {
      "src": "dist",
      "dest": ".deploy",
      "excludes": [
        "temp-cache.json",
        "assets/ignored-file.png"
      ]
    },
    {
      "src": "config/production.json",
      "dest": ".deploy/config.json"
    }
  ]
}

🔄 How It Works Under the Hood

1. Verify Target Branch: Checks if the target deploy branch exists on your remote origin repository.
2. Version Increment: Runs npm version patch --no-git-tag-version to bump package version metadata cleanly.
3. Execute Build: Triggers the configured buildCommand (e.g. npm run build).
4. Shallow Repo Setup: Clones the remote target branch into a cached .deploy folder (using --depth 1).
5. Incremental Sync: Scans and pushes file updates from source directories/files into .deploy/ matching constraints and exclusions.
6. Deploy Server Injection: Automatically injects utility .env loaders and port diagnostics into any deployed server.js file.
7. Commit & Push: Commits changes as Deploy version <x.y.z> and pushes directly to the remote Git branch.

[!TIP] Add /.deploy to your root .gitignore file to ensure the temporary deployment directory remains out of your local development branch history.

🛡️ License

MIT © mytecsys