Configuration

The following options may be passed when instantiating the aws-lite client:

Credentials + region

  • accessKeyId (string)
    • AWS access key; if not provided, defaults to AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY env vars, and then to a ~/.aws/credentials file, if present
    • Manually specify a credentials file location with the AWS_SHARED_CREDENTIALS_FILE env var
    • If no access key is found, aws-lite will throw
  • secretAccessKey (string)
    • AWS secret key; if not provided, defaults to AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY env vars, and then to a ~/.aws/credentials file, if present
    • Manually specify a credentials file location with the AWS_SHARED_CREDENTIALS_FILE env var
    • If no secret key is found, aws-lite will throw
  • sessionToken (string)
    • AWS session token; if not provided, defaults to AWS_SESSION_TOKEN env var, and then to a ~/.aws/credentials file, if present
    • Manually specify a credentials file location with the AWS_SHARED_CREDENTIALS_FILE env var
  • region (string)
    • AWS service region (e.g. us-west-1); if not provided, defaults to AWS_REGION, AWS_DEFAULT_REGION, or AMAZON_REGION env vars
    • By default, a ~/.aws/config (or custom) file will only be loaded by using the awsConfigFile config property, or by making the AWS_SDK_LOAD_CONFIG env var true
    • Manually specify a config file location with the awsConfigfile config property, or with the AWS_CONFIG_FILE (and AWS_SDK_LOAD_CONFIG) env var
    • If host is specified, region can be an arbitrary, non-AWS value; this is helpful when using AWS-compatible APIs
    • If no region is found, aws-lite will throw
    • Region setting can be overridden per-request
  • profile (string)
    • AWS config + credentials profile; if not provided, defaults to AWS_PROFILE env var, and then to the default profile, if present

General config

  • autoloadPlugins (boolean) [default = false]
    • Automatically load installed @aws-lite/* + aws-lite-plugin-* plugins; this is not suggested for production use, and should generally only be used for quick local iteration
  • awsConfigFile (boolean or string) [default = false]
    • Load configuration from an AWS configuration file
    • If true, it will load from the default (~/.aws/config) location
    • If a string, it will load from that custom path
  • awsjsonMarshall (object)
    • Lower-level configuration options for marshalling AWS-flavored JSON; reference here
  • awsjsonUnmarshall (object)
    • Lower-level configuration options for unmarshalling AWS-flavored JSON; reference here
  • debug (boolean) [default = false]
    • Enable debug logging to console
    • Can also be enabled by setting the AWS_LITE_DEBUG environment variable
  • keepAlive (boolean) [default = true]
    • Disable Node.js’s connection keep-alive, helpful for local testing
  • plugins (array)
    • Define aws-lite plugins for the client instance to use; each plugin must an object or import / require statement. Examples:
      • import dynamodb from '@aws-lite/dynamodb'; await awsLite({ plugins: [ dynamodb ] })
      • const dynamodb = require('@aws-lite/dynamodb'); await awsLite({ plugins: [ dynamodb ] })
      • await awsLite({ plugins: [ import('@aws-lite/dynamodb') ] })
      • await awsLite({ plugins: [ await import('@aws-lite/dynamodb') ] })
      • await awsLite({ plugins: [ require('@aws-lite/dynamodb') ] })
  • responseContentType (string)
    • Set an overriding Content-Type header for all responses, helpful for local testing
  • retries (number, aliased to maxAttempts) [default = 5]
    • Set the maximum number of graceful retries when API service failures occur; set to 0 to disable retrying
  • verifyService (boolean) [default = true]
    • Verify client request service names against a list of known AWS services. If false, any service name will be accepted.

Endpoint config

Configure custom endpoints for local testing or AWS-compatible APIs. endpoint is usually the preferred parameter, or use individual properties: pathPrefix, host, port, protocol.

  • endpoint (string, aliased to url)
    • Full URL of the API being requested
    • This value should specify the protocol, and if applicable, port and path; example: http://my-custom-s3-endpoint.net/s3
    • endpoint supersedes pathPrefix, host, port, and protocol; if endpoint is specified, the others will be ignored
    • If a config file is being used (via awsConfigFile or AWS_SDK_LOAD_CONFIG + AWS_CONFIG_FILE env vars), endpoint will be assigned the endpoint_url setting of the specified profile, if present
    • Alternately, endpoint will use the value of the AWS_ENDPOINT_URL env var, if present
  • pathPrefix (string)
    • Add prefix to any specified paths in all requests, helpful for local testing
  • host (string)
    • Set a custom host name to use, helpful for local testing
    • This value should NOT specify a protocol, port, or path; example: my-custom-s3-endpoint.net
  • port (number)
    • Set a custom port number to use, helpful for local testing
  • protocol (string) [default = https]
    • Set the connection protocol to http, helpful for local testing

Example

import awsLite from '@aws-lite/client'

// Load everything from env vars and/or config files
let aws = await awsLite()

// Or specify options
aws = await awsLite({
  // Credentials + region
  accessKeyId: '$accessKey',
  secretAccessKey: '$secretKey',
  sessionToken: '$sessionToken',
  region: 'us-west-1',
  profile: 'work',
  // General config
  autoloadPlugins: false,
  awsConfigFile: '/a/path/to/config',
  debug: true,
  keepAlive: false,
  plugins: [ '@aws-lite/dynamodb', '/a/custom/local/plugin/path' ],
  responseContentType: 'application/json',
  retries: 4,
  // Endpoint config
  endpoint: 'http://my-custom-s3-endpoint.net/s3', // Aliased to `url`
  // The following options are ignored if `endpoint` is present:
  pathPrefix: '/test/path/',
  host: 'localhost',
  port: 12345,
  protocol: 'http',
})

// aws-lite can also be used with AWS-compatible services that use AWS signature v4 (e.g. Backblaze B2)
// Such services can accept alternate credentials passed during instantiation, via env vars, etc.
aws = await awsLite({
  accessKeyId: '$alternateAccessKey',
  secretAccessKey: '$alternateAccessSecretKey',
  region: 'us-west-004',
  endpoint: 'https://s3.us-west-004.backblazeb2.com/',
})
aws-lite is an Apache 2.0-licensed open source project under the umbrella of OpenJS Foundation Architect. aws-lite is not in any way affiliated with Amazon Web Services, Inc. (AWS). All names and trademarks are the property of their respective owners.