Ręczny przykład SDK

Ten kompletny przykład dodaje panel Workspace info i komendę Open workspace info. Korzysta bezpośrednio z buildPlugin(), bez CLI i generatora. Dla większości nowych projektów wygodniejszy będzie generator; ten wariant pokazuje, co dzieje się pod spodem.

Przygotuj projekt

Źródła są w examples/workspace-info. Potrzebujesz Node.js 22.14+ i pnpm 11.25.0. Wersje zestawu to SDK 1.1.0-alpha.1, React/React DOM 19.2.8 oraz TypeScript 7.0.2. tsup 8.5.1 jest zależnością narzędzia budowania.

git clone https://github.com/lomi-dev/docs-app.git
cd docs-app/examples/workspace-info

Dla lokalnego zestawu przed publikacją npm przygotuj archiwum SDK według instrukcji narzędzi, a następnie wskaż jego rzeczywistą ścieżkę. Jeśli plugin-archives leży obok docs-app:

pnpm add --save-exact --ignore-scripts @lomi-dev/plugin-sdk@file:../../../plugin-archives/lomi-dev-plugin-sdk-1.1.0-alpha.1.tgz
pnpm check
pnpm build

To polecenie zapisze zależność file: i uaktualni lockfile przykładu. Nie korzysta ze źródeł aplikacji. Po publikacji właściwego zestawu możesz zastąpić archiwum dokładną wersją @lomi-dev/[email protected], sprawdzić lockfile i zachować go. Dopiero dla tak ustalonego środowiska stosuj pnpm install --frozen-lockfile --ignore-scripts.

buildPlugin() nie uruchamia TypeScript check. Dlatego skrypt build przykładu najpierw wywołuje pnpm check. Sprawdzaj kod zakończenia: nieudany build zachowuje poprzedni package/.

Zainstaluj i otwórz panel

Uruchom aplikację desktopową i otwórz folder projektu.
W Settings > Plugins > Import plugin wybierz docs-app/examples/workspace-info/package.
Włącz Workspace info i wybierz Trust and enable.
Otwórz Commands skrótem Ctrl+Shift+P, a na macOS Cmd+Shift+P, i uruchom Open workspace info.
Zmień opcję Show project path. Przełącz obszar roboczy i wróć, aby sprawdzić, czy panel zachował wybór.

Importuj wygenerowany folder package. Folder nadrzędny zawiera źródła, zależności i narzędzia budowania, które nie powinny trafić do zainstalowanego pluginu.

Pliki przykładu

`package.json`

Plik określa zależności autora i kontrolę typów. Poniższy wariant pokazuje dokładne wersje npm; w pracy na kandydacie zastąp SDK archiwum tak jak wyżej.

{
  "name": "lomi-workspace-info-example",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "packageManager": "[email protected]",
  "scripts": {
    "check": "tsc --noEmit",
    "build": "pnpm check && node build.mjs"
  },
  "dependencies": {
    "@lomi-dev/plugin-sdk": "1.1.0-alpha.1",
    "react": "19.2.8",
    "react-dom": "19.2.8"
  },
  "devDependencies": {
    "@types/react": "19.2.18",
    "@types/react-dom": "19.2.7",
    "tsup": "8.5.1",
    "typescript": "7.0.2"
  }
}

`plugin.json`

{
  "schemaVersion": 1,
  "hostApi": 1,
  "id": "example.workspace-info",
  "name": "Workspace info",
  "version": "1.0.0",
  "description": "Show the active project folder and workspace.",
  "entry": "dist/index.js",
  "activation": "lazy",
  "stylesheets": ["workspace-info.css"],
  "contributes": {
    "views": [
      {
        "id": "example.workspace-info.panel",
        "title": "Workspace info",
        "placement": "central",
        "multiple": false,
        "stateVersion": 1
      }
    ],
    "commands": [
      {
        "id": "example.workspace-info.open",
        "label": "Open workspace info",
        "description": "Show the active project folder and workspace.",
        "context": { "workspace": true }
      }
    ]
  }
}

`src/index.tsx`

import {
  useHostContext,
  type PluginContext,
  type ViewProps,
} from '@lomi-dev/plugin-sdk';

