shopify-tunnel-dev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huy Nguyen The
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# shopify-tunnel-dev
+
+Chạy `shopify app dev` sau một Cloudflare named tunnel có **hostname cố định**. Cả team dùng chung
+một bộ credential, dev mới chỉ cần đặt `VITE_HOST` rồi chạy, không ai phải cấp tunnel hay cert.
+
+Cùng cơ chế và cùng tên biến với `@bss-sbc/shopify-dev`, nên repo đang dùng tool đó đổi sang được
+mà không phải sửa `.env` hay `account.json`. Không có dependency, cần Node >= 20.12.
+
+## Cách chạy
+
+```
+pnpm dev
+  ├─ đọc web/.env hoặc .env, sau đó .cloudflared/account.json (account.json đè lên)
+  ├─ tìm tunnel tên = phần đầu của VITE_HOST, chưa có thì tạo bằng secret chung
+  ├─ trỏ DNS VITE_HOST về tunnel (không ghi đè record của tunnel khác)
+  ├─ chạy connector về http://localhost:$VITE_PORT, chờ edge nhận kết nối
+  └─ npx shopify app dev --tunnel-url https://$VITE_HOST:$VITE_PORT
+```
+
+HTTPS do Cloudflare xử lý, máy dev không cần cert TLS. Nếu không có `cloudflared` trên máy, lần
+chạy đầu tool tự tải bản mới nhất về `~/.cache/shopify-tunnel-dev/`. Muốn dùng binary khác thì đặt
+`CLOUDFLARED_BIN`.
+
+## Setup một lần cho cả team
+
+1. Dùng một Cloudflare account chỉ dành cho dev (lý do ở mục Bảo mật), thêm domain vào account đó.
+2. Chạy `cloudflared tunnel login`, chọn zone. Lệnh này sinh `~/.cloudflared/cert.pem`.
+3. Tạo secret: `openssl rand -base64 32`.
+4. Lưu cả hai lên password manager (Passbolt...), kèm `account.json`:
+
+```json
+{
+  "CF_ACCOUNT_TAG": "<account id>",
+  "CF_SECRET_KEY": "<base64 32 byte>",
+  "CF_HOST_PATTERN": "^dev-banner-[a-zA-Z0-9-]+\\.yourdomain\\.com$"
+}
+```
+
+`CF_HOST_PATTERN` là tuỳ chọn. Nên đặt để mỗi app có tiền tố riêng và không đè DNS của nhau.
+
+## Setup cho repo app
+
+```bash
+pnpm add -D shopify-tunnel-dev       # hoặc git URL / pnpm link khi chưa publish
+```
+
+```json
+"scripts": { "dev": "shopify-tunnel-dev" }
+```
+
+`.gitignore`:
+
+```
+.cloudflared/*
+!.cloudflared/*.example
+```
+
+`shopify.app.toml` của từng dev nên đặt `automatically_update_urls_on_dev = true` (mặc định), để
+Shopify CLI tự cập nhật URL app theo `VITE_HOST`. Mỗi dev nên có app dev riêng trên Partner, vì URL
+app nằm trên Shopify chứ không nằm ở tunnel.
+
+## Dev mới
+
+```bash
+# lấy từ password manager
+.cloudflared/cert.pem
+.cloudflared/account.json
+chmod 600 .cloudflared/*
+```
+
+`.env`:
+
+```
+VITE_HOST=dev-banner-huy.yourdomain.com
+VITE_PORT=9000
+```
+
+Chạy `pnpm dev`.
+
+## Tuỳ chọn
+
+| Flag | Tác dụng |
+|---|---|
+| `-q`, `--quick` | URL `*.trycloudflare.com` ngẫu nhiên, chỉ cần `VITE_PORT`, không cần credential |
+| `-f`, `--force` | Chiếm `VITE_HOST` dù DNS đang trỏ tunnel khác, hoặc tunnel đang có kết nối |
+| còn lại | Chuyển tiếp cho `shopify app dev` (`--reset`, `--store=...`) |
+
+## Chống trùng hostname
+
+`@bss-sbc/shopify-dev` luôn ghi đè DNS và không kiểm tra connector đang chạy, nên hai người đặt
+cùng `VITE_HOST` sẽ bị chia request ngẫu nhiên cho nhau. Tool này dừng với lỗi khi:
+
+- tunnel của `VITE_HOST` đang có kết nối sống từ máy khác;
+- DNS của `VITE_HOST` đang trỏ về tunnel khác.
+
+Nếu chính process của bạn vừa chết và tunnel còn giữ kết nối cũ, chờ vài giây hoặc chạy với `--force`.
+
+## Khác với `@bss-sbc/shopify-dev`
+
+- Đọc `.env` bằng `util.parseEnv` của Node: dòng comment và giá trị có dấu `=` không còn làm hỏng.
+- `account.json` và `cert.pem` chỉ bắt buộc ở named mode, `--quick` không cần.
+- Credential của tunnel truyền qua env (`TUNNEL_CRED_CONTENTS`), không ghi file `<id>.json` ra đĩa.
+- Không có lệnh `start` (prod), vì prod không nên chạy qua tunnel dev.
+
+## Bảo mật
+
+- `cert.pem` cho quyền tạo, xoá và trỏ DNS **mọi** tunnel trong account và zone đã chọn.
+- Ai có `CF_SECRET_KEY` thì chạy được connector cho mọi tunnel mà tool đã tạo.
+
+Vì vậy dùng account Cloudflare riêng cho dev, và không commit hai giá trị này. Rotate: đổi secret
+trên password manager, xoá các tunnel cũ (`cloudflared tunnel delete`), lần `pnpm dev` sau sẽ tự
+tạo lại.
+
+## Test
+
+```bash
+node --test
+```

