Como crear una aplicación con AWS Amplify

Mucho se habla últimamente de AWS Amplify, pero ¿por qué?, ¿qué es? y ¿para qué sirve?

AWS Amplify es un conjunto de herramientas (marco de código de abierto, interfaz de usuario de administración, consola) y servicios (alojamiento web estático) que se pueden utilizar juntos o de forma individual con el fin de ser una opción full stack para la creación de un proyecto.

Algunas de las opciones de integración web y móvil son:  Javascript, React, React Native, Angular, Vue, Next.js, Android, iOS, Ionic y Flutter. Para algunos Frameworks disponemos de los que llaman UI Components que nos proveen componentes útiles para desarrollos más veloces.

Sin embargo, se puede volver abrumador la cantidad de documentación y opciones que tenemos.

Hoy vamos a enfocarnos en una aplicación con aws amplify que consistirá en crear una aplicación en React, usando Amplify para agregar una autorización con AWS Cognito, creando una API(API GATEWAY) con diferentes paths y conectandola a funciones lambdas, de esta manera tenemos una estructura, que según su necesidad o imaginación puede servir de template para infinitos proyectos.

😉 Pre-requisitos:

  • Node.js v12.x o posterior
  • npm v5.x o posterior
  • Git v2.14.1 o posterior
  • Amplify cli

-- CODE language-powershell -- npm install -g @aws-amplify/cli

amplify configure : para configurar se debe tener una cuenta aws a la que se redirigirá para iniciar sesión.

Una vez que haya iniciado sesión, Amplify CLI le pedirá que cree un usuario IAM. Si ya tiene un usuario creado, puede volver a la terminal, presionar enter y agregar sus credenciales.

(El usuario debe ser AdministratorAccess o con acceso a lo siguiente: AWS Amplify - AppSync - Cognito - API Gateway)
 
Specify the AWS Region
? region:# Your preferred region
Specify the username of the new IAM user:
? user name:# User name for Amplify IAM user
Complete the user creation using the AWS console

Enter the access key of the newly created user:
? accessKeyId:# YOUR_ACCESS_KEY_ID
? secretAccessKey:# YOUR_SECRET_ACCESS_KEY
This would update/create the AWS Profile in your local machine
? Profile Name:# (default)

Successfully set up the new user.

Ejemplo:

 
Specify the AWS Region
? region:  us-east-1
? user name:  jazmin@kranio.io
? accessKeyId:  AKIAIOSFODNN7EXAMPLE
? secretAccessKey:  wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
This would update/create the AWS Profile in your local machine
? Profile Name:  kranio

Successfully set up the new user.

🚀 Ahora es momento de comenzar con el proyecto:

Vamos a ir paso a paso, algunos pasos tienen una o más formas de implementar, puedes seguir la opción que más te acomode.

🧠 Paso 1: Crear React App

 
npx create-react-app "nombre de carpeta nueva o una ya conectada a un repositorio(bitbucket-gitHub-gitLab)"

example:

npx create-react-app AmplifyReactProject
cd AmplifyReactProject

🧠 Paso 2: Iniciar amplify

  • Dato: Amplify tiene una serie de comandos muy completos que nos ayudarán a hacer todo lo necesario desde nuestra terminal.
comandos aws amplify

En el siguiente bloque de código puedes ver un ejemplo de como iniciar Amplify en tu App React:

 
Enter a name for the project (AmplifyReactProject)

# All AWS services you provision for your app are grouped into an "environment"
# A common naming convention is dev, staging, and production
Enter a name for the environment (dev)

# Sometimes the CLI will prompt you to edit a file, it will use this editor to open those files.
Choose your default editor # example: VS Code

# Amplify supports JavaScript (Web & React Native), iOS, and Android apps
Choose the type of app that you're building (javascript)

What JavaScript framework are you using (react)

Source directory path (src)

Distribution directory path (build)

Build command (npm run build)

Start command (npm start)

# This is the profile you created with the `amplify configure` command in the introduction step.
Do you want to use an AWS profile

MAS INFO: https://docs.amplify.aws/start/getting-started/setup/q/integration/react/#initialize-a-new-backend

🧠 Paso 3: Instalar amplify libraries(React)

 

npm install aws-amplify @aws-amplify/ui-react


🧠 Paso 4: Configurar Frontend

Abra src / index.js y agregue el siguiente código debajo de la última importación:
 
import Amplify from "aws-amplify";
import awsExports from "./aws-exports";
Amplify.configure(awsExports);

El archivo aws-exports es un archivo de configuración generado por ampify.

🧠 Paso 5: Crear o importar Auth(Cognito) a Amplify

Si no se dispone de un Cognito existente puedes crear uno de esta manera:

 
$amplify add auth

? Do you want to use the default authentication and security configuration? Default configuration
? How do you want users to be able to sign in? Username
? Do you want to configure advanced settings?  No, I am done.