function WorkspaceInfo({ panel, setState }: ViewProps) {
  const host = useHostContext();
  const showPath =
    typeof panel.state === 'object' &&
    panel.state !== null &&
    !Array.isArray(panel.state) &&
    panel.state.showPath === true;

  return (
    <section className="workspace-info">
      <h2>{host.workspaceName ?? 'No workspace selected'}</h2>
      <label>
        <input
          type="checkbox"
          checked={showPath}
          onChange={(event) => setState({ showPath: event.target.checked })}
        />
        Show project path
      </label>
      {showPath && <p>{host.projectPath ?? 'No project selected'}</p>}
      <p>Appearance: {host.appearance}</p>
    </section>
  );
}

export function activate(context: PluginContext) {
  context.registerView('example.workspace-info.panel', WorkspaceInfo);
  context.registerCommand('example.workspace-info.open', async () => {
    await context.openView('example.workspace-info.panel', { showPath: true });
  });
}

`build.mjs`

import { buildPlugin } from '@lomi-dev/plugin-sdk/build';

await buildPlugin({ assets: ['workspace-info.css'] });

`tsconfig.json`

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "skipLibCheck": true,
    "rootDir": "src"
  },
  "include": ["src"]
}

`workspace-info.css`

.workspace-info {
  padding: 16px;
  color: var(--color-surface-text);
  background: var(--plugin-example-dworkspace-hinfo-surface, var(--color-surface));
  overflow-wrap: anywhere;
}

.workspace-info label {
  display: flex;
  align-items: center;
  gap: 8px;
}

Co obsługuje aplikacja

useHostContext() aktualizuje panel po zmianie aktywnego obszaru roboczego lub wyglądu. setState() zapisuje niewielką wartość JSON w opisie panelu przechowywanym w sesji. Przykład nie edytuje dokumentu, więc nie potrzebuje zabezpieczenia niezapisanej pracy.

Aplikacja usuwa rejestracje widoku i komendy podczas dezaktywacji pluginu. Jeśli dodasz nasłuchiwanie zdarzeń, timery lub własne magazyny danych, zastosuj reguły cyklu życia.

Zmień kod i przebuduj

Po zmianie plików uruchom ponownie pnpm build. Wyłącz zainstalowany plugin, zaimportuj nowy folder package i zatwierdź zamiennik. Uruchom aplikację ponownie, jeśli o to poprosi. Instalowane pakiety są kopiami konkretnej rewizji, więc edycja źródeł nie aktualizuje działającego pluginu.

Wszystkie opcje buildPlugin

Opcja	Domyślnie	Znaczenie
`entry`	`src/index.tsx`	Plik źródłowy do kompilacji; pomijany w pakiecie bez manifestowego `entry`
`manifest`	`plugin.json`	Manifest w katalogu projektu
`assets`	`[]`	Pliki i katalogi kopiowane do paczki
`outDir`	`package`	Katalog wyniku; wybierz osobny, przeznaczony wyłącznie na build
`cwd`	`process.cwd()`	Katalog projektu autora
`signal`	Brak	Opcjonalny `AbortSignal` do przerwania operacji

Funkcja zwraca Promise<string> z bezwzględną ścieżką wyniku. Obsługa błędu należy do skryptu wywołującego. Udany build zastępuje zawartość outDir, więc nie umieszczaj tam ręcznie tworzonych plików.

Nazwę wynikowego JavaScriptu i rozszerzenie określa plugin.json.entry. Przykładowo źródło src/main.tsx może zostać zbudowane jako dist/plugin.mjs. Helper generuje ESM dla ES2022, współdzieli React/SDK i sprawdza końcowe importy. Szczegóły zasobów są na stronie Style i zasoby.

Sam helper nie tworzy ZIP ani raportu wydania. Udostępnij kompletny folder package/ albo dodaj do projektu CLI i skorzystaj z jego komendy package. Zaimportuj i zakwalifikuj gotowy folder w Lomi według instrukcji kwalifikacji desktopowej.

Kod źródłowy: kontrakt SDK, narzędzie budowania.