coc-vscode-loader

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

coc-vscode-loader

★ 11 Open GitHub ↗

Run VS Code extensions seamlessly in coc.nvim

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# vscode-coc-loader

[![npm](https://img.shields.io/npm/v/coc-vscode-loader)](https://www.npmjs.com/package/coc-vscode-loader)
[![license](https://img.shields.io/github/license/coc-plugin/coc-vscode-loader)](https://raw.githubusercontent.com/coc-plugin/coc-vscode-loader/main/LICENSE)
[![CI](https://github.com/coc-plugin/coc-vscode-loader/actions/workflows/ci.yml/badge.svg)](https://github.com/coc-plugin/coc-vscode-loader/actions/workflows/ci.yml)
[![Registry Check](https://github.com/coc-plugin/coc-vscode-loader/actions/workflows/registry-check.yml/badge.svg)](https://github.com/coc-plugin/coc-vscode-loader/actions/workflows/registry-check.yml)
[![GitHub stars](https://img.shields.io/github/stars/coc-plugin/coc-vscode-loader)](https://github.com/coc-plugin/coc-vscode-loader/stargazers)
[![last commit](https://img.shields.io/github/last-commit/coc-plugin/coc-vscode-loader)](https://github.com/coc-plugin/coc-vscode-loader)
[![open issues](https://img.shields.io/github/issues/coc-plugin/coc-vscode-loader)](https://github.com/coc-plugin/coc-vscode-loader/issues)
[![Editor](https://img.shields.io/badge/editor-Neovim%200.8%2B%20%7C%20Vim%209.0%2B-blue)]()

Convert VS Code extensions into coc.nvim plugins at install time and run them natively.
Supports **Neovim 0.8+** and **Vim 9.0+**.

[![Browse Registry](https://img.shields.io/badge/🌐_Browse_Available_Extensions-coc--plugin.github.io-blue?style=for-the-badge)](https://coc-plugin.github.io/coc-vscode-registry/)

---

> **⚠️ IMPORTANT: Keep coc-vscode-loader Updated**
>
> coc-vscode-loader is under active development. Each release includes critical bug fixes, converter improvements, and registry updates. **Always use the latest version** — running an outdated version will silently produce broken plugin conversions (e.g., formatters that don't format, wrong notification colors, or language servers that fail to start).
>
> When updating, the loader **automatically detects which installed plugins changed** — affected plugins are marked `[changed]` in the TUI. Only those need reinstalling, not everything.
>
> ```vim
> :CocUpdate coc-vscode-loader   " Update to latest
> :CocCommand loader.open        " Check for [changed] markers, press R on those
> " Or reinstall a specific plugin:
> :CocCommand loader.reinstall <name>
> ```
>
> **Failure to keep the loader + all plugins in sync is the #1 source of reported issues.**

## Automated Upstream Change Detection

Every registry entry points to an upstream VS Code extension that evolves independently. The [Registry Update Check](.github/workflows/registry-check.yml) workflow runs **daily** to ensure nothing silently breaks:

```mermaid
flowchart LR
  A[00:00 / 12:00 Beijing] --> B[Check 134 repos]
  B --> C{Upstream changed?}
  C -->|No| D[Skip]
  C -->|Yes| E[Run converter]
  E --> F{Output changed?}
  F -->|No| G[Skip]
  F -->|Yes| H[Create PR]
  F -->|Error| I[Create Issue]
```

| What happens | Action |
|-------------|--------|
| Upstream has new commits → output matches baseline | ✅ Skipped (no news is good news) |
| Upstream has new commits → output changed | 📬 PR created — review & merge |
| Upstream repo is deleted / archived | 📬 Issue created — investigate |
| Converter fails on new upstream code | 📬 Issue created — debug needed |

Each outdated entry gets **one isolated PR** with detailed diff output and upstream commit history. No noise — only actionable results. See [`docs/registry-update-checker.md`](./docs/registry-update-checker.md) for full design.

Trigger manually: `gh workflow run registry-check.yml` or via the [Actions tab](https://github.com/coc-plugin/coc-vscode-loader/actions/workflows/registry-check.yml).

---

## Quick Start

Install the loader plugin:

```vim
:CocInstall coc-vscode-loader
```

Then open the TUI to browse and install available extensions:

```vim
:CocCommand loader.open
```

**What happens when you install a plugin (AOT — Ahead-of-Time):**
1. `git clone` the upstream VS Code extension source
2. Run the converter (ts-morph AST transforms + text replacements) to produce a complete coc.nvim plugin package
3. `npm install` + `esbuild` to bundle the output
4. Copy the result to `~/.config/coc/extensions/node_modules/coc-<name>` and register it

No runtime interception or JIT overhead — coc.nvim loads a normal plugin at startup.

Or auto-install extensions via vim variable (no TUI needed):

```vim
" .vimrc
let g:coc_loader_global_extensions = ['vscode-pyright', 'vscode-eslint']
```

```lua
-- init.lua
vim.g.coc_loader_global_extensions = { 'vscode-pyright', 'vscode-eslint' }
```

Browse all available extensions online: [coc-plugin.github.io/coc-vscode-registry](https://coc-plugin.github.io/coc-vscode-registry/)

---

## Convert Your Own Plugin

Use the one-step conversion script:

```bash
bash scripts/convert-plugin.sh <name> <github-repo> [subdir]
# Examples:
bash scripts/convert-plugin.sh eslint microsoft/vscode-eslint
bash scripts/convert-plugin.sh volar vuejs/language-tools extensions/vscode
```

For manual conversion:

```bash
cd converter
echo '[{"type":"source","transforms":["import-mapping"],"entry":"src/extension.ts"}]' > convert.json
npx tsx src/cli.ts convert ../path/to/vscode-ext -o ./output --convert-file convert.json
cd ./output && npm install && node esbuild.mjs
```

> 📖 See [`docs/`](./docs/) for full API mapping docs and converter design.

---

## Background

[coc.nvim](https://github.com/neoclide/coc.nvim)'s API is heavily influenced by the VS Code extension API — both use the same LSP protocol, similar provider systems, and comparable namespace structures. This makes it possible to mechanically convert VS Code extensions to run as coc.nvim plugins.

This repo contains two parts:

1. **Converter CLI** ([`converter/`](./converter/)) — automatically converts VS Code extensions to coc plugins
2. **Loader plugin** ([`plugin/`](./plugin/)) — coc.nvim plugin with a TUI to install/update/uninstall converted plugins

### Converter architecture (AOT — runs at install time only)

```
Input (VS Code extension source)
  → 1. git clone upstream repo
  → 2. Scanner — detect files using VS Code API
  → 3. Steps pipeline (5 registered generators):
  │     ├─ language-client  → LanguageClient code (module/binary server)
  │     ├─ source           → Copy + 5 AST transforms (import-mapping, class-to-factory,
  │     │                    provider-register, enum-offset, strip-volar)
  │     ├─ bridge           → Bridge code from BRIDGE_TEMPLATES (tsserver-forward)
  │     ├─ snippets         → Copy snippets JSON + stub entry
  │     └─ mark-unsupported → Remove unsupported API calls
  → 4. Text replacements (.fileName, .uri.fsPath, getWordRangeAtPosition, WorkspaceEdit)
  → 5. Plugin patches (per-entry find/replace from registry)
  → 6. Generate package.json + esbuild.mjs + server-patches.json
  → 7. npm install + esbuild → lib/index.js
  → Output: coc plugin package at ~/.config/coc/extensions/node_modules/coc-<name>
```

---

## Development

### Testing

Three test suites, each catching different issues:

```bash
npm test                    # Unit tests (167) + fixture tests + test coverage check
npm run test:full           # Unit tests + registry baseline diff
npm run test:smoke          # Registry smoke test (all 134 entries — validates output structure)
```

| Suite | What it catches | CI |
|-------|----------------|----|
| `npm test` | Transform/fixture correctness (fast, ~1s) | ✅ |
| `npm run test:full` | Unintended side effects on all 134 registry entries | ❌ (manual) |
| `npm run test:smoke` | Registry entry conversion completeness | ✅ |

**Baseline diff** (`npm run diff:baseline` / `npm run diff:check`):
Before changing converter code, snapshot current output; after changes, compare to detect which plugins are affected. See `AGENTS.md` for full workflow.

**Pre-push hook** — `git push` automatically runs `npm test` + `npm run test:smoke`. Configure once:

```bash
git config core.hooksPath .githooks
# Or just run npm install (pre-configured via postinstall)
```

Skip with `git push --no-verify` (use sparingly).

**GitHub Actions CI** — three sequential jobs:
1. `unit` (Node 20/22): unit tests + fixture tests
2. `diff`: registry baseline check (detects unintended converter side effects)
3. `smoke`: full registry conversion (validates output structure)

### Switch between local dev and npm release

```bash
# Check current mode
bash switch.sh status

# Use local development version
bash switch.sh local

# Use npm published version
bash switch.sh npm
```

Or via npm scripts:

```bash
npm run switch:status
npm run switch:local
npm run switch:npm
```

> **Note for npm 11+**: `switch.sh npm` temporarily removes `file:` dependencies from `extensions/package.json` to avoid reify errors, then restores them automatically.

After switching, run `:CocRestart` in Neovim.

### Build

```bash
npm run build          # build everything
cd plugin && npm run build  # build plugin only
```

## Requirements

### OS
- **Linux** ✅ Fully supported
- **macOS** ✅ Fully supported
- **Windows** ✅ Fully supported

### Editor

| Editor | TUI | Notes |
|--------|-----|-------|
| **Neovim** 0.8+ | ✅ Full floating window + extmark | Recommended, full Mason-style experience |
| **Vim** 9.0+ | ✅ Split window + prop_add | Bottom split, no backdrop, no live search |

### External commands

These must be installed and available on `PATH`:

| Command | Required by | Notes |
|---------|-------------|-------|
| `git` | Source download & update checks | |
| `node` / `npm` / `npx` | Plugin build, converter runtime | Node.js >= 18 |
| `curl` | Registry fetch fallback, binary server download | |
| `unzip` | Binary server extraction (Linux/macOS) | Windows uses built-in `tar.exe` |
| `tar` / `gunzip` | Binary server extraction | `gunzip` uses Node.js `zlib` internally |
| `python3` / `python` | Pip package installation (e.g. ansible-lint) | Only if plugin requires pip packages; Windows falls back to `python` / `py` |

All commands are pre-installed on typical macOS/Linux development machines or available via the system package manager (`apt`, `brew`, etc.).

---

## FAQ

### Plugin installed but not working?

Close the TUI — it will auto-run `:CocRestart`. Or manually run `:CocRestart`.

### Which VS Code extensions are supported?

Browse the [registry website](https://coc-plugin.github.io/coc-vscode-registry/) or check [registry.json](https://github.com/coc-plugin/coc-vscode-registry/blob/main/registry.json). Includes LSP servers, direct-API plugins, and snippet extensions for most languages.

### How is this different from running the VS Code extension directly?

The converter rewrites VS Code API calls to coc.nvim equivalents. You get the same functionality without needing VS Code.

### Can I add my own extension?

Yes! See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full workflow. In short:
1. Add an entry to the [registry repo](https://github.com/coc-plugin/coc-vscode-registry)
2. Run `npm test` + `npm run test:smoke` to verify
3. Submit a PR

---

## Community & Support

- 💬 [Discussions](https://github.com/coc-plugin/coc-vscode-loader/discussions)
- 🐛 [Issues](https://github.com/coc-plugin/coc-vscode-loader/issues)
- 📖 [API mapping docs](./docs/import-mapping.md) · [Converter design](./docs/converter-design-v2.md) · [Registry website](https://coc-plugin.github.io/coc-vscode-registry/)
- ⭐ Star the repo if you find it useful!

coc-vscode-loader

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README