feat: support observability and additional bindings (#549)

Author: RihanArfan

docs/content/changelog/observability-additional-bindings.md

@@ -0,0 +1,86 @@
+---
+title: Worker Logs & Additional Bindings
+description: "Support for Worker Logs and adding additional bindings for Worker projects."
+date: 2025-04-18
+image: '/images/changelog/nuxthub-workers-observability.png'
+category: Core
+authors:
+  - name: Rihan Arfan
+    avatar:
+      src: https://avatars.githubusercontent.com/u/20425781?v=4
+    to: https://bsky.app/profile/rihan.dev
+    username: rihan.dev
+---
+
+::tip
+This feature is available from [`@nuxthub/core >= v0.10.0`](https://github.com/nuxt-hub/core/releases/tag/v0.10.0)
+::
+
+Worker projects on NuxtHub can now enable Worker Logs, and associate additional bindings to deployments all from within the NuxtHub config. This opens the possibility of adding additional [databases](https://developers.cloudflare.com/d1/worker-api/), [R2 buckets](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/), [service bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/), [rate limiting](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/), [queues](https://developers.cloudflare.com/queues/configuration/javascript-apis/) and [more](https://developers.cloudflare.com/workers/runtime-apis/bindings/) to projects.
+
+## Worker Logs
+
+Workers Logs lets you automatically collect, store, filter, and analyze logging data emitted from your Nuxt app. Currently, you can query it in the dashboard for each of your Workers projects within the Cloudflare Dashboard.
+
+Logs include [invocation logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/#invocation-logs), [custom logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/#custom-logs), errors, and uncaught exceptions.
+
+::callout{to="/docs/getting-started/server-logs#cloudflare-dashboard" icon="i-lucide-book"}
+Learn more about enabling Worker Logs.
+::
+
+![Observability Overview](/images/docs/observability-overview.png)
+
+Enable Worker Logs within `hub.bindings.observability.logs` in your `nuxt.config.ts`.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  hub: {
+    bindings: {
+      observability: {
+        // enable with default settings
+        logs: true,
+
+        // customise settings
+        logs: {
+          head_sampling_rate: 0.5,
+          invocation_logs: false
+        }
+      }
+    }
+  },
+```
+
+## Additional bindings
+
+Additional bindings can be configured within `hub.bindings` in your `nuxt.config.ts`. All options are suggested via IntelliSense, however, you can refer to [Cloudflare's API documentation](https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/versions/methods/create/#(params)%200%20%3E%20(param)%20metadata%20%3E%20(schema)%20%3E%20(property)%20bindings) too.
+
+Resources for additional bindings are not provisioned automatically like they are with NuxtHub features such as `hub.database`. You will need to create the resources manually from the Cloudflare dashboard.
+
+::callout{to="/docs/features/additional-bindings" icon="i-lucide-book"}
+Learn more about assigning additional bindings.
+::
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  hub: {
+    bindings: {
+      // <binding type>: {
+      //   <BINDING NAME>: {
+      //     // binding options
+      //   }
+      // }
+
+      // additional cloudflare bindings
+      analytics_engine: {
+        ANALYTICS_TESTING: {
+          dataset: 'testing'
+        }
+      },
+      mtls_certificate: {
+        CERT: {
+          certificate_id: '<CERTIFICATE_ID>'
+        }
+      }
+    }
+  },
+```

docs/content/docs/1.getting-started/5.server-logs.md

@@ -5,13 +5,13 @@ description: Access real-time logs of your deployed Nuxt application.
 
 ## NuxtHub Admin
 
-When you have a successful deployment, you can access to the logs of the deployment in the [NuxtHub Admin](https://admin.hub.nuxt.com/).  
+When you have a successful deployment, you can access to the logs of the deployment in the [NuxtHub Admin](https://admin.hub.nuxt.com/).
 
 Logs are available under the `Server > Logs` section of your project page. You can also access to the logs of each successful deployment in the `Deployments` section.
 
 :img{src="/images/landing/nuxthub-admin-server-logs.png" alt="NuxtHub Admin Server Logs" width="915" height="515" data-zoom-src="/images/landing/nuxthub-admin-server-logs.png" class="rounded"}
 
-## NuxtHub CLI 
+## NuxtHub CLI
 
 Using the [NuxtHub CLI](https://github.com/nuxt-hub/cli), you can access to the logs of both `production` and `preview` deployments.
 
@@ -38,3 +38,53 @@ In preview environment, NuxtHub will stream the logs of the latest successful de
 ```bash [Terminal]
 npx nuxthub logs --preview
 ```
+
+## Cloudflare Dashboard
+
+Worker project types can enable Worker Logs and view the Workers Observability tab dashboard in Cloudflare. Learn more on the [Cloudflare documentation](https://developers.cloudflare.com/workers/observability/).
+
+![Observability Overview](/images/docs/observability-overview.png)
+
+::callout{to="https://dash.cloudflare.com/?to=/:account/workers/services/view/:worker/production/metrics/"}
+Go to the Workers Observability tab in the Cloudflare Dashboard
+::
+
+### Enable Worker Logs
+
+Enable Worker Logs within `hub.bindings.observability.logs` in your `nuxt.config.ts`.
+
+::field-group
+  ::field{name="observability" type="string"}
+    Observability settings
+    >
+    > ::field{name="logs" type="boolean | object"}
+    >   Enable Worker Logs with default configuration.<br><br>
+    >
+    >   Defaults to `head_sampling_rate: 1` and `invocation_logs: true`
+    > ::
+    >
+    > ::field{name="logs" type="boolean | object"}
+    >   Enable Worker Logs with custom configuration.
+    >
+    >   ::collapsible
+    >     ::field{name="head_sampling_rate" type="number"}
+    >       Head-based sampling allows you to log a percentage of incoming requests to your Nuxt app. Especially for high-traffic
+    >       applications, this helps reduce log volume and manage costs, while still providing meaningful insights into your application's
+    >       performance. When you configure a head-based sampling rate, you can control the percentage of requests that get logged.
+    >       All logs within the context  of the request are collected.<br><br>
+    >
+    >       To enable head-based sampling, set `head_sampling_rate` within the observability configuration.
+    >       The valid range is from 0 to 1, where 0 indicates zero out of one hundred requests are logged, and 1 indicates
+    >       every request is logged. If `head_sampling_rate` is unspecified, it is configured to a default value of 1 (100%).
+    >        In the example below, `head_sampling_rate` is set to 0.01, which > means one out of every one hundred requests is logged.
+    >     ::
+    >
+    >     ::field{name="invocation_logs" type="boolean?"}
+    >       Each Workers invocation returns a single invocation log that contains details such as the Request, Response, and related metadata. These invocation logs can be identified by the field $cloudflare.$metadata.type = "cf-worker-event". Each invocation log is enriched with information available to Cloudflare in the context of the invocation.<br><br>
+    >
+    >       In the Workers Logs UI, logs are presented with a localized timestamp and a message. The message is dependent on the invocation handler. For example, Fetch requests will have a message describing the request method and the request URL, while cron events will be listed as cron. Below is a list of invocation handlers along with their invocation message.
+    >     ::
+    >   ::
+    > ::
+  ::
+::

docs/content/docs/2.features/additional-bindings.md

@@ -0,0 +1,96 @@
+---
+title: Additional features
+navigation.title: Additional
+description: Add additional Cloudflare resource bindings to deployments
+---
+
+Cloudflare offer additional resources that aren't directly supported in NuxtHub yet. You can add bindings to associate these resources to your NuxtHub project. Custom bindings can be configured within `hub.bindings` in your `nuxt.config.ts`.
+
+Additional bindings are not provisioned automatically like they are with NuxtHub features such as [`hub.database`](/docs/features/database). You will need to create the resources manually from the Cloudflare dashboard or [wrangler](https://developers.cloudflare.com/workers/wrangler/commands/).
+
+You can add additional bindings to:
+- Add additional [D1 databases](https://developers.cloudflare.com/d1/worker-api/), [R2 buckets](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/) (blob), [KV namespaces](https://developers.cloudflare.com/kv/api/) & [analytics datasets](https://developers.cloudflare.com/analytics/analytics-engine/get-started/#2-write-data-points-from-your-worker)
+- or use [service bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/), [rate limiting](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/), [queues](https://developers.cloudflare.com/queues/configuration/javascript-apis/), and more
+
+::callout{to="https://developers.cloudflare.com/workers/runtime-apis/bindings/" icon="i-lucide-book"}
+View all available binding types on the Cloudflare documentation.
+::
+
+## Configuration
+
+Properties on `hub.bindings`
+
+::field-group
+  ::field{name="compatibilityDate" type="string"}
+    Set a custom compatibility date.
+    <br>Learn more on [Cloudflare's documentation](https://developers.cloudflare.com/workers/configuration/compatibility-dates/).
+  ::
+
+  ::field{name="compatibilityFlags" type="string" default="node_compat"}
+    Set additional compatibility flags, separated with a `space`.
+    <br>Learn more on [Cloudflare's documentation](https://developers.cloudflare.com/workers/configuration/compatibility-flags/).<br><br>
+
+    The [`nodejs_compat`](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) flag is always enabled.
+  ::
+
+  ::field{name="observability"}
+    Observability configurations. View all options on the [observability docs](/docs/getting-started/server-logs#cloudflare-dashboard).
+  ::
+
+  ::field{name="hyperdrive" type="object"}
+    Hyperdrive configuration. Learn more about Hyperdrive on the [PostgreSQL docs](/docs/recipes/postgres#hyperdrive).
+
+    > ::field{name="<BINDING NAME>" type="string"}
+    >   Binding name and Hyperdrive ID.
+    > ::
+  ::
+
+  ::field{name="<additional binding type>" type="object"}
+    Refer to [Cloudflare's API documentation](https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/versions/methods/create/#(params)%200%20%3E%20(param)%20metadata%20%3E%20(schema)%20%3E%20(property)%20bindings) to see a list of binding type names under `Body parameters` → `metadata` → `bindings`.
+
+
+    > ::field{name="<BINDING NAME>" type="object"}
+    >   Binding options (excluding properties `name` and `type`)
+    > ::
+  ::
+::
+
+::note
+Additional bindings are only available within Worker project types.
+::
+
+## Example
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  hub: {
+    bindings: {
+      // <binding type>: {
+      //   <BINDING NAME>: {
+      //     // binding options
+      //   }
+      // }
+
+      // additional cloudflare bindings
+      analytics_engine: {
+        ANALYTICS_TESTING: {
+          dataset: 'testing'
+        }
+      },
+      mtls_certificate: {
+        CERT: {
+          certificate_id: '<CERTIFICATE_ID>'
+        }
+      }
+    }
+  },
+```
+
+
+## Disallowed bindings
+Some bindings types cannot be added for certain features already handled by NuxtHub that do not have additional options, or already support multiple bindings. Refer to the table below.
+
+- `ai` → [`hub.ai`](/docs/features/ai)
+- `assets` → [`hub.workers`](/changelog/workers)
+- `browser_rendering` → [`hub.browser`](/docs/features/browser)
+- `vectorize` → [`hub.vectorize`](/docs/features/vectorize)

docs/content/docs/3.recipes/5.postgres.md

@@ -89,7 +89,7 @@ You may notice that we don't import `usePostgres()`. This is because Nuxt auto-i
 [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) is a Cloudflare service that accelerates queries you make to existing databases, making it faster to access your data from across the globe. By maintaining a connection pool to your database within Cloudflare’s network, Hyperdrive reduces seven round-trips to your database before you can even send a query: the TCP handshake (1x), TLS negotiation (3x), and database authentication (3x).
 
 ::important{to="https://developers.cloudflare.com/hyperdrive/platform/pricing/" target="_blank"}
-Hyperdrive is only available on the Workers Paid plan ($5/month), **learn more**.
+Hyperdrive is limited to 100,000 queries/day on the Workers Free plan. **Learn more**.
 ::
 
 To use Hyperdrive in your Nuxt application:

docs/content/index.yml

@@ -10,8 +10,8 @@ hero:
     light: '/images/landing/hero-light.svg'
     dark: '/images/landing/hero-dark.svg'
   headline:
-    label: "Deploy to Cloudflare Workers"
-    to: /changelog/workers
+    label: "Worker Logs & Additional Bindings"
+    to: /changelog/observability-additional-bindings
     icon: i-lucide-arrow-right
 features:
   - title: Cloud Hosting

docs/public/images/docs/observability-overview.png

@@ -21,7 +21,7 @@ export default defineNuxtConfig({
   },
   future: { compatibilityVersion: 4 },
 
-  compatibilityDate: '2025-01-22',
+  compatibilityDate: '2025-04-22',
 
   nitro: {
     // preset: 'cloudflare-durable',
@@ -47,12 +47,24 @@ export default defineNuxtConfig({
       }
     },
     bindings: {
-      compatibilityDate: '2024-11-18'
+      compatibilityDate: '2025-04-02',
+      observability: {
+        logs: true
+      }
       // compatibilityFlags: ['nodejs_compat']
       // Used for /api/hyperdrive
       // hyperdrive: {
       //   POSTGRES: '8bb2913857b84c939cd908740fa5a5d5'
       // }
+      // Custom bindings example
+      // version_metadata: {
+      //   VERSION: {}
+      // },
+      // analytics_engine: {
+      //   ANALYTICS2: {
+      //     dataset: 'testing'
+      //   }
+      // }
     }
     // projectUrl: ({ branch }) => branch === 'main' ? 'https://playground.nuxt.dev' : `https://${encodeHost(branch).replace(/\//g, '-')}.playground-to39.pages.dev`
   },