{"id":11424,"library":"node-git-server","title":"Node.js Git Server","description":"node-git-server is a highly configurable Git server implemented in Node.js, designed for embedding or standalone deployment within a Node.js environment. The project adheres to a 'zero dependency footprint' philosophy, aiming to keep its core lean and efficient. Its current stable version is 1.0.0, released recently after an extensive beta phase. Key differentiators include its programmatic control over Git operations, extensive configurability for authentication and authorization, and its origin as a hard fork of the well-established `pushover` library. The library migrated to TypeScript starting with version 1.0.0-beta.1, enhancing type safety and developer experience. It now requires Node.js version 16 or newer, aligning with modern Node.js LTS releases. The project shows an active development and release cadence, having frequently updated through its beta cycle to reach a stable 1.0.0 release.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/gabrielcsapo/node-git-server","tags":["javascript","typescript"],"install":[{"cmd":"npm install node-git-server","lang":"bash","label":"npm"},{"cmd":"yarn add node-git-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-git-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses ESM and ships TypeScript types. Use named import for the main server class.","wrong":"const GitServer = require('node-git-server');","symbol":"GitServer","correct":"import { GitServer } from 'node-git-server';"},{"note":"Import types explicitly for configuration objects or event payloads.","symbol":"GitServerOptions","correct":"import type { GitServerOptions } from 'node-git-server';"},{"note":"Type definitions for event payloads like 'push' and 'pull' are available for better type safety.","symbol":"PushEvent","correct":"import type { PushEvent } from 'node-git-server';"}],"quickstart":{"code":"import { GitServer } from 'node-git-server';\nimport path from 'path';\nimport fs from 'fs';\n\nconst REPOS_DIR = path.resolve(process.env.GIT_REPOS_DIR ?? './tmp/repos');\n\n// Ensure the repository directory exists\nif (!fs.existsSync(REPOS_DIR)) {\n  fs.mkdirSync(REPOS_DIR, { recursive: true });\n}\n\nconst git = new GitServer(REPOS_DIR, {\n  autoCreate: true, // Automatically create repositories on first push\n  authenticate: (type, repository, username, password, callback) => {\n    console.log(`Authentication attempt: ${type} for ${repository} by ${username}`);\n    // In a real application, validate username and password against a database\n    if (username === 'gituser' && password === 'gitpass') {\n      console.log('Authentication successful.');\n      return callback(null, true); // Authentication successful\n    }\n    console.log('Authentication failed.');\n    return callback(new Error('Authentication failed'), false); // Authentication failed\n  },\n  authorize: (type, repository, username, callback) => {\n    console.log(`Authorization attempt: ${type} for ${repository} by ${username}`);\n    // In a real application, check permissions based on user and repository\n    if (username === 'gituser') {\n      console.log('Authorization successful.');\n      return callback(null, true); // Authorization successful\n    }\n    console.log('Authorization failed.');\n    return callback(new Error('Authorization failed'), false); // Authorization failed\n  },\n});\n\ngit.on('push', (push) => {\n  console.log(`Push event: ${push.repo}/${push.commit} by ${push.branch}`);\n  push.accept(); // Accept the push\n});\n\ngit.on('fetch', (fetch) => {\n  console.log(`Fetch event: ${fetch.repo} by ${fetch.branch}`);\n  fetch.accept(); // Accept the fetch\n});\n\nconst PORT = parseInt(process.env.GIT_SERVER_PORT ?? '7000', 10);\n\ngit.listen(PORT, () => {\n  console.log(`node-git-server running on port ${PORT}`);\n  console.log(`Serving repositories from: ${REPOS_DIR}`);\n  console.log(`Try cloning: git clone http://localhost:${PORT}/my-repo.git`);\n});\n\n// Handle process exit to close server gracefully\nprocess.on('SIGINT', () => {\n  console.log('Shutting down git server...');\n  git.close(() => {\n    console.log('Git server closed.');\n    process.exit(0);\n  });\n});","lang":"typescript","description":"This quickstart code demonstrates how to set up a basic configurable Git server using node-git-server. It initializes a Git server instance, defines a directory for repositories, implements a simple username/password authentication mechanism, and handles push/fetch events. The server listens on a specified port, allowing users to clone and push to repositories managed by this instance."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 16 or newer. Use a Node Version Manager (NVM) for easy switching.","message":"Version 1.0.0 and subsequent versions no longer support Node.js environments older than Node.js 16. Running on unsupported versions will lead to errors.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Update your `authenticate` function to match the new `(type, repository, username, password, callback)` signature, or `(options: { type: string, repository: string, username?: string, password?: string, headers?: object }, callback)`. Refer to the 0.6.0 release notes for details.","message":"The `authenticate` function signature changed in version 0.6.0. It now accepts an object as the first argument, followed by a callback, allowing for more flexible introspection (e.g., on headers).","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Ensure your project uses ESM imports (`import ... from '...'`) and is configured for TypeScript. If using CommonJS, check for potential compatibility issues or adjust your `tsconfig.json` and build setup.","message":"The library migrated to TypeScript in version 1.0.0-beta.1. While this improves type safety, it implies that the package is primarily consumed as an ESM module. Older CommonJS `require()` statements might encounter issues if not correctly configured or if the package no longer provides a CJS entry point.","severity":"gotcha","affected_versions":">=1.0.0-beta.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js runtime to version 16 or newer. For example, using nvm: `nvm install 16 && nvm use 16`.","cause":"Attempting to run `node-git-server` version 1.0.0 or higher on Node.js versions older than 16.","error":"Error: This version of Node.js is not supported."},{"fix":"Switch to ESM imports: `import { GitServer } from 'node-git-server';` and ensure your `package.json` has `\"type\": \"module\"` or files end with `.mjs`.","cause":"Attempting to `require()` an ESM-only package in a CommonJS context without proper configuration.","error":"ERR_REQUIRE_ESM"},{"fix":"Verify that your `authenticate` and `authorize` function callbacks match the expected `(error, success)` signature and that all arguments are correctly passed as per the documentation (e.g., `(type, repository, username, password, callback)`).","cause":"Incorrect signature provided to the `authenticate` or `authorize` functions, leading to `callback` being undefined or not a function.","error":"TypeError: callback is not a function"}],"ecosystem":"npm"}