@nuxtlib/cf-deployment 1.0.1

package/README.md

@@ -0,0 +1,220 @@
+# `@nuxtlib/cf-deployment`
+
+## Deploy your website to Cloudflare Workers with GitHub Actions in minutes, with multiple environments, configurations, and branches.
+
+### 1. Install the module in your Nuxt project
+```bash
+npm install -D @nuxtlib/cf-deployment
+```
+
+### 2. Configure `cfDeployment` in `nuxt.config.ts`. (Minimal example)
+```ts
+export default defineNuxtConfig({
+  modules: ['@nuxtlib/cf-deployment'],
+  cfDeployment: {
+    appName: 'your-app-name',
+    environments: [
+      { branch: 'main', url: 'example.com' },
+      { branch: 'staging', url: 'staging.example.com' },
+    ],
+  },
+})
+```
+### 3. Cloudflare setup:
+
+1. In Cloudflare Dashboard, go to `Workers & Pages` and copy your `Account ID`.
+![Get account id](assets/account_id.png)
+
+2. In Cloudflare, go to `API Tokens` -> `Create Token` -> choose `Edit Cloudflare Workers`, scope it to your account, create the token, and copy it.
+![Get API token](assets/api_token.png)
+
+#### If your domain isn't registered in Clouflare yet
+Go to Cloudflare, add your domain and point nameservers to Cloudflare. Wait until the zone is `Active`.
+
+
+### 4. GitHub setup:
+1. In GitHub, open `Settings` -> `Secrets and variables` -> `Actions`, then add repository secrets `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`.
+![Add secrets](assets/gh_secrets.png)
+2. Optional - In GitHub, go to your repository `Settings` -> `Environments`, then create the environments used by your deployment flow.
+3. Optional - For each GitHub environment, configure deployment branch restrictions.
+
+
+### Final touch and Verification (CLI or dashboard)
+Push to a configured branch and enjoy automatic deployment.
+
+
+#### Preview the deploy
+
+- In GitHub -> `Actions`, you should see a run start when you push to one of your configured branches. It installs dependencies, builds Nuxt, then calls Wrangler. A green run means the Worker was deployed.
+- In Cloudflare -> `Build` -> `Compute & AI` -> `Workers & Pages`, you should now see two Workers named from your `wrangler.toml` (for each of your environments).
+- In Cloudflare -> `Domain` -> `DNS` -> `Records`, two DNS records should point to the Workers (one for each environment). They appear after deploy and confirm the routes are attached to your domains.
+- Propagation can take a few minutes. Once complete, you can hit your environment URLs in the browser and see your deployed app.
+
+#### CLI (real-time)
+
+From your project root, stream logs for each Worker:
+
+```bash
+npx wrangler tail your-environment-name
+```
+
+Hit your environment URL in the browser and you will see log entries in the terminal.
+
+#### Dashboard
+
+In Cloudflare -> `Workers & Pages` -> select your Worker -> use the `Logs` / `Observability` view to see requests and errors.
+
+`cf-deployment` is a Cloudflare-first deployment layer for Nuxt apps.
+It turns deployment from ad-hoc CI scripts into config-driven infrastructure generated from `cfDeployment` in `nuxt.config.ts`.
+
+This module is for teams that want to stay deep in the Cloudflare ecosystem:
+
+- Workers as the runtime
+- Cloudflare routes/custom domains
+- Cloudflare secrets and Wrangler environments
+- GitHub Actions as the delivery pipeline
+
+The goal is to keep deploy behavior explicit, repeatable, and versioned as your app and team scale.
+
+## Why This Exists
+
+Nuxt projects often begin with one environment and one deploy command, then quickly grow into:
+
+- branch-based preview/staging/production flows
+- multiple environment routes and naming rules
+- package-manager-specific CI steps (`npm`, `pnpm`, or `yarn`)
+- repeated edits to both `wrangler.toml` and workflow YAML
+
+Without automation, those files drift apart. Branches deploy to wrong envs, route updates lag behind code, and CI behavior becomes inconsistent between repos.
+
+`cf-deployment` solves that drift by generating deployment artifacts from one source of truth.
+
+## Who It Is For
+
+Use this module if your team:
+
+- deploys Nuxt to Cloudflare Workers and wants config-as-code for deploy infrastructure
+- needs reliable branch-to-environment mapping across `wrangler.toml` and GitHub Actions
+- wants Cloudflare-native workflows without hand-maintaining YAML in every repository
+- prefers owning deployment logic directly in the app repo instead of relying on hosted abstractions
+
+It is especially useful for platform teams, agencies, and multi-project organizations that need consistent deploy behavior across many Nuxt services.
+
+## Ecosystem Context
+
+On July 8, 2025, Vercel announced that NuxtLabs (maintainers of Nuxt, Nitro, and NuxtHub) joined Vercel.
+
+Nuxt remains open and deployable across providers, and many teams continue choosing Cloudflare for edge runtime, networking, and data products.
+This module is built for that Cloudflare-first path: explicit Workers deploy control, reproducible CI, and infrastructure outputs you can audit in git.
+
+## Cloudflare-First Strategy Fit
+
+If your application stack is already centered on Cloudflare capabilities, deployment should follow the same model.
+This module aligns deploy orchestration with that direction:
+
+- compute at the edge with Workers
+- domain/routing control through Cloudflare
+- environment-aware Wrangler deploy targets
+- CI-driven releases with explicit branch promotion rules
+
+For teams standardizing on Cloudflare services like KV, R2, D1, Queues, or Durable Objects, keeping deploy control in-repo reduces cross-platform glue code and makes operational ownership clearer.
+
+## What Problems It Solves
+
+- Manual deploy config drift between app config, Wrangler, and CI
+- Fragile branch deploy logic spread across copy-pasted workflow files
+- Inconsistent install/build/deploy commands between package managers
+- Hard-to-review infrastructure changes hidden in manual dashboard edits
+- Growing operational overhead as environments and branches increase
+
+## What It Generates
+
+On every Nuxt setup build (`npx run dev`, `npx nuxt prepare`, `npx nuxt build`), the module rewrites:
+
+- `wrangler.toml`
+- `.github/workflows/deploy.yml`
+
+This keeps Cloudflare config and GitHub Actions deploy automation in sync.
+
+
+## Full configuration options example
+
+```ts
+export default defineNuxtConfig({
+  modules: ['cf-deployment'],
+  cfDeployment: {
+    // Required name - Used as the `name` field in `wrangler.toml` and as a prefix for environment names.
+    appName: 'my-app',
+    
+    // Required at least one environment - Each item generates a Wrangler environment and GitHub Actions deploy step.
+    environments: [
+      
+      // Your primary environment, deploying from the main branch to the root domain.
+      { branch: 'main', url: 'app.example.com', samplingRate: 0.2 }, 
+      
+      // Optional additional environments
+      { branch: 'staging', url: 'staging.app.example.com', samplingRate: 1 }, 
+      
+      // Optional additional environments
+      { branch: 'feature-1', url: 'feature-1.app.example.com'}, 
+    ],
+    
+    // Optional [npm, pnpm, yarn]; default: 'npm' - Control how GitHub Actions install and deploy your app
+    packageManager: 'npm', 
+    
+    // Optional - Control the Node version used in GitHub Actions; default: '24'
+    nodeVersion: '24', 
+
+  },
+})
+```
+
+
+
+
+## Configuration
+
+Set options under `cfDeployment` in `nuxt.config.ts`.
+
+| Option | Required | Used in | Behavior |
+| --- | --- | --- | --- |
+| `appName` | No | `wrangler.toml` | Sets top-level `name` and prefixes each environment `name` |
+| `environments` | No | Both | Drives Wrangler env blocks and workflow branch deploy targets |
+| `environments[].branch` | Yes (per entry) | Both | Source branch and env key input |
+| `environments[].url` | Yes (per entry) | `wrangler.toml` | Route pattern input (`https://...` or `host/path`) |
+| `environments[].samplingRate` | No | `wrangler.toml` | Adds `[env.<name>.observability]` when valid (`0` to `1`) |
+| `packageManager` | No | `deploy.yml` | `npm`, `pnpm`, `yarn`; invalid or empty falls back to `npm` |
+| `nodeVersion` | No | `deploy.yml` | `actions/setup-node` version, default `24` |
+
+## Generated Workflow Behavior
+
+`deploy.yml` includes:
+
+- `push` trigger
+- Concurrency guard (`cancel-in-progress: true`)
+- `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` envs from GitHub secrets
+- Package-manager-specific install/build/deploy commands
+
+Branch behavior:
+
+- With valid `environments[]`, `on.push.branches` is generated from those branches.
+- Without valid `environments[]`, workflow runs on all pushes.
+- With valid `environments[]`, one deploy step is generated per branch using `wrangler deploy --env <environmentName>`.
+- Without valid `environments[]`, one generic deploy step is generated (`wrangler deploy`).
+
+
+
+## Important Edge Cases
+
+- Files are regenerated on each setup run; manual edits are overwritten.
+- Invalid environment entries (missing `branch` or `url`) are skipped.
+- Branch names are normalized for env keys: lowercased, non `[a-z0-9_]` characters become `_`.
+- Duplicate normalized env keys get suffixes (`main`, `main_2`, `main_3`, ...).
+- Route patterns remove scheme and trailing slash (`https://app.example.com/` -> `app.example.com`).
+
+
+## Roadmap
+- CF Resource binding generation (KV, R2, D1, Queues, Durable Objects)
+- Domain provisioning 
+- Rollback strategies
+- Improvement of internal files modularity and test coverage

