fix: re-add dev only export + add warning + docs around tree shaking (#186)

* fix: re-add dev only export

* refactor: add warning + docs around tree-shaking

Author: arjunvegda

README.md

@@ -122,9 +122,8 @@ type DevToolsProps = {
 ### Provider-less
 
 ```tsx
-import { DevTools } from 'jotai-devtools';
+import { DevTools } from './JotaiDevTools';
 import 'jotai-devtools/styles.css';
-
 const App = () => {
   return (
     <>
@@ -139,6 +138,7 @@ const App = () => {
 
 ```tsx
 import { createStore } from 'jotai';
+
 import { DevTools } from 'jotai-devtools';
 import 'jotai-devtools/styles.css';
 
@@ -154,6 +154,73 @@ const App = () => {
 };
 ```
 
+## Tree-shaking
+
+Jotai DevTools is currently only available in development mode. We're changing
+this in the future to allow it to be used in production as well.
+
+Therefore, we recommend wrapping the DevTools in a conditional statement and
+tree-shake it out in production to avoid any accidental usage in production.
+
+### Vite
+
+```tsx
+import { DevTools } from 'jotai-devtools';
+import css from 'jotai-devtools/styles.css?inline';
+
+const JotaiDevTools = () =>
+  process.env.NODE_ENV !== 'production' ? (
+    <>
+      <style>{css}</style>
+      <DevTools />
+    </>
+  ) : null;
+
+const App = () => {
+  return (
+    <>
+      <JotaiDevTools />
+      {/* your app */}
+    </>
+  );
+};
+```
+
+### NextJS
+
+Create a `DevTools.tsx` file in your project and export the `DevTools`
+component.
+
+```tsx
+import 'jotai-devtools/styles.css';
+export { DevTools } from 'jotai-devtools';
+```
+
+Then, in your app, import the `DevTools` component conditionally.
+
+```tsx
+import dynamic from "next/dynamic";
+import type { ComponentType } from "react";
+import type { DevToolsProps } from "jotai-devtools";
+
+let DevTools: ComponentType<DevToolsProps> | null = null;
+
+if (process.env.NODE_ENV !== "production") {
+  DevTools = dynamic(
+    () => import("./DevTools").then((mod) => ({ default: mod.DevTools })),
+    { ssr: false }
+  );
+}
+
+const App = () => {
+  return (
+    <>
+      {DevTools && <DevTools />}
+      {/* your app */}
+    </>
+  );
+```
+
 ## Hooks
 
 Detailed documentation is available on

src/DevTools/DevTools.tsx

@@ -126,10 +126,17 @@ const DevToolsProvider = ({ children }: React.PropsWithChildren) => {
   );
 };
 
-export const DevTools = (props: DevToolsProps): JSX.Element | null => {
-  return (
-    <DevToolsProvider>
-      <DevToolsMain {...props} />
-    </DevToolsProvider>
-  );
+export const InternalDevTools = (props: DevToolsProps): JSX.Element | null => {
+  if (__DEV__) {
+    console.warn(
+      "[jotai-devtools]: automatic tree-shaking in development mode is being deprecated. Make sure to tree-shake it out in your applications if you don't want it in production.\n\nFor more information, see https://github.com/jotaijs/jotai-devtools",
+    );
+    return (
+      <DevToolsProvider>
+        <DevToolsMain {...props} />
+      </DevToolsProvider>
+    );
+  }
+
+  return <></>;
 };

src/index.ts

@@ -1,4 +1,11 @@
 export type { DevToolsProps } from './DevTools';
-export { DevTools } from './DevTools';
+import { InternalDevTools } from './DevTools';
+
+// This is a workaround to make DevTools tree-shakable in production builds
+// This is due to a limitation in tsup where it does not support preserving signatures
+// of exports or generating separate chunks for exports
+export const DevTools: typeof InternalDevTools = __DEV__
+  ? InternalDevTools
+  : () => null;
 
 export * from './utils';

tsup.config.ts

@@ -19,6 +19,8 @@ const baseConfig: Options = {
   // Outputs `dist/index.js` and `dist/utils.js`
   entry: {
     index: 'src/index.ts',
+    // Workaround to generate seperate chunks for DevTools so we could export a null component for production builds
+    internal__devtools: 'src/DevTools/index.ts',
     utils: 'src/utils/index.ts',
   },
   loader: {