package/bin/shopify-tunnel-dev.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { resolveCloudflared } from '../src/cloudflared-binary.js';
+import { ConfigError, loadConfig } from '../src/load-config.js';
+import { stopCloudflared } from '../src/run-cloudflared.js';
+import { startNamedTunnel, startQuickTunnel } from '../src/start-tunnel.js';
+
+const USAGE = `Usage: shopify-tunnel-dev [dev] [options] [-- shopify app dev args]
+
+Options:
+  -q, --quick   Random *.trycloudflare.com URL, no Cloudflare credentials needed
+  -f, --force   Take over VITE_HOST even if its DNS record or tunnel is in use
+  -h, --help    Show this help
+
+Any other argument (e.g. --reset, --store=foo) is passed to \`shopify app dev\`.`;
+
+function parseArgs(argv) {
+  const args = argv[0] === 'dev' ? argv.slice(1) : argv;
+  const opts = { quick: false, force: false, help: false, passthrough: [] };
+  for (const arg of args) {
+    if (arg === '-q' || arg === '--quick') opts.quick = true;
+    else if (arg === '-f' || arg === '--force') opts.force = true;
+    else if (arg === '-h' || arg === '--help') opts.help = true;
+    else if (arg !== '--') opts.passthrough.push(arg);
+  }
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) return console.log(USAGE);
+
+  const cfg = loadConfig({ quick: opts.quick });
+  const bin = await resolveCloudflared();
+  const tunnel = opts.quick ? await startQuickTunnel(bin, cfg) : await startNamedTunnel(bin, cfg, opts);
+  console.log(`[tunnel] https://${tunnel.host} -> http://localhost:${cfg.port}`);
+
+  const shopify = spawn(
+    'npx',
+    ['shopify', 'app', 'dev', '--tunnel-url', `https://${tunnel.host}:${cfg.port}`, ...opts.passthrough],
+    { stdio: 'inherit', shell: process.platform === 'win32' },
+  );
+
+  // Ctrl+C already reaches shopify through the process group; stay alive until it exits, and mark the
+  // tunnel as intentionally stopped so its exit is not reported as a crash. A second Ctrl+C forces out.
+  let interrupts = 0;
+  process.on('SIGINT', () => {
+    stopCloudflared(tunnel.child);
+    if (++interrupts > 1) {
+      killTree(shopify);
+      process.exit(130);
+    }
+  });
+  process.on('SIGTERM', () => {
+    stopCloudflared(tunnel.child);
+    killTree(shopify);
+  });
+
+  tunnel.child.on('exit', () => {
+    if (tunnel.child.killedByUs) return;
+    console.error('[tunnel] tunnel is down, stopping shopify app dev');
+    process.exitCode = 1;
+    killTree(shopify);
+  });
+  shopify.on('exit', (code) => {
+    stopCloudflared(tunnel.child);
+    process.exitCode ||= code ?? 1;
+  });
+}
+
+// On Windows shopify runs under a cmd.exe shell and kill() would only end the wrapper, orphaning the
+// real node process that holds the dev port; taskkill /T takes down the whole tree.
+function killTree(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  if (process.platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+  else child.kill('SIGINT');
+}
+
+main().catch((err) => {
+  console.error(err instanceof ConfigError ? `[config] ${err.message}` : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "shopify-tunnel-dev",
+  "version": "0.1.0",
+  "description": "Run `shopify app dev` behind a fixed-hostname Cloudflare named tunnel that the whole team shares one credential set for",
+  "type": "module",
+  "bin": {
+    "shopify-tunnel-dev": "bin/shopify-tunnel-dev.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "shopify",
+    "shopify-app",
+    "cloudflare",
+    "tunnel",
+    "cloudflared"
+  ],
+  "license": "MIT",
+  "author": "Huy Nguyen The"
+}

package/src/cloudflared-binary.js

@@ -0,0 +1,54 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const RELEASE_URL = 'https://github.com/cloudflare/cloudflared/releases/latest/download';
+
+// Resolution order: CLOUDFLARED_BIN > `cloudflared` on PATH > binary cached in ~/.cache.
+// ponytail: no checksum check on the download (HTTPS from GitHub only); pin a version + sha256 if supply chain matters.
+export async function resolveCloudflared() {
+  if (process.env.CLOUDFLARED_BIN) return process.env.CLOUDFLARED_BIN;
+  if (isRunnable('cloudflared')) return 'cloudflared';
+
+  const cacheDir = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'shopify-tunnel-dev');
+  const bin = path.join(cacheDir, process.platform === 'win32' ? 'cloudflared.exe' : 'cloudflared');
+  if (!existsSync(bin)) await download(cacheDir, bin);
+  return bin;
+}
+
+function isRunnable(cmd) {
+  try {
+    execFileSync(cmd, ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function assetName() {
+  const arch = { x64: 'amd64', arm64: 'arm64', arm: 'arm', ia32: '386' }[process.arch];
+  if (arch && process.platform === 'linux') return `cloudflared-linux-${arch}`;
+  if (arch && process.platform === 'darwin') return `cloudflared-darwin-${arch}.tgz`;
+  if (arch && process.platform === 'win32') return `cloudflared-windows-${arch}.exe`;
+  throw new Error(`No cloudflared build for ${process.platform}/${process.arch}; install it and set CLOUDFLARED_BIN`);
+}
+
+async function download(cacheDir, bin) {
+  const asset = assetName();
+  console.log(`[tunnel] downloading ${asset} to ${cacheDir}`);
+  const res = await fetch(`${RELEASE_URL}/${asset}`);
+  if (!res.ok) throw new Error(`Downloading ${asset} failed: HTTP ${res.status}`);
+
+  mkdirSync(cacheDir, { recursive: true });
+  // Write to a temp name first so an interrupted download never leaves a broken binary in the cache.
+  const tmp = `${bin}.${process.pid}.tmp`;
+  writeFileSync(tmp, Buffer.from(await res.arrayBuffer()));
+  if (asset.endsWith('.tgz')) {
+    execFileSync('tar', ['-xzf', tmp, '-C', cacheDir]); // the macOS archive holds a single `cloudflared`
+    rmSync(tmp);
+  } else {
+    renameSync(tmp, bin);
+  }
+  chmodSync(bin, 0o755);
+}

package/src/load-config.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseEnv } from 'node:util';
+
+export class ConfigError extends Error {}
+
+// Same file layout and variable names as @bss-sbc/shopify-dev, so an existing repo can switch
+// without renaming anything: web/.env wins over ./.env, and .cloudflared/account.json overrides
+// keys from the env file.
+export function loadConfig({ cwd = process.cwd(), quick = false } = {}) {
+  const envPath = [path.join(cwd, 'web/.env'), path.join(cwd, '.env')].find((p) => existsSync(p));
+  const cloudflaredDir = path.join(cwd, '.cloudflared');
+  const accountPath = path.join(cloudflaredDir, 'account.json');
+  const certPath = path.join(cloudflaredDir, 'cert.pem');
+
+  const env = envPath ? parseEnv(readFileSync(envPath, 'utf8')) : {};
+  const account = existsSync(accountPath) ? readJson(accountPath) : {};
+  const vars = { ...env, ...account };
+
+  const port = Number(vars.VITE_PORT);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new ConfigError(`VITE_PORT must be a port number, got "${vars.VITE_PORT ?? ''}"`);
+  }
+  if (quick) return { quick, port };
+
+  const missing = ['VITE_HOST', 'CF_ACCOUNT_TAG', 'CF_SECRET_KEY'].filter((key) => !vars[key]);
+  if (missing.length) {
+    throw new ConfigError(`Missing ${missing.join(', ')}. Put VITE_HOST in .env and CF_* in ${accountPath}`);
+  }
+  if (!existsSync(certPath)) {
+    throw new ConfigError(`Missing ${certPath} (origin cert from \`cloudflared tunnel login\`)`);
+  }
+
+  const host = vars.VITE_HOST.trim();
+  if (vars.CF_HOST_PATTERN && !hostPattern(vars.CF_HOST_PATTERN).test(host)) {
+    throw new ConfigError(`VITE_HOST "${host}" does not match CF_HOST_PATTERN ${vars.CF_HOST_PATTERN}`);
+  }
+  // Tunnel name = first DNS label, same rule as @bss-sbc/shopify-dev, so both tools reuse one tunnel.
+  const tunnelName = host.split('.')[0];
+  if (!host.includes('.') || !/^[a-zA-Z0-9-]{3,63}$/.test(tunnelName)) {
+    throw new ConfigError(`VITE_HOST "${host}" must be a full hostname whose first label is 3-63 chars of [a-zA-Z0-9-]`);
+  }
+  // cloudflared rejects tunnel secrets that decode to fewer than 32 bytes.
+  if (Buffer.from(vars.CF_SECRET_KEY, 'base64').length < 32) {
+    throw new ConfigError('CF_SECRET_KEY must be base64 of at least 32 bytes (openssl rand -base64 32)');
+  }
+
+  return {
+    quick,
+    port,
+    host,
+    tunnelName,
+    accountTag: vars.CF_ACCOUNT_TAG,
+    secret: vars.CF_SECRET_KEY,
+    certPath,
+    cloudflaredDir,
+  };
+}
+
+function hostPattern(source) {
+  try {
+    return new RegExp(source);
+  } catch (err) {
+    throw new ConfigError(`CF_HOST_PATTERN is not a valid regex: ${err.message}`);
+  }
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new ConfigError(`Cannot parse ${file}: ${err.message}`);
+  }
+}

package/src/run-cloudflared.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+
+const READY_TIMEOUT_MS = 30_000;
+const TAIL_LINES = 30;
+
+// Spawns a long-running cloudflared and resolves once the edge has registered a connection.
+// Logs stay silent after that; if the process dies, the last lines are printed so the cause is visible.
+export function runCloudflared(bin, args, env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '';
+    let ready = false;
+
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`cloudflared not connected after ${READY_TIMEOUT_MS / 1000}s:\n${tail(output)}`));
+    }, READY_TIMEOUT_MS);
+
+    const onData = (chunk) => {
+      output = (output + chunk).slice(-20_000);
+      if (!ready && output.includes('Registered tunnel connection')) {
+        ready = true;
+        clearTimeout(timer);
+        resolve({ child, output });
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on('exit', (code, signal) => {
+      clearTimeout(timer);
+      const message = `cloudflared exited (${signal ?? code}):\n${tail(output)}`;
+      if (!ready) reject(new Error(message));
+      else if (!child.killedByUs) console.error(`[tunnel] ${message}`);
+    });
+  });
+}
+
+export function stopCloudflared(child) {
+  child.killedByUs = true;
+  child.kill();
+}
+
+function tail(text) {
+  return text.trimEnd().split('\n').slice(-TAIL_LINES).join('\n');
+}

