From b52125de02962452308eca17606c1eade79d550e Mon Sep 17 00:00:00 2001 From: Lars Kappert Date: Tue, 17 Sep 2024 13:54:49 +0200 Subject: [PATCH] Update docs --- .../docs/src/content/docs/blog/knip-v4.mdx | 2 +- .../content/docs/guides/handling-issues.mdx | 391 +++++++++++------- .../content/docs/guides/troubleshooting.md | 38 +- packages/docs/src/content/docs/index.mdx | 9 +- .../content/docs/overview/configuration.md | 9 +- .../docs/src/content/docs/reference/cli.md | 6 +- .../content/docs/reference/known-issues.md | 80 ++-- packages/docs/src/styles/content.css | 4 + 8 files changed, 324 insertions(+), 215 deletions(-) diff --git a/packages/docs/src/content/docs/blog/knip-v4.mdx b/packages/docs/src/content/docs/blog/knip-v4.mdx index eae9665bf..ec87fb7b2 100644 --- a/packages/docs/src/content/docs/blog/knip-v4.mdx +++ b/packages/docs/src/content/docs/blog/knip-v4.mdx @@ -152,6 +152,6 @@ Remember, Knip it before you ship it! Have a great day ☀️ [1]: ./slim-down-to-speed-up.md [2]: ../features/compilers.md -[3]: ../guides/troubleshooting#minimal-reproduction +[3]: ../guides/issue-reproduction [4]: https://github.com/sponsors/webpro [5]: ../reference/cli#--experimental-tags diff --git a/packages/docs/src/content/docs/guides/handling-issues.mdx b/packages/docs/src/content/docs/guides/handling-issues.mdx index 11e1cebe9..a8bde036d 100644 --- a/packages/docs/src/content/docs/guides/handling-issues.mdx +++ b/packages/docs/src/content/docs/guides/handling-issues.mdx @@ -15,27 +15,40 @@ the issue types one by one. For instance, reducing the number of unused files will also reduce the number of unused dependencies. Therefore it's recommended to work this page from top to bottom. -If you haven't already, make sure to make yourself familiar with the following -topics: - -- [Configuration][1] -- [Entry files][2] -- [Configuring project files][3] -- [Using monorepos & workspaces?][4] - ## Unused files -Files are reported as unused if they are in the set of project files, but not in -the set of files resolved from the entry files: +The first thing we're looking at is unused files, since the positive effect of +getting those right trickles down into the other issue types as well. Files are +reported as unused if they are in the set of `project` files, but not in the set +of files resolved from the `entry` files: ``` unused files = project files - (entry files + resolved files) ``` -In this section we'll look into common patterns that cause unused files and how -to handle them. +Let's go over common causes for adding `entry` patterns manually: + +- [Dynamic import specifiers][1] +- [Unsupported arguments in scripts][2] +- [Unsupported file formats][3] +- [Missing plugin][4] +- [Incomplete plugin][5] +- [Integrated monorepos][6] +- [Build artifacts and ignored files][7] +- [Auto-mocking or auto-imports][8] + +The recommended solution is usually to add the file as shown in each example as +an `entry` file. + +:::caution -Use `--files` to [filter the report][5] and focus on unused files: +Please don't add unused files to the `ignore` option before reading [configuring +project files][9]. Learn why and when to use `entry`, `project` and `ignore` +patterns for better results and performance. + +::: + +Use `--files` to [filter the report][10] and focus on unused files: ```sh knip --files @@ -45,75 +58,113 @@ This works with other issue types as well. For instance, use `--dependencies` to focus only on dependencies and exclude issues related to unused files and exports. -### Implicit imports +### Dynamic import specifiers -Some files are imported by other tooling, such as fixtures, mocks or templates. -And some frameworks import files such as routes or models, while Knip doesn't -have a plugin for that framework yet. +Dynamic import specifiers aren't resolved, such as: -If those files are in the set of project files, but not imported by your code, -they might be reported as unused files. If they should be included, extend the -`entry` file patterns: - -```json -{ - "entry": ["src/index.ts", "src/models/*.ts"] -} +```ts +const entry = await import(path.join(baseDir, 'entry.ts')); ``` -On the other hand, to exclude them from the `project` files using negated -`project` patterns: +### Unsupported arguments in scripts + +Some tooling command arguments aren't recognized: ```json { - "project": ["src/**/*.ts", "!src/**/__unimported__/**"] + "name": "my-lib", + "version": "1.0.0", + "scripts": { + "build": "unknown-build-cli --entryPath entry.ts" + } } ``` -Also see [configuring project files][6] to learn more about `entry` and -`project` files, and when to use `ignore` patterns. +The same goes for other scripts such as those in GitHub Actions workflows or Git +hooks. See [script parser][11] for what Knip does support. + +### Unsupported file formats -### Plugins +Entry files referenced in HTML files (e.g. ` + + +``` -You might be using a tool or framework that's not in the list of available -plugins. Configuration and entry files (and related dependencies) may be -reported as unused because there is no plugin yet that includes those files. For -example, if `tool.config.js` contains a reference to `@tool/package` then both -the file and the dependency may be reported as an unused. +### Missing plugin -[Create a new plugin][7] for tools or frameworks that are not [in the list][8] -yet, or [request it][9]. +You might be using a tool or framework for which Knip doesn't have a plugin +(yet). Configuration and entry files (and related dependencies) may be reported +as unused because there is no plugin yet that would include those files. For +example, -#### Existing plugins +- Config file `tool.config.js` contains a reference to the package + `"@tool/plugin"` and both the file and the dependency may be reported as an + unused. +- A framework imports all files matching `src/models/*.ts` and those might be + reported as unused. -Files may be reported as unused if existing plugins do not include that entry -file pattern yet. +[Create a new plugin][12] for tools or frameworks that are not [in the list][13] +yet, or [request it][14]. -See the [plugins section of entry files][10] for more details. [Override plugin -configuration][11] to customize default patterns for existing plugins. +### Incomplete plugin + +Files may be reported as unused if existing plugins do not include that entry +file pattern yet. See the [plugins section of entry files][15] for more details. +[Override plugin configuration][16] to customize default patterns for existing +plugins. ### Integrated monorepos Multiple instances of configuration files like `.eslintrc` and `jest.config.json` across the repository may be reported as unused when working -in a (mono)repo with a single `package.json`. See [integrated monorepos][12] for +in a (mono)repo with a single `package.json`. See [integrated monorepos][17] for more details and how to configure plugins to target those configuration files. ### Build artifacts and ignored files -Sometimes build artifacts and `.gitignore` files may have a surprising effects -on files reported as unused. Results may be different in separate runs, +In rare cases, build artifacts and `.gitignore` files may have a surprising +effects on files reported as unused. Results may be different in separate runs, depending on the presence of build artifacts. Knip tries to do the right thing, but in some cases you may need to add a file to the `entry` file patterns manually for better or more consistent results. +### Auto-mocking or auto-imports + +Some frameworks have features like "auto-mocking" or "auto-imports" enabled, +such as Jest and Nuxt. The solution is to include such entry files by extending +the `entry` file patterns. This is recommended in most cases: + +```json +{ + "entry": ["src/index.ts", "src/models/*.ts"] +} +``` + +Alternatively, exceptions and outliers can be excluded from the analysis using +negated `project` patterns: + +```json +{ + "project": ["src/**/*.ts", "!src/**/__mocks__/**"] +} +``` + ## Unused dependencies Dependencies imported in unused files are reported as unused dependencies. -That's why it's strongly recommended to try and remedy [unused files][13] first. -This solves many cases of reported unused dependencies. +That's why it's strongly recommended to try and remedy [unused files][18] first. +Better `entry` and `project` file coverage will solve many cases of reported +unused dependencies. + +The most common causes for unused and unlisted dependencies include: + +- \[Missing or incomplete plugin]\(#missing-or-incomplete-plugin) +- [Unreachable code][19] :::caution[Monorepo] @@ -123,13 +174,14 @@ descendent workspace. ::: -Use the `--dependencies` flag to [filter][5] dependency related issues: +Use `--dependencies` to [filter the report][10] and focus on dependency related +issues: ```sh knip --dependencies ``` -### Plugins +### Missing or incomplete plugin If a plugin exists and the dependency is referenced in the configuration file, but its custom dependency finder does not detect it, then that's a false @@ -150,35 +202,22 @@ you don't feel like a plugin could solve it, a last resort is to ignore it: } ``` -Depending on the situation, you may want to use `ignoreBinaries` instead. See -[unlisted binaries][14]. +If a binary (or "executable") is referenced you'll want to use `ignoreBinaries` +instead. See [unlisted binaries][20]. -### TypeScript, Jest & ESLint +### TypeScript, Jest & legacy ESLint -Within monorepos, tools like TypeScript, ESLint and Jest are a story of their -own. Sharing and extending configurations is convenient, but for a project -linter like Knip it can be a challenge to assign dependencies to the right -workspace. +In monorepos, sharing and extending configurations is convenient, but for a +project linter like Knip certain scenarios can be a challenge to assign +dependencies to the right workspace. Specifically, the root cause is usually a +combination of JSON-based configuration files that extend from each other across +workspaces in a monorepo. This is an issue since we can't "assign" dependencies +to other workspaces and incorrectly end up having "unlisted dependencies". -The new [ESLint flat config system][15] does not have this issue, so it's +Most notably, tools like TypeScript, Jest and legacy ESLint suffer from this. +The new [ESLint flat config system][21] does not have this issue, so it's recommended to migrate if you haven't already. -We can't "assign" dependencies to other workspaces. But workspaces that use the -`@internal/eslint-config` package can force-enable the ESLint plugin (without -having `eslint` listed) and ignore related dependencies (adjust to your -situation). So if you can't migrate to the ESLint flat config yet, here's a -workaround: - -```json -{ - "eslint": true, - "ignoreDependencies": ["^eslint-.*"] -} -``` - -The same idea applies for false positives caused by tools like TypeScript and -Jest that share and extend configurations across the monorepo. - ## Unlisted dependencies This means that a dependency is used, but not listed in `package.json`. @@ -198,20 +237,24 @@ Binaries are executable Node.js scripts. Many npm packages, when installed, add an executable file to use from scripts in `package.json`. Examples include TypeScript with the `tsc` binary, Next.js with the `next` binary, and so on. -Knip detects such binaries in scripts and checks whether there's package -installed that includes the binary. It looks up the `bin` field in the +Knip detects such binaries in scripts and checks whether there's a package +installed that includes that binary. It looks up the `bin` field in the `package.json` file of installed packages. If it doesn't find it, it will be reported as an unlisted binary as there is no package listed that contains it. -Except for those listed as `IGNORED_GLOBAL_BINARIES` in `constants.ts`. + +Except for binaries that are most likely meant to be installed on the OS already +and not installed from npm (details: [list in source][22]). ### Missing binaries In case unused (dev) dependencies look like a match against unlisted binaries, then this might be caused by `node_modules` not containing the packages. And this might have been caused by either the way your package manager installs -dependencies, or by not running Knip from the root of the repository. +dependencies and binaries, or by not running Knip from the root of the +repository. -Knip should run from the root. But you can [lint individual workspaces][16]. +Run Knip from the project root. From there you can [lint individual +workspaces][23]. ### Example @@ -239,42 +282,70 @@ This technically works as `commitlint` is a transitive dependency of ## npx -For `npx` scripts, Knip assumes that `--yes` (as in `npx --yes package`) means -that the package is not listed. Knip expects the dependency to be listed with -`--no` or no flag at all. +For usages of the `npx` command, Knip assumes `npx --yes my-package` means that +`my-package` is not listed. Knip expects the dependency to be listed with `--no` +or no flag at all. The recommendation here is to be explicit: -The recommendation here is to be explicit: use `--yes` if the dependency is not -supposed to be listed in `package.json`. Or use `--no` if the dependency is -listed. +- Use `npx --yes` if the dependency is not supposed to be listed in + `package.json`. +- Use `npx --no` if the dependency is listed in `package.json`. ## Unused exports By default, Knip does not report unused exports of `entry` files. -When unused exports are reported, and you want to keep exporting those, there -are a few options: +The most common causes for unused exports include: -- [Ignore exports used in file][17] for exports used internally. -- Individual exports can be [tagged using JSDoc syntax][18]. -- Have the export in or re-exported by an [entry file][2]: - - Add the file to the `entry` file patterns array in the configuration - - Move the export(s) to an entry file - - Re-export the unused export(s) from an entry file - - Add the file to the `exports` field of `package.json` +- [Enumerations][24] +- [External libraries][25] -Use the `--exports` flag to [filter][5] and focus only on issues related to -exports: +Use the `--exports` flag to [filter][10] and focus on issues related to exports: ```sh knip --exports ``` +### Enumerations + +Currently Knip does not consider all exports or enum members referenced when +implicitly referenced in an enumeration like the following example: + + + + + ```ts + import * as Fruits from './fruits.js'; + import { FruitsEnum } from './fruits.js'; + + for (const fruit of Object.values(Fruits)); // Exports are not referenced explicitly + + Object.entries(FruitsEnum); // Members are not referenced explicitly + ``` + + + + + + ```ts + export const apple = 'apple'; + export const orange = 'orange'; + + export enum FruitsEnum { + apple = 'apple', + orange = 'orange', + } + ``` + + + + +See [namepace imports][26] to see what patterns Knip does consider to be used +exports. + ### External libraries Are the exports consumed or imported by an external library, resulting in a -non-standard consumption of your exports? Try the `--include-libs` flag. - -Here's an example: +non-standard consumption of your exports? Here's an example: @@ -309,27 +380,37 @@ Knip does not include external type definitions by default so it won't see the export being referenced. To include the type definitions of external libraries, use the -[--include-libs][19] flag: +[--include-libs][27] flag: ```shell knip --include-libs ``` This comes at a performance and memory penalty, but should give better results -if you need it. This flag is implied when [classMembers][20] are included (that +if you need it. This flag is implied when [classMembers][28] are included (that feature comes with roughly the same performance penalty). -### Non-standard files +### Exclude exports from the report -The exports of non-standard extensions like `.astro`, `.mdx`, `.vue` or -`.svelte` are not available by default. See [compilers][21] for more details on -how to include them. +To exclude unused exports from the report, there are a few options: -### Missing exports? +- [Ignore exports used in file][29] for exports used internally. +- Individual exports can be [tagged using JSDoc syntax][30]. +- Have the export in an entry file: + - Add the file to the `entry` file patterns array in the configuration. + - Move the export(s) to an entry file. + - Add the file to the `exports` field of `package.json` +- Re-export the unused export(s) from an entry file. -Do you expect certain exports in the report, but are they missing? They might be -exported from an entry file. Use [--include-entry-exports][22] to make Knip also -report unused exports in entry files. +## Missing exports? + +Did you expect certain exports in the report, but are they missing? They might +be exported from an entry file. In that case, use [--include-entry-exports][31] +to make Knip also report unused exports in entry files. + +The exports of non-standard extensions like `.astro`, `.mdx`, `.vue` or +`.svelte` are not available by default. See [compilers][32] for more details on +how to include them. ## Class members @@ -340,13 +421,12 @@ knip --include classMembers ``` This option is also available in the Knip configuration file. Note that this -feature comes at a cost: linting will take more time and more memory (in rare -cases it may even run out of memory in large repositories). +feature comes at a cost: linting will take more time and more memory. -Individual class members can be [tagged using JSDoc syntax][18]. +Individual class members can be [tagged using JSDoc syntax][30]. Classes exported from entry files are ignored, and so are their members. Use -[--include-entry-exports][22] to make Knip also report members of unused exports +[--include-entry-exports][31] to make Knip also report members of unused exports in entry files. ## Enum members @@ -358,46 +438,51 @@ members can also be disabled altogether, for example: knip --exclude enumMembers ``` -Individual enum members can be [tagged using JSDoc syntax][18]. +Individual enum members can be [tagged using JSDoc syntax][30]. Enums exported from entry files are ignored, and so are their members. Use -[--include-entry-exports][22] to make Knip also report members of unused exports +[--include-entry-exports][31] to make Knip also report members of unused exports in entry files. -## False positives - -If you believe Knip incorrectly reports something as unused (i.e. a false -positive), this could be caused by one of multiple reasons: - -- Knip requires additional configuration, for instance additional [entry - files][2] or [paths][23] should be added. -- Knip has a bug. Help your own project and Knip by creating a [minimal - reproduction][24] and open an issue on GitHub. - -Also see [troubleshooting][25] if you haven't already. - -[1]: ../overview/configuration.md -[2]: ../explanations/entry-files.md -[3]: ../guides/configuring-project-files.md -[4]: ../features/monorepos-and-workspaces.md -[5]: ../features/rules-and-filters.md#filters -[6]: ./configuring-project-files.md -[7]: ./writing-a-plugin.md -[8]: ../reference/plugins.md -[9]: https://github.com/webpro-nl/knip/issues/483 -[10]: ../explanations/plugins.md#entry-files -[11]: ../explanations/entry-files.md#plugins -[12]: ../features/integrated-monorepos.md -[13]: #unused-files -[14]: #unlisted-binaries -[15]: https://eslint.org/docs/latest/use/configure/configuration -[16]: ../features/monorepos-and-workspaces.md#lint-a-single-workspace -[17]: ../reference/configuration.md#ignoreexportsusedinfile -[18]: ../reference/jsdoc-tsdoc-tags.md -[19]: ../reference/cli#--include-libs -[20]: #class-members -[21]: ../features/compilers.md -[22]: ../reference/configuration.md#includeentryexports -[23]: ../reference/configuration.md#paths -[24]: ../guides/troubleshooting.md#minimal-reproduction -[25]: ./troubleshooting.md +## Feedback or false positives? + +If you believe Knip incorrectly reports something as unused (i.e. there's a +false positive), feel free to create a [minimal reproduction][33] and open an +issue on GitHub. It'll make Knip better for everyone! Join the [Discord +channel][34] to discuss any feedback or questions you may have. + +[1]: #dynamic-import-specifiers +[2]: #unsupported-arguments-in-scripts +[3]: #unsupported-file-formats +[4]: #missing-plugin +[5]: #incomplete-plugin +[6]: #integrated-monorepos +[7]: #build-artifacts-and-ignored-files +[8]: #auto-mocking-or-auto-imports +[9]: ./configuring-project-files.md +[10]: ../features/rules-and-filters.md#filters +[11]: ../features/script-parser.md +[12]: ./writing-a-plugin.md +[13]: ../reference/plugins.md +[14]: https://github.com/webpro-nl/knip/issues/483 +[15]: ../explanations/plugins.md#entry-files +[16]: ../explanations/entry-files.md#plugins +[17]: ../features/integrated-monorepos.md +[18]: #unused-files +[19]: #unreachable-code +[20]: #unlisted-binaries +[21]: https://eslint.org/docs/latest/use/configure/configuration +[22]: + https://github.com/webpro-nl/knip/blob/6f561ff09b4f1bf36585b64210ee34ea27ae04ea/packages/knip/src/constants.ts#L32-L133 +[23]: ../features/monorepos-and-workspaces.md#lint-a-single-workspace +[24]: #enumerations +[25]: #external-libraries +[26]: ../guides/namespace-imports.md +[27]: ../reference/cli#--include-libs +[28]: #class-members +[29]: ../reference/configuration.md#ignoreexportsusedinfile +[30]: ../reference/jsdoc-tsdoc-tags.md +[31]: ../reference/configuration.md#includeentryexports +[32]: ../features/compilers.md +[33]: ../guides/issue-reproduction +[34]: https://discord.gg/r5uXTtbTpc diff --git a/packages/docs/src/content/docs/guides/troubleshooting.md b/packages/docs/src/content/docs/guides/troubleshooting.md index 923777ddd..738e54b96 100644 --- a/packages/docs/src/content/docs/guides/troubleshooting.md +++ b/packages/docs/src/content/docs/guides/troubleshooting.md @@ -6,30 +6,36 @@ sidebar: We can distinguish two types of issues: -- [Issues reported by Knip][1] +- [Lint issues reported by Knip][1] - [Exceptions thrown by Knip][2] -Both of which could be either an issue on your end or with Knip. +Also see the [debug][3] and [trace][4] options below that can help to +troubleshoot issues. -Use [--debug][3] and [--trace][4] to help troubleshoot issues. +## Lint issues reported by Knip -## Issues reported by Knip +Knip reports lint issues in your codebase. See [handling issues][5] to deal with +the reported issues. -This indicates a successful run, but clutter was found. Continue to [handle -issues][5] and deal with the reported clutter. +If Knip reports false positives and you're considering filing a GitHub issue, +please do! It'll make Knip better for everyone. Please read [issue +reproduction][6] first. -If Knip reports false positives and you want to open an issue, please see [issue -reproduction][6]. +Exit code 1 indicates a successful run, but lint issues were found. ## Exceptions thrown by Knip -Knip (or one of its plugins loading a configuration file) may throw an error, -resulting in an unsuccessful run. You might be encountering a [known issue][7]. +Knip may throw an exception, resulting in an unsuccessful run. -Add `--debug` to the command for more error details to better locate the cause -of the error. +See [known issues][7] as it may be listed there and a workaround may be +available. If it isn't clear what's throwing the exception, try another run with +`--debug` to locate the cause of the issue with more details. -Feel free to report bugs, please see [issue reproduction][6]. +If Knip throws an exception and you're considering filing a GitHub issue, please +do! It'll make Knip better for everyone. Please read [issue reproduction][6] +first. + +Exit code 2 indicates an exception was thrown by Knip. ## Debug @@ -51,13 +57,11 @@ This will give a lengthy output, including: ## Trace -Use `--trace` to see where exports are used. +Use `--trace` to see where all exports are used. Or be more specific: - Use `--trace-file [path]` to output this only for the given file. - Use `--trace-export [name]` to output this only for the given export name. - -Use both to be more specific, this is useful e.g. for tracing only the `default` -export of a certain file. +- Use both to trace a specific named or default export of a certain file. This works across re-exports, barrel files and workspaces. Here's an example screenshot: diff --git a/packages/docs/src/content/docs/index.mdx b/packages/docs/src/content/docs/index.mdx index 44ffe0c91..ba272aa7e 100644 --- a/packages/docs/src/content/docs/index.mdx +++ b/packages/docs/src/content/docs/index.mdx @@ -36,13 +36,13 @@ import Contributors from '../../components/Contributors.astro'; - [Find & remove unused files, dependencies and exports][3] + [Find & remove unused files, dependencies and exports][2] - Try Knip on the [playground][2] + Try Knip on the [playground][3] @@ -109,8 +109,8 @@ Special thanks to the wonderful people who have contributed to this project: - [Unused exports][12] [1]: ./sponsors -[2]: ./playground -[3]: ./explanations/why-use-knip.md +[2]: ./explanations/why-use-knip.md +[3]: ./playground [4]: ./guides/troubleshooting.md [5]: https://www.jamesshopland.com [6]: @@ -122,4 +122,3 @@ Special thanks to the wonderful people who have contributed to this project: [10]: https://tech.basemachina.jp/entry/introduction-knip [11]: ./typescript/unused-dependencies.md [12]: ./typescript/unused-exports.md -[13]: ./overview/getting-started.md diff --git a/packages/docs/src/content/docs/overview/configuration.md b/packages/docs/src/content/docs/overview/configuration.md index b66787419..6c5eb48ef 100644 --- a/packages/docs/src/content/docs/overview/configuration.md +++ b/packages/docs/src/content/docs/overview/configuration.md @@ -5,10 +5,8 @@ description: config ## Defaults -Knip has good defaults and aims for "zero config". For best results, Knip might -need some configuration. - -Here's a simplified version of the default configuration: +Knip has good defaults and aims for "zero config". Here's a simplified version +of the default configuration: ```json { @@ -18,8 +16,7 @@ Here's a simplified version of the default configuration: ``` Entry files are the starting point for Knip to find more source files and -external dependencies. The resulting set of used files is matched against the -set of `project` files to determine which files are unused. +external dependencies. :::tip diff --git a/packages/docs/src/content/docs/reference/cli.md b/packages/docs/src/content/docs/reference/cli.md index e12992820..0aa738b70 100644 --- a/packages/docs/src/content/docs/reference/cli.md +++ b/packages/docs/src/content/docs/reference/cli.md @@ -361,13 +361,13 @@ The default exit codes: | Code | Description | | :--: | :--------------------------------------------------------------- | -| `0` | Knip ran successfully, no lint errors | -| `1` | Knip ran successfully, but there is at least one lint error | +| `0` | Knip ran successfully, no lint issues | +| `1` | Knip ran successfully, but there is at least one lint issues | | `2` | Knip did not run successfully due to bad input or internal error | ### `--no-exit-code` -Always exit with code zero (`0`), even when there are lint errors. +Always exit with code zero (`0`), even when there are lint issues. ### `--max-issues` diff --git a/packages/docs/src/content/docs/reference/known-issues.md b/packages/docs/src/content/docs/reference/known-issues.md index 1027cd897..3dbcee59d 100644 --- a/packages/docs/src/content/docs/reference/known-issues.md +++ b/packages/docs/src/content/docs/reference/known-issues.md @@ -2,9 +2,24 @@ title: Known Issues --- -This page contains a list of known issues you might run into when using Knip. +This page contains a list of known issues you might run into when using Knip: -## The CJS build of Vite's Node API is deprecated +- [Exceptions from config files][1] +- [False positives with external libs][2] +- [DefinitelyTyped packages in dependencies][3] +- [Extensionless imports][4] + +## Exceptions from config files + +An exception may be thrown when a Knip plugin loads a JavaScript or TypeScript +configuration file such as `webpack.config.js` or `vite.config.ts`. Knip may +load such files differently, in a different environment, or without certain +environment variables set. + +If it isn't clear what's throwing the exception, try another run with `--debug` +to locate the cause of the issue with more details. + +### The CJS build of Vite's Node API is deprecated ``` The CJS build of Vite's Node API is deprecated. See https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details. @@ -14,10 +29,10 @@ Only a warning, but can be suppressed by setting the `VITE_CJS_IGNORE_WARNING` environment variable: ``` -VITE_CJS_IGNORE_WARNING=true knip +VITE_CJS_IGNORE_WARNING=1 knip ``` -## Config files using ESM features +### Config files using ESM features Knip may fail when a plugin tries to load a TypeScript configuration file (e.g. `vite.config.ts`) with an error message like one of these: @@ -36,7 +51,7 @@ TypeError: Reflect.metadata is not a function Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in [...]/node_modules/estree-walker/package.json ``` -This is caused by Knip using [jiti][1] to load and execute TypeScript +This is caused by Knip using [jiti][5] to load and execute TypeScript configuration files that contains ESM syntax (such as top-level await), which may incorrectly consider it as CommonJS (instead of not transforming ESM). @@ -45,17 +60,17 @@ Potential workarounds: - Turn the configuration file from TS into JS (e.g. `vitest.config.ts` → `vitest.config.js`). Knip loads modules directly using native `import()` calls. -- Use Bun with [knip-bun][2]. -- [Disable the plugin][3] (not recommended, try the other options first). +- Use Bun with [knip-bun][6]. +- [Disable the plugin][7] (not recommended, try the other options first). Use `knip --debug` in a monorepo to help locate where the error is coming from. -Issues like [#72][4] and [#194][5] are hopefully fixed in [jiti v2][6]. By the +Issues like [#72][8] and [#194][9] are hopefully fixed in [jiti v2][10]. By the way, nothing but love for jiti (it's awesome). -[GitHub Issue #565][7] +[GitHub Issue #565][11] -## Path aliases in config files +### Path aliases in config files Loading the configuration file (e.g. `cypress.config.ts`) for one of Knip's plugins may give an error: @@ -73,41 +88,46 @@ the configuration file. Unfortunately jiti does not seem to support this. Potential workarounds: -- Rewrite the import the configuration to a relative import. -- Use Bun with [knip-bun][2]. -- [Disable the plugin][3] (not recommended, try the other options first). +- Rewrite the import in the configuration file to a relative import. +- Use Bun with [knip-bun][6]. +- [Disable the plugin][7] (not recommended, try the other options first). ## False positives with external libs Knip may report false positives when exports are consumed by external libraries. -Please see [external libs][8]. +Please see [external libs][12]. ## Definitely Typed packages in `dependencies` Knip is strict in the divide between `dependencies` and `devDependencies`. Some -projects are published with one or more DT packages bundled. Knip does not make -exceptions for such DT packages (`@types/*`) listed in `dependencies`. +packages are published with one or more DT packages bundled (i.e. listed in +`dependencies`). Knip does not make exceptions for such type packages +(`@types/*`) and expects them in `devDependencies`. ## Extensionless imports -Knip does not support extensionless imports for non-standard extensions, such as -for `.svg` files. Bundlers like Webpack may support this, but Knip does not. -Examples: +Knip does not support extensionless imports for some non-standard extensions, +such as for `.svg` files. Bundlers like Webpack may support this, but Knip does +not. Examples: ```ts title="App.vue" import Component from './Component'; // → Should resolve to ./Component.vue import ArrowIcon from '../icons/Arrow'; // → Does NOT resolve to ../icons/Arrow.svg ``` -The recommendation is to add the extension when importing such files, similar to -how standard ES Modules work. - -[1]: https://github.com/unjs/jiti -[2]: ./cli.md#knip-bun -[3]: ./configuration.md#plugins -[4]: https://github.com/unjs/jiti/issues/72 -[5]: https://github.com/unjs/jiti/issues/194 -[6]: https://github.com/unjs/jiti/issues/174 -[7]: https://github.com/webpro-nl/knip/issues/565 -[8]: ../guides/handling-issues.mdx#external-libraries +The recommendation is to always add the extension when importing such files, +similar to how standard ES Modules work. + +[1]: #exceptions-from-config-files +[2]: #false-positives-with-external-libs +[3]: #definitely-typed-packages-in-dependencies +[4]: #extensionless-imports +[5]: https://github.com/unjs/jiti +[6]: ./cli.md#knip-bun +[7]: ./configuration.md#plugins +[8]: https://github.com/unjs/jiti/issues/72 +[9]: https://github.com/unjs/jiti/issues/194 +[10]: https://github.com/unjs/jiti/issues/174 +[11]: https://github.com/webpro-nl/knip/issues/565 +[12]: ../guides/handling-issues.mdx#external-libraries diff --git a/packages/docs/src/styles/content.css b/packages/docs/src/styles/content.css index 198c290fa..3c8ea68f9 100644 --- a/packages/docs/src/styles/content.css +++ b/packages/docs/src/styles/content.css @@ -121,3 +121,7 @@ section.plugins li { border: 1px solid var(--sl-color-orange); margin-top: 2rem; } + +.sl-markdown-content .starlight-aside { + margin-top: 2rem; +}