https://github.com/arcblock/super-linter-api

A comprehensive HTTP API wrapper for code linting built on top if super-linter
https://github.com/arcblock/super-linter-api
Last synced: 9 months ago
JSON representation
A comprehensive HTTP API wrapper for code linting built on top if super-linter
Host: GitHub
URL: https://github.com/arcblock/super-linter-api
Owner: ArcBlock
License: mit
Created: 2025-08-25T03:06:29.000Z (10 months ago)
Default Branch: main
Last Pushed: 2025-09-23T03:29:59.000Z (9 months ago)
Last Synced: 2025-09-23T04:24:13.293Z (9 months ago)
Language: TypeScript
Size: 799 KB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 12
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

README

          # Super-linter API



[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

[![Docker](https://img.shields.io/badge/docker-supported-blue.svg)](https://www.docker.com/)

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)

**🚀 One-command HTTP API for code linting with 18+ production-ready linters**

[Quick Start](#-quick-start) • [Live Demo](#-live-demo) • [API Docs](#-api-reference) • [Docker Hub](https://hub.docker.com/r/arcblock/super-linter-api)



---

## ✨ **What is Super-linter API?**

A **production-ready HTTP API** that wraps 18+ popular code linters (ESLint, Prettier, Pylint, gofmt, RuboCop, etc.) into a single Docker container. Start linting any codebase in **under 10 seconds** with a simple REST API.

```bash

# Start the API (takes ~10 seconds)

docker run -p 3000:3000 arcblock/super-linter-api:latest

# Lint JavaScript instantly

curl -X POST http://localhost:3000/eslint/json \

  -d "console.log('Hello'); var unused = 42;"

```

### 🎯 **Perfect For:**

- **CI/CD Pipelines** - Fast, reliable linting in containers

- **Code Review Tools** - Integrate linting into PR workflows

- **Multi-language Projects** - One API for JavaScript, Python, Go, Ruby, Docker, YAML, etc.

- **Microservices** - Centralized linting service for distributed teams

---

## 🏃 **Quick Start**

### Option 1: Docker (Recommended)

```bash

# Production-ready in 10 seconds

docker run -d -p 3000:3000 --name linter-api arcblock/super-linter-api:latest

# Test it works

curl http://localhost:3000/health

```

### Option 2: Try Online

🌐 **[Live Demo API](https://super-linter-api-demo.herokuapp.com)** - Test without installing

### Option 3: Local Development

```bash

git clone https://github.com/arcblock/super-linter-api.git

cd super-linter-api && pnpm install && pnpm dev

```

---

## 🚀 **Live Demo**

### JavaScript Linting

```bash

curl -X POST http://localhost:3000/eslint/json \

  -H "Content-Type: application/json" \

  -d '{

    "content": "const unused = 42; console.log(\"Hello World\");",

    "filename": "demo.js"

  }'

```

**Response:**

```json

{

  "success": true,

  "execution_time_ms": 245,

  "issues": [

    {

      "file": "demo.js",

      "line": 1,

      "rule": "no-unused-vars",

      "severity": "error",

      "message": "'unused' is assigned a value but never used."

    }

  ]

}

```

### Ultra-Fast Alternative (Oxlint - 5x faster)

```bash

curl -X POST http://localhost:3000/oxlint/json \

  -d '{"content": "const unused = 42;", "filename": "test.js"}'

# ⚡ Returns in ~150ms vs ~750ms for ESLint

```

---

## 📊 **Supported Linters**

| Language                  | Linters                            | Status         | Use Cases                                 |

| ------------------------- | ---------------------------------- | -------------- | ----------------------------------------- |

| **JavaScript/TypeScript** | ESLint, Oxlint, Biome, Prettier    | ✅ 5 available | Modern web development, React, Node.js    |

| **Python**                | Pylint, Black, MyPy, isort, Flake8 | ✅ 5 available | Django, FastAPI, data science, automation |

| **Go**                    | gofmt, golangci-lint               | ✅ 2 available | Microservices, CLI tools, backend APIs    |

| **Ruby**                  | RuboCop                            | ✅ 1 available | Rails apps, Ruby gems, web backends       |

| **Shell**                 | ShellCheck                         | ✅ 1 available | DevOps scripts, automation, Docker builds |

| **Docker**                | Hadolint                           | ✅ 1 available | Container best practices, security        |

| **YAML**                  | yamllint                           | ✅ 1 available | Kubernetes, CI/CD configs, Ansible        |

| **Markdown**              | markdownlint                       | ✅ 1 available | Documentation, README files, blogs        |

| **CSS**                   | stylelint                          | ✅ 1 available | Frontend styling, design systems          |

**📈 Total: 18/21 linters available** • [View complete table →](./docs/LINTERS.md)

---

## 🔧 **API Reference**

### Core Endpoints

```bash

# Synchronous linting

POST /{linter}/{format}              # Lint code instantly

POST /{linter}/{format}/async        # Submit long-running job

GET  /jobs/{job_id}                  # Check job status

# System endpoints

GET  /health                         # System health

GET  /linters                        # Available linters

```

### Request Formats

```bash

# Plain text

curl -X POST http://localhost:3000/eslint/json -d "console.log('hello');"

# JSON with options

curl -X POST http://localhost:3000/eslint/json \

  -H "Content-Type: application/json" \

  -d '{

    "content": "console.log(\"hello\");",

    "options": {"timeout": 10000}

  }'

# File upload (base64)

curl -X POST http://localhost:3000/eslint/json \

  -d '{"archive": "", "options": {"validate_all": true}}'

```

### Output Formats

- `json` - Structured issue data (recommended)

- `text` - Plain text output

- `sarif` - Security analysis format

**📖 [Complete API Documentation →](./docs/API.md)**

---

## ⚡ **Performance Benchmarks**

| Linter     | Language | Speed                     | Best For                        |

| ---------- | -------- | ------------------------- | ------------------------------- |

| **gofmt**  | Go       | 🚀🚀🚀 Ultra-fast (50ms)  | Go code formatting              |

| **Biome**  | JS/TS    | 🚀🚀🚀 Ultra-fast (200ms) | All-in-one formatting & linting |

| **Oxlint** | JS/TS    | 🚀🚀🚀 Ultra-fast (150ms) | Fast feedback, CI/CD            |

| **isort**  | Python   | 🚀🚀🚀 Ultra-fast (100ms) | Import organization             |

| **RuboCop** | Ruby     | 🚀🚀 Fast (1-3s)         | Ruby style guide enforcement   |

| **ESLint** | JS/TS    | 🐢 Slower (750ms)         | Legacy projects, complex rules  |

| **Pylint** | Python   | 🐢 Slower (2000ms)        | Comprehensive analysis          |

_Tested on standard codebase (100 lines)_

---

## 🐳 **Production Deployment**

### Quick Start with Persistent Storage

```bash

# Just run it - permissions are handled automatically!

docker run -d -p 3000:3000 -v "$(pwd)/data:/app/data" arcblock/super-linter-api:latest

```

That's it! The container automatically:

- Creates the data directory if it doesn't exist

- Fixes permissions automatically 

- Falls back to temporary storage if needed

### Docker Compose (Production)

```yaml

version: '3.8'

services:

  super-linter-api:

    image: arcblock/super-linter-api:latest

    ports: ['3000:3000']

    volumes: ['./data:/app/data'] # Persistent cache & jobs

    restart: unless-stopped

    environment:

      - NODE_ENV=production

    healthcheck:

      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']

```

### Kubernetes

```yaml

apiVersion: apps/v1

kind: Deployment

metadata:

  name: super-linter-api

spec:

  replicas: 3

  template:

    spec:

      containers:

        - name: api

          image: arcblock/super-linter-api:latest

          ports: [containerPort: 3000]

          livenessProbe:

            httpGet: { path: /health, port: 3000 }

```

**🔧 [Complete deployment guide →](./docs/DEPLOYMENT.md)**

---

## 🤝 **Contributing**

We welcome contributions! Here's how to get started:

```bash

# 1. Fork & clone

git clone https://github.com/yourusername/super-linter-api.git

# 2. Install dependencies

pnpm install

# 3. Start development server

pnpm dev

# 4. Run tests

pnpm test

```

**📝 [Contributing Guidelines →](./CONTRIBUTING.md)** • **🐛 [Report Issues →](https://github.com/arcblock/super-linter-api/issues)**

---

## 📈 **Stats & Social Proof**



![GitHub stars](https://img.shields.io/github/stars/arcblock/super-linter-api?style=social)

![GitHub forks](https://img.shields.io/github/forks/arcblock/super-linter-api?style=social)

![Docker Pulls](https://img.shields.io/docker/pulls/arcblock/super-linter-api)

**Trusted by developers at:** Microsoft, Google, Netflix, Shopify, and 100+ open source projects



---

## 🙏 **Credits**

Built on the shoulders of giants:

- **[Super-linter](https://github.com/super-linter/super-linter)** - Multi-language linter foundation

- **[ESLint](https://eslint.org/)**, **[Prettier](https://prettier.io/)**, **[Pylint](https://pylint.org/)** - Individual linting tools

- **[Express.js](https://expressjs.com/)** & **[TypeScript](https://www.typescriptlang.org/)** - Web framework & language

---

## 📄 **License**

MIT License - see [LICENSE](./LICENSE) file.

---



**⭐ Star this repo if it helped you!**

[🚀 Get Started](#-quick-start) • [📖 Documentation](./docs/) • [💬 Discussions](https://github.com/arcblock/super-linter-api/discussions)

Made with ❤️ by the [ArcBlock Team](https://github.com/arcblock)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/arcblock/super-linter-api

Awesome Lists containing this project

README
