Menu
7/9 Publicar no GitHub e npmTodas as páginas

Tutoriais · Plugins

Publicar no GitHub e no npm

Layout do repositório, package.json, npm publish e um workflow do GitHub Actions que publica a cada tag.

Nesta página

Layout do repositório

Um plugin por repositório, com o ade.plugin.json na raiz. É onde o instalador o procura primeiro — e, no pacote npm, é o único lugar: a origem npm não procura em subpastas (a origem git procura até duas pastas abaixo).

meu-plugin/
├── ade.plugin.json              ← na RAIZ do repositório
├── package.json
├── README.md
├── LICENSE
├── integrations/
│   └── index.mjs
├── skills/
│   └── minha-skill/
│       └── SKILL.md
├── scripts/
│   └── check-release.mjs
└── .github/
    └── workflows/
        └── publish.yml

ade.plugin.json e package.json

O manifesto descreve o plugin para o Jarvis ADE; o package.json descreve o pacote para o npm. As duas version devem andar juntas.

ade.plugin.json
{
  "id": "meu-plugin",
  "name": "Meu Plugin",
  "version": "0.1.0",
  "description": "O que o seu plugin faz, em uma frase.",
  "author": "Seu Nome",
  "homepage": "https://github.com/SEU-USUARIO/meu-plugin",
  "license": "MIT",
  "contributes": {
    "integrations": [
      {
        "id": "principal",
        "name": "Meu Plugin",
        "command": "node",
        "args": ["integrations/index.mjs"],
        "events": ["board.card_moved"]
      }
    ]
  }
}
package.json
{
  "name": "jarvis-plugin-meu-plugin",
  "version": "0.1.0",
  "description": "O que o seu plugin faz, em uma frase.",
  "license": "MIT",
  "type": "module",
  "keywords": ["jarvis-ade-plugin"],
  "repository": {
    "type": "git",
    "url": "git+https://github.com/SEU-USUARIO/jarvis-plugin-meu-plugin.git"
  },
  "homepage": "https://github.com/SEU-USUARIO/jarvis-plugin-meu-plugin#readme",
  "files": ["ade.plugin.json", "integrations/", "skills/", "README.md", "LICENSE"],
  "engines": { "node": ">=18" }
}
O que cada campo do package.json faz pelo plugin
CampoPor quê
keywords: ["jarvis-ade-plugin"]A marca que identifica o pacote como um plugin do Jarvis ADE.
repositoryDeve apontar para o repositório público no GitHub. O Marketplace confere que o repositório do pacote npm é o mesmo que você cadastrou.
filesLista o que vai no pacote. Inclua o ade.plugin.json e as pastas que ele referencia (integrations/, skills/…). O npm sempre inclui package.json, README e LICENSE.
sem dependenciesPlugins não têm dependências em runtime: só a pasta do pacote é copiada para o usuário.
sem scripts de instalaçãoNada de preinstall, install ou postinstall. O Marketplace avisa quando encontra dependências em runtime ou scripts de instalação.
sem private: trueprivate: true faz o npm publish recusar o pacote.
enginesO Node mínimo que o seu sidecar exige.

Publicar à mão, a primeira vez

  1. Confira o que vai no pacote

    terminal
    npm pack --dry-run

    A lista precisa ter o ade.plugin.json e os arquivos que ele referencia — e nada de node_modules.

  2. Entre no npm e publique

    terminal
    npm login
npm publish --access public

    --access public é necessário na primeira publicação de um pacote com escopo (@usuario/nome), que o npm trata como privado por padrão.

  3. Teste a instalação a partir do npm

    No Jarvis ADE: Marketplace de Plugins → Instalados → Importar plugin, origem Pacote npm, e o nome do pacote (por exemplo jarvis-plugin-meu-plugin). Repita com a origem URL git apontando para o repositório. Se o manifesto está na raiz e nada depende de node_modules, as duas funcionam.

Publicar a cada tag com GitHub Actions

Depois da primeira vez, deixe o GitHub publicar. O fluxo: você sobe a versão, cria a tag v0.2.0, e o workflow confere que tag, package.json e ade.plugin.json dizem a mesma versão e que o pacote continua sem dependências nem scripts de instalação — só então publica.

scripts/check-release.mjs
// scripts/check-release.mjs — barra o publish se algo divergir. Sem dependências.
import { readFileSync } from 'node:fs'

const read = (file) => JSON.parse(readFileSync(file, 'utf8'))
const pkg = read('package.json')
const manifest = read('ade.plugin.json')
const tag = (process.env.GITHUB_REF_NAME ?? '').replace(/^v/, '')

const problems = []
if (pkg.version !== tag) problems.push(`package.json (${pkg.version}) != tag (${tag || 'vazia'})`)
if (manifest.version !== tag) problems.push(`ade.plugin.json (${manifest.version}) != tag (${tag || 'vazia'})`)
if (Object.keys(pkg.dependencies ?? {}).length > 0) problems.push('package.json tem "dependencies": plugins são livres de dependências em runtime')
for (const hook of ['preinstall', 'install', 'postinstall']) {
  if (pkg.scripts?.[hook]) problems.push(`package.json tem o script de instalação "${hook}"`)
}
if (!pkg.keywords?.includes('jarvis-ade-plugin')) problems.push('falta a keyword "jarvis-ade-plugin"')

if (problems.length > 0) {
  for (const p of problems) console.error(`✗ ${p}`)
  process.exit(1)
}
console.log(`✓ release ${tag} consistente`)
.github/workflows/publish.yml
name: Publicar no npm

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: read
  id-token: write # necessário para --provenance

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          registry-url: https://registry.npmjs.org

      - name: Conferir tag, versões e regras do plugin
        run: node scripts/check-release.mjs

      - name: Ver o que vai no pacote
        run: npm pack --dry-run

      - name: Publicar
        run: npm publish --access public --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
  • Crie o segredo NPM_TOKEN em Settings → Secrets and variables → Actions do repositório, com um token do npm que tenha permissão de publicar esse pacote.
  • id-token: write e --provenance anexam ao pacote a prova de que ele foi construído por este workflow neste repositório público.
  • Não há passo npm install: o plugin não tem dependências, e o workflow não deve precisar delas. (Se você compila TypeScript, adicione o passo de build e versione o resultado, ou publique de uma árvore já compilada.)
lançando uma versão
# 1. suba a versão nos DOIS arquivos (package.json e ade.plugin.json)
npm version 0.2.0 --no-git-tag-version
# edite "version" em ade.plugin.json para 0.2.0

# 2. commit + tag + push — o workflow publica no npm
git commit -am "release: 0.2.0"
git tag v0.2.0
git push origin main --tags

Antes de registrar no Marketplace

  • O repositório do GitHub é público.
  • O ade.plugin.json está na raiz e é válido (veja a referência do manifesto).
  • O pacote npm está publicado, com repository apontando para esse repositório e a keyword jarvis-ade-plugin.
  • Sem dependências em runtime e sem scripts de instalação.

Tudo certo? Siga para registrar no Marketplace.