nuxt-safe-runtime-config 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 onmax
+
+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,185 @@
+# Nuxt Safe Runtime Config
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Validate Nuxt runtime config at build time using **Zod**, **Valibot**, **ArkType**, or any Standard Schema compatible library.
+
+- [✨  Release Notes](/CHANGELOG.md)
+
+## Features
+
+- 🔒  Validate runtime config at build time with **Zod**, **Valibot**, **ArkType**, and more
+- 🚀  Works with any [Standard Schema](https://standardschema.dev/) compatible library
+- 🛠  Only runs during dev/build/generate phases
+- ⚡  Zero runtime overhead - validation happens at build time only
+- 📝  Does not modify your runtime config or types - only validates them
+
+## Quick Setup
+
+Install the module to your Nuxt application with one command:
+
+```bash
+npx nuxi module add nuxt-safe-runtime-config
+```
+
+## Usage
+
+1. Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['nuxt-safe-runtime-config']
+})
+```
+
+2. Define your runtime config schema using **Valibot**, **Zod**, **ArkType**, or any other Standard Schema compatible library:
+
+### With Valibot
+
+```typescript
+import { number, object, optional, string } from 'valibot'
+
+const runtimeConfigSchema = object({
+  public: object({
+    apiBase: string(),
+    appName: optional(string()),
+  }),
+  databaseUrl: string(),
+  secretKey: string(),
+  port: optional(number()),
+})
+```
+
+### With Zod
+
+```typescript
+import { z } from 'zod'
+
+const runtimeConfigSchema = z.object({
+  public: z.object({
+    apiBase: z.string(),
+    appName: z.string().optional(),
+  }),
+  databaseUrl: z.string(),
+  secretKey: z.string(),
+  port: z.number().optional(),
+})
+```
+
+### With ArkType
+
+```typescript
+import { type } from 'arktype'
+
+const runtimeConfigSchema = type({
+  'public': {
+    'apiBase': 'string',
+    'appName?': 'string'
+  },
+  'databaseUrl': 'string',
+  'secretKey': 'string',
+  'port?': 'number'
+})
+```
+
+3. Configure your Nuxt app:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['nuxt-safe-runtime-config'],
+
+  // Your regular runtime config
+  runtimeConfig: {
+    databaseUrl: process.env.DATABASE_URL || 'postgresql://localhost:5432/mydb',
+    secretKey: process.env.SECRET_KEY || 'default-secret-key',
+    port: Number.parseInt(process.env.PORT || '3000'),
+    public: {
+      apiBase: process.env.PUBLIC_API_BASE || 'https://api.example.com',
+      appName: 'My Nuxt App',
+    },
+  },
+
+  // Add your schema for validation
+  safeRuntimeConfig: {
+    $schema: runtimeConfigSchema,
+  },
+})
+```
+
+The module will validate your runtime config against the schema during:
+
+- `nuxi dev` (development mode)
+- `nuxi build`
+- `nuxi generate`
+
+If validation fails, the build process will stop with detailed error messages.
+
+## Important Notes
+
+**This module only validates your runtime config - it does not modify it.** Your native `runtimeConfig` remains unchanged, and no TypeScript types are modified. The module simply ensures that your runtime configuration matches your schema at build time, helping you catch configuration errors early in the development process.
+
+## Error Messages
+
+When validation fails, you'll see detailed error messages like:
+
+```
+Safe Runtime Config: Validation failed!
+  1. databaseUrl: This field is required
+  2. public.apiBase: Expected string, received undefined
+  3. port: Expected number, received string
+```
+
+The module will stop the build process until all validation errors are resolved.
+
+## Why This Module?
+
+I wanted to use **Valibot** for runtime config validation, but Nuxt doesn't currently support Standard Schema. While Nuxt has its own schema validation system, it's primarily designed for module authors and broader Nuxt configuration.
+
+This module focuses specifically on **runtime config validation** using the Standard Schema specification, allowing you to use your preferred validation library (Valibot, Zod, ArkType, etc.).
+
+The goal is to eventually make Standard Schema a first-class citizen in Nuxt. If this module gains enough adoption, I plan to create a PR to add `standardSchema` support to Nuxt core.
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+
+```bash
+# Install dependencies
+pnpm install
+
+# Generate type stubs
+pnpm run dev:prepare
+
+# Develop with the playground
+pnpm run dev
+
+# Build the playground
+pnpm run dev:build
+
+# Run ESLint
+pnpm run lint
+
+# Run Vitest
+pnpm run test
+pnpm run test:watch
+
+# Release new version
+pnpm run release
+```
+
+</details>
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-safe-runtime-config/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-safe-runtime-config
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-safe-runtime-config.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-safe-runtime-config
+[license-src]: https://img.shields.io/npm/l/nuxt-safe-runtime-config.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-safe-runtime-config
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,10 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+interface ModuleOptions {
+    $schema: StandardSchemaV1;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-safe-runtime-config",
+  "configKey": "safeRuntimeConfig",
+  "version": "0.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.1",
+    "unbuild": "3.5.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,59 @@
+import { defineNuxtModule } from '@nuxt/kit';
+import { consola } from 'consola';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-safe-runtime-config",
+    configKey: "safeRuntimeConfig"
+  },
+  defaults: {
+    $schema: void 0
+    // No default schema, users must provide their own
+  },
+  setup(options, nuxt) {
+    if (!options.$schema)
+      return;
+    if (nuxt.options.dev) {
+      nuxt.hook("modules:done", async () => {
+        await validateRuntimeConfig(nuxt, options);
+      });
+      return;
+    }
+    nuxt.hook("build:done", async () => {
+      await validateRuntimeConfig(nuxt, options);
+    });
+  }
+});
+async function validateRuntimeConfig(nuxt, options) {
+  const schemaConfig = options.$schema;
+  if (!schemaConfig)
+    return;
+  try {
+    const runtimeConfig = nuxt.options.runtimeConfig || {};
+    if (!isStandardSchema(schemaConfig)) {
+      consola.error("Safe Runtime Config: Schema is not Standard Schema compatible");
+      return;
+    }
+    const result = await schemaConfig["~standard"].validate(runtimeConfig);
+    if ("issues" in result && result.issues && result.issues.length > 0) {
+      consola.error("Safe Runtime Config: Validation failed!");
+      result.issues.forEach((issue, index) => {
+        consola.error(`  ${index + 1}. ${formatIssue(issue)}`);
+      });
+      throw new Error("Runtime config validation failed");
+    }
+    consola.success("Validated Runtime Config");
+  } catch (error) {
+    consola.error("Safe Runtime Config: Validation error:", error);
+    throw error;
+  }
+}
+function isStandardSchema(schema) {
+  return schema && typeof schema === "object" && "~standard" in schema && typeof schema["~standard"] === "object" && typeof schema["~standard"].validate === "function";
+}
+function formatIssue(issue) {
+  const path = issue.path ? issue.path.map((p) => p.key || p).join(".") : "root";
+  return `${path}: ${issue.message || "Validation error"}`;
+}
+
+export { module as default };

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,3 @@
+import { defineNuxtPlugin } from "#app";
+export default defineNuxtPlugin((_nuxtApp) => {
+});

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,84 @@
+{
+  "name": "nuxt-safe-runtime-config",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Validate Nuxt runtime config with Standard Schema at build time",
+  "author": {
+    "name": "onmax"
+  },
+  "license": "MIT",
+  "repository": "onmax/nuxt-safe-runtime-config",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "runtime-config",
+    "validation",
+    "standard-schema",
+    "valibot",
+    "zod",
+    "arktype",
+    "build-time"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^3.17.4",
+    "@standard-schema/spec": "^1.0.0",
+    "consola": "^3.4.2"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^4.13.3",
+    "@antfu/ni": "^25.0.0",
+    "@nuxt/devtools": "^2.4.1",
+    "@nuxt/eslint": "^1.4.1",
+    "@nuxt/eslint-config": "^1.4.1",
+    "@nuxt/module-builder": "^1.0.1",
+    "@nuxt/schema": "^3.17.4",
+    "@nuxt/test-utils": "^3.19.1",
+    "@types/node": "latest",
+    "bumpp": "^10.1.1",
+    "changelogen": "^0.6.1",
+    "eslint": "^9.28.0",
+    "eslint-plugin-format": "^1.0.1",
+    "lint-staged": "^16.1.0",
+    "nuxt": "^3.17.4",
+    "simple-git-hooks": "^2.13.0",
+    "typescript": "~5.8.3",
+    "valibot": "^1.1.0",
+    "vitest": "^3.2.0",
+    "vue-tsc": "^2.2.10"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  },
+  "scripts": {
+    "dev": "nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground && pnpm -C test/fixtures/validation-failure prepare && pnpm -C test/fixtures/validation-success prepare",
+    "release": "nr lint && nr typecheck && nr test && nr prepack && bumpp && pnpm publish",
+    "typecheck": "nuxt typecheck && pnpm -C playground typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  }
+}