Edit FAQ

packages/docs/src/content/docs/reference/faq.md

@@ -19,10 +19,10 @@ do.
 
 ### Why does Knip have plugins?
 
-Plugins are an essential part of Knip. They save a lot of configuration out of
-the box by adding entry files as accurately as possible and only for the tools
-actually installed. Yet the real magic is in their custom parsers for
-configuration files.
+Plugins are an essential part of Knip. They prevent you from a lot of
+configuration out of the box, by adding entry files as accurately as possible
+and only for the tools actually installed. Yet the real magic is in their custom
+parsers for configuration files.
 
 For instance, Vitest has the `environment` configuration option. The Vitest
 plugin knows `"node"` is the default value for `environment` which does not
@@ -37,8 +37,6 @@ point to a file in another workspace in the same monorepo, e.g.
 `setupFiles: ['@org/shared/jest-setup.ts']`. Those entry files may also contain
 imports of internal modules or external dependencies, and so on.
 
-With an easy-to-use plugin API, many plugins have been created by contributors.
-
 ### Why is Knip so heavily engineered?
 
 Even though I love the Unix philosophy, at this point I believe for Knip it
@@ -48,12 +46,12 @@ Building up the module and dependency graph requires non-standard module
 resolution and not only static but also dynamic analysis (i.e. actually load and
 execute modules), such as for parsers of plugins to receive the exported value
 of dynamic tooling configuration files. Additionally, [exports consumed by
-external libraries][6] require type information, as supported by the TypeScript
+external libraries][1] require type information, as supported by the TypeScript
 backend.
 
 The rippling effect of plugins and recursively adding entry files and
-dependencies to build up this graph - as answered with the previous question -
-is also exactly what's meant by ["comprehensive" here][7].
+dependencies to build up the graph is also exactly what's meant by
+["comprehensive" here][2].
 
 ## Building the graph
 
@@ -143,12 +141,12 @@ seem to meet all requirements to be usable on its own by Knip:
   `module.js`
 
 A few strategies have been tried and tweaked, and Knip currently uses a
-combination of [enhanced-resolve][1], the TypeScript module resolver and a few
+combination of [enhanced-resolve][3], the TypeScript module resolver and a few
 customizations. This single custom module resolver function is hooked into the
 TypeScript compiler and language service hosts.
 
 Everything else outside the dependency graph is handled by `enhanced-resolve`
-when doing things like [script parsing][2] and resolving references to files in
+when doing things like [script parsing][4] and resolving references to files in
 other workspaces.
 
 ### How does Knip handle non-standard import syntax?
@@ -174,14 +172,13 @@ A workspace is a directory with a `package.json` file. They're configured in
 `package.json` file, but is not a workspace (from a package manager
 perspective), it can be added as a workspace to the Knip configuration.
 
-Projects - in the context of TypeScript - are basically directories with a
-`tsconfig.json` file. They're not a concept in Knip.
+Projects - in the context of TypeScript - are directories with a `tsconfig.json`
+file. They're not a concept in Knip.
 
 A TypeScript program has a 1-to-1 relationship with workspaces if they're
 analyzed in isolation. However, by default Knip optimizes for performance and
-utilizes [workspace sharing](../guides/performance.md#workspace-sharing). That's
-why debug output contains messages like "Installed 2 programs for 29
-workspaces".
+utilizes [workspace sharing][5]. That's why debug output contains messages like
+"Installed 2 programs for 29 workspaces".
 
 ### Why doesn't Knip match my TypeScript project structure?
 
@@ -205,28 +202,32 @@ have it handled as a separate workspace.
 
 ### Why doesn't Knip analyze workspaces in isolation by default?
 
-Knip creates TypeScript programs to create a dependency graph and traverse the
-AST. In a monorepo, it would make a lot of sense to create one program per
+Knip creates TypeScript programs to create a module graph and traverse file
+ASTs. In a monorepo, it would make a lot of sense to create one program per
 workspace. However, memory usage (and duration) goes through the roof quickly
 when one program per workspace is created, sometimes even crashing Node.js.
-That's why Knip shares a single program for workspaces if their configuration
-allows it. This optimization is enabled by default, while it also allows the
-module resolver (one per program) to do some more caching.
+That's why Knip shares the files of multiple workspaces in a single program if
+their configuration allows it. This optimization is enabled by default, while it
+also allows the module resolver (one per program) to do some more caching.
 
-This can be disabled using the `--isolate-workspaces` flag, but is rarely
-necessary in practice.
+This can be disabled using the `--isolate-workspaces` flag (rarely necessary in
+practice).
 
-Also see [workspace sharing][3] (and [Slim down to speed up][4] for full
+Also see [workspace sharing][5] (and [Slim down to speed up][6] for full
 history).
 
 ### Why doesn't Knip just use `ts.findReferences`?
 
 TypeScript has a very good "Find references" feature, that you might be using in
 your IDE as well. Yet at scale this becomes too slow. That's why Knip builds up
-its own module graph to look up export usage a lot faster.
+its own module graph to look up export usages. The added benefit is that this
+comprehensive graph is serializable (and thus cacheable) and potentially usable
+for other tools to build upon as well.
 
 Knip does use `ts.findReferences` to find references to class members (i.e. when
-`classMembers` is enabled).
+the issue type `classMembers` is included). In case analysis of exports requires
+type information of external dependencies, the [`--include-libs ` flag][1] will
+trigger the same.
 
 ### Why can't I use path aliases to reference other workspaces?
 
@@ -292,7 +293,7 @@ other file types.
 Knip comes with basic "compilers" for a few common non-standard file types.
 They're not actual compilers, they're regular expressions only to extract import
 statements. Override the built-in Vue "compiler" with the real one in your
-project. Also see the answer to the previous question and [Compilers][8].
+project. Also see the answer to the previous question and [Compilers][7].
 
 ## Miscellaneous
 
@@ -322,7 +323,7 @@ Which mode should've been the default? They both have their merits:
   tooling, including most issues found in production mode. This mode has the
   most impact on DX, for the same reason.
 
-Also see [production mode][9].
+Also see [production mode][8].
 
 ### Why doesn't Knip have...?
 
@@ -339,15 +340,14 @@ extend Knip include:
 
 These are all interesting ideas, but do increase the API surface area. This
 would mean more development efforts and maintenance. Time is limited and
-[sponsorships][10] currently don't cover - this can change though!
-
-[1]: https://www.npmjs.com/package/enhanced-resolve
-[2]: #parser
-[3]: ../guides/performance.md#workspace-sharing
-[4]: ../blog/slim-down-to-speed-up.md
-[5]: ../explanations/entry-files.md#default-entry-file-patterns
-[6]: ../guides/handling-issues.mdx#external-libraries
-[7]: ../explanations/why-use-knip.md#comprehensive
-[8]: ../features/compilers.md
-[9]: ../features/production-mode.md
-[10]: /sponsors
+[sponsorships][9] currently don't cover - this can change though!
+
+[1]: ../guides/handling-issues.mdx#external-libraries
+[2]: ../explanations/why-use-knip.md#comprehensive
+[3]: https://www.npmjs.com/package/enhanced-resolve
+[4]: #parser
+[5]: ../guides/performance.md#workspace-sharing
+[6]: ../blog/slim-down-to-speed-up.md
+[7]: ../features/compilers.md
+[8]: ../features/production-mode.md
+[9]: /sponsors