feat(angular-query-devtools): move devtools to conditional sub-paths, improves tree shaking and dependency injection

Author: arnoud-dv

.github/labeler.yml

@@ -1,5 +1,3 @@
-'package: angular-query-devtools-experimental':
-  - 'packages/angular-query-devtools-experimental/**/*'
 'package: angular-query-experimental':
   - 'packages/angular-query-experimental/**/*'
 'package: eslint-plugin-query':

codecov.yml

@@ -19,10 +19,6 @@ comment:
 
 component_management:
   individual_components:
-    - component_id: angular-query-devtools-experimental
-      name: '@tanstack/angular-query-devtools-experimental'
-      paths:
-        - packages/angular-query-devtools-experimental/**
     - component_id: angular-query-experimental
       name: '@tanstack/angular-query-experimental'
       paths:

docs/framework/angular/devtools.md

@@ -7,27 +7,38 @@ title: Devtools
 
 The devtools help you debug and inspect your queries and mutations. You can enable the devtools by adding `withDevtools` to `provideTanStackQuery`.
 
-By default, the devtools are enabled when Angular [`isDevMode`](https://angular.dev/api/core/isDevMode) returns true. So you don't need to worry about excluding them during a production build. The core tools are lazily loaded and excluded from bundled code. In most cases, all you'll need to do is add `withDevtools()` to `provideTanStackQuery` without any additional configuration.
+By default, Angular Query Devtools are only included in development mode bundles, so you don't need to worry about excluding them during a production build.
 
 ```ts
 import {
   QueryClient,
   provideTanStackQuery,
-  withDevtools,
 } from '@tanstack/angular-query-experimental'
 
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
+
 export const appConfig: ApplicationConfig = {
   providers: [provideTanStackQuery(new QueryClient(), withDevtools())],
 }
 ```
 
-## Configuring if devtools are loaded
+## Devtools in production
+
+Devtools are automatically excluded from production builds. However, it might be desirable to lazy load the devtools in production.
+
+To use `withDevtools` in production builds, import using the `production` sub-path. The function exported from the production subpath is identical to the main one, but won't be excluded from production builds.
+
+```ts
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'
+```
 
-If you need more control over when devtools are loaded, you can use the `loadDevtools` option. This is particularly useful if you want to load devtools based on environment configurations. For instance, you might have a test environment running in production mode but still require devtools to be available.
+To control when devtools are loaded, you can use the `loadDevtools` option. This is particularly useful if you want to load devtools based on environment configurations or user interaction. For instance, you might have a test environment running in production mode but still require devtools to be available.
 
-When not setting the option or setting it to 'auto', the devtools will be loaded when Angular is in development mode.
+When not setting the option or setting it to 'auto', the devtools will be loaded automatically when Angular runs in development mode.
 
 ```ts
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
+
 provideTanStackQuery(new QueryClient(), withDevtools())
 
 // which is equivalent to
@@ -39,7 +50,12 @@ provideTanStackQuery(
 
 When setting the option to true, the devtools will be loaded in both development and production mode.
 
+This is particularly useful if you want to load devtools based on environment configurations. E.g. you could set this to true either when `isDevMode()` is true or when the application is running on your production build staging environment.
+
 ```ts
+// Make sure to use the production sub-path to load devtools in production builds
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'
+
 provideTanStackQuery(
   new QueryClient(),
   withDevtools(() => ({ loadDevtools: true })),
@@ -55,44 +71,67 @@ provideTanStackQuery(
 )
 ```
 
-The `withDevtools` options are returned from a callback function to support reactivity through signals. In the following example
-a signal is created from a RxJS observable that listens for a keyboard shortcut. When the event is triggered, the devtools are lazily loaded.
-Using this technique allows you to support on-demand loading of the devtools even in production mode, without including the full tools in the bundled code.
+## Derive options through reactivity
+
+Options are passed to `withDevtools` from a callback function to support reactivity through signals. In the following example
+a signal is created from a RxJS observable that emits on a keyboard shortcut. When the derived signal is set to true, the devtools are lazily loaded.
+
+> If you don't need devtools in production builds, don't use the `production` sub-path. Even though most of the devtools are lazy loaded on-demand, code is needed for on-demand loading and option handling. When importing devtools from `@tanstack/angular-query-experimental/devtools`, all devtools code will be excluded from your build and no lazy chunks will be created, minimizing deployment size.
+
+The example below always loads devtools in development mode and loads on-demand in production mode when a keyboard shortcut is pressed.
 
 ```ts
+import { Injectable, isDevMode } from '@angular/core'
+import { fromEvent, map, scan } from 'rxjs'
+import { toSignal } from '@angular/core/rxjs-interop'
+
 @Injectable({ providedIn: 'root' })
-class DevtoolsOptionsManager {
+export class DevtoolsOptionsManager {
   loadDevtools = toSignal(
     fromEvent<KeyboardEvent>(document, 'keydown').pipe(
       map(
         (event): boolean =>
           event.metaKey && event.ctrlKey && event.shiftKey && event.key === 'D',
       ),
-      scan((acc, curr) => acc || curr, false),
+      scan((acc, curr) => acc || curr, isDevMode()),
     ),
     {
-      initialValue: false,
+      initialValue: isDevMode(),
     },
   )
 }
+```
+
+If you want to use an injectable such as a service in the callback you can use `deps`. The injected value will be passed as parameter to the callback function.
+
+This is similar to `deps` in Angular's [`useFactory`](https://angular.dev/guide/di/dependency-injection-providers#factory-providers-usefactory) provider.
+
+```ts
+// ...
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools/production'
 
 export const appConfig: ApplicationConfig = {
   providers: [
     provideHttpClient(),
     provideTanStackQuery(
       new QueryClient(),
-      withDevtools(() => ({
-        initialIsOpen: true,
-        loadDevtools: inject(DevtoolsOptionsManager).loadDevtools(),
-      })),
+      withDevtools(
+        (devToolsOptionsManager: DevtoolsOptionsManager) => ({
+          loadDevtools: devToolsOptionsManager.loadDevtools(),
+        }),
+        {
+          // `deps` is used to inject and pass `DevtoolsOptionsManager` to the `withDevtools` callback.
+          deps: [DevtoolsOptionsManager],
+        },
+      ),
     ),
   ],
 }
 ```
 
-### Options
+### Options returned from the callback
 
-Of these options `client`, `position`, `errorTypes`, `buttonPosition`, and `initialIsOpen` support reactivity through signals.
+Of these options `loadDevtools`, `client`, `position`, `errorTypes`, `buttonPosition`, and `initialIsOpen` support reactivity through signals.
 
 - `loadDevtools?: 'auto' | boolean`
   - Defaults to `auto`: lazily loads devtools when in development mode. Skips loading in production mode.

docs/framework/angular/reference/functions/withdevtools.md

@@ -6,7 +6,7 @@ title: withDevtools
 # Function: withDevtools()
 
 ```ts
-function withDevtools(withDevtoolsFn?): DeveloperToolsFeature
+function withDevtools(withDevtoolsFn?): DevtoolsFeature
 ```
 
 Enables developer tools.
@@ -35,7 +35,7 @@ A function that returns `DevtoolsOptions`.
 
 ## Returns
 
-[`DeveloperToolsFeature`](../../type-aliases/developertoolsfeature.md)
+[`DevtoolsFeature`](../../type-aliases/developertoolsfeature.md)
 
 A set of providers for use with `provideTanStackQuery`.
 

docs/framework/angular/reference/index.md

@@ -35,7 +35,7 @@ title: '@tanstack/angular-query-experimental'
 - [DefinedCreateQueryResult](../type-aliases/definedcreatequeryresult.md)
 - [DefinedInitialDataInfiniteOptions](../type-aliases/definedinitialdatainfiniteoptions.md)
 - [DefinedInitialDataOptions](../type-aliases/definedinitialdataoptions.md)
-- [DeveloperToolsFeature](../type-aliases/developertoolsfeature.md)
+- [DevtoolsFeature](../type-aliases/developertoolsfeature.md)
 - [PersistQueryClientFeature](../type-aliases/persistqueryclientfeature.md)
 - [QueriesOptions](../type-aliases/queriesoptions.md)
 - [QueriesResults](../type-aliases/queriesresults.md)

docs/framework/angular/reference/type-aliases/developertoolsfeature.md

@@ -1,12 +1,12 @@
 ---
-id: DeveloperToolsFeature
-title: DeveloperToolsFeature
+id: DevtoolsFeature
+title: DevtoolsFeature
 ---
 
-# Type Alias: DeveloperToolsFeature
+# Type Alias: DevtoolsFeature
 
 ```ts
-type DeveloperToolsFeature = QueryFeature<'DeveloperTools'>
+type DevtoolsFeature = QueryFeature<'DeveloperTools'>
 ```
 
 A type alias that represents a feature which enables developer tools.

docs/framework/angular/reference/type-aliases/queryfeatures.md

@@ -6,7 +6,7 @@ title: QueryFeatures
 # Type Alias: QueryFeatures
 
 ```ts
-type QueryFeatures = DeveloperToolsFeature | PersistQueryClientFeature
+type QueryFeatures = DevtoolsFeature | PersistQueryClientFeature
 ```
 
 A type alias that represents all Query features available for use with `provideTanStackQuery`.

examples/angular/auto-refetching/src/app/app.config.ts

@@ -6,8 +6,8 @@ import {
 import {
   QueryClient,
   provideTanStackQuery,
-  withDevtools,
 } from '@tanstack/angular-query-experimental'
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
 import { mockInterceptor } from './interceptor/mock-api.interceptor'
 import type { ApplicationConfig } from '@angular/core'
 

examples/angular/basic-persister/src/app/app.config.ts

@@ -2,10 +2,10 @@ import { provideHttpClient, withFetch } from '@angular/common/http'
 import {
   QueryClient,
   provideTanStackQuery,
-  withDevtools,
 } from '@tanstack/angular-query-experimental'
 import { withPersistQueryClient } from '@tanstack/angular-query-persist-client'
 import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
 import type { ApplicationConfig } from '@angular/core'
 
 const localStoragePersister = createSyncStoragePersister({

examples/angular/basic/src/app/app.config.ts

@@ -2,8 +2,8 @@ import { provideHttpClient, withFetch } from '@angular/common/http'
 import {
   QueryClient,
   provideTanStackQuery,
-  withDevtools,
 } from '@tanstack/angular-query-experimental'
+import { withDevtools } from '@tanstack/angular-query-experimental/devtools'
 import type { ApplicationConfig } from '@angular/core'
 
 export const appConfig: ApplicationConfig = {