From d67402033f92d848bfb6ec34a574ce7b9becadda Mon Sep 17 00:00:00 2001 From: Lars Kappert Date: Sat, 21 Sep 2024 18:46:28 +0200 Subject: [PATCH] Update docs --- .../docs/src/content/docs/blog/knip-v3.mdx | 2 +- .../docs/src/content/docs/blog/knip-v4.mdx | 2 +- .../docs/src/content/docs/blog/knip-v5.mdx | 2 +- .../content/docs/explanations/why-use-knip.md | 51 +++++++++++++------ .../src/content/docs/features/auto-fix.mdx | 2 +- packages/docs/src/content/docs/index.mdx | 40 +++++++++++---- .../content/docs/overview/getting-started.mdx | 8 +-- .../docs/reference/dynamic-configuration.mdx | 4 +- packages/docs/src/styles/content.css | 4 +- 9 files changed, 77 insertions(+), 38 deletions(-) diff --git a/packages/docs/src/content/docs/blog/knip-v3.mdx b/packages/docs/src/content/docs/blog/knip-v3.mdx index 0cb2b7232..81da5333e 100644 --- a/packages/docs/src/content/docs/blog/knip-v3.mdx +++ b/packages/docs/src/content/docs/blog/knip-v3.mdx @@ -49,7 +49,7 @@ on your end: Try out the latest Knip v3 release today! - + ```shell diff --git a/packages/docs/src/content/docs/blog/knip-v4.mdx b/packages/docs/src/content/docs/blog/knip-v4.mdx index ec87fb7b2..e23e40a9f 100644 --- a/packages/docs/src/content/docs/blog/knip-v4.mdx +++ b/packages/docs/src/content/docs/blog/knip-v4.mdx @@ -114,7 +114,7 @@ removed and option(s) added to the Knip configuration file. The docs are in the What are you waiting for? Start using Knip v4 today! - + ```shell diff --git a/packages/docs/src/content/docs/blog/knip-v5.mdx b/packages/docs/src/content/docs/blog/knip-v5.mdx index 0f6510dc2..a10543e50 100644 --- a/packages/docs/src/content/docs/blog/knip-v5.mdx +++ b/packages/docs/src/content/docs/blog/knip-v5.mdx @@ -157,7 +157,7 @@ change is large enough to warrant a major bump. What are you waiting for? Start using Knip v5 today! - + ```shell diff --git a/packages/docs/src/content/docs/explanations/why-use-knip.md b/packages/docs/src/content/docs/explanations/why-use-knip.md index f41914110..798bf9261 100644 --- a/packages/docs/src/content/docs/explanations/why-use-knip.md +++ b/packages/docs/src/content/docs/explanations/why-use-knip.md @@ -8,6 +8,18 @@ The value of removing clutter from your code is undeniable. However, finding them is a manual and tedious job. This is where Knip comes in. As codebases grow in complexity and size, automated and comprehensive tooling becomes critical. +:::tip[TL;DR] + +Knip finds and fixes unused files, exports and dependencies. + +Deep analysis from [fine-grained entry points][1] based on the actual frameworks +and tooling in your [(mono)repo][2] with [custom module resolution][6], +[configuration file parsers][3], [compilers][4], a [shell script parser][5] and +additional heuristics to maximize coverage for comprehensive and actionable +results. + +::: + ## Less is more There are plenty of reasons to delete unused files, dependencies and "dead @@ -26,9 +38,9 @@ code": the same for files, dependencies and exports that you forgot to delete. - Keeping dead code around has a negative value on readability, as it can be misleading and distracting. Even if it serves no purpose it will need to be - maintained (source: [Safe dead code removal โ†’ YAGNI][1]). -- Also see [Why are unused dependencies a problem?][2] and [Why are unused - exports a problem?][3]. + maintained (source: [Safe dead code removal โ†’ YAGNI][7]). +- Also see [Why are unused dependencies a problem?][8] and [Why are unused + exports a problem?][9]. ## Automation @@ -41,9 +53,10 @@ times better and faster than trying to do it manually. :::tip -Knip not only finds clutter, it can also [clean it][4]! Use Knip next to a -linter like ESLint or Biome: after removing unused variables inside files, Knip -might find even more unused code. Rinse and repeat! +Knip not only finds clutter, it can also [clean it][10]! + +Use Knip next to a linter like ESLint or Biome: after removing unused variables +inside files, Knip might find even more unused code. Rinse and repeat! ::: @@ -55,9 +68,9 @@ synergy: - Utilizing plugins to find their dependencies includes the capacity to find additional entry files. This results in more resolved and used files. Better - coverage gives greater insights into unused files and exports. -- Analyzing more files reveals more dependency usage, refining the list of both - unused and unlisted dependencies. + coverage gives better insights into unused files and exports. +- Analyzing more files reveals more unused exports and dependency usage, + refining the list of both unused and unlisted dependencies. - This approach is amplified in a monorepo setting. In fact, files and internal dependencies can recursively reference each other (across workspaces). @@ -94,13 +107,19 @@ so you can easily get rid of false positives? A variety of reasons: 1. A false positive may be a bug in Knip, and should be reported (not easily dismissed). -2. Instead of proprietary comments, use [standardized annotations][5] serving as - documentation as well. +2. Instead of proprietary comments, use [standardized annotations][11] serving + as documentation as well. 3. In the event you want to remove Knip, just uninstall `knip`. And not countless useless comments scattered throughout the codebase. -[1]: https://jfmengels.net/safe-dead-code-removal/#yagni-you-arent-gonna-need-it -[2]: ../typescript/unused-dependencies.md#why-are-unused-dependencies-a-problem -[3]: ../typescript/unused-exports.md#why-are-unused-exports-a-problem -[4]: ../features/auto-fix.mdx -[5]: ../reference/jsdoc-tsdoc-tags.md +[1]: ./entry-files.md +[2]: ../features/monorepos-and-workspaces.md +[3]: ./plugins.md#configuration-files +[4]: ../features/compilers.md +[5]: ../features/script-parser.md +[6]: ../reference/faq.md#why-doesnt-knip-use-an-existing-module-resolver +[7]: https://jfmengels.net/safe-dead-code-removal/#yagni-you-arent-gonna-need-it +[8]: ../typescript/unused-dependencies.md#why-are-unused-dependencies-a-problem +[9]: ../typescript/unused-exports.md#why-are-unused-exports-a-problem +[10]: ../features/auto-fix.mdx +[11]: ../reference/jsdoc-tsdoc-tags.md diff --git a/packages/docs/src/content/docs/features/auto-fix.mdx b/packages/docs/src/content/docs/features/auto-fix.mdx index 1f0f81fbf..1e1379a8d 100644 --- a/packages/docs/src/content/docs/features/auto-fix.mdx +++ b/packages/docs/src/content/docs/features/auto-fix.mdx @@ -63,7 +63,7 @@ Rinse and repeat! Verify changes in `package.json` and update dependencies using your package manager: - + ```shell diff --git a/packages/docs/src/content/docs/index.mdx b/packages/docs/src/content/docs/index.mdx index ba272aa7e..84f973680 100644 --- a/packages/docs/src/content/docs/index.mdx +++ b/packages/docs/src/content/docs/index.mdx @@ -1,12 +1,12 @@ --- -title: Knip the clutter! +title: Declutter your JavaScript & TypeScript projects description: Project linter to find and remove unused files, dependencies and exports in JavaScript and TypeScript projects template: splash hero: title: Knip! - tagline: Cut the clutter from JavaScript & TypeScript projects + tagline: Declutter your JavaScript & TypeScript projects image: file: ../../assets/logo.svg actions: @@ -27,28 +27,48 @@ import Sponsors from '../../components/Sponsors.astro'; import Projects from '../../components/Projects.astro'; import Contributors from '../../components/Contributors.astro'; + + + + Knip finds and fixes unused files, exports and dependencies. Use it for enhanced + code and dependency management. + + Read the full explanation: [why should I use Knip?][1] + + + + + + Deep analysis from fine-grained entry points based on the actual frameworks + and tooling in your (mono)repo with custom module resolution, configuration + file parsers, compilers, a shell script parser and additional heuristics to + maximize coverage for comprehensive and actionable results. + + + + :::div{.sponsor} -[Support Knip!][1] +[Support Knip!][2] ::: - + - [Find & remove unused files, dependencies and exports][2] + Thousands of projects are already using Knip! - Try Knip on the [playground][3] + Try Knip on the [playground][3]. - Need help? [Start troubleshooting][4] + Need help? [Start troubleshooting][4]. @@ -80,7 +100,7 @@ Eternal gratitude to the companies and people that are already supporting Knip: -Please see [Sponsors][1] for the full list. Consider supporting the project too! +Please see [Sponsors][2] for the full list. Consider supporting the project too! ## ๐Ÿงก Contributors @@ -108,8 +128,8 @@ Special thanks to the wonderful people who have contributed to this project: - [Unused dependencies][11] - [Unused exports][12] -[1]: ./sponsors -[2]: ./explanations/why-use-knip.md +[1]: ./explanations/why-use-knip.md +[2]: ./sponsors [3]: ./playground [4]: ./guides/troubleshooting.md [5]: https://www.jamesshopland.com diff --git a/packages/docs/src/content/docs/overview/getting-started.mdx b/packages/docs/src/content/docs/overview/getting-started.mdx index 2bd39af28..fbcc7b4da 100644 --- a/packages/docs/src/content/docs/overview/getting-started.mdx +++ b/packages/docs/src/content/docs/overview/getting-started.mdx @@ -16,7 +16,7 @@ Want to try Knip without installation? Visit [the playground][1]. This is the easiest and recommended way to install Knip: - + ```shell @@ -52,7 +52,7 @@ This is the easiest and recommended way to install Knip: Now you can run Knip to lint your project: - + ```shell @@ -94,7 +94,7 @@ You can skip the rest of this page and go to [configuration][2]. Alternatively, manually install Knip using your package manager: - + ```shell @@ -147,7 +147,7 @@ Then add a `knip` script to your `package.json`: To run Knip without adding it to your project: - + ```shell diff --git a/packages/docs/src/content/docs/reference/dynamic-configuration.mdx b/packages/docs/src/content/docs/reference/dynamic-configuration.mdx index 6e00f4947..cf61aceee 100644 --- a/packages/docs/src/content/docs/reference/dynamic-configuration.mdx +++ b/packages/docs/src/content/docs/reference/dynamic-configuration.mdx @@ -9,7 +9,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; Instead of a JSON file, you can use a JavaScript or TypeScript file for a dynamic configuration and type annotations: - + ```ts title="knip.ts" @@ -45,7 +45,7 @@ dynamic configuration and type annotations: You can export a regular or async function that returns the configuration object as well: - + ```ts title="knip.ts" diff --git a/packages/docs/src/styles/content.css b/packages/docs/src/styles/content.css index 43fd3b068..230c89d2c 100644 --- a/packages/docs/src/styles/content.css +++ b/packages/docs/src/styles/content.css @@ -91,10 +91,10 @@ section.plugins li { } } -.sponsor { +.sl-markdown-content .sponsor { font-size: 2rem; text-align: center; - margin-bottom: 5rem; + margin: 5rem 0; } .sl-badge.caution,