Developer Hub
Publishing
A focused guide for the publishing stage of extension development. coc.nvim extensions expose an activate(context) entry point to the Node.js extension host.
Publishing and maintenance
An installable extension is a normal npm package with coc.nvim metadata. Verify the package contents, engine requirement, and editor CI before making the publish decision.
- 1
Compile lib/
- 2
Declare engines.coc
- 3
Inspect the npm tarball
- 4
Run Vim and Neovim CI
package.json
| 1 | { |
| 2 | "name": "coc-demo", |
| 3 | "version": "0.1.0", |
| 4 | "description": "A coc.nvim extension example", |
| 5 | "main": "lib/index.js", |
| 6 | "files": ["lib"], |
| 7 | "engines": { "node": ">=22.15.0", "coc": "^0.0.82" }, |
| 8 | "activationEvents": ["onCommand:coc-demo.hello"], |
| 9 | "contributes": { "commands": [{ "command": "coc-demo.hello", "title": "Say hello" }] }, |
| 10 | "scripts": { |
| 11 | "build": "node esbuild.mjs", |
| 12 | "prepare": "npm run build", |
| 13 | "typecheck": "tsc -p tsconfig.json --noEmit", |
| 14 | "test": "npm run test:nvim", |
| 15 | "test:nvim": "coc-test --nvim "test/**/*.test.ts"", |
| 16 | "test:vim": "coc-test --vim "test/**/*.test.ts"" |
| 17 | }, |
| 18 | "coc-test": { "entryFile": "src/index.ts" } |
| 19 | } |
Release checklist
| 1 | npm run typecheck |
| 2 | npm run build |
| 3 | |
| 4 | # Review every file npm would include; do not publish from an unreviewed tree. |
| 5 | npm pack --dry-run |
.github/workflows/test.yml
| 1 | name: Test and publish |
| 2 | |
| 3 | on: [push, pull_request] |
| 4 | |
| 5 | permissions: |
| 6 | contents: read |
| 7 | id-token: write # required only by the npm Trusted Publisher job |
| 8 | |
| 9 | jobs: |
| 10 | editor: |
| 11 | strategy: |
| 12 | fail-fast: false |
| 13 | matrix: { editor: [nvim, vim] } |
| 14 | runs-on: ubuntu-latest |
| 15 | steps: |
| 16 | - uses: actions/checkout@v4 |
| 17 | - uses: actions/setup-node@v4 |
| 18 | with: { node-version: 22, cache: npm } |
| 19 | - run: sudo apt-get update && sudo apt-get install -y neovim vim |
| 20 | - run: npm ci |
| 21 | - run: npm run typecheck |
| 22 | - run: npm run build |
| 23 | - run: npm run test:${{ matrix.editor }} |
| 24 | |
| 25 | # Configure npm Trusted Publishing for this exact repository/workflow first. |
| 26 | publish: |
| 27 | if: github.ref == 'refs/heads/master' && github.event_name == 'push' |
| 28 | needs: editor |
| 29 | runs-on: ubuntu-latest |
| 30 | permissions: { contents: read, id-token: write } |
| 31 | steps: |
| 32 | - uses: actions/checkout@v4 |
| 33 | - uses: actions/setup-node@v4 |
| 34 | with: { node-version: 22, registry-url: https://registry.npmjs.org } |
| 35 | - run: npm ci |
| 36 | - run: npm run build |
| 37 | - run: npm pack --dry-run |
| 38 | - run: npm publish --provenance |
Trusted publishing: configure npm Trusted Publishing for the exact GitHub repository and workflow before relying on OIDC. Verify it with
npm trust list coc-demo --json; the publishing job needs id-token: write. When that configuration is in place, npm publish --provenance creates an npm provenance statement. These checks do not authorize a publish, and Git commits, tags, pushes, and npm publish remain explicit maintainer decisions.