{"id":39002453,"url":"https://github.com/onmax/nuxt-safe-runtime-config","last_synced_at":"2026-01-17T17:13:05.744Z","repository":{"id":297179391,"uuid":"995934486","full_name":"onmax/nuxt-safe-runtime-config","owner":"onmax","description":"Validate Nuxt runtime config using Zod, Valibot, ArkType... any Standard Schema library","archived":false,"fork":false,"pushed_at":"2026-01-02T13:34:13.000Z","size":195,"stargazers_count":26,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T00:22:54.259Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-04T08:08:57.000Z","updated_at":"2026-01-05T20:39:24.000Z","dependencies_parsed_at":"2026-01-01T16:08:26.124Z","dependency_job_id":null,"html_url":"https://github.com/onmax/nuxt-safe-runtime-config","commit_stats":null,"previous_names":["onmax/nuxt-safe-runtime-config"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/onmax/nuxt-safe-runtime-config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnuxt-safe-runtime-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnuxt-safe-runtime-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnuxt-safe-runtime-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnuxt-safe-runtime-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onmax","download_url":"https://codeload.github.com/onmax/nuxt-safe-runtime-config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnuxt-safe-runtime-config/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28512063,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T17:13:03.800Z","updated_at":"2026-01-17T17:13:05.726Z","avatar_url":"https://github.com/onmax.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg alt=\"Nuxt safe runtime config logo\" loading=\"lazy\" width=\"50\" height=\"50\" decoding=\"async\" data-nimg=\"1\" style=\"color:transparent\" src=\"https://raw.githubusercontent.com/onmax/nuxt-safe-runtime-config/refs/heads/main/.github/logo.svg\" /\u003e\n  \u003c/br\u003e\n  Nuxt Safe Runtime Config\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\nValidate Nuxt runtime config at build time using \u003cb\u003eZod\u003c/b\u003e, \u003cb\u003eValibot\u003c/b\u003e, \u003cb\u003eArkType\u003c/b\u003e, or any Standard Schema compatible library.\n\u003c/p\u003e\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/nuxt-safe-runtime-config\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/nuxt-safe-runtime-config.svg\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/nuxt-safe-runtime-config\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dm/nuxt-safe-runtime-config.svg\" alt=\"npm downloads\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/onmax/nuxt-safe-runtime-config/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/onmax/nuxt-safe-runtime-config.svg\" alt=\"License\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://nuxt.com\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Nuxt-3.0+-00DC82.svg\" alt=\"Nuxt\" /\u003e\n  \u003c/a\u003e\n\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/nuxt/nuxt/discussions/32301\"\u003e\n      🔗 Related Nuxt RFC: Enable Standard Schema Validation in Nuxt Config\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## Features\n\n- 🔒 **Build-time validation** with Zod, Valibot, ArkType, or any [Standard Schema](https://standardschema.dev/) library\n- 🚀 **Runtime validation** (opt-in) validates config when the server starts\n- ✨ **Auto-generated types** — `useSafeRuntimeConfig()` is fully typed without manual generics\n- 🛠 **ESLint plugin** warns when using `useRuntimeConfig()` instead of the type-safe composable\n- ⚡ **Zero runtime overhead** by default — validation happens at build time only\n\n## Quick Setup\n\nInstall the module:\n\n```bash\nnpx nuxi module add nuxt-safe-runtime-config\n```\n\n## Usage\n\n### 1. Define your schema\n\nUse Zod, Valibot, ArkType, or any Standard Schema compatible library:\n\n\u003cdetails\u003e\n\u003csummary\u003eWith Valibot\u003c/summary\u003e\n\n```typescript\nimport { number, object, optional, string } from 'valibot'\n\nconst runtimeConfigSchema = object({\n  public: object({\n    apiBase: string(),\n    appName: optional(string()),\n  }),\n  databaseUrl: string(),\n  secretKey: string(),\n  port: optional(number()),\n})\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWith Zod\u003c/summary\u003e\n\n```typescript\nimport { z } from 'zod'\n\nconst runtimeConfigSchema = z.object({\n  public: z.object({\n    apiBase: z.string(),\n    appName: z.string().optional(),\n  }),\n  databaseUrl: z.string(),\n  secretKey: z.string(),\n  port: z.number().optional(),\n})\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWith ArkType\u003c/summary\u003e\n\n```typescript\nimport { type } from 'arktype'\n\nconst runtimeConfigSchema = type({\n  'public': {\n    'apiBase': 'string',\n    'appName?': 'string'\n  },\n  'databaseUrl': 'string',\n  'secretKey': 'string',\n  'port?': 'number'\n})\n```\n\n\u003c/details\u003e\n\n### 2. Configure in nuxt.config.ts\n\n```typescript\nexport default defineNuxtConfig({\n  modules: ['nuxt-safe-runtime-config'],\n\n  runtimeConfig: {\n    databaseUrl: process.env.DATABASE_URL || 'postgresql://localhost:5432/mydb',\n    secretKey: process.env.SECRET_KEY || 'default-secret-key',\n    port: Number.parseInt(process.env.PORT || '3000'),\n    public: {\n      apiBase: process.env.PUBLIC_API_BASE || 'https://api.example.com',\n      appName: 'My Nuxt App',\n    },\n  },\n\n  safeRuntimeConfig: {\n    $schema: runtimeConfigSchema,\n  },\n})\n```\n\n### 3. Use the type-safe composable\n\nAccess your validated config with full type safety — types are auto-generated from your schema:\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nconst config = useSafeRuntimeConfig()\n// config.public.apiBase is typed as string\n// config.secretKey is typed as string\n\u003c/script\u003e\n```\n\n## Configuration Options\n\n| Option              | Type                            | Default           | Description                                |\n| ------------------- | ------------------------------- | ----------------- | ------------------------------------------ |\n| `$schema`           | `StandardSchemaV1`              | —                 | Your validation schema (required)          |\n| `validateAtBuild`   | `boolean`                       | `true`            | Validate during dev/build                  |\n| `validateAtRuntime` | `boolean`                       | `false`           | Validate when server starts                |\n| `onBuildError`      | `'throw' \\| 'warn' \\| 'ignore'` | `'throw'`         | How to handle build validation errors      |\n| `onRuntimeError`    | `'throw' \\| 'warn' \\| 'ignore'` | `'throw'`         | How to handle runtime validation errors    |\n| `logSuccess`        | `boolean`                       | `true`            | Log successful validation                  |\n| `logFallback`       | `boolean`                       | `true`            | Log when using JSON Schema fallback        |\n| `jsonSchemaTarget`  | `string`                        | `'draft-2020-12'` | JSON Schema version for runtime validation |\n\n## Runtime Validation\n\nBy default, validation only runs at build time. Enable runtime validation to catch environment variable issues when the server starts:\n\n```ts\nexport default defineNuxtConfig({\n  safeRuntimeConfig: {\n    $schema: runtimeConfigSchema,\n    validateAtRuntime: true,\n  },\n})\n```\n\nRuntime validation uses [@cfworker/json-schema](https://github.com/cfworker/cfworker/tree/main/packages/json-schema) to validate the config after environment variables are merged. This lightweight validator (~8KB) works on all runtimes including edge (Cloudflare Workers, Vercel Edge, Netlify Edge). It catches issues like:\n\n- Environment variables with wrong types (e.g., `NUXT_PORT=abc` when expecting a number)\n- Missing required environment variables in production\n- Invalid values that pass build-time checks but fail at runtime\n\n## ESLint Integration\n\nThe module includes an ESLint plugin that warns when using `useRuntimeConfig()` instead of `useSafeRuntimeConfig()`.\n\n### With @nuxt/eslint (Automatic)\n\nIf you use [@nuxt/eslint](https://eslint.nuxt.com), the rule is auto-registered. No configuration needed.\n\n### Manual Setup\n\nAdd to your `eslint.config.mjs`:\n\n```javascript\nimport { configs } from 'nuxt-safe-runtime-config/eslint'\n\nexport default [\n  configs.recommended,\n  // ... your other configs\n]\n```\n\nOr configure manually:\n\n```javascript\nimport plugin from 'nuxt-safe-runtime-config/eslint'\n\nexport default [\n  {\n    plugins: { 'safe-runtime-config': plugin },\n    rules: { 'safe-runtime-config/prefer-safe-runtime-config': 'warn' },\n  },\n]\n```\n\nThe rule includes auto-fix support — run `eslint --fix` to automatically replace `useRuntimeConfig()` calls.\n\n## Type Safety\n\nTypes are auto-generated at build time from your schema's JSON Schema representation. The `useSafeRuntimeConfig()` composable returns a fully typed object — no manual generics needed:\n\n```ts\nconst config = useSafeRuntimeConfig()\n// config is fully typed based on your schema\n```\n\nGenerated types are stored in `.nuxt/types/safe-runtime-config.d.ts` and automatically included in your project.\n\n## Error Messages\n\nWhen validation fails, you see detailed error messages:\n\n```\n[safe-runtime-config] Validation failed!\n  1. databaseUrl: Invalid type: Expected string but received undefined\n  2. public.apiBase: Invalid type: Expected string but received undefined\n  3. port: Invalid type: Expected number but received string\n```\n\nThe module stops the build process until all validation errors are resolved.\n\n## Why This Module?\n\nNuxt's built-in schema validation is designed for module authors and broader configuration. This module focuses specifically on **runtime config validation** using Standard Schema, allowing you to:\n\n- Use your preferred validation library (Valibot, Zod, ArkType)\n- Catch configuration errors at build time\n- Optionally validate at runtime for environment variable issues\n- Get full type safety in your components\n\n## Contribution\n\n\u003cdetails\u003e\n  \u003csummary\u003eLocal development\u003c/summary\u003e\n\n```bash\n# Install dependencies\npnpm install\n\n# Generate type stubs\npnpm run dev:prepare\n\n# Develop with the playground\npnpm run dev\n\n# Build the playground\npnpm run dev:build\n\n# Run ESLint\npnpm run lint\n\n# Run Vitest\npnpm run test\npnpm run test:watch\n\n# Release new version\npnpm run release\n```\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Fnuxt-safe-runtime-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonmax%2Fnuxt-safe-runtime-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Fnuxt-safe-runtime-config/lists"}