feat(devtools): ability to change ports and domains in devtools server

.changeset/bright-dryers-march.md

@@ -0,0 +1,5 @@
+---
+"@refinedev/core": patch
+---
+
+Bump `@refinedev/devtools-internal` dependency to reflect the latest changes in the Refine Devtools.

.changeset/shiny-planes-obey.md

@@ -0,0 +1,11 @@
+---
+"@refinedev/cli": patch
+---
+
+fix(cli): avoid polluting `process.env` with unwanted environment variables
+
+Previously, the `@refinedev/cli` used `dotenv` to load environment variables from `.env` files and populate `process.env`. This caused issues when the users app has a different convention for environment variables, e.g. `.env.development`, `.env.production`, etc.
+
+Now, the `@refinedev/cli` will read the file but avoid populating `process.env` with the variables and keep the values in its scope without passing them to the child processes. This will prevent unwanted environment variables from being passed to the child processes and avoid conflicts with the user's environment variables.
+
+[Resolves #5803](https://github.com/refinedev/refine/issues/5803)

.changeset/twenty-months-bathe.md

@@ -0,0 +1,26 @@
+---
+"@refinedev/cli": patch
+"@refinedev/devtools-server": minor
+"@refinedev/devtools-shared": minor
+"@refinedev/devtools-ui": minor
+"@refinedev/devtools": minor
+"@refinedev/devtools-internal": minor
+---
+
+feat(devtools): ability to change the port of the devtools server
+
+Now users can change the port of the devtools server by setting the `REFINE_DEVTOOLS_PORT` environment variable. Previously, the port was hardcoded to "5001" and could not be changed.
+
+If you're using `@refinedev/cli`'s runner commands to start your development server, `REFINE_DEVTOOLS_PORT` will be propagated to your app with appropriate prefix. E.g. if you're using Vite, the environment variable will be `VITE_REFINE_DEVTOOLS_PORT` and it will be used by the `@refinedev/devtools`'s `<DevtoolsProvider />` component to connect to the devtools server.
+
+- In Next.js apps, it will be prefixed with `NEXT_PUBLIC_`
+- In Craco and Create React App apps, it will be prefixed with `REACT_APP_`
+- In Remix apps and other custom setups, the environment variable will be used as is.
+
+In some scenarios where the environment variables are not passed to the browser, you may need to manually set the Refine Devtools URL in the `<DevtoolsProvider />` component via the `url` prop. Remix apps do not automatically pass environment variables to the browser, so you will need to set the URL manually. If not set, the default URL will be used.
+
+While the port can be changed, this feature also allows users to host the devtools server on a different machine or domain and provide the `<DevtoolsProvider />` with the custom domain URL. This such case will be useful if you're dockerizing your app and devtools server separately.
+
+**Enterprise Edition**: Refine Devtools running on ports other than "5001" is only available in the Enterprise Edition. If you're using the Community Edition, Refine Devtools will not work if the port is changed.
+
+[Resolves #5111](https://github.com/refinedev/refine/issues/5111)

documentation/docs/enterprise-edition/devtools/docker.tsx

@@ -0,0 +1,203 @@
+import React from "react";
+import { Sandpack } from "@site/src/components/sandpack";
+
+export default function DockerExample() {
+  return (
+    <Sandpack
+      showNavigator={false}
+      showLineNumbers
+      showFiles
+      hidePreview
+      showOpenInCodeSandbox={false}
+      dependencies={{
+        "@refinedev/core": "latest",
+        "@refinedev/simple-rest": "latest",
+        "@refinedev/react-router-v6": "latest",
+        "react-router-dom": "latest",
+        "react-router": "latest",
+      }}
+      files={{
+        "/App.tsx": {
+          code: AppTsxCode,
+        },
+        "/package.json": {
+          code: PackageJsonCode,
+        },
+        "/Dockerfile.dev": {
+          code: DockerfileDevCode,
+        },
+        "/Dockerfile.devtools": {
+          code: DockerfileDevtoolsCode,
+        },
+        "/docker-compose.yml": {
+          code: DockerComposeYmlCode,
+        },
+        "/nginx.conf": {
+          code: NginxConfCode,
+        },
+        "/style.css": {
+          code: "",
+          hidden: true,
+        },
+      }}
+    />
+  );
+}
+
+const AppTsxCode = /* jsx */ `
+import { Refine } from "@refinedev/core";
+import { DevtoolsProvider, DevtoolsPanel } from "@refinedev/devtools";
+
+export default function App() {
+    return (
+        <DevtolsProvider
+            url="http://devtools.local"
+        >
+            <Refine
+                // ...
+            >
+                {/* ... */}
+                <DevtoolsPanel />
+            </Refine>
+        </DevtolsProvider>
+    )
+}
+`.trim();
+
+const PackageJsonCode = /* json */ `
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "refine dev --devtools false -- --host",
+    "devtools": "refine devtools",
+    "refine": "refine"
+  },
+  "dependencies": {
+    "@refinedev/cli": "^2.16.36",
+    "@refinedev/core": "^4.53.0",
+    "@refinedev/devtools": "^1.2.6"
+  }
+}
+`.trim();
+
+const DockerfileDevCode = /* dockerfile */ `
+# We're setting up our development server and running it on port 5173.
+# We'll then use Nginx to reverse proxy the requests to the correct services.
+# We're running the application at port 5173 and we'll access it via http://my-app.local.
+
+# Use the official Node.js image as a parent image
+FROM refinedev/node
+
+# Copy the package.json and package-lock.json
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy the rest of the application
+COPY . .
+
+# Expose the port the app runs on
+EXPOSE 5173
+
+# Command to run the development server
+CMD ["npm", "run", "dev"]
+`.trim();
+
+const DockerfileDevtoolsCode = /* dockerfile */ `
+# We're setting up our Devtools server and running it on port 5001.
+# We'll then use Nginx to reverse proxy the requests to the correct services.
+# We're running devtools at port 5001 and we'll access it via http://devtools.local.
+
+# Use the Refine's Node.js image as a parent image
+FROM refinedev/node
+
+# Copy the package.json and package-lock.json
+COPY package*.json ./
+
+# Install dependencies
+RUN npm install
+
+# Copy the rest of the application
+COPY . .
+
+# Expose the port the devtools server runs on
+EXPOSE 5001
+
+# Command to run the devtools server
+CMD ["npm", "run", "devtools"]
+`.trim();
+
+const DockerComposeYmlCode = /* yaml */ `
+# We're setting up a development environment with two services: dev and devtools.
+# The dev service is the main service that runs the application.
+# The devtools service is the service that runs the Refine Devtools.
+version: "3"
+services:
+  dev:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    volumes:
+      - app:/app/refine
+      - /app/refine/node_modules
+    networks:
+      - dev-network
+  devtools:
+    build:
+      context: .
+      dockerfile: Dockerfile.devtools
+    volumes:
+      - app:/app/refine
+      - /app/refine/node_modules
+    networks:
+      - dev-network
+  nginx:
+    image: nginx:latest
+    ports:
+      - "80:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf
+    networks:
+      - dev-network
+networks:
+  dev-network:
+    driver: bridge
+volumes:
+  app:
+`.trim();
+
+const NginxConfCode = /* nginx */ `
+# We're setting up a reverse proxy to map the requests to the correct services.
+# Then we'll add the necessary aliases to the /etc/hosts file to make the services accessible via the domain names.
+events {
+    worker_connections 1024;
+}
+http {
+    server {
+        listen 80;
+        server_name my-app.local;
+        location / {
+            proxy_pass http://dev:5173;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+    server {
+        listen 80;
+        server_name devtools.local;
+        location / {
+            proxy_pass http://devtools:5001;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+}
+`.trim();

documentation/docs/enterprise-edition/devtools/index.md

@@ -0,0 +1,52 @@
+---
+title: Devtools
+---
+
+import DockerUsage from "./docker.tsx";
+
+# Refine Devtools
+
+In addition to the features provided by the [Refine Devtools](/docs/guides-concepts/development/#using-devtools), Enterprise Edition allows you to change the port of the devtools server or use a custom domain for the devtools server. This is useful if you're dockerizing your app and devtools server separately or using multiple Refine apps and want to use Refine Devtools for multiple apps.
+
+## Specifying the Port
+
+You can be using `@refinedev/cli` or `@refinedev/devtools-server` to start the devtools server. Both of these tools will respect the `REFINE_DEVTOOLS_PORT` environment variable. Changing the port is as simple as setting the `REFINE_DEVTOOLS_PORT` environment variable to the desired port number.
+
+```bash
+REFINE_DEVTOOLS_PORT=5002 refine dev
+```
+
+When `REFINE_DEVTOOLS_PORT` is set in `refine dev` command, it will be automatically propagated to your App and made available as an environment variable. The environment variable will automatically be used by the `<DevtoolsProvider />` component of the `@refinedev/devtools` to connect to the devtools server. If the environment variable is not working in the browser or you want to use a custom domain, you can manually set the URL in the `<DevtoolsProvider />` component via the `url` prop.
+
+```tsx title="App.tsx"
+import Refine from "@refinedev/core";
+import { DevtoolsProvider, DevtoolsPanel } from "@refinedev/devtools";
+
+const App = () => {
+  return (
+    <DevtoolsProvider
+      // highlight-next-line
+      url="http://refine-devtools.local"
+    >
+      <Refine>
+        {/* ... */}
+        <DevtoolsPanel />
+      </Refine>
+  );
+};
+```
+
+## Using Custom Domains with Docker
+
+In this example, we'll dockerize a Refine app and Refine Devtools separately and serve them on `http://my-app.local` and `http://devtools.local` respectively. After our setup is complete, we'll use the `url` prop of the `<DevtoolsProvider />` component to connect to the devtools server.
+
+<DockerUsage />
+
+Then, we'll need to update our `/etc/hosts` file to point `my-app.local` and `devtools.local` to `127.0.0.1`,
+
+```txt
+127.0.0.1 my-app.local
+127.0.0.1 devtools.local
+```
+
+That's it! Now you can run your Refine app and Refine Devtools separately in Docker containers and connect to the devtools server using the custom domain. Notice that we're only changing one line in our `App.tsx` file to use the custom domain, rest will be handled by the `@refinedev/devtools` package.

documentation/docs/guides-concepts/development/index.md

@@ -244,8 +244,13 @@ import { DevtoolsPanel, DevtoolsProvider } from "@refinedev/devtools";
 
 const App = () => {
   return (
-    // highlight-next-line
-    <DevtoolsProvider>
+    {/* highlight-start */}
+    <DevtoolsProvider
+      // If you're running devtools server on a different port or a domain, you can set the URL manually.
+      // Note that, custom domains and ports are only available in the Enterprise Edition.
+      // url="http://localhost:5001"
+    >
+    {/* highlight-end */}
       <Refine
       // ...
       >
@@ -277,7 +282,13 @@ As an alternative, you can also install the `@refinedev/devtools-server` package
 
 **Required Ports**
 
-Devtools server will run on port `5001`. Devtools will serve HTTP and WebSocket connections on this port. Make sure the port is available on your machine.
+Devtools server will run on port `5001` by default. Devtools will serve HTTP and WebSocket connections on this port. If you want to change the port, you can set the `REFINE_DEVTOOLS_PORT` environment variable to the desired port number.
+
+:::simple Enterprise Edition
+
+Refine Devtools running on ports other than "5001" is only available in the Enterprise Edition. If you're using the Community Edition, Refine Devtools will not work if the port is changed. Checkout [Refine Devtools in Enterprise Edition](/docs/enterprise-edition/devtools) for more information.
+
+:::
 
 ## Using Inferencer
 

documentation/sidebars.js

@@ -894,7 +894,10 @@ module.exports = {
       type: "category",
       label: "Enterprise Edition",
       className: "category-as-header",
-      items: ["enterprise-edition/okta/index"],
+      items: [
+        "enterprise-edition/okta/index",
+        "enterprise-edition/devtools/index",
+      ],
     },
     // Migration Guide
     {

packages/cli/src/commands/runner/dev/index.ts

@@ -1,12 +1,13 @@
 import { ProjectTypes } from "@definitions/projectTypes";
-import { getProjectType } from "@utils/project";
+import { getDevtoolsEnvKeyByProjectType, getProjectType } from "@utils/project";
 import { type Command, Option } from "commander";
 import { updateNotifier } from "src/update-notifier";
 import { devtoolsRunner } from "src/commands/devtools";
 import { projectScripts } from "../projectScripts";
 import { runScript } from "../runScript";
 import { getPlatformOptionDescription, getRunnerDescription } from "../utils";
-import { isDevtoolsInstalled } from "@utils/package";
+import { isDevtoolsInstalled } from "src/utils/package";
+import { ENV } from "src/utils/env";
 
 const dev = (program: Command) => {
   return program
@@ -44,6 +45,8 @@ const action = async (
 
   await updateNotifier();
 
+  const devtoolsPortEnvKey = getDevtoolsEnvKeyByProjectType(projectType);
+
   const devtoolsDefault = await isDevtoolsInstalled();
 
   const devtools = params.devtools === "false" ? false : devtoolsDefault;
@@ -52,7 +55,12 @@ const action = async (
     devtoolsRunner({ exitOnError: false });
   }
 
-  runScript(binPath, command);
+  const envWithDevtoolsPort =
+    devtools && ENV.REFINE_DEVTOOLS_PORT
+      ? { [devtoolsPortEnvKey]: ENV.REFINE_DEVTOOLS_PORT }
+      : undefined;
+
+  runScript(binPath, command, envWithDevtoolsPort);
 };
 
 export default dev;