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