crazypython/aws-amplify

A declarative library for application development using cloud services with JavaScript

AWS Amplify

AWS Amplify is a JavaScript library for frontend and mobile developers building cloud-enabled applications. The library is a declarative interface across different categories of operations in order to make common tasks easier to add into your application. The default implementation works with Amazon Web Services (AWS) resources but is designed to be open and pluggable for usage with other cloud services that wish to provide an implementation or custom backends.

• Installation
  • Web Development
  • React Native Development
• Documentation
• Examples
  • 1. Collect user session metrics.
  • 2. Add Authentication
  • 3. Override default authentication screens
  • 4. Sign HTTP requests
  • 5. Upload and Download public or private content
• Contributing

Installation

Web Development

AWS Amplify is available as the aws-amplify package on npm

$ npm install aws-amplify --save

If you are developing a React app, you can install an additional package aws-amplify-react containing Higher Order Components:

$ npm install aws-amplify-react --save

React Native Development

For React Native development, install aws-amplify

$ npm install aws-amplify --save

If you are developing a React Native app, you can install an additional package aws-amplify-react-native containing Higher Order Components:

$ npm install aws-amplify-react-native --save

Unless your react-native app was created using Expo v25.0.0 or greater, you will need to link libraries in your project for the Auth module on React Native.

To link amazon-cognito-identity-js, you must first eject the project:

$ npm run eject
$ react-native link amazon-cognito-identity-js

Now run your application as normal:

$ react-native run-ios

Documentation is available here

Examples

AWS Amplify supports many category scenarios such as Auth, Analytics, APIs and Storage as outlined in the Developer Guide. A couple of samples are below. For in-depth samples with specific frameworks:

• React
• React Native
• Ionic
• Vue (coming soon)
• Angular (coming soon)

The examples assume you have an aws-exports.js file which describes your backend. This file is autogenerated and created by the awsmobile-cli:

$ npm install -g awsmobile-cli
$ cd your-project
$ awsmobile init     # <-- This will create a new AWS Mobile Hub project and retrieve the aws-exports.js file for you.

1. Collect user session metrics

By default, AWS Amplify can send user session information as metrics with a few lines of code:

import Amplify, { Analytics } from 'aws-amplify';
import aws_exports from './aws-exports';

Amplify.configure(aws_exports);
...
Analytics.record('myCustomEvent');

See here for the Analytics developer guide.

2. Add Authentication to your App

Take a fresh React app created by create-react-app as an example.
First initialize the project with awsmobile-cli, and add the user-signin feature to the backend awsmobile project

$ cd your-project
$ awsmobile init    
$ awsmobile user-signin enable
$ awsmobile push

Then edit the App.js file:

import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';

import Amplify from 'aws-amplify';
import { withAuthenticator } from 'aws-amplify-react';
import aws_exports from './aws-exports';

Amplify.configure(aws_exports);

class App extends Component {
  render() {
    return (
      <div className="App">
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <h1 className="App-title">Welcome to React</h1>
        </header>
        <p className="App-intro">
          To get started, edit <code>src/App.js</code> and save to reload.
        </p>
      </div>
    );
  }
}

export default withAuthenticator(App);

If you are working in React Native the exact same setup is used. Simply include aws-amplify-react-native instead:

...
import Amplify from 'aws-amplify';
import { withAuthenticator } from 'aws-amplify-react-native';
import aws_exports from './aws-exports';
Amplify.configure(aws_exports);

...

export default withAuthenticator(App);

3. Override default authentication screens

The withAuthenticator HOC gives you some good default authentication screens. But if you need to customize those screens with more than simply styles, it also provides an optional third parameter through which you can pass the list of customized (or not) screens:

import React, { Component } from 'react';
import { ConfirmSignIn, ConfirmSignUp, ForgotPassword, SignIn, SignUp, VerifyContact, withAuthenticator } from 'aws-amplify-react';

class App extends Component {
  render() {
    ...
  }
}

class MySignIn extends SignIn {
  render() {
    ...
  }
}

export default withAuthenticator(App, false, [
  <MySignIn/>,
  <ConfirmSignIn/>,
  <VerifyContact/>,
  <SignUp/>,
  <ConfirmSignUp/>,
  <ForgotPassword/>
]);

4. Sign HTTP requests

Sign REST requests with AWS Signature Version 4 using the API module to one or multiple endpoints:

let apiName = 'MyApiName';
let path = '/path'; 
let options = {
    headers: {...} // OPTIONAL
}
API.get(apiName, path, options).then(response => {
    // Add your code here
});

5. Upload and Download public or private content

With configurable settings, store content in an S3 bucket in public folders for all of your application's users or in private folders for each user identity:

  Storage.put(key, fileObj, {level: 'private'})
        .then (result => console.log(result))
        .catch(err => console.log(err));
        
    // Stores data with specifying its MIME type
    Storage.put(key, fileObj, {
        level: 'private',
        contentType: 'text/plain'
    })
    .then (result => console.log(result))
    .catch(err => console.log(err));

Contributing

See Contributing Guidelines