Development

Development in this repository is using:

• pnpm
• TypeScript
• oxc

This document describes commands and tasks that might help during development. Use what fits your workflow best, but make sure QA passes.

Contents

• Getting started
• Agents
• Contributing a plugin?
• Running Knip
• Tests
• QA
• GitHub Action
• Test Preview Packages
• Test VS Code Extension

Getting started

This guide assumes familiarity with concepts like forking, cloning a repo and working with a package manager.

• Fork the project using the GitHub website or the gh CLI
• Clone the repository
• Install dependencies

Example terminal commands on your machine to get started:

git clone git@github.com:[username]/knip.git
# Or using the GitHub CLI: gh repo fork webpro-nl/knip --clone
cd knip
pnpm install
cd packages/knip
pnpm build
pnpm test

To skip slower tests related to CLI and --fix, while still covering all the essentials and plugins:

pnpm test --smoke

Note that Git core.symlinks=true is required for some tests.

Agents

Using coding agents cq AI-powered tooling? Inform it about AGENTS.md. Take responsibility and make sure to not cause unnecessary review and "wall of text" overhead to maintainers. Also consider this before opening a pull request.

Contributing a plugin?

In addition to the generic guidelines in this document, there's a guide for writing a plugin.

Running Knip

Knip is written in TypeScript, run it including your changes directly using Node.js v24+ or Bun.

Run Knip without compilation:

node path/to/knip/packages/knip/src/cli.ts

Alias

Set up an alias like so:

alias k="node --inspect ~/p/knip/packages/knip/src/cli.ts"

Invoke k to run Knip including any local changes. And if it's in the built-in terminal, it will stop at breakpoints. For the rest of this document, knip or node --inspect can be replaced with k.

Tests

Most pull requests should probably include one or more tests.

Assuming you've created test/feature.test.ts and fixtures/feature (the plugin create command does for you), here's a few ideas to run and debug Knip from a test.

Creating a new plugin? The plugin guide has a command to set up a test with fixtures for you.

Run single test file

node --test test/my-feature.test.ts
bun test test/plugins/my-plugin.test.ts

Run Knip in the directory

knip --directory fixtures/feature

Attach debugger to Node.js

To debug Knip in an IDE (e.g. VS Code or WebStorm), open the built-in terminal and allow the debugger to connect:

cd fixtures/feature
node --inspect ../../src/cli.ts

Make sure VS Code is set up to attach to the Node.js process ("Always" or "With flag").

Attach debugger from inside a test file

Run configurations for VS Code and WebStorm² are set up in the repo. This a great way to debug almost anything in Knip.

• Using Node.js
  • From any test file, run the "Debug test with tsx/Node.js" launch config
• Using Bun
  • VS Code: ensure the Bun extension is enabled
  • WebStorm: ensure the Bun plugin is enabled
  • From any test file, run the "Debug test with Bun" launch config

From now on, just set a breakpoint and hit F5 (Code) or ctrl-r (WS) from any test file to run and debug.

² Requires at least WebStorm 2025.2 EAP

Attach debugger to tests

In case you're wondering if or why some code is ever hit, attach the debugger to each test. Set a breakpoint and run all tests in one of the following ways:

• From built-in terminal: node --inspect --test test/**/*.test.ts
• Use the "Debug all tests with Bun" launch config.

QA

Knip has a few tools set up to verify code quality and to format code and documentation:

pnpm fmt
pnpm lint
pnpm knip
pnpm knip --strict
pnpm test

GitHub Action

The ci.yml workflow runs the tests across Bun, recent Node.js versions, Ubuntu, macOS and Windows. QA in CI must be all green before a pull request can be merged. The integration.yml workflow runs Knip in multiple repositories using Knip, against the latest version of the code.

Test Preview Packages

For pull requests and on each push, the pkg.pr.new bot posts preview URLs for Knip, the language server, and MCP. Replace PR_NUMBER below with the pull request number, or a published commit hash to test a specific revision.

Install the preview in the affected project with your package manager, for example:

npm i -D https://pkg.pr.new/knip@PR_NUMBER

For a standalone language server, configure the LSP client to launch:

npm exec --yes --allow-remote=all --package=https://pkg.pr.new/@knip/language-server@PR_NUMBER -- knip-language-server --stdio

Use the client's usual transport. The server prefers project-local Knip; to test its bundled fallback, use a project without a locally resolvable Knip.

Test VS Code Extension

With Node.js v24+, pnpm, and vsce installed, check out the branch or pull request to test, then run from the repository root:

pnpm install
pnpm --dir packages/mcp-server run prepack
pnpm --dir packages/vscode-knip package

Install the generated platform-specific .vsix from packages/vscode-knip/ using VS Code's "Extensions: Install from VSIX..." command, then reload the window. This replaces the Marketplace version. To return to it, uninstall the preview and reinstall Knip from the Marketplace.