@harnessio/idp-plugins-sdk

SDK for building Harness plugins with React. Provides communication utilities, context management, and routing synchronization for plugins running in iframes.

Installation

npm install @harnessio/idp-plugins-sdk

Peer Dependencies

This package requires the following peer dependencies:

• react (^18.0.0 || ^19.0.0)
• react-dom (^18.0.0 || ^19.0.0)
• react-router-dom (^6.0.0 || ^7.0.0)

Usage

Basic Setup

import { PluginAPI, PluginContextProvider, PluginRouter } from '@harnessio/idp-plugins-sdk'

// Initialize the plugin as early as possible
PluginAPI.init()

function App() {
  return (
    <PluginContextProvider>
      <PluginRouter>
        {/* Your app routes here */}
      </PluginRouter>
    </PluginContextProvider>
  )
}

Using Plugin Context

import { usePluginContext } from '@harnessio/idp-plugins-sdk'

function MyComponent() {
  const context = usePluginContext()

  if (!context) {
    return <div>Loading...</div>
  }

  return (
    <div>
      <p>Theme: {context.theme}</p>
      <p>Location: {context.location}</p>
    </div>
  )
}

Proxy Fetch (for authenticated API calls)

import { PluginAPI } from '@harnessio/idp-plugins-sdk'

async function fetchData() {
  const response = await PluginAPI.proxyFetch('/api/some-endpoint')
  const data = await response.json()
  return data
}

API Reference

PluginAPI

Static class for communication with the host application.

• PluginAPI.init() - Signals to the host that the plugin is ready
• PluginAPI.getContext() - Retrieves the current plugin context
• PluginAPI.proxyFetch(url, init?) - Proxies third-party fetch requests through the host external proxy (/v1/external-proxy/*)

Data APIs

• PluginAPI.harnessFetch(path, init?) - Authenticated call to a Harness backend. The host performs the request with the user's session (cookie auth + Harness-Account header). Accepts relative Harness paths only (e.g. /api/..., /gateway/..., /ng/api/...); absolute URLs are rejected. JSON / text responses only (no streaming).
• PluginAPI.getEntity(entityRef) - Fetch a single entity's details by its canonical entityRef.
• PluginAPI.listEntities(filter?) - List entities matching a curated EntityListFilter (kind, owner, tags, name, namespace).

// Harness backend call
const res = await PluginAPI.harnessFetch('/ng/api/projects')
const projects = await res.json()

// Entities
const entity = await PluginAPI.getEntity('component:default/my-service')
const list = await PluginAPI.listEntities({ kind: 'component', owner: 'team-a' })

Navigation APIs

• PluginAPI.navigateToEntity({ entityRef, tab? }) - Navigate the host to an entity page (optional sub-route tab).
• PluginAPI.navigateToWorkflow({ workflowRef, mode?, formData? }) - Navigate the host to a workflow. mode is 'detail' (default), 'execute' (new-execution form, optionally pre-filled via formData), or 'history'.
• PluginAPI.navigateToExternalLink({ url, target? }) - Open an absolute http(s) URL outside Harness. Relative URLs and non-http schemes are rejected; target defaults to '_blank' ('_self' is rejected). Host opens with noopener,noreferrer.
• PluginAPI.triggerWorkflow({ templateRef, values?, secrets? }) - Start a workflow via the host scaffolderApi.scaffold() call. Returns { taskId }. Pass a Scaffolder template ref (template:namespace/name). workflow: refs are converted on the host.

await PluginAPI.navigateToEntity({ entityRef: 'component:default/my-service', tab: 'docs' })
await PluginAPI.navigateToWorkflow({ workflowRef: 'template:default/onboard', mode: 'execute', formData: { team: 'a' } })
await PluginAPI.navigateToExternalLink({ url: 'https://docs.harness.io' })

const { taskId } = await PluginAPI.triggerWorkflow({
  templateRef: 'template:account/github_repos_checker',
  values: { orgId: 'testautoidp' },
  secrets: {},
})

All of the above throw a PluginAPIError (with a code) on client-side validation failure or when the host returns an error.

PluginContextProvider

React context provider that manages plugin context state.

usePluginContext()

Hook to access the current plugin context.

PluginRouter

Router component that synchronizes with the parent page's URL.

useParentRoutingSync()

Hook for manual route synchronization with the parent page.

Development

# Install dependencies
npm install

# Build the package
npm run build

# Watch mode
npm run dev

License

MIT