Skip to content
Source
Sign inSign up
TanStack/devtools
Open History to see the last commit

production.md

98 lines3.7 KB

1---
2title: Production
3id: production
4---
5​
6​
7The whole point of devtools is to help you during development, so it's generally not recommended to include them in production builds, but if you know what you're doing, you can.
8​
9​
10## Vite Plugin Configuration
11​
12The default behavior of the Vite plugin is to remove all devtools related code from the production build. This is usually what you want, but if you want to keep the devtools in production (not recommended) you can set the `removeDevtoolsOnBuild` option to `false`.
13​
14```ts
15import { devtools } from '@tanstack/devtools-vite'
16​
17export default {
18 plugins: [
19 devtools({
20 removeDevtoolsOnBuild: false
21 }),
22 // ... rest of your plugins here
23 ],
25```
26​
27This will include the devtools and all it's plugins in the production build.
28​
29## Excluding Devtools from Production on non-vite projects
30​
31If you're running devtools in a non-vite project you will have to manually exclude the devtools from your production build. You can do this by using environment variables or any other method you prefer.
32​
33We would recommend you create a separate file for the devtools import and then conditionally import that file in your main application file depending on the environment.
34​
35Here's an example using environment variables:
36​
37```tsx
38// devtools-setup.tsx
39import { TanStackDevtools } from '@tanstack/react-devtools'
40​
41export default function Devtools(){
42 return <TanStackDevtools plugins={[
43 // Add your custom plugins here
44 ]} />
46​
47// App.tsx
48const Devtools = process.env.NODE_ENV === 'development' ? await import('./devtools-setup') : () => null
49​
50function App() {
51 return (
52 <>
53 <YourApp />
54 <Devtools />
55 </>
56 )
58```
59​
60## Event client in production
61​
62By default the **root import** of `@tanstack/devtools-event-client` no-ops
63outside development. When your bundler sets `process.env.NODE_ENV` to anything
64other than `'development'`, the real client is replaced by a no-op and
65tree-shaken out of your production bundle:
66​
67```ts
68// dev: real client β€” production: no-op (tree-shaken away)
69import { EventClient } from '@tanstack/devtools-event-client'
70```
71​
72If you are an open-source author who deliberately wants devtools events in
73production, import the real client from the `/production` subpath instead. It is
74never stripped:
75​
76```ts
77// always the real client, in every environment
78import { EventClient } from '@tanstack/devtools-event-client/production'
79```
80​
81The public API is identical between the two imports β€” only the production
82runtime behavior differs.
83​
84This is independent of the Vite plugin's `removeDevtoolsOnBuild` option β€” the event client strips itself based on `NODE_ENV`, whether or not you use the Vite plugin.
85​
86## Where to install the Devtools
87​
88If you are using the devtools in development only, you can install them as a development dependency and only import them in development builds. This is the default recommended way to use the devtools.
89​
90If you are using the devtools in production, you need to install them as a regular dependency and import them in your application code.
91​
92This depends on if you are shedding development dependencies in production or not, but generally it's recommended to install them as a regular dependency if you are using them in production.
93​
94## Development / Production workflow
95​
96For Development, you can install the devtools as a development dependency and import them in your application code. The Vite plugin will take care of stripping them out of the production build.
97​
98For Production, you can install the devtools as a regular dependency and import them in your application code using the `/production` sub-export and then you also need to set `removeDevtoolsOnBuild` to `false` in the Vite plugin configuration.