1 | # AWS SDK for JavaScript
|
2 |
|
3 | [![NPM version](https://img.shields.io/npm/v/aws-sdk.svg)](https://www.npmjs.com/package/aws-sdk)
|
4 | [![NPM downloads](https://img.shields.io/npm/dm/aws-sdk.svg)](https://www.npmjs.com/package/aws-sdk)
|
5 | [![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.svg)](https://gitter.im/aws/aws-sdk-js)
|
6 |
|
7 | [![Build Status](https://travis-ci.org/aws/aws-sdk-js.svg?branch=master)](https://travis-ci.org/aws/aws-sdk-js)
|
8 | [![Coverage Status](https://codecov.io/gh/aws/aws-sdk-js/branch/master/graph/badge.svg)](https://codecov.io/gh/aws/aws-sdk-js)
|
9 | [![Known Vulnerabilities](https://snyk.io/test/github/aws/aws-sdk-js/badge.svg)](https://snyk.io/test/github/aws/aws-sdk-js)
|
10 |
|
11 | The official AWS SDK for JavaScript, available for browsers and mobile devices,
|
12 | or Node.js backends
|
13 |
|
14 | For release notes, see the [CHANGELOG](https://github.com/aws/aws-sdk-js/blob/master/CHANGELOG.md). Prior to v2.4.8, release notes can be found at https://aws.amazon.com/releasenotes/?tag=releasenotes%23keywords%23javascript
|
15 |
|
16 | If you are upgrading from 1.x to 2.0 of the SDK, please see the
|
17 | [upgrading notes](https://github.com/aws/aws-sdk-js/blob/master/UPGRADING.md)
|
18 | for information on how to migrate existing code to work with the new major
|
19 | version.
|
20 |
|
21 | ## Installing
|
22 |
|
23 | ### In the Browser
|
24 |
|
25 | To use the SDK in the browser, simply add the following script tag to your
|
26 | HTML pages:
|
27 |
|
28 | <script src="https://sdk.amazonaws.com/js/aws-sdk-2.543.0.min.js"></script>
|
29 |
|
30 | You can also build a custom browser SDK with your specified set of AWS services.
|
31 | This can allow you to reduce the SDK's size, specify different API versions of
|
32 | services, or use AWS services that don't currently support CORS if you are
|
33 | working in an environment that does not enforce CORS. To get started:
|
34 |
|
35 | http://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/building-sdk-for-browsers.html
|
36 |
|
37 | The AWS SDK is also compatible with [browserify](http://browserify.org).
|
38 |
|
39 | For browser-based web, mobile and hybrid apps, you can use [AWS Amplify Library](https://aws.github.io/aws-amplify/?utm_source=aws-js-sdk&utm_campaign=browser) which extends the AWS SDK and provides an easier and declarative interface.
|
40 |
|
41 | ### In Node.js
|
42 |
|
43 | The preferred way to install the AWS SDK for Node.js is to use the
|
44 | [npm](http://npmjs.org) package manager for Node.js. Simply type the following
|
45 | into a terminal window:
|
46 |
|
47 | ```sh
|
48 | npm install aws-sdk
|
49 | ```
|
50 |
|
51 | ### In React Native
|
52 | To use the SDK in a react native project, first install the SDK using npm:
|
53 |
|
54 | ```sh
|
55 | npm install aws-sdk
|
56 | ```
|
57 |
|
58 | Then within your application, you can reference the react native compatible version of the SDK with the following:
|
59 |
|
60 | ```javascript
|
61 | var AWS = require('aws-sdk/dist/aws-sdk-react-native');
|
62 | ```
|
63 |
|
64 | Alternatively, you can use [AWS Amplify Library](https://aws.github.io/aws-amplify/media/react_native_guide?utm_source=aws-js-sdk&utm_campaign=react-native) which extends AWS SDK and provides React Native UI components and CLI support to work with AWS services.
|
65 |
|
66 | ### Using Bower
|
67 |
|
68 | You can also use [Bower](http://bower.io) to install the SDK by typing the
|
69 | following into a terminal window:
|
70 |
|
71 | ```sh
|
72 | bower install aws-sdk-js
|
73 | ```
|
74 |
|
75 | ## Usage and Getting Started
|
76 |
|
77 | You can find a getting started guide at:
|
78 |
|
79 | http://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide
|
80 |
|
81 | API reference at:
|
82 |
|
83 | https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/
|
84 |
|
85 | ## Usage with TypeScript
|
86 | The AWS SDK for JavaScript bundles TypeScript definition files for use in TypeScript projects and to support tools that can read `.d.ts` files.
|
87 | Our goal is to keep these TypeScript definition files updated with each release for any public api.
|
88 |
|
89 | ### Pre-requisites
|
90 | Before you can begin using these TypeScript definitions with your project, you need to make sure your project meets a few of these requirements:
|
91 |
|
92 | * Use TypeScript v2.x
|
93 | * Includes the TypeScript definitions for node. You can use npm to install this by typing the following into a terminal window:
|
94 |
|
95 | ```sh
|
96 | npm install --save-dev @types/node
|
97 | ```
|
98 |
|
99 | * If you are targeting at es5 or older ECMA standards, your `tsconfig.json` has to include `'es5'` and `'es2015.promise'` under `compilerOptions.lib`.
|
100 | See [tsconfig.json](https://github.com/aws/aws-sdk-js/blob/master/ts/tsconfig.json) for an example.
|
101 |
|
102 | ### In the Browser
|
103 | To use the TypeScript definition files with the global `AWS` object in a front-end project, add the following line to the top of your JavaScript file:
|
104 |
|
105 | ```javascript
|
106 | /// <reference types="aws-sdk" />
|
107 | ```
|
108 |
|
109 | This will provide support for the global `AWS` object.
|
110 |
|
111 | ### In Node.js
|
112 | To use the TypeScript definition files within a Node.js project, simply import `aws-sdk` as you normally would.
|
113 |
|
114 | In a TypeScript file:
|
115 |
|
116 | ```javascript
|
117 | // import entire SDK
|
118 | import AWS from 'aws-sdk';
|
119 | // import AWS object without services
|
120 | import AWS from 'aws-sdk/global';
|
121 | // import individual service
|
122 | import S3 from 'aws-sdk/clients/s3';
|
123 | ```
|
124 |
|
125 | In a JavaScript file:
|
126 |
|
127 | ```javascript
|
128 | // import entire SDK
|
129 | var AWS = require('aws-sdk');
|
130 | // import AWS object without services
|
131 | var AWS = require('aws-sdk/global');
|
132 | // import individual service
|
133 | var S3 = require('aws-sdk/clients/s3');
|
134 | ```
|
135 |
|
136 | ### With React
|
137 |
|
138 | To create React applications with AWS SDK, you can use [AWS Amplify Library](https://aws.github.io/aws-amplify/media/react_guide?utm_source=aws-js-sdk&utm_campaign=react) which provides React components and CLI support to work with AWS services.
|
139 |
|
140 | ### With Angular
|
141 | Due to the SDK's reliance on node.js typings, you may encounter compilation
|
142 | [issues](https://github.com/aws/aws-sdk-js/issues/1271) when using the
|
143 | typings provided by the SDK in an Angular project created using the Angular CLI.
|
144 |
|
145 | To resolve these issues, either add `"types": ["node"]` to the project's `tsconfig.app.json`
|
146 | file, or remove the `"types"` field entirely.
|
147 |
|
148 | [AWS Amplify Library](https://aws.github.io/aws-amplify/media/angular_guide?utm_source=aws-js-sdk&utm_campaign=angular) provides Angular components and CLI support to work with AWS services.
|
149 |
|
150 | ### Known Limitations
|
151 | There are a few known limitations with the bundled TypeScript definitions at this time:
|
152 |
|
153 | * Service client typings reflect the latest `apiVersion`, regardless of which `apiVersion` is specified when creating a client.
|
154 | * Service-bound parameters use the `any` type.
|
155 |
|
156 | ## Getting Help
|
157 | Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests and have limited bandwidth to address them.
|
158 |
|
159 | * Ask a question on [StackOverflow](https://stackoverflow.com/) and tag it with `aws-sdk-js`
|
160 | * Come join the AWS JavaScript community on [gitter](https://gitter.im/aws/aws-sdk-js?source=orgpage)
|
161 | * Open a support ticket with [AWS Support](https://console.aws.amazon.com/support/home#/)
|
162 | * If it turns out that you may have found a bug, please [open an issue](https://github.com/aws/aws-sdk-js/issues/new)
|
163 |
|
164 | ## Opening Issues
|
165 | If you encounter a bug with the AWS SDK for JavaScript we would like to hear
|
166 | about it. Search the [existing issues](https://github.com/aws/aws-sdk-js/issues)
|
167 | and try to make sure your problem doesn’t already exist before opening a new
|
168 | issue. It’s helpful if you include the version of the SDK, Node.js or browser
|
169 | environment and OS you’re using. Please include a stack trace and reduced repro
|
170 | case when appropriate, too.
|
171 |
|
172 | The GitHub issues are intended for bug reports and feature requests. For help
|
173 | and questions with using the AWS SDK for JavaScript please make use of the
|
174 | resources listed in the [Getting Help](https://github.com/aws/aws-sdk-js#getting-help)
|
175 | section. There are limited resources available for handling issues and by
|
176 | keeping the list of open issues lean we can respond in a timely manner.
|
177 |
|
178 | ## Supported Services
|
179 |
|
180 | Please see [SERVICES.md](https://github.com/aws/aws-sdk-js/blob/master/SERVICES.md) for a list of supported services.
|
181 |
|
182 | ## License
|
183 |
|
184 | This SDK is distributed under the
|
185 | [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0),
|
186 | see LICENSE.txt and NOTICE.txt for more information.
|