{"id":13525255,"url":"https://github.com/fastify/env-schema","last_synced_at":"2025-05-14T21:06:25.702Z","repository":{"id":34160772,"uuid":"170855376","full_name":"fastify/env-schema","owner":"fastify","description":"Validate your env variables using Ajv and dotenv","archived":false,"fork":false,"pushed_at":"2025-05-01T09:17:03.000Z","size":183,"stargazers_count":237,"open_issues_count":4,"forks_count":28,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-01T10:25:52.948Z","etag":null,"topics":["environment","environment-variables","fastify-library","json-schema","validation"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/env-schema","language":"JavaScript","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/fastify.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},"funding":{"github":"fastify","open_collective":"fastify"}},"created_at":"2019-02-15T11:35:10.000Z","updated_at":"2025-05-01T09:17:00.000Z","dependencies_parsed_at":"2023-10-17T05:01:24.821Z","dependency_job_id":"40f1de95-8b5c-434c-9e95-45416f8cad39","html_url":"https://github.com/fastify/env-schema","commit_stats":{"total_commits":166,"total_committers":31,"mean_commits":5.354838709677419,"dds":0.5783132530120482,"last_synced_commit":"61f49974302a5e2cb89c00c4181d10c7fe55e8dc"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fenv-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fenv-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fenv-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Fenv-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/env-schema/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227611,"owners_count":22035669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["environment","environment-variables","fastify-library","json-schema","validation"],"created_at":"2024-08-01T06:01:17.176Z","updated_at":"2025-05-14T21:06:20.629Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# env-schema\n\n[![CI](https://github.com/fastify/env-schema/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/env-schema/actions/workflows/ci.yml)\n[![NPM version](https://img.shields.io/npm/v/env-schema.svg?style=flat)](https://www.npmjs.com/package/env-schema)\n[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)\n\nUtility to check environment variables using [JSON schema](https://json-schema.org/), [Ajv](http://npm.im/ajv), and\n[dotenv](http://npm.im/dotenv).\n\nSee [supporting resources](#supporting-resources) section for helpful guides on getting started.\n\n## Install\n\n```\nnpm i env-schema\n```\n\n## Usage\n\n```js\nconst envSchema = require('env-schema')\n\nconst schema = {\n  type: 'object',\n  required: [ 'PORT' ],\n  properties: {\n    PORT: {\n      type: 'number',\n      default: 3000\n    }\n  }\n}\n\nconst config = envSchema({\n  schema: schema,\n  data: data, // optional, default: process.env\n  dotenv: true // load .env if it is there, default: false\n  // or you can pass DotenvConfigOptions\n  // dotenv: {\n  //   path: '/custom/path/to/.env'\n  // }\n})\n\nconsole.log(config)\n// output: { PORT: 3000 }\n```\n\nsee [DotenvConfigOptions](https://github.com/motdotla/dotenv#options)\n\n### Custom ajv instance\n\nOptionally, the user can supply their own ajv instance:\n\n```js\nconst envSchema = require('env-schema')\nconst Ajv = require('ajv')\n\nconst schema = {\n  type: 'object',\n  required: [ 'PORT' ],\n  properties: {\n    PORT: {\n      type: 'number',\n      default: 3000\n    }\n  }\n}\n\nconst config = envSchema({\n  schema: schema,\n  data: data,\n  dotenv: true,\n  ajv: new Ajv({\n    allErrors: true,\n    removeAdditional: true,\n    useDefaults: true,\n    coerceTypes: true,\n    allowUnionTypes: true\n  })\n})\n\nconsole.log(config)\n// output: { PORT: 3000 }\n```\n\nIt is possible to enhance the default ajv instance providing the `customOptions` function parameter.\nThis example shows how to use the `format` keyword in your schemas.\n\n```js\nconst config = envSchema({\n  schema: schema,\n  data: data,\n  dotenv: true,\n  ajv: {\n    customOptions (ajvInstance) {\n      require('ajv-formats')(ajvInstance)\n      return ajvInstance\n    }\n  }\n})\n```\n\nNote that it is mandatory to return the ajv instance.\n\n### Order of configuration loading\n\nThe order of precedence for configuration data is as follows, from least\nsignificant to most:\n1. Data sourced from `.env` file (when `dotenv` configuration option is set)\n2. Data sourced from environment variables in `process.env`\n3. Data provided via the `data` configuration option\n\n### Fluent-Schema API\n\nIt is also possible to use [fluent-json-schema](http://npm.im/fluent-json-schema):\n\n```js\nconst envSchema = require('env-schema')\nconst S = require('fluent-json-schema')\n\nconst config = envSchema({\n  schema: S.object().prop('PORT', S.number().default(3000).required()),\n  data: data, // optional, default: process.env\n  dotenv: true, // load .env if it is there, default: false\n  expandEnv: true, // use dotenv-expand, default: false\n})\n\nconsole.log(config)\n// output: { PORT: 3000 }\n```\n\n**NB** Support for additional properties in the schema is disabled for this plugin, with the `additionalProperties` flag set to `false` internally.\n\n### Custom keywords\nThis library supports the following Ajv custom keywords:\n\n#### `separator`\nType: `string`\n\nApplies to type: `string`\n\nWhen present, the provided schema value will be split on this value.\n\nExample:\n```js\nconst envSchema = require('env-schema')\n\nconst schema = {\n  type: 'object',\n  required: [ 'ALLOWED_HOSTS' ],\n  properties: {\n    ALLOWED_HOSTS: {\n      type: 'string',\n      separator: ','\n    }\n  }\n}\n\nconst data = {\n  ALLOWED_HOSTS: '127.0.0.1,0.0.0.0'\n}\n\nconst config = envSchema({\n  schema: schema,\n  data: data, // optional, default: process.env\n  dotenv: true // load .env if it is there, default: false\n})\n\n// config.ALLOWED_HOSTS =\u003e ['127.0.0.1', '0.0.0.0']\n```\n\nThe ajv keyword definition objects can be accessed through the property `keywords` on the `envSchema` function:\n\n```js\nconst envSchema = require('env-schema')\nconst Ajv = require('ajv')\n\nconst schema = {\n  type: 'object',\n  properties: {\n    names: {\n      type: 'string',\n      separator: ','\n    }\n  }\n}\n\nconst config = envSchema({\n  schema: schema,\n  data: data,\n  dotenv: true,\n  ajv: new Ajv({\n    allErrors: true,\n    removeAdditional: true,\n    useDefaults: true,\n    coerceTypes: true,\n    allowUnionTypes: true,\n    keywords: [envSchema.keywords.separator]\n  })\n})\n\nconsole.log(config)\n// output: { names: ['foo', 'bar'] }\n```\n\n### TypeScript\n\nYou can specify the type of your `config`:\n\n```ts\nimport { envSchema, JSONSchemaType } from 'env-schema'\n\ninterface Env {\n  PORT: number;\n}\n\nconst schema: JSONSchemaType\u003cEnv\u003e = {\n  type: 'object',\n  required: [ 'PORT' ],\n  properties: {\n    PORT: {\n      type: 'number',\n      default: 3000\n    }\n  }\n}\n\nconst config = envSchema({\n  schema\n})\n```\n\nYou can also use a `JSON Schema` library like `typebox`:\n\n```ts\nimport { envSchema } from 'env-schema'\nimport { Static, Type } from '@sinclair/typebox'\n\nconst schema = Type.Object({\n  PORT: Type.Number({ default: 3000 })\n})\n\ntype Schema = Static\u003ctypeof schema\u003e\n\nconst config = envSchema\u003cSchema\u003e({\n  schema\n})\n```\n\nIf no type is specified the `config` will have the `EnvSchemaData` type.\n\n```ts\nexport type EnvSchemaData = {\n  [key: string]: unknown;\n}\n```\n\n## Supporting resources\n\nThe following section lists helpful reference applications, articles, guides, and other\nresources that demonstrate the use of env-schema in different use cases and scenarios:\n\n* A reference application using [Fastify with env-schema and dotenv](https://github.com/lirantal/fastify-dotenv-envschema-example)\n\n## Acknowledgments\n\nKindly sponsored by [Mia Platform](https://www.mia-platform.eu/) and\n[NearForm](https://nearform.com).\n\n## License\n\nLicensed under [MIT](./LICENSE).\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fenv-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Fenv-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Fenv-schema/lists"}