$amplify push

Importar un Cognito existente:

 

amplify import auth


MÁS INFO: https://docs.amplify.aws/cli/auth/import/

🧠 Paso 6: Usar auth para login en el front-end

Para usar esta autorización (creada o importada) en nuestra App, tenemos dos caminos:

  • Con withAuthenticator:
Abra   src / App.js y realice los siguientes cambios:
🔹 Importar los componentes AmplifySignOut : withAuthenticatory y AmplifySignOut :
 

import { withAuthenticator, AmplifySignOut } from "@aws-amplify/ui-react";


🔹 Agregue el componente AmplifySignOut al principio del todo: Este componente nos ayuda a salir de la session.
 


🔹 Cambie la exportación predeterminada para que sea la withAuthenticator envoltura del componente principal:
 

export default withAuthenticator(App)


🔹 Ejecute la App con npm start y debería ver esto:
login screen: enter sername and password and click sign in button

🔹 Ahora para acceder a su app debe crear una cuenta (cognito), para eso puede usar la opción create account, confirmar con su correo e ingresar.

🔹 Pero también tiene la opcion de entrar a cognito desde la consola aws, buscar su userPool y agregar usuarios manualmente:

consola de cognito para definir usuarios manulamente
Si es una aplicación privada es recomendable deshabilitar la opción create account y solo crear cuentas desde la consola, así cualquier persona no ingresará ni se podrán crear cuentas.

🔹 Para deshabilitar create account. En la sección Politicas responda la segunda pregunta con la opción: Permitir que solo los administradores creen usuarios.

consola para definir niveles de seguridad
  • Con Customización:

Tenemos la opción de customizar nuestro Login, para eso necesitamos conocimientos sobre la librería que se esté usando, en este caso React. Puede tener una idea con esta documentación:

https://docs.amplify.aws/lib/auth/emailpassword/q/platform/js/#custom-attributes

https://docs.amplify.aws/start/getting-started/auth/q/integration/react/#create-login-ui

🧠 Paso 7: Crear una API Gateway con amplify (REST)

Al momento de crear una API tenemos muchas posibilidades, hoy veremos como agregar dos path unidos cada uno a una lambda function diferente.

Antes de crear la API vamos a entender que queremos lograr.  Vamos a unir funciones lambdas a paths distintos en nuestra API.

De esta forma:

🔹 Para el path /pathOne se creará una función {lambdaExampleOne}
🔹 Para el path /pathTwo se creará una función {lambdaExampleTwo}

Al momento de crear nuestra API tendremos crear un path inmediatamente, por eso vamos a agregar uno en este paso y luego veremos como agregar otro.

  • Al momento de agregar una función nos da tres opciones como "template", cada uno tiene propósitos distintos:
 

? Choose the function template that you want to use: (Use arrow keys)
❯ Hello world function
  CRUD function for Amazon DynamoDB table (Integration with Amazon API Gateway and Amazon DynamoDB)
  Serverless express function (Integration with Amazon API Gateway)


• El Hello World function creará una función básica de Lambda hello world
• La CRUD function for Amazon DynamoDB table (Integration with Amazon API Gateway and Amazon DynamoDB) función agregaría una plantilla de función Lambda predefinida sin servidor-express para operaciones CRUD a las tablas de DynamoDB (que puede crear siguiendo las indicaciones de la CLI o usar las tablas que ya ha configurado con el amplify add storagecomando)
• La Serverless express function (Integration with Amazon API Gateway) añadirá un predefinido expresar sin servidor- Lambda plantilla de función con el enrutamiento habilitado para sus rutas de API REST

MAS INFO: https://docs.amplify.aws/cli/function/#set-up-a-function

 

$amplify add api

? Please select from one of the below mentioned services:
    `REST`
? Provide a friendly name for your resource to be used as a label for this category in the project:
    `KranioApiExample`
? Provide a path (e.g., /book/{isbn}):
    `/pathOne`
? Choose a Lambda source
    `Create a new Lambda function`
? Provide a friendly name for your resource to be used as a label for this category in the project:
    `kranio`
? Provide the AWS Lambda function name:
    `lambdaExampleOne`
? Choose the function runtime that you want to use:
    `NodeJS`
? Choose the function template that you want to use:
    `Serverless ExpressJS function (Integration with API Gateway)`
? Do you want to access other resources created in this project from your Lambda function?
    `No`
? Do you want to invoke this function on a recurring schedule?
    `No`
? Do you want to edit the local lambda function now? `No`
Successfully added the Lambda function locally
? Restrict API access
    `Yes`
? Who should have access?
    `Authenticated`
? What kind of access do you want for Authenticated users?
    `create, read, update, delete`
Successfully added auth resource locally.
? Do you want to add another path?
    `No`
$amplify push


