Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

chore(web): prefer vinext for frontend development (#44246)

Stephen Zhoudf1d22827f0a
diff --git a/.devcontainer/post_create_command.sh b/.devcontainer/post_create_command.sh
index 7460636824d..988eda2d6be 100755
--- a/.devcontainer/post_create_command.sh
+++ b/.devcontainer/post_create_command.sh
@@ -8,7 +8,7 @@ pipx install uv
echo "alias start-api=\"cd $WORKSPACE_ROOT/api && uv run python -m flask run --host 0.0.0.0 --port=5001 --debug\"" >> ~/.bashrc
echo "alias start-worker=\"cd $WORKSPACE_ROOT/api && uv run python -m celery -A app.celery worker -P threads -c 1 --loglevel INFO -Q dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention\"" >> ~/.bashrc
-echo "alias start-web=\"cd $WORKSPACE_ROOT/web && pnpm dev:inspect\"" >> ~/.bashrc
+echo "alias start-web=\"cd $WORKSPACE_ROOT/web && pnpm dev\"" >> ~/.bashrc
echo "alias start-web-prod=\"cd $WORKSPACE_ROOT/web && pnpm build && pnpm start\"" >> ~/.bashrc
echo "alias start-containers=\"cd $WORKSPACE_ROOT/docker && docker-compose -f docker-compose.middleware.yaml -p dify --env-file middleware.env up -d\"" >> ~/.bashrc
echo "alias stop-containers=\"cd $WORKSPACE_ROOT/docker && docker-compose -f docker-compose.middleware.yaml -p dify --env-file middleware.env down\"" >> ~/.bashrc
diff --git a/dev/start-web b/dev/start-web
index baf008274b6..07f80a5d07d 100755
--- a/dev/start-web
+++ b/dev/start-web
@@ -5,4 +5,4 @@ set -x
SCRIPT_DIR="$(dirname "$(realpath "$0")")"
ROOT_DIR="$(dirname "$SCRIPT_DIR")"
-pnpm --dir "$ROOT_DIR" install && pnpm --dir "$ROOT_DIR/web" dev:inspect
+pnpm --dir "$ROOT_DIR" install && pnpm --dir "$ROOT_DIR/web" dev
diff --git a/package.json b/package.json
index 821cd6c983d..706337856dd 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
"scripts": {
"check": "vp run check:cached",
"check:fix": "vp run lint:eslint:fix && vp check --fix",
- "dev": "concurrently -k -n vinext,proxy \"vp run dify-web#dev:vinext\" \"vp run dify-web#dev:proxy\"",
+ "dev": "concurrently -k -n vinext,proxy \"vp run dify-web#dev\" \"vp run dify-web#dev:proxy\"",
"knip": "knip --workspace web",
"knip:production": "knip --workspace web --production --include files",
"knip:production-unused-check": "node ./scripts/check-web-production-unused-after-knip-fix.mjs",
diff --git a/web/AGENTS.md b/web/AGENTS.md
index 253708d233d..97d2138e332 100644
--- a/web/AGENTS.md
+++ b/web/AGENTS.md
@@ -1,5 +1,6 @@
## Frontend Workflow
+- Prefer vinext for frontend development. With a local backend, start the API separately and use `./dev/start-web` or `pnpm -C web dev` for the frontend only; the Dev Container `start-web` alias also starts only the frontend. For a remote backend, use root `pnpm dev` to start vinext and the API proxy. The local API and proxy both default to port 5001, so do not start both on that port. Switch to the Next.js development server (`pnpm -C web dev:next`) only when testing Next.js-specific functionality or investigating behavior that differs from Next.js.
- Read `docs/test.md` only for frontend test work and `docs/lint.md` only when running or changing static checks.
- Use the repo-local `how-to-write-component` skill when implementation requires component ownership, state, data-flow, effect, or interaction-boundary decisions. Do not load it for test-only, copy-only, or styling-only changes.
- Use `frontend-code-review` only for explicit frontend review or audit requests, including test reviews. Use `frontend-testing` when writing or changing Vitest or React Testing Library tests.
diff --git a/web/README.md b/web/README.md
index 6b855f1465d..778d9f68176 100644
--- a/web/README.md
+++ b/web/README.md
@@ -32,13 +32,33 @@ cp web/.env.example web/.env.local
> 1. When the frontend and backend run on different subdomains, set NEXT_PUBLIC_COOKIE_DOMAIN=1. The frontend and backend must be under the same top-level domain in order to share authentication cookies.
> 1. It's necessary to set NEXT_PUBLIC_API_PREFIX and NEXT_PUBLIC_PUBLIC_API_PREFIX to the correct backend API URL.
-Finally, start the default development stack from the repository root. This runs vinext and the local API proxy together:
+Finally, choose how to connect to the backend. Use vinext as the first choice for frontend development in either mode.
+
+#### Local backend
+
+Follow the [backend setup guide] to start middleware and the API separately. Then start only the frontend:
+
+```bash
+pnpm -C web dev
+```
+
+`./dev/start-web` installs workspace dependencies and starts the same frontend. The Dev Container `start-web` alias also starts only the frontend and pairs with `start-api`.
+
+#### Remote backend through the proxy
+
+Configure `DEV_PROXY_TARGET` and the other proxy targets in `web/.env.local`, then run this command from the repository root to start vinext and the API proxy together:
```bash
pnpm dev
```
-Use `pnpm -C web dev` only when you specifically need the Next.js development server without the default vinext process. Proxy environment variables are documented in `web/.env.example`; route ownership remains in `web/dev-proxy.config.ts`.
+This mode connects to a remote backend and does not start the local API. The local API and proxy both default to port `5001`; run only one on that port. Proxy environment variables are documented in `web/.env.example`; route ownership remains in `web/dev-proxy.config.ts`.
+
+#### Next.js compatibility checks
+
+Switch to the Next.js development server with `pnpm -C web dev:next` only when testing Next.js-specific functionality or investigating behavior that differs from Next.js; use `pnpm -C web dev:next:inspect` when you need the Node.js debugger. These commands start only the frontend. For a remote backend, run `pnpm -C web dev:proxy` in a separate terminal alongside Next.js.
+
+#### Open the frontend
Open <http://localhost:3000> with your browser to see the result.
@@ -149,6 +169,7 @@ The Dify community can be found on [Discord community], where you can ask questi
[Storybook]: https://storybook.js.org
[Vite+]: https://viteplus.dev
[Vitest]: https://vitest.dev
+[backend setup guide]: ../api/README.md
[pnpm]: https://pnpm.io
[versioned vinext guide]: https://github.com/cloudflare/vinext/blob/vinext%401.0.0-beta.13/README.md
[vinext Node deployment]: https://vinext.dev/docs/deploying/other-platforms
diff --git a/web/package.json b/web/package.json
index ddc04d3b833..a1cfe85942b 100644
--- a/web/package.json
+++ b/web/package.json
@@ -13,8 +13,9 @@
"analyze": "next experimental-analyze",
"build": "next build",
"build:vinext": "vp build",
- "dev": "next dev",
- "dev:inspect": "next dev --inspect",
+ "dev": "vp dev",
+ "dev:next": "next dev",
+ "dev:next:inspect": "next dev --inspect",
"dev:proxy": "dev-proxy --config ./dev-proxy.config.ts --env-file ./.env.local",
"dev:vinext": "vp dev",
"gen-doc-paths": "node ./scripts/gen-doc-paths.ts && vp fmt types/doc-paths.ts",