podman-desktop/assets/js/7bdcd7a7.d02b8df8.js

"use strict";(self.webpackChunkdocs=self.webpackChunkdocs||[]).push([[7714],{58711:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>p,frontMatter:()=>o,metadata:()=>d,toc:()=>c});var s=i(24246),t=i(71670);const o={sidebar_position:1,title:"Writing",description:"Writing a Podman Desktop extension",tags:["podman-desktop","extension","writing"],keywords:["podman desktop","extension","writing"]},r="Writing a Podman Desktop extension",d={id:"extensions/write/index",title:"Writing",description:"Writing a Podman Desktop extension",source:"@site/docs/extensions/write/index.md",sourceDirName:"extensions/write",slug:"/extensions/write/",permalink:"/docs/extensions/write/",draft:!1,unlisted:!1,editUrl:"https://github.com/containers/podman-desktop/tree/main/website/docs/extensions/write/index.md",tags:[{label:"podman-desktop",permalink:"/docs/tags/podman-desktop"},{label:"extension",permalink:"/docs/tags/extension"},{label:"writing",permalink:"/docs/tags/writing"}],version:"current",sidebarPosition:1,frontMatter:{sidebar_position:1,title:"Writing",description:"Writing a Podman Desktop extension",tags:["podman-desktop","extension","writing"],keywords:["podman desktop","extension","writing"]},sidebar:"mySidebar",previous:{title:"Writing extensions",permalink:"/docs/extensions/"},next:{title:"Onboarding workflow",permalink:"/docs/extensions/write/onboarding-workflow"}},a={},c=[{value:"Initializing a Podman Desktop extension",id:"initializing-a-podman-desktop-extension",level:2},{value:"Prerequisites",id:"prerequisites",level:4},{value:"Procedure",id:"procedure",level:4},{value:"Verification",id:"verification",level:4},{value:"Writing a Podman Desktop extension entry point",id:"writing-a-podman-desktop-extension-entry-point",level:2},{value:"Prerequisites",id:"prerequisites-1",level:4},{value:"Procedure",id:"procedure-1",level:4},{value:"Verification",id:"verification-1",level:4},{value:"Additional resources",id:"additional-resources",level:4},{value:"Next steps",id:"next-steps",level:4}];function l(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h4:"h4",li:"li",ol:"ol",p:"p",pre:"pre",ul:"ul",...(0,t.a)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.h1,{id:"writing-a-podman-desktop-extension",children:"Writing a Podman Desktop extension"}),"\n",(0,s.jsx)(n.p,{children:"To write a Podman Desktop extension, start a Node.js or TypeScript project calling the Podman Desktop API, and ensure all runtime dependencies are inside the final binary."}),"\n",(0,s.jsx)(n.h2,{id:"initializing-a-podman-desktop-extension",children:"Initializing a Podman Desktop extension"}),"\n",(0,s.jsx)(n.p,{children:"Write the Podman Desktop extension Node.js package metadata."}),"\n",(0,s.jsx)(n.h4,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"JavaScript or TypeScript"}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"procedure",children:"Procedure"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Create and edit a ",(0,s.jsx)(n.code,{children:"package.json"})," file."]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:"{}\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Add TypeScript and Podman Desktop API to the development dependencies:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",metastring:"lines",children:' "devDependencies": {\n   "@podman-desktop/api": "latest",\n   "typescript": "latest"\n },\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Add the required metadata:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",metastring:"lines",children:'  "name": "my-extension",\n  "displayName": "My Hello World extension",\n  "description": "How to write my first extension",\n  "version": "0.0.1",\n  "icon": "icon.png",\n  "publisher": "benoitf",\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Add the Podman Desktop version that might run this extension:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",metastring:"lines",children:'  "engines": {\n    "podman-desktop": "latest"\n  },\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Add the main entry point:"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",metastring:"lines",children:' "main": "./dist/extension.js"\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Add a Hello World command contribution"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",metastring:"lines",children:'  "contributes": {\n    "commands": [\n     {\n       "command": "my.first.command",\n       "title": "My First Extension: Hello World"\n     }\n   ]\n  }\n'})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Add an ",(0,s.jsx)(n.code,{children:"icon.png"})," file to the project."]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"verification",children:"Verification"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Full ",(0,s.jsx)(n.code,{children:"package.json"})," example:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\n  "devDependencies": {\n    "@podman-desktop/api": "latest",\n    "typescript": "latest"\n  },\n  "name": "my-extension",\n  "displayName": "My Hello World extension",\n  "description": "How to write my first extension",\n  "version": "0.0.1",\n  "icon": "icon.png",\n  "publisher": "benoitf",\n  "engines": {\n    "podman-desktop": "latest"\n  },\n  "main": "./dist/extension.js",\n  "contributes": {\n    "commands": [\n      {\n        "command": "my.first.command",\n        "title": "My First Extension: Hello World"\n      }\n    ]\n  }\n}\n'})}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"writing-a-podman-desktop-extension-entry-point",children:"Writing a Podman Desktop extension entry point"}),"\n",(0,s.jsx)(n.p,{children:"Write the extension features."}),"\n",(0,s.jsx)(n.h4,{id:"prerequisites-1",children:"Prerequisites"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"JavaScript or TypeScript"}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"procedure-1",children:"Procedure"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Create and edit a ",(0,s.jsx)(n.code,{children:"dist/extension.js"})," file."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Import the Podman Desktop API"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import * as podmanDesktopAPI from '@podman-desktop/api';\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["Expose the ",(0,s.jsx)(n.code,{children:"activate"})," function to call on activation."]}),"\n",(0,s.jsx)(n.p,{children:"The signature of the function can be:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Synchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"export function activate(): void;\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Asynchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"export async function activate(): Promise<void>;\n"})}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["(Optional) Add an extension context to the ",(0,s.jsx)(n.code,{children:"activate"})," function enabling the extension to register disposable resources:"]}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"export async function activate(extensionContext: podmanDesktopAPI.ExtensionContext): Promise<void> {}\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Register the command and the callback"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"import * as podmanDesktopAPI from '@podman-desktop/api';\nexport async function activate(extensionContext: podmanDesktopAPI.ExtensionContext): Promise<void> {\n  // register the command referenced in package.json file\n  const myFirstCommand = podmanDesktopAPI.commands.registerCommand('my.first.command', async () => {\n    // display a choice to the user for selecting some values\n    const result = await podmanDesktopAPI.window.showQuickPick(['un', 'deux', 'trois'], {\n      canPickMany: true, // user can select more than one choice\n    });\n\n    // display an information message with the user choice\n    await podmanDesktopAPI.window.showInformationMessage(`The choice was: ${result}`);\n  });\n\n  // create an item in the status bar to run our command\n  // it will stick on the left of the status bar\n  const item = podmanDesktopAPI.window.createStatusBarItem(podmanDesktopAPI.StatusBarAlignLeft, 100);\n  item.text = 'My first command';\n  item.command = 'my.first.command';\n  item.show();\n\n  // register disposable resources to it's removed when we deactivte the extension\n  extensionContext.subscriptions.push(myFirstCommand);\n  extensionContext.subscriptions.push(item);\n}\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["(Optional) Expose the ",(0,s.jsx)(n.code,{children:"deactivate"})," function to call on deactivation."]}),"\n",(0,s.jsx)(n.p,{children:"The signature of the function can be:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Synchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"export function deactivate(): void;\n"})}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"Asynchronous"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-typescript",children:"export async function deactivate(): Promise<void>;\n"})}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"verification-1",children:"Verification"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsxs)(n.p,{children:["The extension compiles and produces the output in the ",(0,s.jsx)(n.code,{children:"dist"})," folder."]}),"\n"]}),"\n",(0,s.jsxs)(n.li,{children:["\n",(0,s.jsx)(n.p,{children:"All runtime dependencies are inside the final binary."}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"additional-resources",children:"Additional resources"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["Consider a packer such as ",(0,s.jsx)(n.a,{href:"https://rollupjs.org",children:"Rollup"})," or ",(0,s.jsx)(n.a,{href:"https://webpack.js.org",children:"Webpack"})," to shrink the size of the artifact."]}),"\n"]}),"\n",(0,s.jsx)(n.h4,{id:"next-steps",children:"Next steps"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/docs/extensions/publish",children:"Publishing a Podman Desktop extension"})}),"\n"]})]})}function p(e={}){const{wrapper:n}={...(0,t.a)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(l,{...e})}):l(e)}},71670:(e,n,i)=>{i.d(n,{Z:()=>d,a:()=>r});var s=i(27378);const t={},o=s.createContext(t);function r(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);