Una vez creada la api podemos importarla y configurarla en nuestra App.

Por ejemplo en App.js en React o main.ts en Angular:
 


También tenemos la opción de importar una API ya existente solamente omitiendo la creación y agregándola a la configuración directamente.

Esta configuración nos permite hacer requisiciones directo a la api, por ejemplo para un GET:

 

import { API } from "aws-amplify";

const apiName = 'MyApiName';
const path = '/path';
const myInit = { // OPTIONAL
    headers: {}, // OPTIONAL
    response: true, // OPTIONAL (return the entire Axios response object instead of only response.data)
    queryStringParameters: {  // OPTIONAL
        name: 'param',
    },
};

API
  .get(apiName, path, myInit)
  .then(response => {
		console.log(response);
    // Add your code here
  })
  .catch(error => {
    console.log(error.response);
 });


🧠 Paso 8: Agregar otro path a nuestra API

En el paso anterior creamos nuestra API y la configuramos, ahora vamos a agregar un nuevo path y vamos a unirla a una función Lambda nueva tal como el path anterior.

 

// Opciones para agregar, actualizar o eliminar path:

$ amplify api update
? Please select from one of the below mentioned services: REST
? Please select the REST API you would want to update KranioApiExample
? What would you like to do
> Add another path
  Update path
  Remove path


 

$ amplify api update
? Please select from one of the below mentioned services: REST
? Please select the REST API you would want to update KranioApiExample
? What would you like to do Add another path
? Provide a path (e.g., /book/{isbn}): /pathTwo
? Choose a Lambda source (Use arrow keys)
> Create a new Lambda function
  Use a Lambda function already added in the current Amplify project


Estas acciones generaron dentro del directorio Amplify/backend carpetas con los recursos, donde podremos trabajar la funcionalidad para las lambdas.

estructura de carpetas y recursos

🧠 Paso 9: Amplify Deploy

Después de crear nuestros recursos en amplify, tanto el frontend como el backend, tenemos que implementarlos. Para esto tenemos varias posibilidades.

Tenemos el comando:

 

amplify push

Para implementar solo el backend de nuestro proyecto amplify.

Tenemos también el comando:

 

amplify publish


Que aplicará tanto el frontend como el backend de nuestro proyecto. Pero para implementar el frontend, antes tenemos que crear un hosting que consiste en una estructura que albergará la aplicación web, tenemos tres: amplify console, directamente en un bucket de s3 o una combinación de bucket de s3 con cloudfront.

Para esto usamos el comando:

 

amplify add hosting

MÁS INFO: https://docs.amplify.aws/cli/hosting/hosting/

Amplify CI/CD

Tenemos dos posibilidades de tener un pipeline de despliegue continuo con amplify: manual o automatizado por amplify. Al hacer un add hosting puedes elegir cómo quieres hacerlo, lo interesante es que puedes tener un tipo específico para cada entorno y un formato en dev, un formato en una rama de feature, un formato para qa, eligiendo siempre lo que mejor se adapte.

Lo siguiente es un ejemplo de despliegue automatizado de Amplify:

  • Primero localizamos el front environment de nuestra App en AWS Amplify y lo conectamos a nuestro repositorio:
selecion de template para frontend
  • Luego elegimos la rama en la que queremos hacer deploy,en este caso develop, sin embargo, como se comentó anteriormente, se puede configurar tantos despliegues automatizados como ramas tenga nuestro proyecto.
seleccionar rama y configuración
  • Lo siguiente es seleccionar nuestra aplicación en el environment (dev) y agregar un rol con acceso a amplify. Si no hay ninguno puedes crear fácilmente en la opción Create new role y seguir lo pasos indicados, luego refrescar para que aparezca es suficiente.
seleccionar aplicación en el enviroment(dev)
  • Esto es necesario para continuar:
llenar campos obligatorios
  • Antes de avanzar al siguiente paso presiona la casilla de: Allow AWS Amplify  to automatically deploy all files hosted in your project root directory
click para permitir deploy automatico aws amplify
  • Finalmente Presionamos Save and Deploy y es todo, la aplicación comenzará el despliegue:
iniciar el desplieuge (deploy) de la aplicación
confirmación del deploy de la aplicación con aws amplify

🧠 Conclusión

Finalmente, ahora sabes que es amplify, sus opciones, y tienes una guia ejemplo de cómo implementar servicios en Backend como API Gateway, Cognito, Lambda Functions con una librería Front-end en específico. Tienes un proceso para crear una aplicación con aws amplify. Es momento de adaptarlo a tu necesidad. Ya sea si tienes una aplicación en front que necesite un backend rápido y escalable o si quieres partir de cero, esta será sin duda una buena opción.

¿Tienes una idea? ¿no sabes cómo empezar? Escribenos.

Co-autor: Gustavo Matozinho

Jazmín Trujillo

September 30, 2021