{"id":19410121,"url":"https://github.com/nicolasdao/sls-config-parser","last_synced_at":"2025-04-24T10:32:19.731Z","repository":{"id":35077206,"uuid":"203083232","full_name":"nicolasdao/sls-config-parser","owner":"nicolasdao","description":"Parses serverless.yml files so that their values can be use locally in JS code during development.","archived":false,"fork":false,"pushed_at":"2023-03-04T04:32:42.000Z","size":609,"stargazers_count":3,"open_issues_count":16,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T03:33:27.338Z","etag":null,"topics":["aws-sdk","config","environment-variables","serverless","serverless-framework","yml"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicolasdao.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2019-08-19T02:22:30.000Z","updated_at":"2023-09-18T20:03:40.000Z","dependencies_parsed_at":"2023-12-05T16:10:25.088Z","dependency_job_id":"985b4518-6b82-4755-976c-fbe9cdb9a471","html_url":"https://github.com/nicolasdao/sls-config-parser","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fsls-config-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fsls-config-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fsls-config-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasdao%2Fsls-config-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicolasdao","download_url":"https://codeload.github.com/nicolasdao/sls-config-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250609127,"owners_count":21458432,"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":["aws-sdk","config","environment-variables","serverless","serverless-framework","yml"],"created_at":"2024-11-10T12:14:53.857Z","updated_at":"2025-04-24T10:32:19.401Z","avatar_url":"https://github.com/nicolasdao.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless Config File Parser \u0026middot; [![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com) [![Tests](https://travis-ci.org/nicolasdao/sls-config-parser.svg?branch=master)](https://travis-ci.org/nicolasdao/sls-config-parser) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Neap](https://neap.co/img/made_by_neap.svg)](#this-is-what-we-re-up-to)\n__*sls-config-parser*__ parses serverless.yml files so that its values can be used locally in JS code during development, including automatically setting up environment variables. Its main usage is to set up the environment variables (including the access key and secret from the `~/.aws/credentials` as well as the region from the `~/.aws/config`) locally so it is possible to test functions locally. Setting up the environment variables is done in a package.json script as follow:\n\n```js\n\"scripts\": {\n\t\"start\": \"node -r sls-config-parser/setenv index.js --inclcreds --stage prod\"\n}\n```\n\nThis script sets up the environment variables based on the profile defined in the `serverless.yml` file and the credentials defined in the `~/.aws/credentials` and `~/.aws/config` the file.\n\n\u003e WARNING: The package is in beta. Limitations:\n\u003e\t- Not tested on Windows.\n\u003e\t- Only works with YAML files (JSON support coming soon).\n\u003e\t- No support for CloudFormation intrinsic functions yet (e.g., Ref, !Sub, !Join).\n\n# Table of Contents\n\n\u003e * [Install](#install) \n\u003e * [Getting started](#getting-started) \n\u003e\t- [Parsing the serverless.yml](#parsing-the-serverlessyml)\n\u003e\t- [Getting the environment variables](#getting-the-environment-variables)\n\u003e\t- [Setting up environment variables](#setting-up-environment-variables)\n\u003e\t\t- [Why is it important?](#why-is-it-important)\n\u003e\t\t- [Setting things up](#setting-things-up)\n\u003e\t- [Overriding serverless.yml properties](#overriding-serverlessyml-properties)\n\u003e * [Annexes](#annexes)\n\u003e\t  - [`sls-config-parser/setenv` API](#sls-config-parsersetenv-api)\n\u003e * [About Neap](#this-is-what-we-re-up-to)\n\u003e * [License](#license)\n\n\n# Install\n\n```\nnpm i sls-config-parser\n```\n\n\u003e Dev dependency VS App dependency:\n\u003e Depending on your use case, install it as a dev dependency or as an app dependency. The dev dependency case occurs when, for example, you're only interested in setting environment variables based on your .aws/credentials and your serverless.yml.\n\n# Getting started\n## Parsing the serverless.yml\nAssuming there is a `serverless.yml` file in your root folder:\n\n```js\nconst { Config } = require('sls-config-parser')\n\nconst defaultCfg = new Config()\nconst stagingCfg = new Config({ stage: 'staging' })\nconst prodCfg = new Config({ stage: 'prod' })\nconst customCfg = new Config({ stage: 'prod', _path:'../path-to-another-config/some-other.yml' })\n\nconsole.log('DEFAULT CONFIG:')\nconsole.log(defaultCfg.config())\n\nconsole.log('STAGING CONFIG:')\nconsole.log(stagingCfg.config())\n\nconsole.log('PROD CONFIG:')\nconsole.log(prodCfg.config())\n\nconsole.log('CUSTOM CONFIG:')\nconsole.log(customCfg.config())\n```\n\n## Getting the environment variables\n\nLet's imagine we have the following `serverless.yml` file:\n\n```yml\nservice: graphql\n\ncustom:\n  stage: ${opt:stage, 'dev'}\n  dynamoDB:${file(./config/local.yml)}\n\nprovider:\n  name: aws\n  runtime: nodejs10.x\n  region: ap-southeast-2\n  profile: fairplay\n  stage: ${self:custom.stage}\n  environment:\n    DATA_01: hello ${self:provider.stage}\n    DATA_02: boom boom\n\nfunctions:\n  graphql:\n    handler: handler.handler\n    events:\n      - http:\n          path: /\n          method: ANY\n    environment:\n      GRAPHQL_ENV_01: graphql_01\n      GRAPHQL_ENV_02: graphql_02\n  rest:\n    handler: handler.rest\n    events:\n      - http:\n          path: /rest\n          method: ANY\n    environment:\n      REST_ENV_01: rest_01\n      REST_ENV_02: rest_02\n\nresources:\n  Resources:\n    UserTable:\n      Type: AWS::DynamoDB::Table\n      Properties: \n        TableName: user_${self:provider.stage}\n        AttributeDefinitions: \n          - AttributeName: id\n            AttributeType: N\n          - AttributeName: username\n            AttributeType: S\n          - AttributeName: data\n            AttributeType: M\n        KeySchema: \n          - AttributeName: id\n            KeyType: N\n        ProvisionedThroughput: ${self:custom.dynamoDB.${self:provider.stage}ProvisionedThroughput}\n        Tags: \n          - Key: Type\n            Value: test\n          - Key: Name\n            Value: graphql\n```\n\n```js\nconst { Config } = require('sls-config-parser')\n\nconst defaultCfg = new Config()\n\n// EXAMPLE 01: Returns an object with all the environment variables (both global and local to all functions).\n// For example: env.DATA_01 -\u003e 'hello dev', env.GRAPHQL_ENV_01 -\u003e 'graphql_01', env.REST_ENV_01 -\u003e 'rest_01'\nconsole.log(defaultCfg.env())\n\n// EXAMPLE 02: Returns the same data as above, but as an array rather than an object.\n// For example: [{ name: 'DATA_01', value: 'hello dev' }, { name:'GRAPHQL_ENV_01', value: 'graphql_01' }, ...]\nconsole.log(defaultCfg.env({ format:'array' }))\n\n// EXAMPLE 03: Returns the same data as #01, but only focus on the global variables and the 'graphql' function variables.\nconsole.log(defaultCfg.env({ functions:['graphql'] }))\n\n// EXAMPLE 04: Returns the same data as #03, but ignore the global variables.\nconsole.log(defaultCfg.env({ functions:['graphql'], ignoreGlobal:true }))\n\n// EXAMPLE 05: Returns the global variables only.\nconsole.log(defaultCfg.env({ ignoreFunctions:true }))\n\n// EXAMPLE 06: Returns the same data as #01 with the additionnal AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY defined\n// in the ~/.aws/credentials file. If there are multiple profiles in the credentials file, sls-config-parser uses the\n// profile defined under the provider.profile property in the serverless.yml file (in our case, that profile is called \n// 'fairplay').\n// For example: env.AWS_ACCESS_KEY_ID -\u003e 'SHWKHSKWHKHKWSW', env.AWS_SECRET_ACCESS_KEY -\u003e 'dbwjdejewgdewdjjgjewdgewdg'\nconsole.log(defaultCfg.env({ inclAccessCreds:true }))\n\n// EXAMPLE 07: Same as #06, but with a custom credentials file.\n console.log(defaultCfg.env({ inclAccessCreds:true, awsCreds:'../path-to-other-creds/other-creds-file' }))\n```\n\n## Setting up environment variables\n\nThis is the original purpose of this package. This section contains some context in the [Why is it important?](#why-is-it-important) section. If you're already aware of the running a Lambda locally, you can jump to the [Setting things up](#setting-things-up) section.\n\n### Why is it important?\n\nTo use the nodeJS AWS SDK (e.g., using it to read or write to a DynamoDB), it must be configured with the access key and access secret or with an IAM policy. The easiest way to perform this is to explicitly set it up in your code:\n\n```js\nconst AWS = require('aws-sdk')\nAWS.config = new AWS.Config({ accessKeyId:'WHIWHHIHH', secretAccessKey: 'debwjkdbewkjbdkjedbk', region:'ap-southeast-2' })\n\nconst db = new AWS.DynamoDB.DocumentClient({ apiVersion: '2012-08-10' })\n```\n\nThis code makes it straightforward to test locally. However, the above approach is not recommended, as it explicitly exposes the access key and secret. A nefarious conributor could use those credentials to exploit your system.\n\nThe recommended approach is to configure an IAM policy in the `iamRoleStatements` property of the `provider` section in the `serverless.yml`. Once this is done, the AWS SDK does not require explicit access key and secret, as those are safely set up as environment variables on your Lambda at deployment time. You can then simply use this instead:\n\n```js\nconst AWS = require('aws-sdk')\n\nconst db = new AWS.DynamoDB.DocumentClient({ apiVersion: '2012-08-10' })\n```\n\nAnd yet, this creates another issue: How do you test this code locally? The answer to this question is easy to understand, but annoying to implement, and that where this package comes into play. To make the above code work locally, the following environment variables must be set up:\n- AWS_ACCESS_KEY_ID\n- AWS_SECRET_ACCESS_KEY\n- AWS_REGION\n\nThe first two variables are located under the `~/.aws/credentials` file while the third one is under the `~/.aws/config`. You could manually set those variables in a start script in your package.json as follow:\n\n```js\n\"scripts\": {\n\t\"start\": \"AWS_ACCESS_KEY_ID=******* AWS_SECRET_ACCESS_KEY=********** AWS_REGION=ap-southeast-2 node index.js\"\n}\n```\n\nHowever, this is far from being flexible. Besides, there might be more environment variables to set up based on your `serverless.yml` file (which could also define a specific `provider.profile` value influencing the value of the access key and secret). Ideally, those variables are automatically set up based on the correct selected stage of the `serverless.yml` file. That's exactly what this package offers.\n\n### Setting things up\n\n\u003e PREREQUISITE: The following assumes that you have a `~/.aws/credentials` and a `~/.aws/config` file properly configured (i.e., the profile defined in the `serverless.yml` under the `provider.profile` property exists).\n\nTo set up all the environment variables in your local environment, add a script in your package.json similar to this:\n\n```js\n\"scripts\": {\n\t\"dev\": \"node -r sls-config-parser/setenv index.js --inclcreds --stage dev\"\n}\n```\n\n\u003e To know more about this script's API, please refer to the [`sls-config-parser/setenv` API](#sls-config-parsersetenv-api) section of the [Annexes](#annexes).\n\nTo run your Lambda locally, just run:\n\n```\nnpm run dev\n```\n\n# Overriding serverless.yml properties\n\nSometimes you may need to overide some serverless.yml properties in your package.json scripts (e.g., you wish to set up a specific provider's profile without setting one up in the serverless.yml file). You can achieve this with the `--force` option as follow:\n\n```js\n\"scripts\": {\n  \"start\": \"node -r sls-config-parser/setenv index.js --inclcreds --stage prod --force 'provider.profile=neap;provider.region=ap-southeast-2'\"\n}\n```\n\n# Annexes\n## `sls-config-parser/setenv` API\n\n```js\n\"scripts\": {\n\t\"dev\": \"node -r sls-config-parser/setenv index.js --inclcreds --stage dev\"\n}\n```\n\nThe `-r` options means _require_. This requires the JS file located under the path `sls-config-parser/setenv.js`. This file executes a function which takes the options `--inclcreds` and `--stage dev` and sets up the environment variables defined in the `serverless.yml` and in the `~/.aws/credentials` and a `~/.aws/config` files. Once this is done, the `index.js` file is executed. \n\nThe options for the `sls-config-parser/setenv.js` function are:\n- __`--inclcreds`__: If specified, this means the environment variables defined in the `~/.aws/credentials` file and in the `~/.aws/config` file must be set up. Otherwise, only the variables of the `serverless.yml` are included.\n- __`--stage \u003cstage-name\u003e`__: Defines which stage must be used in the `serverless.yml`.\n- __`--path \u003cpath-value\u003e`__: Specifies another location for the `serverless.yml`.\n\n\n# This Is What We re Up To\nWe are Neap, an Australian Technology consultancy powering the startup ecosystem in Sydney. We simply love building Tech and also meeting new people, so don't hesitate to connect with us at [https://neap.co](https://neap.co).\n\nOur other open-sourced projects:\n#### GraphQL\n* [__*graphql-s2s*__](https://github.com/nicolasdao/graphql-s2s): Add GraphQL Schema support for type inheritance, generic typing, metadata decoration. Transpile the enriched GraphQL string schema into the standard string schema understood by graphql.js and the Apollo server client.\n* [__*schemaglue*__](https://github.com/nicolasdao/schemaglue): Naturally breaks down your monolithic graphql schema into bits and pieces and then glue them back together.\n* [__*graphql-authorize*__](https://github.com/nicolasdao/graphql-authorize.git): Authorization middleware for [graphql-serverless](https://github.com/nicolasdao/graphql-serverless). Add inline authorization straight into your GraphQl schema to restrict access to certain fields based on your user's rights.\n\n#### React \u0026 React Native\n* [__*react-native-game-engine*__](https://github.com/bberak/react-native-game-engine): A lightweight game engine for react native.\n* [__*react-native-game-engine-handbook*__](https://github.com/bberak/react-native-game-engine-handbook): A React Native app showcasing some examples using react-native-game-engine.\n\n#### Authentication \u0026 Authorization\n* [__*userin*__](https://github.com/nicolasdao/userin): UserIn let's App engineers to implement custom login/register feature using Identity Providers (IdPs) such as Facebook, Google, Github. \n\n#### General Purposes\n* [__*core-async*__](https://github.com/nicolasdao/core-async): JS implementation of the Clojure core.async library aimed at implementing CSP (Concurrent Sequential Process) programming style. Designed to be used with the npm package 'co'.\n* [__*jwt-pwd*__](https://github.com/nicolasdao/jwt-pwd): Tiny encryption helper to manage JWT tokens and encrypt and validate passwords using methods such as md5, sha1, sha256, sha512, ripemd160.\n\n#### Google Cloud Platform\n* [__*google-cloud-bucket*__](https://github.com/nicolasdao/google-cloud-bucket): Nodejs package to manage Google Cloud Buckets and perform CRUD operations against them.\n* [__*google-cloud-bigquery*__](https://github.com/nicolasdao/google-cloud-bigquery): Nodejs package to manage Google Cloud BigQuery datasets, and tables and perform CRUD operations against them.\n* [__*google-cloud-tasks*__](https://github.com/nicolasdao/google-cloud-tasks): Nodejs package to push tasks to Google Cloud Tasks. Include pushing batches.\n\n# License\nCopyright (c) 2017-2019, Neap Pty Ltd.\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n* Neither the name of Neap Pty Ltd nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL NEAP PTY LTD BE LIABLE FOR ANY\nDIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\nLOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND\nON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://neap.co\" target=\"_blank\"\u003e\u003cimg src=\"https://neap.co/img/neap_color_horizontal.png\" alt=\"Neap Pty Ltd logo\" title=\"Neap\" height=\"89\" width=\"200\"/\u003e\u003c/a\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasdao%2Fsls-config-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicolasdao%2Fsls-config-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasdao%2Fsls-config-parser/lists"}