package/src/start-tunnel.js

@@ -0,0 +1,90 @@
+import { execFile } from 'node:child_process';
+import { rmSync } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { runCloudflared } from './run-cloudflared.js';
+
+const execFileAsync = promisify(execFile);
+// Default grace period is 30s, which would hang every Ctrl+C; dev traffic does not need draining.
+const baseEnv = () => ({ ...process.env, NO_AUTOUPDATE: 'true', TUNNEL_GRACE_PERIOD: '1s' });
+
+// Throwaway *.trycloudflare.com URL, no Cloudflare account needed. Hostname changes every run.
+export async function startQuickTunnel(bin, { port }) {
+  const { child, output } = await runCloudflared(
+    bin,
+    ['tunnel', '--no-autoupdate', '--url', `http://localhost:${port}`],
+    baseEnv(),
+  );
+  const host = output.match(/https:\/\/([a-z0-9-]+\.trycloudflare\.com)/)?.[1];
+  if (!host) {
+    child.kill();
+    throw new Error('Quick tunnel connected but no trycloudflare.com URL was printed');
+  }
+  return { child, host };
+}
+
+// Fixed hostname on the team's Cloudflare zone. Every dev shares cert.pem + one tunnel secret, so a
+// tunnel created on one machine can be run from any other; the tunnel is created on first run only.
+export async function startNamedTunnel(bin, cfg, { force = false } = {}) {
+  const env = { ...baseEnv(), TUNNEL_ORIGIN_CERT: cfg.certPath };
+  const cf = (args, extraEnv = {}) => execFileAsync(bin, args, { env: { ...env, ...extraEnv } });
+
+  let tunnel = await findTunnel(cf, cfg.tunnelName);
+  if (!tunnel) {
+    console.log(`[tunnel] creating tunnel ${cfg.tunnelName}`);
+    tunnel = await createTunnel(cf, cfg);
+  } else if (tunnel.connections?.length && !force) {
+    // Two connectors on one tunnel = Cloudflare load-balances requests between two laptops.
+    throw new Error(
+      `Tunnel "${cfg.tunnelName}" already has ${tunnel.connections.length} live connection(s): ` +
+        `someone else is probably running with VITE_HOST=${cfg.host}. ` +
+        'Pick another VITE_HOST, or pass --force if it is your own process that just died.',
+    );
+  }
+
+  await routeDns(cf, tunnel.id, cfg.host, force);
+
+  // Credentials are rebuilt from the shared secret and handed over via env, never written to disk.
+  const credentials = JSON.stringify({ AccountTag: cfg.accountTag, TunnelSecret: cfg.secret, TunnelID: tunnel.id });
+  const { child } = await runCloudflared(
+    bin,
+    ['tunnel', '--no-autoupdate', 'run', '--url', `http://localhost:${cfg.port}`, tunnel.id],
+    { ...env, TUNNEL_CRED_CONTENTS: credentials },
+  );
+  return { child, host: cfg.host };
+}
+
+async function findTunnel(cf, name) {
+  const { stdout } = await cf(['tunnel', 'list', '--output', 'json', '--name', name]);
+  return (JSON.parse(stdout || '[]') ?? []).find((t) => t.name === name);
+}
+
+async function createTunnel(cf, cfg) {
+  // create insists on writing a credentials file; run uses TUNNEL_CRED_CONTENTS instead, so drop it.
+  // It goes next to account.json (already secret and gitignored), not world-readable tmp, in case a
+  // hard kill skips the cleanup.
+  const credFile = path.join(cfg.cloudflaredDir, `create-${process.pid}.json`);
+  try {
+    const { stdout } = await cf(
+      ['tunnel', 'create', '--output', 'json', '--credentials-file', credFile, cfg.tunnelName],
+      { TUNNEL_CREATE_SECRET: cfg.secret },
+    );
+    const tunnel = JSON.parse(stdout);
+    if (!tunnel?.id) throw new Error(`Unexpected \`cloudflared tunnel create\` output: ${stdout}`);
+    return tunnel;
+  } finally {
+    rmSync(credFile, { force: true });
+  }
+}
+
+async function routeDns(cf, tunnelId, host, force) {
+  try {
+    await cf(['tunnel', 'route', 'dns', ...(force ? ['--overwrite-dns'] : []), tunnelId, host]);
+  } catch (err) {
+    const detail = (err.stderr || err.message).trim();
+    throw new Error(
+      `Cannot point ${host} at tunnel ${tunnelId}: ${detail}\n` +
+        'If the record belongs to another tunnel, pick another VITE_HOST or pass --force to take it over.',
+    );
+  }
+}