{"id":16170406,"url":"https://github.com/corentinth/figue","last_synced_at":"2025-11-09T15:07:12.190Z","repository":{"id":57686315,"uuid":"492721657","full_name":"CorentinTh/figue","owner":"CorentinTh","description":"Configuration management library, like convict but with zod","archived":false,"fork":false,"pushed_at":"2025-01-10T11:25:26.000Z","size":303,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-12T11:38:27.616Z","etag":null,"topics":["config","configuration-management","env","environment-variables","zod"],"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/CorentinTh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["CorentinTh"]}},"created_at":"2022-05-16T07:09:42.000Z","updated_at":"2025-03-09T06:33:47.000Z","dependencies_parsed_at":"2024-09-10T13:17:14.136Z","dependency_job_id":"75fde77c-0f9b-4285-8c49-4f86d7f6f7ca","html_url":"https://github.com/CorentinTh/figue","commit_stats":{"total_commits":15,"total_committers":1,"mean_commits":15.0,"dds":0.0,"last_synced_commit":"d3c7132adff88f7764aec2755d42ff169a7a3ee4"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorentinTh%2Ffigue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorentinTh%2Ffigue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorentinTh%2Ffigue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CorentinTh%2Ffigue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CorentinTh","download_url":"https://codeload.github.com/CorentinTh/figue/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243955755,"owners_count":20374373,"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":["config","configuration-management","env","environment-variables","zod"],"created_at":"2024-10-10T03:18:40.451Z","updated_at":"2025-11-09T15:07:12.180Z","avatar_url":"https://github.com/CorentinTh.png","language":"TypeScript","funding_links":["https://github.com/sponsors/CorentinTh","https://buymeacoffee.com/cthmsst"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./.github/fig.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"./.github/fig-outlined.png\"\u003e\n  \u003cimg src=\"./.github/fig.png\" alt=\"Figue\" width=\"200\" /\u003e\n\u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e\n  Figue - Application configuration management\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  The modern way to handle and validate your application configuration with any standard-schema-compliant validation library.\n\u003c/p\u003e\n\n\n## Introduction\n\nFigue is a modern configuration management library for Node.js. It is designed to be easy to use, flexible, it can used in any environment, and can be used with any standard-schema-compliant validation library, like [zod](https://github.com/colinhacks/zod) or [valibot](https://github.com/fabian-hiller/valibot).\n\nThink of it as a modern version of [convict](https://github.com/mozilla/node-convict/tree/master/packages/convict) but simpler, cross env and using battle tested validation libraries.\n\n## Features\n\n- Environment variables support\n- Validation with any standard-schema-compliant validation library\n- Flat object support\n- Multiple sources of configuration\n- Type-safe configuration\n- Composable configuration\n- No runtime dependencies\n\n## Usage\n\nInstall package:\n\n```sh\n# pnpm\npnpm install figue\n\n# npm\nnpm install figue\n\n# yarn\nyarn install figue\n\n```\n\nImport:\n\n```js\nimport { defineConfig } from 'figue';\n```\n\n## API\n\n### Basic example\n\nUse the `defineConfig` function to define your configuration, here with [valibot](https://github.com/fabian-hiller/valibot):\n\n```typescript\nimport { defineConfig } from 'figue';\nimport * as v from 'valibot';\n\nconst { config } = defineConfig(\n  {\n    env: {\n      doc: 'Application current environment',\n      default: 'development',\n      schema: v.picklist(['development', 'production', 'test']),\n      env: 'NODE_ENV',\n    },\n    port: {\n      doc: 'Application port to listen',\n      schema: v.pipe(v.union([v.number(), v.string()]), v.transform(Number)),\n      default: 3000,\n      env: 'PORT',\n    },\n    db: {\n      host: {\n        doc: 'Database server url',\n        schema: v.pipe(v.string(), v.url()),\n        default: 'http://localhost:5432',\n        env: 'APP_DB_HOST',\n      },\n      username: {\n        doc: 'Database server username',\n        schema: v.string(),\n        default: 'pg',\n        env: 'APP_DB_USERNAME',\n      },\n      password: {\n        doc: 'Database server password',\n        schema: v.string(),\n        default: '',\n        env: 'APP_DB_PASSWORD',\n      },\n    },\n  },\n  {\n    envSource: process.env,\n  },\n);\n\nconsole.log(config);\n// {\n//   env: \"development\",\n//   port: 3000,\n//   db: {\n//     url: \"https://localhost\",\n//     username: \"pg\",\n//     password: \"\",\n//   },\n// }\n```\n\nYou can see more examples in the [demo](./demo) folder.\n- Figue with zod: [demo/figue-zod.ts](./demo/figue-zod.ts)\n- Figue with valibot: [demo/figue-valibot.ts](./demo/figue-valibot.ts)\n\n### Load environnement\n\nUse the `envSource` key of the second argument of `defineConfig` to specify the source of the environment variables:\n\n```typescript\nconst { config } = defineConfig(\n  {\n    /* ... */\n  },\n  {\n    envSource: process.env,\n  },\n);\n```\n\nIn some case you don't have access to a `process.env` variable, like with `vite`, just simply load what stores your env variables :\n\n```typescript\nconst { config } = defineConfig(\n  {\n    /* ... */\n  },\n  {\n    envSource: import.meta.env,\n  },\n);\n```\n\nYou can even specify you custom environment storage as long as it's a simple flat object map, for example:\n\n```typescript\nconst { config } = defineConfig(\n  {\n    env: {\n      doc: 'Application current environment',\n      default: 'development',\n      schema: z.enum(['development', 'production', 'test']),\n      env: 'NODE_ENV',\n    },\n\n    /* ... */\n  },\n  {\n    envSource: {\n      NODE_ENV: 'development',\n      PORT: '3000',\n      APP_DB_HOST: 'localhost',\n      APP_DB_USERNAME: 'pg',\n      APP_DB_PASSWORD: '',\n    },\n  },\n);\n```\n\nIf, for some reason, you have multiple sources of environment variables, you can use the `envSources` key of the second argument of `defineConfig` to specify an array of sources:\n\n```typescript\nconst { config } = defineConfig(\n  {\n    /* ... */\n  },\n  {\n    envSource: [import.meta.env, myEnvs],\n  },\n);\n```\n\n### Environment variable fallback\n\nYou can specify multiple environment variable names for a single configuration field by providing an array of strings. Figue will use the first environment variable that is found in your environment sources.\n\nThis feature is particularly useful when:\n- Supporting multiple deployment environments with different environment variable naming conventions\n- Migrating from legacy environment variable names while maintaining backward compatibility\n- Providing fallback options for missing environment variables\n\n```typescript\nconst { config } = defineConfig(\n  {\n    port: {\n      doc: 'Application port to listen',\n      schema: z.coerce.number(),\n      default: 3000,\n      // Will use PORT if available, otherwise APP_PORT, otherwise SERVER_PORT\n      env: ['PORT', 'APP_PORT', 'SERVER_PORT'],\n    },\n    database: {\n      host: {\n        doc: 'Database host',\n        schema: z.string(),\n        default: 'localhost',\n        // Useful for supporting legacy environment variable names\n        env: ['DATABASE_HOST', 'DB_HOST', 'LEGACY_DB_URL'],\n      },\n    },\n    workerId: {\n      doc: 'Worker identifier',\n      schema: z.string().optional(),\n      // Or using some plateform specific environment variable\n      env: ['WORKER_ID', 'HEROKU_DYNO_ID', 'RENDER_INSTANCE_ID'],\n    },\n  },\n  {\n    envSource: process.env,\n  },\n);\n```\n\n\n\nSome caveats:\n- If none of the specified environment variables are found, Figue will fall back to the default as expected when no `env` key is present.\n- If a variable is found but its value is nullish or falsy (like an empty string, or undefined), Figue will still consider it as set and use that value. If you want to ignore such values, you should handle that in your schema validation.\n- Ensure that the order of environment variables in the array reflects their priority, as Figue will use the first one it finds.\n\n### Get defaults\n\nYou can use the `getDefaults` key of the second argument of `defineConfig` to specify a function that will be called to get some defaults:\n\n```typescript\nconst { config } = defineConfig(\n  {\n    env: {\n      doc: 'Application current environment',\n      default: 'development',\n      schema: z.enum(['development', 'production', 'test']),\n      env: 'NODE_ENV',\n    },\n    port: {\n      doc: 'Application port to listen',\n      schema: z.coerce.number().int().positive(),\n      default: 3000,\n      env: 'PORT',\n    },\n  },\n  {\n    envSource: {\n      PORT: 3001,\n    },\n    // The config argument is build from the config definition defaults and the envSources\n    // Typically you will use it to override some defaults based the config\n    getDefaults: ({ config }) =\u003e ({\n      port: config.env === 'test' ? 4444 : config.port,\n    }),\n  },\n);\n\n```\n\nYou can also use the `defaults` property of the second argument of `defineConfig` to specify some static defaults (for example taken from a json file):\n\n```typescript\nconst { config } = defineConfig(\n  {\n    /* ... */\n  },\n  {\n    // Either an array of config partial...\n    defaults: [\n      {\n        port: 4444,\n      },\n    ],\n\n    // ... or a single config partial\n    defaults: {\n      port: 4444,\n    },\n  },\n);\n```\n\n## What's wrong with convict?\n\nConvict is meant to be used in node based environnement, it needs to have access to global variables that may may not be present in some environnement (like `process`, `global`), and it also imports `fs`.\n\n## Figue?\n\n**Figue** is the french for _fig_ -\u003e con-fig.\n\n## Development\n\n- Clone this repository\n- Install dependencies using `pnpm install`\n- Run interactive tests using `pnpm dev`\n\n## Credits\n\nThis project is crafted with ❤️ by [Corentin Thomasset](https://corentin.tech).\nIf you find this project helpful, please consider [supporting my work](https://buymeacoffee.com/cthmsst).\n\nFig icons created by \u003ca href=\"https://www.flaticon.com/free-icons/fig\" title=\"fig icons\"\u003eFreepik - Flaticon\u003c/a\u003e\n\n## License\n\nThis project is under the [MIT license](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorentinth%2Ffigue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcorentinth%2Ffigue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcorentinth%2Ffigue/lists"}