Instruct users to import tidewave conditionally in dev mode

Author: jonatanklosko

README.md

@@ -53,9 +53,10 @@ Add `tidewave[flask]` as a dependency to your `pyproject.toml`:
 Now, in your application definition, you can initialize the `Tidewave` class and pass your Flask application to `init_app`:
 
 ```python
-from tidewave.flask import Tidewave
-tidewave = Tidewave()
-tidewave.init_app(app)
+if app.debug:
+    from tidewave.flask import Tidewave
+    tidewave = Tidewave()
+    tidewave.init_app(app)
 ```
 
 Tidewave will automatically detect if your Flask application is using SQLAlchemy and Jinja2 and configure them automatically.
@@ -80,20 +81,24 @@ Add `tidewave[fastapi]` as a dependency to your `pyproject.toml`:
 "tidewave[fastapi] @ git+https://github.com/tidewave-ai/tidewave_python.git",
 ```
 
-Now, in your application definition, you can initialize the `Tidewave` class and pass your FastAPI application to `install`:
+Now, in your application definition, you can initialize the `Tidewave` class and pass your FastAPI application to `install`. Note that you only want to do this in **development mode**:
 
 ```python
-from tidewave.fastapi import Tidewave
-tidewave = Tidewave()
-tidewave.install(app)
-```
+# Your preferable way of detecting dev mode.
+is_dev = os.environ.get("RUN_MODE", None) == "development"
 
-Note Tidewave only runs when `app.debug` is `True`. Therefore, remember to start your dev server with `fastapi dev`. If you are setting `app.debug` programatically, remember to do so before you call `tidewave.install`.
+if is_dev:
+    from tidewave.fastapi import Tidewave
+    tidewave = Tidewave()
+    tidewave.install(app)
+```
 
-If you are using Jinja2, you need to add our extension too (preferably in `app.debug` mode only):
+If you are using Jinja2, you need to add our extension too:
 
 ```python
-if app.debug:
+if is_dev:
+    # ...
+
     from tidewave.jinja2 import Extension
     templates.env.add_extension(Extension)
 ```

src/tidewave/fastapi/__init__.py

@@ -29,9 +29,6 @@ def __init__(self, config: Optional[dict[str, Any]] = None):
         self.config = config or {}
 
     def install(self, app: FastAPI, sqlalchemy_base=None, sqlalchemy_engine=None):
-        if not app.debug:
-            return
-
         # Create WSGI app for MCP handling
         def wsgi_app(environ, start_response):
             start_response("404 Not Found", [("Content-Type", "text/plain")])

src/tidewave/flask/__init__.py

@@ -27,7 +27,9 @@ def __init__(self, config: Optional[dict[str, Any]] = None):
 
     def init_app(self, app):
         if not app.debug:
-            return
+            raise RuntimeError(
+                "You should only call Tidewave.init_app in development, but app.debug=False."
+            )
 
         # Create MCP tools
         mcp_tools = [

tests/test_fastapi.py

@@ -18,7 +18,7 @@ class TestFastAPITidewave(unittest.TestCase):
 
     def test_with_debug_mode(self):
         """Test that Tidewave initializes properly with FastAPI app in debug mode"""
-        app = FastAPI(debug=True)
+        app = FastAPI()
 
         @app.get("/test")
         def test_route():
@@ -52,32 +52,9 @@ def test_route():
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.json(), {"message": "Test response"})
 
-    def test_with_production_mode(self):
-        """Test that Tidewave does not initialize middleware in production mode"""
-        app = FastAPI(debug=False)  # Production mode
-
-        @app.get("/test")
-        def test_route():
-            return {"message": "Test response"}
-
-        tidewave = Tidewave()
-        tidewave.install(app)
-
-        # Verify middleware was NOT applied (no tidewave routes should be mounted)
-        tidewave_routes = [
-            route for route in app.routes if hasattr(route, "path") and "tidewave" in route.path
-        ]
-        self.assertEqual(len(tidewave_routes), 0)
-
-        # Test that the app still works normally
-        client = TestClient(app)
-        response = client.get("/test")
-        self.assertEqual(response.status_code, 200)
-        self.assertEqual(response.json(), {"message": "Test response"})
-
     def test_x_frame_options_and_csp_headers(self):
         """Test that X-Frame-Options and CSP headers"""
-        app = FastAPI(debug=True)
+        app = FastAPI()
 
         @app.get("/test")
         def test_route():
@@ -107,7 +84,7 @@ def test_route():
 
     def test_with_sqlalchemy(self):
         """Test that SQLAlchemy tools are added when SQLAlchemy parameters are provided"""
-        app = FastAPI(debug=True)
+        app = FastAPI()
 
         # Create SQLAlchemy setup
         engine = create_engine("sqlite:///:memory:")

tests/test_flask.py

@@ -6,6 +6,7 @@
 
 from flask import Flask, render_template_string
 
+import pytest
 from flask_sqlalchemy import SQLAlchemy
 
 from tidewave.flask import Tidewave
@@ -61,7 +62,9 @@ def test_route():
             return render_template_string(template)
 
         tidewave = Tidewave()
-        tidewave.init_app(app)
+
+        with pytest.raises(RuntimeError):
+            tidewave.init_app(app)
 
         # Verify middleware was NOT applied (wsgi_app should still be original type)
         self.assertEqual(type(app.wsgi_app).__name__, original_wsgi_app_type)