{"id":25933398,"url":"https://github.com/robertwhurst/milieu","last_synced_at":"2025-08-17T10:35:13.598Z","repository":{"id":43408115,"uuid":"153563481","full_name":"RobertWHurst/Milieu","owner":"RobertWHurst","description":"Config loader for node","archived":false,"fork":false,"pushed_at":"2023-01-08T12:19:04.000Z","size":404,"stargazers_count":4,"open_issues_count":5,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-17T10:35:13.102Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobertWHurst.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-18T04:26:36.000Z","updated_at":"2025-08-07T13:14:52.000Z","dependencies_parsed_at":"2023-02-08T05:45:58.533Z","dependency_job_id":null,"html_url":"https://github.com/RobertWHurst/Milieu","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/RobertWHurst/Milieu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2FMilieu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2FMilieu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2FMilieu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2FMilieu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobertWHurst","download_url":"https://codeload.github.com/RobertWHurst/Milieu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobertWHurst%2FMilieu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270837404,"owners_count":24654375,"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","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2025-03-04T00:53:40.397Z","updated_at":"2025-08-17T10:35:13.501Z","avatar_url":"https://github.com/RobertWHurst.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Milieu\n\nOne could say it is one's milieu that shapes their future\n![](http://i.imgur.com/FgRHMFQ.jpg)\n\n[![npm](https://img.shields.io/npm/v/milieu.svg?maxAge=2592000?style=flat-square)](https://www.npmjs.com/package/milieu)\n\n## Install with NPM\n\n```shell\nnpm install milieu\n```\n\n## Introduction\n\nMilieu is a config loader in the spirit of\n[rc](https://github.com/dominictarr/rc) It shares the same features as RC, but\ngoes a few steps further.\n\nMilieu loads config values from argv flags, environment variables, and config\nfiles. The values are compiled into a single config object which you can use\nin your application. You can trace the sources of these values using Milieu's\nexplain feature.\n\nMilieu can parse JSON config files out of the box. You can also use INI and YAML\nfiles by installing the optional dependencies\n[ini](https://github.com/isaacs/ini) and/or\n[js-yaml](https://github.com/nodeca/js-yaml) modules.\n\n\u003e The word milieu is defined as the physical or social setting in which people\n\u003e live or in which something happens or develops.\n\n```javascript\nvar milieu = require('milieu');\n\nvar config = milieu('application-name', {\n  server: {\n    port: 8001\n  },\n  mongo: {\n    url: 'mongodb://localhost'\n  }\n});\n```\n\n### Milieu Compile Order\nMilieu looks in the following places and compiles a config by merging upward\nthrough the following sources. Items highest in the list get the highest\npriority, and override config values in the sources below.\n\n0. argv flags - Ex. `--test--my-key val` becomes `config.test.myKey === 'val'`\n   in the config. Anything after -- is ignored.\n0. environment variables - Ex. `APPLICATION_NAME__TEST__MY_KEY=\"val\"` becomes\n   `config.test.myKey === 'val'`\n0. config files (replace {appname} with the name of your application)\n  (Accepts JSON, INI, or YAML) (File extensions are optional)\n  0. ~/.{appname}rc\n  0. ~/.{appname}/config\n  0. ~/.config/{appname}\n  0. ~/.config/{appname}/config\n  0. /etc/{appname}rc\n  0. /etc/{appname}/config\n  0. /usr/local/etc/{appname}rc\n  0. /usr/local/etc/{appname}/config\n  0. ./.{appname}rc\n  0. ../.{appname}rc\n  0. ../../.{appname}rc\n  0. ../../../.{appname}rc\n  0. ...\n\n\n## Milieu Templating and Type Casting\nMilieu provides both file and environment variable templating. It also provides\nsyntax for type casting. Below are a few examples.\n\nTo load values from a file use the `$(path/to/file)` syntax. If the path is not\nabsolute, it will be relative to the current working directory. You can use\nthese tokens as many times as you need within a single value.\n\n```javascript\nvar config = milieu('application-name', {\n  specialFile: 'part1: $(path/to/specialFile-part-1.txt)\\npart2: $(path/to/specialFile-part-2.txt)'\n});\n```\n\nTo load values from environment variables use the `${VAR_NAME}` syntax. You can\nuse these tokens as many times as you need within a single value.\n\n```javascript\nvar config = milieu('application-name', {\n  secretTokens: '1:${SECRET_TOKEN_1}2:${SECRET_TOKEN_2}3:${SECRET_TOKEN_3}'\n});\n```\n\nType casting can be achieved with filters. To cast a value simply add the type\nname and a colon to the beginning of your string. Types supported are `number`\nand `boolean`. JSON can also be parsed using `json` as the type.\n\n```javascript\nvar config = milieu('application-name', {\n  secretNumber: 'number:${SECRET_NUMBER}'\n  secretBool  : 'boolean:${SECRET_BOOL}'\n  secretObj   : 'json:${SECRET_JSON}'\n});\n```\n\n\n## Milieu Explain\nMilieu has a feature called explain. There are explain two methods;\n`config.explain()` and `config.printExplainTable()`. `config.explain()` returns\nan object indicating the origin of each config value.\n`config.printExplainTable()` prints a table to stdout which can be used\nto inspect your config from the cli. This is great for understanding how your\nconfiguration was resolved, and can be helpful for debugging production systems.\n\n![example](http://i.imgur.com/BzzxMAy.png)\n\nLets suppose we have a config for our server at `/etc/application-name/config`.\nIn it we set the value of `server.port` and nothing else. We also execute our\napplication below passing the flag `--debug true`. Our explanation object will\ncontain the origin of each config key as shown below.\n\n```javascript\nvar milieu = require('milieu');\n\nvar explanation = milieu('application-name', {\n  server: {\n    port: 8001\n  },\n  mongo: {\n    url: 'mongodb://localhost'\n  },\n  debug: false\n}).explain();\n\nexplanation === {\n  server: {\n    port: '/etc/application-name/config'\n  },\n  mongo: {\n    url: 'default'\n  },\n  debug: 'flag'\n}\n```\n\nIf you wish to generate a table on the command line instead of working with an\nexplanation object, call `config.printExplainTable`.\n\n```javascript\nvar milieu = require('milieu');\n\n// prints table to stdout\nmilieu('application-name', {\n  server: {\n    port: 8001\n  },\n  mongo: {\n    url: 'mongodb://localhost'\n  },\n  debug: false\n}).printExplainTable();\n```\n\n\n# API Docs\n\n## milieuFactory\n\n```\nmilieuFactory(applicationName String, defaultConfig Object, opts Object) -\u003e config Object\n```\n\nInternally creates an instance of Milieu instance and returns it.\nAccepts a `applicationName` and a `defaultConfig`. It also\noptionally accepts an `opts` object to configure Milieu. See\n[Milieu's load order](#milieu-load-order) to understand how the config object\nis resolved. These does refer to milieuFactory as `milieuFactory` but It is\nrecommended that the name `milieu` be used instead as most users will not\ninteract with `Milieu` constructor or it's instance directly.\n\n### Milieu Options\n- `opts.argv` Pass a custom argv array. Defaults to `process.argv`.\n- `opts.env`  Pass a custom env object. Defaults to `process.env`.\n- `opts.platform`  Pass a custom platform string. Defaults to\n  `process.platform`.\n- `opts.unsetEnvValues` If true, deletes env values that belong to the config.\n  Defaults to `false`.\n- `opts.parseValues` If true, parses strings `'null'`, `'true'`, `'false'`,\n  and `'NaN'` into `null`, `true`, `false`, and `NaN`. Defaults to `true`.\n\n\n```javascript\nvar milieuFactory = require('milieu');\n\nvar config = milieuFactory('application-name', {\n  defaultKey: 'value'\n});\n```\n\n\n## Milieu\n\n```\nnew Milieu(applicationName String, defaultConfig Object, opts Object) -\u003e Milieu\n```\n\nThe Milieu constructor. Accepts the same arguments as\n[milieuFactory](#milieuFactory).\n\n```javascript\nvar Milieu = require('milieu').Milieu;\n\nvar milieu = new Milieu('application-name', {\n  defaultKey: 'value'\n});\n```\n\n## Milieu#toObject\n\n```\nmilieu.toObject() -\u003e config Object\n```\n\nResolves the config object. Use this method to retrieve your config if using a\nMilieu instance directly.\n\n```javascript\nvar Milieu = require('milieu').Milieu;\n\nvar milieu = new Milieu('application-name', {\n  defaultKey: 'value'\n});\n\nvar config = milieu.toObject();\n```\n\n## Milieu#explain\n\n```\nmilieu.explain() -\u003e explanation Object\n```\n\nReturns an explanation object.\n\n```javascript\nvar Milieu = require('milieu').Milieu;\n\nvar milieu = new Milieu('application-name', {\n  defaultKey: 'value'\n});\n\nvar explanation = milieu.explain();\n```\n\n## Milieu#printExplainTable\n\n```\nmilieu.explain() -\u003e explanation Object\n```\n\nPrints an explanation table to stdout.\n\n```javascript\nvar Milieu = require('milieu').Milieu;\n\nvar milieu = new Milieu('application-name', {\n  defaultKey: 'value'\n});\n\n// prints to stdout\nmilieu.printExplainTable();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertwhurst%2Fmilieu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobertwhurst%2Fmilieu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobertwhurst%2Fmilieu/lists"}