
freelens
Skills for creating Freelens extensions and porting v1 extensions to the v2 extension API
- GitHub stars
- 5.8K
Install
/plugin install freelens@freelensRun it inside Claude Code after adding the marketplace with /plugin marketplace add freelensapp/freelens.
Contents
Discovered from sourceSkills 2
Create a Freelens extension
A Freelens v2 extension starts as a copy of freelensapp/freelens-example-extension, the reference template the Freelens extension documentation points to. This skill is the workflow. The documents below are the source of truth: read the parts each step names instead of relying on memory, because most extension code found elsewhere is written for the v1 API, which v2 does not load.
Documents
Fetch the raw URLs; they return Markdown.
| Document | Read it for |
|---|---|
api.md | The normative contracts C1 to C15: what the host guarantees and how a violation fails. |
migrating-from-v1.md | The v2 API from an author's side; "Registering things: declarative fields", "Styling and CSS" and "The development loop" apply to a new extension too. |
binaries.md | Only for an extension that ships executables. |
AGENTS.md of the template | The build, type-check, test, lint and CI patterns, each with its reason, and "Rules That Fail Silently". |
README.md of the template | Installing an extension in Freelens and the development loop. |
| The source tree of the template | The worked example: a CRD in two API versions, with a page, a details panel, a menu item and a preference. |
1. Copy the template
The template is not a GitHub template repository. Copy its tree at main,
without its git history, into the new repository's root. Either:
curl -fsSL https://github.com/freelensapp/freelens-example-extension/archive/refs/heads/main.tar.gz |
tar -xz --strip-components=1
or, into a new directory:
gh repo clone freelensapp/freelens-example-extension my-extension -- --depth 1
rm -rf my-extension/.git
Then git init if the directory is not a repository yet.
2. Keep, adapt, remove, rewrite
Every file of the template is in one of the groups below. A file of the copy
that is not listed was added to the template after this list: find what it is
for in the template's AGENTS.md before deciding.
Keep as is
The tooling every extension shares. Its versions follow Freelens, and
AGENTS.md gives the reason for each setting; change one only with a reason of
the same kind.
- Build:
vite.config.mjs,build/vite-plugin-host-modules.mjs,build/vite-plugin-standard-decorators.mjs,build/vite-plugin-css-module-declarations.mjs,svgo.config.mjs. - TypeScript, one program per environment:
tsconfig.base.json,tsconfig.json,src/tsconfig.json,src/main/tsconfig.json,src/renderer/tsconfig.json,src/common/tsconfig.json. - Environment tests:
environment-tests/tsconfig.json,environment-tests/tsconfig.main.json,environment-tests/tsconfig.renderer.json,environment-tests/dom-apis.ts,environment-tests/node-apis.ts,environment-tests/shared-apis.ts,environment-tests/worker-apis.ts. - Tests:
vitest.config.ts,test/freelens-extensions.ts(the runtime stub of@freelensapp/extensions; add the members the new tests reach),vitest.integration.config.tsandintegration/tsconfig.json(the runner and the program of the integration tests). - Lint and format:
biome.jsonc,knip.jsonc,.trunk/trunk.yaml,.trunk/.gitignore,.yamllint.yaml,examples/.yamlfmt.yaml,integration/fixtures/.yamlfmt.yaml,.editorconfig,.gitattributes,.gitignore. - Toolchain and dependencies:
mise.toml,mise.lock,.nvmrc,pnpm-workspace.yaml,pnpm-lock.yaml(pnpm installupdates it after thepackage.jsonchanges),.renovaterc.json(needs the Renovate app on the repository; a dependency that the Freelens catalog does not have must be excluded with!in its catalog rule, or its lookup fails on the Dependency Dashboard). - Agent configuration:
CLAUDE.md,.claude/settings.json. - Shared components and styles:
src/renderer/components/error-boundary.tsx,src/renderer/components/error-boundary.test.tsx,src/renderer/components/error-page.tsx,src/renderer/components/error-page.module.scss,src/renderer/components/error-page.module.d.scss.ts,src/renderer/components/error-page.test.tsx,src/renderer/components/available-version.tsx,src/renderer/components/available-version.module.scss,src/renderer/components/available-version.module.d.scss.ts,src/renderer/components/available-version.test.tsx(createAvailableVersionPage, for a CRD served in more than one API version; remove the four files if no page needs them),src/renderer/vars.scss. - Workflows that apply to any extension and need no secret:
.github/workflows/type-check.yaml,.github/workflows/check.yaml,.github/workflows/unit-tests.yaml,.github/workflows/trunk-check.yaml,.github/workflows/mise-lock-check.yaml,.github/workflows/cleanup-cache.yaml,.github/workflows/integration-tests.yaml(removed with the integration tests, "4. Verify").
Keep, then adapt
src/main/index.ts: theMain.LensExtension. Rename the class; it loads the preferences store, so drop that with the store.src/renderer/index.tsx: theRenderer.LensExtensionwith every registration. Replace theExampleregistrations with the extension's own, keepingextension={this}on each page, and keepclusterPages,kubeObjectDetailItemsandkubeObjectMenuItemsmapped throughwithPageErrorBoundary,withDetailsErrorBoundaryandwithMenuItemErrorBoundary, so that every entry renders inside the error boundary ("Renderer Components" inAGENTS.md). List incustomResourcesthe models of the custom resources the extension gives a page of its own, and only those ("CRD KubeObject Pattern" inAGENTS.md).src/renderer/api/types.ts:ExampleKubeObjectCRD, the CRD metadata with a page title. Rename it, or remove it with the last CRD model.src/common/store/index.ts,src/common/store/preferences-store.ts,src/common/store/preferences-store.test.ts:ExamplePreferencesStore, a store loaded by both processes. Rename it, itsconfigNameand its fields, and keep a test that imports the class: it fails on an@observablefield withoutaccessor. Remove all three if the extension stores nothing.src/renderer/preferences/example-preference.tsx: theappPreferencesinput and hint. Adapt them to the store, or remove them with it.src/renderer/icons/index.ts: re-exports the icons; point it at the new ones.integration/__tests__/extensions.tests.ts: keep it with the integration tests ("4. Verify"). The test installs the checkout in place in Freelens dev, opens its preferences page, and fails on any error either process logs. Remove the preferences test if the extension has noappPreferences.integration/__tests__/extension-helpers.ts: the code the integration test sessions share. SetextensionNameto the new package name,preferencesTitleandpreferencesInputLabelto the extension'sappPreferencesentry, the page id inpageLinkTestIdto the extension'sclusterPageMenusid, andcrdName,testObjectNameand the paths ofsetUpClusterandtearDownClusterto the extension's own CRD and test objects.integration/__tests__/example-v1alpha1.tests.ts,integration/__tests__/example-v1alpha2.tests.ts,integration/fixtures/v1alpha1/kustomization.yaml,integration/fixtures/v1alpha1/namespace.yaml,integration/fixtures/v1alpha2/kustomization.yaml,integration/fixtures/v1alpha2/namespace.yaml: one session per API version that clicks through the list page, the details and the menu of the test object on a kind cluster. Adapt them to the extension's own kinds and versions, one test file and one fixtures directory per version, or remove them for an extension without a cluster view. "Workflows" inAGENTS.mdexplains why each version runs in a session of its own.
Remove, or replace with the extension's own feature
The Example CRD. Its files are the model to follow for the extension's own
resources, one file per API version.
- Models and their tests:
src/renderer/api/example/example-v1alpha1.ts,src/renderer/api/example/example-v1alpha1.test.ts,src/renderer/api/example/example-v1alpha2.ts,src/renderer/api/example/example-v1alpha2.test.ts. - List pages:
src/renderer/pages/examples-page-v1alpha1.tsx,src/renderer/pages/examples-page-v1alpha2.tsx,src/renderer/pages/examples-page.module.scss,src/renderer/pages/examples-page.module.d.scss.ts. - Details panels:
src/renderer/details/example-details-v1alpha1.tsx,src/renderer/details/example-details-v1alpha2.tsx. - Menu items:
src/renderer/menus/example-active-toggle-menu-item-v1alpha1.tsx,src/renderer/menus/example-active-toggle-menu-item-v1alpha2.tsx. - Icon:
src/renderer/icons/example.svg,src/renderer/icons/example.tsx. - CRDs and test objects:
examples/v1alpha1/crds/customresourcedefinition.yaml,examples/v1alpha1/crds/kustomization.yaml,examples/v1alpha1/test/example.yaml,examples/v1alpha1/test/kustomization.yaml,examples/v1alpha2/crds/customresourcedefinition.yaml,examples/v1alpha2/crds/kustomization.yaml,examples/v1alpha2/test/example.yaml,examples/v1alpha2/test/kustomization.yaml.
Rewrite
package.json:name(in an npm scope the publisher owns;@freelensappis not available),description,repository.url,author,copyrightandkeywords, andversionreset to the new extension's first version. Keeptype,main,renderer,files,engines,publishConfig,scripts,devDependenciesandpackageManager.README.md: the new extension's own. Its "Install", "Build from the source" and "Development loop" sections carry over with the names replaced.LICENSE: the copyright holder and years, or another license, matchinglicenseinpackage.json.AGENTS.md: keep the generic sections as they are: "Common Commands", "Rules That Fail Silently", "Build", "TypeScript", "Lint and CI", "Checking the Extension in Freelens Dev" (with the example page URL of the new extension), "Code Style", "Security", "Electron Multi-Process", "Troubleshooting" and "Best Practices". Rewrite the ones about this repository: "Project Overview" (its toolchain and dependency paragraphs stay), "Architecture", and "CRD KubeObject Pattern" and "Renderer Components" with the new extension's classes and files in place ofExample. Keep "GitHub Actions (Claude Code Action) Rules" only with the Claude workflows below, withfreelensapp/freelens-example-extensionandfreelensappreplaced by the new repository and its owner. Drop the "Agent Skills" section, which is about the template's place behind these skills.
Workflows tied to the repository
Keep each one only if the extension wants what it does, and configure the repository first: without its environment and secret, it fails.
| Workflow | What it does | Needs |
|---|---|---|
.github/workflows/release.yaml | On a v* tag: builds, packs, publishes to npm (a version with a hyphen under the next dist-tag) and creates a GitHub release, marked as a prerelease for such a version, with the tarball, its .tgz.sha256 and an SBOM. | Environment publishing, with npm trusted publishing set up for the package, the repository and this workflow, or an NPM_TOKEN secret. |
.github/workflows/npm-version.yaml | On demand, and after a release that is not a prerelease: opens an "Automated npm version" pull request with the bumped version. | Environment automated with a GH_TOKEN secret that can push branches and open pull requests. |
.github/workflows/tag.yaml | When an "Automated npm version" pull request is merged, prerelease versions included: tags main with v<version>, which starts release.yaml. | Environment automated with GH_TOKEN; a tag created with the default GITHUB_TOKEN starts no workflow. |
.github/workflows/npm-dedupe.yaml, .github/workflows/trunk-upgrade.yaml, .github/workflows/biome-migrate.yaml | Scheduled maintenance: each opens a pull request when it changes something. | Environment automated with GH_TOKEN. |
.github/workflows/claude.yaml, .github/workflows/claude-task.yaml | Claude Code in CI, started from a comment that mentions the Claude handle, or on demand. | The Claude GitHub App on the repository, a CLAUDE_CODE_OAUTH_TOKEN secret, and the "GitHub Actions (Claude Code Action) Rules" in AGENTS.md. |
3. Write the extension's code
Follow the patterns the template's AGENTS.md and the contracts set:
- "CRD KubeObject Pattern" in
AGENTS.mdfor a custom resource model: the metadata instatic readonlyproperties, the instancekindandapiVersiondeclared as literals, per-object logic instaticmethods that take the object, and no instance methods, because the objects the host passes are not instances of the subclass. - "Renderer Components" in
AGENTS.mdfor pages, details panels, menu items and preferences:observer, the error boundary applied where the registrations are made (atry/catcharound the call of a component misses what a child or a callback of the host's list layout throws later), the extension passed from the registration, details panels and menu items registered withRenderer.K8sApi.detailsForandRenderer.K8sApi.menuItemFor, menu item props fromCommon.Types.KubeObjectMenuItemProps, CSS modules imported for their class names, icons through?raw. - "Rules That Fail Silently" in
AGENTS.md: check every change against it, since each item compiles when broken. - Contract C6 (registration) in
api.md: an extension contributes through the declarative fields of itsLensExtensionsubclass, and each registered component gets only the props the host renders it with. - Contract C9 (routing) in
api.md: a page component gets onlyparams. - A new runtime dependency is bundled and goes in
dependencies("Knip" inAGENTS.md); one with install scripts needs anallowBuildsentry inpnpm-workspace.yaml. - An extension that renders
Renderer.Component.MonacoEditoraddsmonaco-editortodevDependenciesat the host's version, although it never imports it; otherwise the editor'soptionsand callback types areany("Project Overview" inAGENTS.md).
4. Verify
pnpm install
pnpm type:check
pnpm build
pnpm test:unit
pnpm knip:check
pnpm lint:check
pnpm trunk:check
All of them pass. dist/ then has main.js, renderer.js and one
stylesheet, renderer.css, with their source maps. pnpm knip:check fails on
a file nothing imports, such as a leftover module or barrel, or the
available-version.* files when no page uses them: remove the file rather than
ignore it in knip.jsonc.
Then run the extension in Freelens, as "From a directory" and "Development
loop" in the template's README.md describe: install the checkout's directory
from the Extensions page and run pnpm dev. Open every page, details panel,
menu item and preference the extension registers, and check that neither the
renderer's DevTools console nor the terminal running Freelens shows an error.
To run these checks through an agent attached to Freelens dev, follow
"Checking the Extension in Freelens Dev" in the template's AGENTS.md.
The integration tests are a pattern of the template, not a contract of the
extension API. Keep them, or remove them as a whole: integration/,
vitest.integration.config.ts, .github/workflows/integration-tests.yaml, the
playwright devDependency, the test:integration and
type:check:integration scripts, and their entries in knip.jsonc. Kept, they
are the preferred way to test the extension in Freelens: Freelens dev, which
pnpm dev of a freelensapp/freelens checkout starts, driven with Playwright
over CDP, and run with pnpm test:integration ("Workflows" in AGENTS.md).
The CRD sessions add a kubectl pattern for custom resources, which is destructive: it deletes the CRD and every object of it on the cluster, and the sessions install the checkout in the Freelens dev profile in place of any other installation of the extension. Run them in a sandbox: a kind cluster with nothing worth keeping, named in every kubectl call, never a shared or production context, and a fresh profile in CI.
An extension with a page that loads stores of its own, such as an overview or
a dashboard, opens that page as the first view of a session, right after the
cluster is connected. Opened after the list pages, it finds their stores
loaded and passes even when it loads nothing itself, which is how an effect
that breaks under React.StrictMode goes unnoticed ("Rules That Fail
Silently" in AGENTS.md).
A gap or an error in the Freelens documents, in @freelensapp/extensions or in
this skill is reported to
freelensapp/freelens, and one
in the template to
freelensapp/freelens-example-extension,
rather than worked around in the extension without a word.
Port a Freelens extension to v2
An extension needs this port when its package.json declares
engines.freelens as ^1.x or depends on @freelensapp/extensions 1.x.
Freelens v2 breaks the v1 extension API on purpose, and it refuses such an
extension at discovery, before any of its code runs.
This skill is the workflow. The documents below are the source of truth: read the sections each step names instead of relying on memory of the v1 API.
Documents
Fetch the raw URLs; they return Markdown. Read the issues and the pull request
with gh, which returns their source, as in step 1.
| Document | Read it for |
|---|---|
migrating-from-v1.md | The porting guide: what changed and what replaces it, the "v1→v2 rename table" and the "Checklist" at the end. |
api.md | The normative contracts C1 to C15: what the host guarantees and how a violation fails. C15 is for an extension that runs kubectl or helm. |
binaries.md | Only for an extension that ships executables. |
AGENTS.md of the template | The build, type-check, test, lint and CI patterns of a v2 extension, each with its reason, and "Rules That Fail Silently". |
README.md of the template | Installing an extension in Freelens and the development loop. |
| The source tree of the template | The worked example of a v2 extension. |
references/migration-issue.md | The template of the migration issue: the plan of a v2 migration, with the project-specific sections to fill in. |
| freelensapp/freelens-example-extension#326 | The same plan carried out for the template: a worked example of a completed migration issue, with its findings. |
| freelensapp/freelens-example-extension#327 | A worked example of a feature issue: the port of one feature, the Example CRD. |
| freelensapp/freelens-example-extension#336 | The pull request that ported that feature, with its functional checks. |
1. Plan the port in two kinds of issue
Open both in the extension's own repository.
The migration issue covers the extension itself: manifest, build,
TypeScript layout, tests, CI, documentation and the components its features
share. Its body is the template
references/migration-issue.md of this skill,
next to this file. Copy it as it is; its sections marked
(generic) stay as written, and every item starts unticked.
freelensapp/freelens-example-extension#326 is the same plan carried out for
the template itself: read it for what a filled-in inventory, a step report
and a finding look like, not to copy it.
- Check the pin of "Source of truth" first: a Freelens release tag, and the
@freelensapp/extensionsrelease of the same version. It is never older than what this skill and the documents it links to require. The template's ownpackage.jsonnames the release the template is checked against; a pin older than that is a sign. When the pin is older, move it in the issue to that release, with the versions of "Stack alignment" as Freelens has them there, record the move under "Findings" of the issue, and report the stale pin to freelensapp/freelens, where this skill lives. - Fill in every
(to fill in: ...)placeholder, so that none is left when the issue is opened. They are the sections marked (project-specific): "Inventory" (every v1 construct in the repository, with its v2 requirement and the API symbols to check), "Functional checks" and "Decisions", and the feature issues of the template note. The findings of earlier ports are already folded into the generic sections; "Findings" starts empty. - In "Inventory", answer in its "HTTP and cluster access" row how the
extension makes HTTP requests and how it reaches a cluster, in main and in
the renderer, with "none" when it does neither. A v1 client still works in
v2 on a plain network, so nothing points at it, but it goes around the
cluster's proxy setting and everything else Freelens does for the cluster,
so the port does not find it by itself; search for
fetch(, bundled HTTP and Kubernetes clients,kubeConfigPath, and spawnedkubectlorhelm. The v2 answers (C12 inapi.md):- HTTP outside a cluster: in main
Main.Util.fetch, also given as thefetchoption of a bundled library that takes one (an SDK, an MCP transport), notglobalThis.fetchor a bundled client; in the renderer the globalfetch, Chromium's, which the host uses there too; - a catalog cluster:
K8sApi.forClusterfor aKubeApiof one kind, orK8sApi.KubeJsonApi.forClusterfor requests by path, not a client built from the cluster'skubeConfigPath("Reaching a catalog cluster" inmigrating-from-v1.md); - kubectl or helm: the host's, through
Main.Shell(C15): the paths ofgetKubectlPathandgetHelmPath, run withgetEnvironmentas the environment, not a binary found by name or given the raw kubeconfig.
- HTTP outside a cluster: in main
- "Decisions" settles at least the version of the extension, its integration
tests (kept on the template's pattern, with the Freelens ref they run
against, or none; "Integration tests" below), and how the port lands: in one
PR, or in stages on a branch that nothing is released from, as the
template's port landed on
main; and how its pull requests are merged (squash, merge commit or rebase), which "Rules for the CI agent" refers to rather than assumes. - A short reference such as
#328resolves in the repository it is written in. The template writes the issues and pull requests of freelensapp/freelens-example-extension in full; write any that the issue adds the same way. - Keep the Claude handle split as
@<!-- -->claude, as the template has it: an issue whose body contains the handle starts the Claude workflow when it is opened, and so does a comment that contains it, in a repository that has one.
One feature issue per feature. Each lists its scope, the v1 constructs and
API symbols it uses, its steps with a prefix of its own (E1, E2, ...) and
its functional checks. Keeping the features out of the migration issue keeps
that issue to what every extension has; its "Rules for the CI agent" say how
the two are worked on together. Two kinds of feature have a pattern:
-
A custom resource, with its models, pages, details and menu items, or another view of the extension, as #327 is for the
ExampleCRD. Its steps follow "Adding an API" inAGENTS.md, and its checks include the Custom Resources tree of thecustomResourcesitem. -
A feature in the main process: a local server (an HTTP bridge, a socket), spawned processes, a bundled Node library such as
@kubernetes/client-node. freelensapp/freelens-for-claude-extension#73 is one. Its steps cover:- the ESM main: no
require,__dirnameormodule.exportsof its own left, its files located withthis.manifestPath, and every bundled CommonJS library loading fromdist/main.js, which needs thenodeplatform and the__dirnamedefinition of "Process-specific settings" inAGENTS.md; - the lifecycle: what
onActivatestarts,onDeactivatestops, because a reload runsonDeactivatebefore the new build'sonActivate("The development loop" inmigrating-from-v1.md), and a server still bound to its port or a child process left running survives it; - HTTP and cluster access, as the "HTTP and cluster access" row of the migration issue's inventory gives them;
- the channel between the renderer and main: IPC (
Main.Ipc.handleandRenderer.Ipc.invoke) for short request/response exchanges, and a local HTTP server for a stream or the bulk of the traffic. The extension API has no send to a single frame:Ipc.broadcastreaches every frame of every window, so per-cluster data sent that way reaches the frames of other clusters, while an HTTP request gives each frame a stream of its own. A secret such as the server's bearer token goes overinvoke, not into anExtensionStore, which the host syncs to every frame and saves to disk, and which keeps a key once saved. freelensapp/freelens-for-claude-extension#106 hands its bridge token over that way; - a spawned kubectl or helm through
Main.Shell(C15), and a shipped executable afterbinaries.md.
Its functional checks: the server answers and the processes run once the extension is enabled, both are gone after it is disabled, a rebuild under
pnpm devleaves exactly one of each, and the main-process log has no error. Such a feature registers no model, so thecustomResourcesitem of "Validation by maintainers" does not apply to it. - the ESM main: no
Before the first trigger comment, compare the job that runs the agent in
the repository's .github/workflows/claude.yaml with the claude job of the
template's:
its --max-turns (400 there) and its timeout-minutes (120 there). A run
stops at whichever it reaches first, and "Rules for the CI agent" of the
migration issue asks for a set of steps that fits in one run, so a comment
sized for the template's limits ends in the middle of a step under lower ones,
as the first run of freelensapp/freelens-ai-extension did at 200 turns. Either
raise both to the template's values, in a commit of their own before the
first run, or size the trigger comments to the repository's values.
2. Order of work
- Manifest. Bump
engines.freelensto^2.0.0first: until then the host refuses the extension, and nothing else is observable ("Step one: bumpengines.freelens" inmigrating-from-v1.md). Install the exact@freelensapp/extensionsversion that "Source of truth" in the migration issue names, and set"type": "module"("package.jsonfor an extension"). - Toolchain and build. Align them with the template as it is on its
current
main: take the files thatcreate-extensionlists under "Keep as is", the dependency versions of the template'spackage.json, and its scripts. Where a version there is ahead of the one "Stack alignment" in the migration issue pins, keep the file and set the pinned version, and say so in the PR. Never take the files from an older commit of the template to match the pin: that also drops the template's changes that do not depend on it. The template renders noRenderer.Component.MonacoEditor; an extension that does declaresmonaco-editorindevDependencies, at the host's version, for the editor's types, even when its v1package.jsondid not list it ("Project Overview" inAGENTS.md). Move the code intosrc/main/,src/renderer/andsrc/common/, one TypeScript program each ("Source layout: one tsconfig per runtime environment" inmigrating-from-v1.md, "Build" and "TypeScript" inAGENTS.md). Remove whatever only the v1 build needed: the bundler configuration, the global externals, legacy decorator plugins. - API changes. Let
pnpm type:checkdrive them. Look every error up in the "v1→v2 rename table" ofmigrating-from-v1.mdand follow the section it links. Decorators follow "MobX 7 and mobx-react 10 (standard decorators only)", stylesheets "Styling and CSS", and Node or Electron in renderer code "Node and Electron in the renderer". - Features. One feature issue at a time: a custom resource or a view after
"CRD KubeObject Pattern" and "Renderer Components" in
AGENTS.md, a feature in the main process after its pattern in step 1. - Functional check in Freelens, as in "Verify" below.
3. What compiles and fails at runtime
The type check does not catch everything a v1 extension gets wrong on v2. Check the port against:
- "Rules That Fail Silently" in
AGENTS.md: a second copy of React or mobx,@observablewithoutaccessor, Node or Electron in renderer code, a CSS asset other thandist/renderer.css, an instance method on a KubeObject subclass, a cluster page that expects more thanparams, a version choice throughgetStore()in a component that is not anobserver,this.propsof an@observerclass component read outside itsrender(), anAbortControlleror a list of watches kept in a ref across runs of an effect, a page, details panel or menu item outside an error boundary, a CommonJSmain. - The extension's effects that load stores themselves, as an overview or a
dashboard does. Search for
useRefholding anAbortController, or the disposers ofsubscribe(), that an effect's cleanup aborts or releases. Freelens dev renders inReact.StrictMode, which runs the effect, cleans it up and runs it again on the same instance: the second run loads with a signal that is already aborted, the host takes that for no failure, and the view shows nothing without an error. Create the controller and the list of watches inside the effect ("Rules That Fail Silently" inAGENTS.md). - The extension's own version choice. An extension that already has a copy of
createAvailableVersionPage, or another component that picks the served API version throughgetStore(), keeps it from before the port, and it is usually a plain function component. Make it anobserver, or replace the copy with the template'ssrc/renderer/components/available-version.tsxand its test: otherwise a page that renders before the cluster frame has loaded the CRDs, as a page Freelens restores when a cluster is opened does, shows the kind as not installed ("CRD KubeObject Pattern" inAGENTS.md). - The extension's
@observerclass components. Under v1 they could readthis.propsanywhere; under mobx-react 10 only their ownrender()may. Search forthis.propsin@computedgetters and in the methods passed to the host, such asgetItemsandcustomizeHeaderofKubeObjectListLayout: each throws[mobx-react] Cannot read "X.props" in a reactive contextwhen the page renders, and the host shows "App crash". Read the values inrender()and hand them to the callback, or make the component a function component ("MobX 7 and mobx-react 10 (standard decorators only)" inmigrating-from-v1.md). - The porting hint in "Renderer Components" in
AGENTS.md: theclusterPagesandglobalPagesregistrations that compiled under v1 and getundefinedprops on v2, and how to pass the extension from the registration instead. - The
kubeObjectDetailItemsandkubeObjectMenuItemsregistrations. A v1 registration withkindandapiVersionswritten out still compiles, and so does one that pairs a component with the model of another version. Replace each withRenderer.K8sApi.detailsFororRenderer.K8sApi.menuItemForand the model class, and declare the instancekindandapiVersionof every model as literals, without which two versions of one kind are not told apart. A menu item whose props extendRenderer.Component.KubeObjectMenuPropscompiles too; make it extendCommon.Types.KubeObjectMenuItemProps, the props the host passes ("CRD KubeObject Pattern" and "Renderer Components" inAGENTS.md). - The error boundary. A v1 extension that keeps an error in its place with a
try/catcharound the call of a component, such as the template's formerwithErrorPage, catches only what that call throws: an error that a child throws when React renders it, or that a callback such asrenderTableContentsthrows from the host'sKubeObjectListLayout, replaces the main area, or from a details panel or a menu item the whole cluster view. Copy the template'ssrc/renderer/components/error-boundary.tsxand its test, mapclusterPages,globalPages,kubeObjectDetailItemsandkubeObjectMenuItemsthrough its wrappers, and remove thetry/catchwrapper ("Renderer Components" and "Rules That Fail Silently" inAGENTS.md). - The "Checklist" at the end of
migrating-from-v1.md, including the two items it marks as failing silently.
4. Findings
Work on the extension, never around Freelens:
- A gap or an error in the Freelens documents or in
@freelensapp/extensions, such as a symbol that is missing from the API namespaces, a type that does not match what the host passes, or a document that contradicts the declaration, is reported to freelensapp/freelens, and recorded under "Findings" and "Upstream work item" of the migration issue. It is not worked around silently in the extension, withas any,globalThis.requireor a reach into the host's internals. - A finding of the migration issue that applies to any port is reported to
freelensapp/freelens, so
that this skill or
references/migration-issue.mdis changed for the ports after this one. A gap in the template's files is reported to freelensapp/freelens-example-extension.
5. Verify
pnpm install
pnpm type:check
pnpm build
pnpm test:unit
pnpm knip:check
pnpm lint:check
pnpm trunk:check
All of them pass. dist/ then has main.js, renderer.js and one
stylesheet, renderer.css, with their source maps. pnpm knip:check fails on
a file nothing imports, such as a leftover v1 module or barrel, or the
available-version.* files when no page uses them: remove the file rather than
ignore it in knip.jsonc.
Then run the extension in Freelens 2.x, as "From a directory" and "Development
loop" in the template's README.md describe: install the checkout's directory
from the Extensions page and run pnpm dev. The Extensions page lists it as
enabled. Open every page, details panel, menu item and preference the
extension registers, and check that neither the renderer's DevTools console nor
the terminal running Freelens shows an error. Make one change through mobx,
such as a preference, and check that the UI follows it: that proves the
extension uses the host's mobx. Check that every custom resource listed in
customResources is gone from the Custom Resources tree of the cluster
sidebar, and that the log has no error rejecting one of its entries; an
extension that presents no custom resource sets no customResources, and its
item in "Validation by maintainers" says so. Then tick the functional checks of
the migration issue and of each feature issue.
To run these checks through an agent attached to Freelens dev, follow
"Checking the Extension in Freelens Dev" in the template's AGENTS.md.
Integration tests
Integration tests are a pattern of the template, not a contract of the
extension API: a port may keep them, add them or leave them out. The preferred
way is the template's: Vitest in the extension's own repository, driving
Freelens dev, which pnpm dev of a freelensapp/freelens checkout starts, with
Playwright attached over CDP ("Workflows" in the template's AGENTS.md). v1
tests that run inside a Freelens checkout, under its Vitest, with its
helpers/ and a packaged app started through _electron, are rewritten onto
the template's integration/ rather than ported as they are.
An extension with custom resources can also take the kubectl pattern of the template's CRD sessions, which apply a CRD and its test objects to a kind cluster and delete them again. Such tests are destructive: they delete the CRD and every object of it on the cluster, and they install the checkout in the Freelens dev profile in place of any other installation of the extension. Run them in a sandbox: a kind cluster with nothing worth keeping, named in every kubectl call, never a shared or production context, and a fresh profile in CI.
An extension with a page that loads stores of its own, such as an overview or
a dashboard, opens that page as the first view of a session, right after the
cluster is connected. Opened after the list pages, it finds their stores
loaded and passes even when it loads nothing itself, which is how an effect
that breaks under React.StrictMode goes unnoticed ("Rules That Fail
Silently" in the template's AGENTS.md).
Sponsors
Details
- Marketplace
- freelensapp/freelens
- Source
- plugins/freelens
- Category
- Community