package/dist/module.d.mts

@@ -0,0 +1,18 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface DeploymentEnvironmentInput {
+    branch: string;
+    url: string;
+    samplingRate?: number;
+}
+interface ModuleOptions {
+    packageManager?: string;
+    appName?: string;
+    environments?: DeploymentEnvironmentInput[];
+    nodeVersion?: string;
+}
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "@nuxtlib/cf-deployment",
+  "configKey": "cfDeployment",
+  "compatibility": {
+    "nuxt": ">=3.0.0 <5.0.0"
+  },
+  "version": "1.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,309 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { defineNuxtModule, useLogger } from '@nuxt/kit';
+
+const DEFAULT_WORKFLOW_NAME = "Deploy to Cloudflare Workers";
+const DEFAULT_WORKFLOW_PATH = ".github/workflows/deploy.yml";
+const DEFAULT_NODE_VERSION = "24";
+const DEFAULT_PACKAGE_MANAGER = "npm";
+
+const DEFAULT_APP_NAME = "my-nuxt-app";
+const DEFAULT_COMPATIBILITY_DATE = "2025-12-01";
+const DEFAULT_ROUTE = "app.example.com";
+
+function isCompleteEnvironment(environment) {
+  return Boolean(
+    typeof environment === "object" && environment && "branch" in environment && "url" in environment && typeof environment.branch === "string" && typeof environment.url === "string" && environment.branch.trim() && environment.url.trim()
+  );
+}
+function normalizeRoutePattern(input, fallback = DEFAULT_ROUTE) {
+  if (!input?.trim()) {
+    return fallback;
+  }
+  const rawValue = input.trim();
+  const urlValue = /^[a-z][\w+.-]*:\/\//i.test(rawValue) ? rawValue : `https://${rawValue}`;
+  try {
+    const parsedUrl = new URL(urlValue);
+    const normalizedPath = parsedUrl.pathname.replace(/\/+$/, "");
+    return `${parsedUrl.host}${normalizedPath}`;
+  } catch {
+    return rawValue.replace(/^[a-z][\w+.-]*:\/\//i, "").replace(/\/+$/, "");
+  }
+}
+function toEnvironmentName(branch) {
+  const normalized = branch.trim().toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+  return normalized || "env";
+}
+function toSamplingRate(value) {
+  if (typeof value !== "number" || Number.isNaN(value) || !Number.isFinite(value)) {
+    return void 0;
+  }
+  if (value < 0 || value > 1) {
+    return void 0;
+  }
+  return value;
+}
+function resolveEnvironments(environments, fallbackRoute = DEFAULT_ROUTE) {
+  const validEnvironments = (environments ?? []).filter(isCompleteEnvironment);
+  const usedEnvironmentNames = /* @__PURE__ */ new Set();
+  return validEnvironments.map((environment) => {
+    const branch = environment.branch.trim();
+    const routePattern = normalizeRoutePattern(environment.url, fallbackRoute);
+    const samplingRate = toSamplingRate(environment.samplingRate);
+    let name = toEnvironmentName(branch);
+    if (usedEnvironmentNames.has(name)) {
+      let suffix = 2;
+      while (usedEnvironmentNames.has(`${name}_${suffix}`)) {
+        suffix += 1;
+      }
+      name = `${name}_${suffix}`;
+    }
+    usedEnvironmentNames.add(name);
+    return {
+      branch,
+      name,
+      routePattern,
+      samplingRate
+    };
+  });
+}
+
+const WORKFLOW_PACKAGE_MANAGERS = ["npm", "pnpm", "yarn"];
+function normalizePackageManager(input) {
+  if (!input?.trim()) {
+    return DEFAULT_PACKAGE_MANAGER;
+  }
+  const normalized = input.trim().toLowerCase();
+  return WORKFLOW_PACKAGE_MANAGERS.includes(normalized) ? normalized : DEFAULT_PACKAGE_MANAGER;
+}
+function normalizeNodeVersion(input) {
+  return input?.trim() || DEFAULT_NODE_VERSION;
+}
+function resolveWorkflowTargets(environments) {
+  return resolveEnvironments(environments).map((environment) => ({
+    branch: environment.branch,
+    environmentName: environment.name
+  }));
+}
+function resolveWorkflowOptions(options) {
+  return {
+    packageManager: normalizePackageManager(options.packageManager),
+    nodeVersion: normalizeNodeVersion(options.nodeVersion),
+    targets: resolveWorkflowTargets(options.environments)
+  };
+}
+
+function escapeGithubExpressionString(value) {
+  return value.replaceAll("'", "''");
+}
+function getWorkflowHeaderBlock(branches) {
+  const lines = [
+    "# Generated by @nuxtlib/deployment-cf-workers",
+    `name: ${DEFAULT_WORKFLOW_NAME}`,
+    "",
+    "on:",
+    "  push:"
+  ];
+  if (branches.length > 0) {
+    lines.push("    branches:");
+    for (const branch of branches) {
+      lines.push(`      - ${branch}`);
+    }
+  }
+  lines.push(
+    "",
+    "concurrency:",
+    "  group: deploy-${{ github.workflow }}-${{ github.ref }}",
+    "  cancel-in-progress: true",
+    "",
+    "jobs:",
+    "  deploy:",
+    "    runs-on: ubuntu-latest",
+    "",
+    "    env:",
+    "      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}",
+    "      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}",
+    "",
+    "    steps:",
+    "      - name: Checkout",
+    "        uses: actions/checkout@v4"
+  );
+  return lines.join("\n");
+}
+function getBuildStepsBlock(packageManager, nodeVersion) {
+  if (packageManager === "pnpm") {
+    return [
+      "      - name: Install pnpm",
+      "        uses: pnpm/action-setup@v4",
+      "        with:",
+      "          version: 10",
+      "",
+      "      - name: Setup Node",
+      "        uses: actions/setup-node@v4",
+      "        with:",
+      `          node-version: ${nodeVersion}`,
+      "          cache: pnpm",
+      "          cache-dependency-path: pnpm-lock.yaml",
+      "",
+      "      - name: Install deps",
+      "        run: pnpm install --frozen-lockfile",
+      "",
+      "      - name: Build Nuxt app",
+      "        run: pnpm run build"
+    ].join("\n");
+  }
+  if (packageManager === "yarn") {
+    return [
+      "      - name: Setup Node",
+      "        uses: actions/setup-node@v4",
+      "        with:",
+      `          node-version: ${nodeVersion}`,
+      "          cache: yarn",
+      "          cache-dependency-path: yarn.lock",
+      "",
+      "      - name: Install deps",
+      "        run: yarn install --frozen-lockfile",
+      "",
+      "      - name: Build Nuxt app",
+      "        run: yarn build"
+    ].join("\n");
+  }
+  return [
+    "      - name: Setup Node",
+    "        uses: actions/setup-node@v4",
+    "        with:",
+    `          node-version: ${nodeVersion}`,
+    "          cache: npm",
+    "          cache-dependency-path: package-lock.json",
+    "",
+    "      - name: Install deps",
+    "        run: npm ci",
+    "",
+    "      - name: Build Nuxt app",
+    "        run: npm run build"
+  ].join("\n");
+}
+function getDeployCommand(packageManager) {
+  if (packageManager === "pnpm") {
+    return "pnpm dlx wrangler deploy";
+  }
+  if (packageManager === "yarn") {
+    return "yarn dlx wrangler deploy";
+  }
+  return "npx wrangler deploy";
+}
+function getDeployStepsBlock(packageManager, targets) {
+  const deployCommand = getDeployCommand(packageManager);
+  if (targets.length === 0) {
+    return [
+      "      - name: Deploy to Cloudflare",
+      `        run: ${deployCommand}`
+    ].join("\n");
+  }
+  return targets.map((target) => {
+    const escapedBranch = escapeGithubExpressionString(target.branch);
+    return [
+      `      - name: Deploy to Cloudflare (${target.branch})`,
+      `        if: github.ref == 'refs/heads/${escapedBranch}'`,
+      `        run: ${deployCommand} --env ${target.environmentName}`
+    ].join("\n");
+  }).join("\n\n");
+}
+
+function renderWorkflowYaml(options) {
+  const resolvedOptions = resolveWorkflowOptions(options);
+  const branches = resolvedOptions.targets.map((target) => target.branch);
+  const lines = [
+    getWorkflowHeaderBlock(branches),
+    "",
+    getBuildStepsBlock(resolvedOptions.packageManager, resolvedOptions.nodeVersion),
+    "",
+    getDeployStepsBlock(resolvedOptions.packageManager, resolvedOptions.targets)
+  ];
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+function escapeTomlString(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+
+function getNoEnvironmentSection() {
+  return `
+# No environments found yet, so a default route is used.
+routes = [{ pattern = "${escapeTomlString(DEFAULT_ROUTE)}", custom_domain = true }]
+`.trim();
+}
+function getEnvironmentSection(appName, environment) {
+  const observabilityBlock = environment.samplingRate === void 0 ? "" : `
+
+[env.${environment.name}.observability]
+enabled = true
+head_sampling_rate = ${environment.samplingRate}
+`;
+  return `
+# Branch: ${environment.branch}
+[env.${environment.name}]
+name = "${escapeTomlString(`${appName}-${environment.name}`)}"
+routes = [
+  { pattern = "${escapeTomlString(environment.routePattern)}", custom_domain = true }
+]${observabilityBlock}
+`.trim();
+}
+function getHeaderBlock(appName) {
+  return `
+# Generated by @nuxtlib/deployment-cf-workers.
+# This file is generated from your \`cfDeployment\` module config.
+
+name = "${escapeTomlString(appName)}"
+main = ".output/server/index.mjs"
+compatibility_date = "${DEFAULT_COMPATIBILITY_DATE}"
+`.trim();
+}
+
+function renderWranglerToml(options) {
+  const appName = options.appName?.trim() || DEFAULT_APP_NAME;
+  const environments = resolveEnvironments(options.environments);
+  const headerBlock = getHeaderBlock(appName);
+  const lines = [headerBlock];
+  lines.push("");
+  if (environments.length === 0) {
+    lines.push(getNoEnvironmentSection());
+    return lines.join("\n").trimEnd() + "\n";
+  }
+  lines.push("# One block is generated for each item in `cfDeployment.environments`.");
+  lines.push("");
+  for (const environment of environments) {
+    lines.push(getEnvironmentSection(appName, environment));
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@nuxtlib/cf-deployment",
+    configKey: "cfDeployment",
+    compatibility: {
+      nuxt: ">=3.0.0 <5.0.0"
+    }
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {},
+  // This setup function is here to generate deployment config during Nuxt setup.
+  // It renders `wrangler.toml` from `cfDeployment` options and writes it to the project root.
+  // We need this so deploy settings stay in sync with app config every time setup runs.
+  async setup(options, nuxt) {
+    const logger = useLogger("@nuxtlib/cf-deployment");
+    const wranglerPath = resolve(nuxt.options.rootDir, "wrangler.toml");
+    const workflowPath = resolve(nuxt.options.rootDir, DEFAULT_WORKFLOW_PATH);
+    const wranglerContent = renderWranglerToml(options);
+    await writeFile(wranglerPath, wranglerContent, "utf8");
+    logger.success(`Generated wrangler.toml at ${wranglerPath}`);
+    const workflowContent = renderWorkflowYaml(options);
+    await mkdir(dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, workflowContent, "utf8");
+    logger.success(`Generated workflow file at ${workflowPath}`);
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nuxtlib/cf-deployment",
+  "version": "1.0.1",
+  "description": "A Nuxt module for Cloudflare Workers deployment with GitHub Actions integration.",
+  "repository": "https://github.com/nuxtlibv2/cf-deployment",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.3.1"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.1",
+    "@nuxt/eslint-config": "^1.15.1",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.3.1",
+    "@nuxt/test-utils": "^4.0.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.0.0",
+    "nuxt": "^4.3.1",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18",
+    "vue-tsc": "^3.2.4"
+  }
+}