# @threeleafsoftware/serverless-spa-plugin

> A plugin to simplify deploying Single Page Applications using S3 and CloudFront

Latest version **1.0.2** (published 2022-11-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @threeleafsoftware/serverless-spa-plugin
pnpm add @threeleafsoftware/serverless-spa-plugin
yarn add @threeleafsoftware/serverless-spa-plugin
bun add @threeleafsoftware/serverless-spa-plugin
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2022-11-04 |
| First published | 2022-11-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 14.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Daniel Braga |
| Maintainers | daniel-braga |

## Links

- npm: https://www.npmjs.com/package/@threeleafsoftware/serverless-spa-plugin
- Repository: https://github.com/threeleafsoftware/serverless-spa-plugin
- Issues: https://github.com/threeleafsoftware/serverless-spa-plugin/issues
- npm.io page: https://npm.io/package/@threeleafsoftware/serverless-spa-plugin

## Recent versions

- 1.0.2 (latest) — 2022-11-04
- 0.0.0-development — 2022-11-04
- 1.0.1 — 2022-11-04

## README

# Serverless SPA Plugin

A plugin for [Serverless Framework](https://serverless.com), to simplify deploying Single Page Application using S3 and CloudFront.

Based on the [official example](https://github.com/serverless/examples/tree/master/aws-node-single-page-app-via-cloudfront/serverless-single-page-app-plugin), with some important tweaks:

- Configurable app source directory
- Configurable stack output name to indicate the distribution id

## Instalation

Install the package with NPM or Yarn.

NPM:

```
npm install --save-dev @threeleafsoftware/serverless-spa-plugin
```

Yarn:

```
yarn add --dev @threeleafsoftware/serverless-spa-plugin
```

## Setup

Then register it in your serverless.yml file, as a plugin:

```
plugins:
  - @threeleafsoftware/serverless-spa-plugin
```

Set plugin variables:

```
custom:
  spa:
    appDir: dist
    appBucket: my.app.com
    distributionIdOutputKey: WebAppCloudFrontDistributionId
```

Finally, add appropriately-named resources (Origin Access Control, Bucket, BucketPolicy and Distribution) and Outputs:

```
service: 'my-webapp'
frameworkVersion: '3'

plugins:
  - serverless-spa-plugin

provider:
  name: 'aws'
  ...

custom:
  spa:
    appDir: dist
    appBucket: my.webapp.com
    distributionIdOutputKey: WebAppCloudFrontDistributionId

resources:
  Resources:

    WebAppCloudFrontOriginAccessControl:
      Type: AWS::CloudFront::OriginAccessControl
      Properties:
        OriginAccessControlConfig:
            Description: Origin Access Control to WebApp bucket
            Name: WebAppOAC
            OriginAccessControlOriginType: s3
            SigningBehavior: always
            SigningProtocol: sigv4

    WebAppS3Bucket:
      Type: AWS::S3::Bucket
      Properties:
        BucketName: ${self:custom.spa.appBucket}
        AccessControl: PublicRead
        WebsiteConfiguration:
          IndexDocument: index.html
          ErrorDocument: index.html

    WebAppS3BucketPolicy:
      Type: AWS::S3::BucketPolicy
      Properties:
        Bucket:
          Ref: WebAppS3Bucket
        PolicyDocument:
          Statement:
            - Sid: AllowCloudFrontServicePrincipalReadOnly
              Action:
                - 's3:GetObject'
              Effect: Allow
              Resource:
                Fn::Join:
                  - ''
                  - - 'arn:aws:s3:::'
                    - Ref: WebAppS3Bucket
                    - /*
              Principal:
                Service: "cloudfront.amazonaws.com"
              Condition:
                StringEquals:
                  "aws:SourceArn":
                    - Fn::Join:
                      - ''
                      - - 'arn:aws:cloudfront::'
                        - Ref: AWS::AccountId
                        - ':distribution/'
                        - Ref: WebAppCloudFrontDistribution

    WebAppCloudFrontDistribution:
      Type: AWS::CloudFront::Distribution
      DependsOn:
        - WebAppS3Bucket
        - WebAppCloudFrontOriginAccessControl
      Properties:
        DistributionConfig:
          Aliases:
            - ${self:custom.spa.appBucket}
          ViewerCertificate:
            CloudFrontDefaultCertificate: 'true'
          Origins:
            - DomainName: ${self:custom.spa.appBucket}.s3.amazonaws.com
              Id: WebApp
              OriginAccessControlId: !Ref WebAppCloudFrontOriginAccessControl
              S3OriginConfig:
                OriginAccessIdentity: ''
          Enabled: 'true'
          DefaultRootObject: index.html
          CustomErrorResponses:
            - ErrorCode: 404
              ResponseCode: 200
              ResponsePagePath: /index.html
          DefaultCacheBehavior:
            AllowedMethods:
              - DELETE
              - GET
              - HEAD
              - OPTIONS
              - PATCH
              - POST
              - PUT
            TargetOriginId: WebApp
            ForwardedValues:
              QueryString: 'false'
              Cookies:
                Forward: none
            ViewerProtocolPolicy: redirect-to-https

  Outputs:

    WebAppCloudFrontDistributionId:
      Description: 'Cloudfront distribution ID'
      Value:
         Fn::GetAtt:
          - WebAppCloudFrontDistribution
          - Id

```

## Deploy

Warning: Whenever you making changes to CloudFront resource in serverless.yml the deployment might take a while e.g 20 minutes.

In order to deploy the Single Page Application you need to setup the infrastructure first by running

```
serverless deploy
```

The expected result should be similar to:

```
Serverless: Packaging service…
Serverless: Uploading CloudFormation file to S3…
Serverless: Uploading service .zip file to S3…
Serverless: Updating Stack…
Serverless: Checking Stack update progress…
...........................
Serverless: Stack update finished…

Service Information
service: serverless-simple-http-endpoint
stage: dev
region: us-east-1
api keys:
  None
endpoints:
  None
functions:
  None
```

After this step your S3 bucket and CloudFront distribution is setup. Now you need to upload your static file e.g. index.html and app.js to S3. You can do this by running

```
serverless syncToS3
```

The expected result should be similar to

```
Serverless: upload: dist/index.html to s3://my.webapp.com/index.html
Serverless: upload: dist/app.js to s3://my.webapp.com/app.js
Serverless: Successfully synced to the S3 bucket
```

Now you just need to figure out the deployed URL. You can use the AWS Console UI or run

```
sls domainInfo
```

The expected result should be similar to

```
Serverless: Web App Domain: dyj5gf0t6nqke.cloudfront.net
```

Visit the printed domain domain and navigate on the web site. It should automatically redirect you to HTTPS and visiting /about will not result in an error with the status code 404, but rather serves the index.html and renders the about page.

## Re-deploying

If you make changes to your Single Page Application you might need to invalidate CloudFront's cache to make sure new files are served. Meaning, run:

```
serverless syncToS3
```

To sync your files and then:

```
serverless invalidateCloudFrontCache
```

---
_Source: https://npm.io/package/@threeleafsoftware/serverless-spa-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._