Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

make local development the default

yoma1d0bb191645b
diff --git a/.env.local.example b/.env.local.example
index cd8e7ee7..d09ee0b8 100644
--- a/.env.local.example
+++ b/.env.local.example
@@ -91,7 +91,9 @@ EDGE_EVER_ROUTE_PATTERN=
VITE_API_BASE_URL=http://127.0.0.1:8787
# Optional: multi-instance deployment.
-# Set `EDGE_EVER_INSTANCE=<name>` in .env.local or Cloudflare Build Variables.
+# Select remote instances explicitly per command instead of setting a persistent
+# local default, for example: EDGE_EVER_INSTANCE=prod bun run dev:remote.
+# Cloudflare Builds may still set EDGE_EVER_INSTANCE as a Build Variable.
# The scripts prefer `EDGE_EVER_<NAME>_*` values and fall back to the generic
# `EDGE_EVER_*` values above.
# For example, `EDGE_EVER_INSTANCE=prod` prefers `EDGE_EVER_PROD_WORKER_NAME`,
diff --git a/AGENTS.md b/AGENTS.md
index fed78eaa..8f139a16 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -36,9 +36,11 @@ Release 标签必须精确指向 `main` 上经过验证的发布提交。除非
## 本地启动约束
-本地预览或调试时,必须优先使用 `bun run dev` 启动完整开发环境,让 API 通过 `scripts/run-wrangler.mjs` 读取 `.env.local` 中的个性化实例配置。实例名称、D1/R2 资源、账号等本机私有配置均以 `.env.local` 为准,严禁在代理指令或代码中硬编码个人实例名。
+本地预览或调试时,必须优先使用 `bun run dev` 启动完整的纯本地开发环境。该命令使用本地 D1/R2 和固定演示种子,不得读取或连接 `.env.local` 中的远程个性化实例。
-除非用户明确要求只启动前端静态界面,否则不要单独运行 `bun run dev:web`;该命令不会启动 API,也不会保证读取 `.env.local` 中的实例配置,容易导致前端请求 `127.0.0.1:8787` 失败或误判环境。
+只有用户明确要求连接远程实例时,才能使用 `EDGE_EVER_INSTANCE=<实例名> bun run dev:remote`。实例名称、D1/R2 资源、账号等本机私有配置均以 `.env.local` 为准,严禁在代理指令或代码中硬编码个人实例名;禁止在未显式指定实例的情况下启动远程开发环境。
+
+除非用户明确要求只启动前端静态界面,否则不要单独运行 `bun run dev:web`;该命令不会启动 API,容易导致前端请求 `127.0.0.1:8787` 失败或误判环境。
## 组件复用与造轮子约束
diff --git a/README.md b/README.md
index 155cf76b..fccdee8d 100644
--- a/README.md
+++ b/README.md
@@ -117,16 +117,16 @@ Apply local D1 migrations:
bun run db:migrate:local
```
-For a fully local development environment, run the command below. It applies pending local migrations and initializes the local D1/R2 stores once with the repository's fixed demo seed. Existing local changes are preserved on later restarts.
+Start the default development environment. It applies pending local migrations and initializes local D1/R2 stores once with the repository's fixed demo seed. Existing local changes are preserved on later restarts, and no remote instance is contacted.
```sh
-bun run dev:local
+bun run dev
```
-Start local development:
+To intentionally develop against a configured remote instance, select it explicitly:
```sh
-bun run dev
+EDGE_EVER_INSTANCE=<name> bun run dev:remote
```
Checks:
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 80d79483..b7e365bf 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -119,16 +119,16 @@ bun install
bun run db:migrate:local
```
-如需启动完全本地的开发环境,请运行下面的命令。它会先应用本地迁移,并在首次启动时使用仓库内固定的 Demo 种子初始化本地 D1/R2;后续重启会保留本地修改。
+启动默认开发环境。它会先应用本地迁移,并在首次启动时使用仓库内固定的 Demo 种子初始化本地 D1/R2;后续重启会保留本地修改,且不会连接任何远程实例。
```sh
-bun run dev:local
+bun run dev
```
-启动本地开发:
+如需明确连接已配置的远程实例,必须显式指定实例名:
```sh
-bun run dev
+EDGE_EVER_INSTANCE=<实例名> bun run dev:remote
```
常用检查:
diff --git a/package.json b/package.json
index 93ca23fd..3881978f 100644
--- a/package.json
+++ b/package.json
@@ -8,10 +8,12 @@
"packages/*"
],
"scripts": {
- "dev": "concurrently -k -n api,web -c cyan,magenta \"bun run dev:api\" \"bun run dev:web\"",
- "dev:api": "bun scripts/run-wrangler.mjs dev --remote --port 8787",
+ "dev": "bun run dev:local",
+ "dev:api": "bun run dev:api:local",
"dev:local": "bun run db:migrate:local && concurrently -k -n api,web -c cyan,magenta \"bun run dev:api:local\" \"bun run dev:web\"",
- "dev:api:local": "EDGE_EVER_LOCAL_DEMO_SEED=true bun scripts/run-wrangler.mjs dev --local --port 8787",
+ "dev:api:local": "EDGE_EVER_INSTANCE= EDGE_EVER_LOCAL_DEMO_SEED=true bun scripts/run-wrangler.mjs dev --local --port 8787",
+ "dev:remote": "concurrently -k -n api,web -c cyan,magenta \"bun run dev:api:remote\" \"bun run dev:web\"",
+ "dev:api:remote": "bun scripts/run-wrangler.mjs dev --remote --port 8787",
"dev:web": "vite --config apps/web/vite.config.ts --host 127.0.0.1 --port 5173",
"dev:mobile": "bun --cwd apps/mobile expo start",
"dev:site": "bun --cwd apps/site dev",
@@ -26,7 +28,7 @@
"typecheck": "tsc -p tsconfig.json --noEmit",
"typecheck:mobile": "bun run --cwd apps/mobile typecheck",
"test:restore-deleted-notebook": "bun scripts/test-restore-deleted-notebook.mjs",
- "db:migrate:local": "bun scripts/run-wrangler.mjs d1 migrations apply DB --local",
+ "db:migrate:local": "EDGE_EVER_INSTANCE= bun scripts/run-wrangler.mjs d1 migrations apply DB --local",
"db:migrate:remote": "bun scripts/run-wrangler.mjs d1 migrations apply DB --remote",
"auth:hash": "bun scripts/hash-password.mjs",
"auth:reset-password": "bun scripts/reset-password.mjs",
diff --git a/scripts/run-wrangler.mjs b/scripts/run-wrangler.mjs
index 88c29e06..cdfb17a3 100644
--- a/scripts/run-wrangler.mjs
+++ b/scripts/run-wrangler.mjs
@@ -69,6 +69,7 @@ const generatedSecretsPath = resolve(
? `.env.wrangler.generated.${instanceKey.toLowerCase()}.secrets`
: ".env.wrangler.generated.secrets",
);
+const generatedLocalDevEnvPath = resolve(".env.wrangler.generated.local");
let config = readFileSync(baseConfigPath, "utf8");
let changed = false;
@@ -186,6 +187,16 @@ custom_domain = ${customDomain ? "true" : "false"}
const isRemoteCommand =
wranglerArgs.includes("deploy") || wranglerArgs.includes("--remote");
+const isRemoteDevCommand = wranglerArgs.includes("dev") && wranglerArgs.includes("--remote");
+const isLocalDevCommand = wranglerArgs.includes("dev") && wranglerArgs.includes("--local");
+
+if (isRemoteDevCommand && !instance) {
+ console.error(
+ "Remote development requires an explicit instance. Run EDGE_EVER_INSTANCE=<name> bun run dev:remote.",
+ );
+ process.exit(1);
+}
+
if (isRemoteCommand && config.includes(`database_id = "${PLACEHOLDER_D1_ID}"`)) {
console.error(
[
@@ -206,6 +217,7 @@ if (changed) {
const isDeployCommand = wranglerArgs.includes("deploy");
const hasSecretsFileArg = wranglerArgs.some((arg) => arg === "--secrets-file" || arg.startsWith("--secrets-file="));
+const hasEnvFileArg = wranglerArgs.some((arg) => arg === "--env-file" || arg.startsWith("--env-file="));
const authPassword = envValue("AUTH_PASSWORD");
const authPasswordHash = envValue("AUTH_PASSWORD_HASH");
const authSecrets = {
@@ -214,6 +226,11 @@ const authSecrets = {
};
const finalWranglerArgs = [...wranglerArgs];
+if (isLocalDevCommand && !hasEnvFileArg) {
+ writeFileSync(generatedLocalDevEnvPath, "# Intentionally empty: local development must not inherit remote instance secrets.\n");
+ finalWranglerArgs.push("--env-file", generatedLocalDevEnvPath);
+}
+
if (isDeployCommand && Object.keys(authSecrets).length > 0 && !hasSecretsFileArg) {
writeFileSync(generatedSecretsPath, `${JSON.stringify(authSecrets, null, 2)}\n`);
finalWranglerArgs.push("--secrets-file", generatedSecretsPath);