Serverless Finch

homepage icon https://github.com/fernando-mc/serverless-finch
Follow @fernando-mc

Tracked

NPM Downloads Last Month
7332
Issues
9
Stars
164
Forks
33
Watchers
164
Watch Star Fork Issue Download License NPM Build Status Coverage Status Contributors

Repo README Contents:

serverless-finch

npm npm license

A Serverless Framework plugin for deployment of static website assets of your Serverless project to AWS S3.

Installation

npm install --save serverless-finch

Usage

First, update your serverless.yml by adding the following:

plugins:
  - serverless-finch

custom:
  client:
    bucketName: [unique-s3-bucketname] # (see Configuration Parameters below)
    # [other configuration parameters] (see Configuration Parameters below)

NOTE: For full example configurations, please refer to the examples folder.

Second, Create a website folder in the root directory of your Serverless project. This is where your distribution-ready website should live. By default the plugin expects the files to live in a folder called client/dist. But this is configurable with the distributionFolder option (see the Configuration Parameters below).

The plugin uploads the entire distributionFolder to S3 and configures the bucket to host the website and make it publicly available, also setting other options based the Configuration Parameters specified in serverless.yml.

To test the plugin initially you can copy/run the following commands in the root directory of your Serverless project to get a quick sample website for deployment:

mkdir -p client/dist
touch client/dist/index.html
touch client/dist/error.html
echo "Go Serverless" >> client/dist/index.html
echo "error page" >> client/dist/error.html

Third, run the plugin, and visit your new website!

serverless client deploy [--region $REGION] [--no-delete-contents] [--no-config-change] [--no-policy-change] [--no-cors-change]

The plugin should output the location of your newly deployed static site to the console.

Note: See Command-line Parameters for details on command above

WARNING: The plugin will overwrite any data you have in the bucket name you set above if it already exists.

If later on you want to take down the website you can use:

serverless client remove

Configuration Parameters

bucketName

required

custom:
  client:
    bucketName: [unique-s3-bucketname]

Use this parameter to specify a unique name for the S3 bucket that your files will be uploaded to.


distributionFolder

optional, default: client/dist

custom:
  client:
    ...
    distributionFolder: [path/to/files]
    ...

Use this parameter to specify the path that contains your website files to be uploaded. This path is relative to the path that your serverless.yaml configuration files resides in.


indexDocument

optional, default: index.html

custom:
  client:
    ...
    indexDocument: [file-name.ext]
    ...

The name of your index document inside your distributionFolder. This is the file that will be served to a client visiting the base URL for your website.


errorDocument

optional, default: error.html

custom:
  client:
    ...
    errorDocument: [file-name.ext]
    ...

The name of your error document inside your distributionFolder. This is the file that will be served to a client if their initial request returns an error (e.g. 404). For an SPA, you may want to set this to the same document specified in indexDocument so that all requests are redirected to your index document and routing can be handled on the client side by your SPA.


bucketPolicyFile

custom:
  client:
    ...
    bucketPolicyFile: [path/to/policy.json]
    ...

Use this parameter to specify the path to a custom policy file. If not set, it defaults to a config for a basic static website. Currently, only JSON is supported. In your policy, make sure that your resource has the correct bucket name specified above: "Resource": "arn:aws:s3:::BUCKET_NAME/*",


objectHeaders

optional, no default

custom:
  client:
    ...
    objectHeaders:
      ALL_OBJECTS:
        - name: [header-name]
          value: [header-value]
        ...
      'someGlobPattern/*.html':
        - name: [header-name]
          value: [header-value]
        ...
      specific-directory/:
        - name: [header-name]
          value: [header-value]
        ...
      specific-file.ext:
        - name: [header-name]
          value: [header-value]
        ...
      ... [more file- or folder-specific rules]
    ...

Use the objectHeaders option to set HTTP response headers be sent to clients requesting uploaded files from your website.

Headers may be specified globally for all files in the bucket by adding a name, value pair to the ALL_OBJECTS property of the objectHeaders option. They may also be specified for specific folders or files within your site by specifying properties with names like specific-directory/ (trailing slash required to indicate folder) or specific-file.ext, where the folder and/or file paths are relative to distributionFolder.

Headers with more specificity will take precedence over more general ones. For instance, if ‘Cache-Control’ was set to ‘max-age=100’ in ALL_OBJECTS and to ‘max-age=500’ in my/folder/, the files in my/folder/ would get a header of ‘Cache-Control: max-age=500’.


redirectAllRequestsTo

optional, no default

custom:
  client:
    ...
    redirectAllRequestsTo:
      hostName: [hostName]
      protocol: [http|https]
    ...

Use the redirectAllRequestsTo option if you want to route all traffic coming to your website to a different address. hostName is the address that requests should be redirected to (e.g. ‘www.other-website.com’). protocol is the protocol to use for the redirect and must be either ‘http’ or ‘https’.

AWS Documentation


routingRules

optional, no default

custom:
  client:
    ...
    routingRules:
      - redirect:
          hostName: [hostName]
          httpRedirectCode: [CODE]
          protocol: [http|https]
          replaceKeyPrefixWith: [prefix]
          replaceKeyWith: [object]
        condition:
          keyPrefixEquals: [prefix]
          httpErrorCodeReturnedEquals: [CODE]
      - [more-rules...]
    ...

The routingRules option can be used to define rules for when and how certain requests to your site should be redirected. Each rule in the redirectRules list consists of a (required) redirect definition and (optionally) a condition on which the redirect is applied.

The redirect property of each rule has five optional parameters:

The condition property has two optional parameters:

If condition is not specified, then all requests will be redirected in accordance with the specified redirect properties

AWS Documentation


Command-line Parameters

–region

optional, defaults to value specified in provider section of serverless.yml

serverless client deploy --region $REGION

Use this parameter to specify what AWS region your bucket will be deployed in.

This option will always determine the deployment region if specified. If region is not specified via the CLI, we use the region option specified under custom/client in serverless.yml. If that is not specified, we use the Serverless region specified under provider in serverless.yml.


–no-delete-contents

optional, default false (deletes contents by default)

serverless client deploy --no-delete-contents

Use this parameter if you do not want to delete the contents of your bucket before deployment. Files uploaded during deployment will still replace any corresponding files already in your bucket.


–no-config-change

optional, default false (overwrites bucket configuration by default)

serverless client deploy --no-config-change

Use this parameter if you do not want to overwrite the bucket configuration when deploying to your bucket.


–no-policy-change

optional, default false (overwrites bucket policy by default)

serverless client deploy --no-policy-change

Use this parameter if you do not want to overwrite the bucket policy when deploying to your bucket.


–no-cors-change

optional, default false (overwrites bucket CORS configuration by default)

serverless client deploy --no-cors-change

Use this parameter if you do not want to overwrite the bucket CORS configuration when deploying to your bucket.


–no-confirm

optional, default false (disables confirmation prompt)

serverless client deploy --no-confirm

Use this parameter if you do not want a confirmation prompt to interrupt automated builds.


Contributing

For guidelines on contributing to the project, please refer to our Contributing page.

Release Notes

v2.0.*

v1.4.*

v1.3.*

v1.2.*

Maintainers

Contributors

Forked from the serverless-client-s3