Add Nitro and Nuxt integration entries (#15)

Author: onmax

.agents/CONTEXT.md

@@ -0,0 +1,27 @@
+# Safe Runtime Config
+
+This context defines the project language for validating Nuxt and Nitro runtime configuration.
+
+## Language
+
+**Runtime validation**:
+Validation of the resolved server runtime config when Nitro starts.
+_Avoid_: startup validation, server validation
+
+**Build validation**:
+Validation of configured runtime config during Nuxt or Nitro build hooks.
+_Avoid_: compile-time validation, static validation
+
+## Relationships
+
+- **Runtime validation** happens after runtime environment values have been resolved.
+- **Build validation** happens before the server starts.
+
+## Example dialogue
+
+> **Dev:** "Should this failure be handled by **Build validation**?"
+> **Domain expert:** "No, it depends on the server's resolved environment, so it belongs to **Runtime validation**."
+
+## Flagged ambiguities
+
+- "runtime validation" means validation when Nitro starts, not validation inside the Vue app runtime.

.gitignore

@@ -18,6 +18,7 @@ dist
 *.tgz
 
 # Nuxt
+.nitro
 .nuxt
 .output
 .nuxtrc

README.md

@@ -286,6 +286,8 @@ Runtime validation uses [@cfworker/json-schema](https://github.com/cfworker/cfwo
 - Missing required environment variables in production
 - Invalid values that pass build-time checks but fail at runtime
 
+Shelve runtime fetching is separate from validation ownership. If `shelve.fetchAtRuntime` is enabled, the Shelve runtime plugin runs before validation so fetched secrets are included in the validated config.
+
 ## ESLint Integration
 
 The module includes an ESLint plugin that warns when using `useRuntimeConfig()` instead of `useSafeRuntimeConfig()`.

build.config.ts

@@ -1,9 +1,12 @@
 import { defineBuildConfig } from 'unbuild'
 
 export default defineBuildConfig({
-  entries: [{ input: 'src/eslint/index', name: 'eslint' }],
+  entries: [
+    { input: 'src/nitro', name: 'nitro' },
+    { input: 'src/eslint/index', name: 'eslint' },
+  ],
   declaration: true,
   clean: false,
   rollup: { emitCJS: false },
-  externals: ['@typescript-eslint/utils', '@typescript-eslint/types', 'eslint'],
+  externals: ['@nuxt/kit', '@typescript-eslint/utils', '@typescript-eslint/types', 'eslint'],
 })

docs/content/1.guide/4.validation.md

@@ -5,12 +5,14 @@ icon: ph:seal-check
 
 The module validates your runtime config to catch configuration errors early. By default, validation runs at build time only.
 
+Validation is handled by the package's Nitro module. In Nuxt apps, the Nuxt module exposes the user-facing API, types, and imports, then passes validation options into Nitro. Generated validation files are internal implementation details and their paths are not part of the public API.
+
 ## Build-time Validation (Default)
 
-With default settings, validation runs at:
+With default settings, build validation runs through Nitro during:
 
 - **Dev start** - when running `nuxt dev`
-- **Build completion** - when running `nuxt build`
+- **Build** - when running `nuxt build`
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
@@ -54,6 +56,8 @@ When enabled:
 2. A Nitro plugin validates `useRuntimeConfig()` on cold start
 3. Uses [@cfworker/json-schema](https://github.com/cfworker/cfworker/tree/main/packages/json-schema) (~8KB, edge-compatible)
 
+Shelve runtime fetching remains a separate integration. When `shelve.fetchAtRuntime` is enabled, that runtime fetch plugin runs before validation so fetched secrets can be validated.
+
 What it catches:
 
 - Missing env vars in production (`DATABASE_URL` not set)

eslint.config.mjs

@@ -13,5 +13,8 @@ export default antfu({
     'playground/shelve.json',
     'src/runtime/**/*.d.ts',
     'src/runtime/**/*.js',
+    'test/fixtures/**/.nitro/**',
+    'test/fixtures/**/.nuxt/**',
+    'test/fixtures/**/.output/**',
   ],
 })

package.json

@@ -24,14 +24,38 @@
   ],
   "sideEffects": false,
   "exports": {
-    ".": { "types": "./dist/types.d.mts", "import": "./dist/module.mjs" },
-    "./eslint": { "types": "./dist/eslint.d.mts", "import": "./dist/eslint.mjs" }
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./nuxt": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./nitro": {
+      "types": "./dist/nitro.d.mts",
+      "import": "./dist/nitro.mjs"
+    },
+    "./eslint": {
+      "types": "./dist/eslint.d.mts",
+      "import": "./dist/eslint.mjs"
+    }
   },
   "main": "./dist/module.mjs",
   "typesVersions": {
     "*": {
-      ".": ["./dist/types.d.mts"],
-      "eslint": ["./dist/eslint.d.mts"]
+      ".": [
+        "./dist/types.d.mts"
+      ],
+      "nuxt": [
+        "./dist/types.d.mts"
+      ],
+      "nitro": [
+        "./dist/nitro.d.mts"
+      ],
+      "eslint": [
+        "./dist/eslint.d.mts"
+      ]
     }
   },
   "files": [
@@ -56,10 +80,19 @@
   },
   "peerDependencies": {
     "@nuxt/kit": "^3.0.0 || ^4.0.0 || ^5.0.0-0",
-    "eslint": ">=9.0.0"
+    "eslint": ">=9.0.0",
+    "nitro": "^3.0.0-beta"
   },
   "peerDependenciesMeta": {
-    "eslint": { "optional": true }
+    "@nuxt/kit": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    },
+    "nitro": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@cfworker/json-schema": "catalog:",
@@ -93,6 +126,7 @@
     "eslint": "catalog:",
     "eslint-plugin-format": "catalog:",
     "lint-staged": "catalog:",
+    "nitro": "catalog:",
     "nuxt": "catalog:",
     "simple-git-hooks": "catalog:",
     "typescript": "catalog:",