A Serverless Framework plugin for deployment of static website assets of your Serverless project to AWS S3.
npm install --save serverless-finch
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
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.
tags
optional, default: none
custom:
client:
...
tags:
tagKey: tagvalue
tagKey2: tagValue2
...
Use this parameter to specify a list of tags as key:value pairs that will be assigned to your bucket.
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 single 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/*",
Note: You can also use ${env:PWD}
if you want to dynamically specify the policy within your repo. for example:
custom:
client:
...
bucketPolicyFile: "${env:PWD}/path/to/policy.json"
...
_Additionally, you will want to specify different policies depending on your stage using ${self:provider.stage}
to ensure your BUCKET_NAME
corosponds to the stage._
custom:
client:
...
bucketPolicyFile: "/path/to/policy-${self:provider.stage}.json"
...
corsFile
custom:
client:
...
corsFile: path/to/cors.json
...
Path to a JSON file defining the bucket CORS configuration.
If not set, it defaults to the configuration defined here.
See above docs on bucketPolicyFile
option for how to provide a dynamic file path.
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: protocol # "http" or "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'.
routingRules
optional, no default
custom:
client:
...
routingRules:
- redirect:
hostName: hostName
httpRedirectCode: httpCode
protocol: protocol # "http" or "https"
replaceKeyPrefixWith: prefix
replaceKeyWith: [object]
condition:
keyPrefixEquals: prefix
httpErrorCodeReturnedEquals: httpCode
- ...
...
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:
hostName
is the name of the host that the request should be redirected to (e.g. 'www.other-site.com'). Defaults to the host from the original request.httpRedirectCode
is the HTTP status code to use for the redirect (e.g. 301, 303, 308).protocol
is the protocol to use for the redirect and must be 'http' or 'https'. Defaults to the protocol from the original request.replaceKeyPrefixWith
specifies the string to replace the portion of the route specified in the keyPrefixEquals
with in the redirect. For instance, if you want to redirect requests for pages starting with '/images' to pages starting with '/assets/images', you can specify keyPrefixEquals
as '/images' and replaceKeyPrefixWith
as '/assets/images'. Cannot be specified along with replaceKeyWith
.replaceKeyWith
specifies a specific page to redirect requests to (e.g. 'landing.html'). Cannot be specified along with replaceKeyPrefixWith
.The condition
property has two optional parameters:
keyPrefixEquals
specifies that requests to pages starting with the specified value should be redirected. Often used with the replaceKeyPrefixWith
and replaceKeyWith
redirect
properties.httpErrorCodeReturnedEquals
specifies that requests resulting in the given HTTP error code (e.g. 404, 500) should be redirected.If condition
is not specified, then all requests will be redirected in accordance with the specified redirect
properties
uploadOrder
optional, no default
custom:
client:
...
uploadOrder:
- .*
- .*/assets/.*
- service-worker\.js
- index\.html
...
The uploadOrder
option can be used to control the order that files are uploaded to the bucket.
Each entry is evaluated as a case-insensitive regular expression.
Unmatched files are uploaded first.
When combined with --no-delete-contents
this can help with zero downtime (e.g. by uploading assets before the html files that depend on them).
keyPrefix
optional, no default
custom:
client:
...
keyPrefix: s3-folder/possible-sub-folder
...
Adding a keyPrefix option, so that it's possibly to upload files to a prefixed s3 path. You can use this to specify a key prefix path such as static
so the deployment matches the naming conventions of popular frontend frameworks and tools.
sse
optional, no default
custom:
client:
...
sse: AES256
...
Enable server side encryption for the uploaded files. You can use AES256
or aws:kms
.
manageResources
optional, default true
(the plugin does manage your resources by default)
custom:
client:
...
manageResources: false
...
This allows you to opt out of having serverless-finch create or configure the s3 bucket. Instead, you can rely on an existing bucket or a CloudFormation definition.
--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.
Please read our contribution guide.
See Releases for releases after v2.6.0
.
keyPrefix
option - Pull 102 - Josephsse
option to allow you to encrypt files with Server Side Encryption using AES256
or aws:kms
- Pull 91 - Severi HaverilamanageResources
option to allow you to tell serverless-finch to not interact with your S3 bucket - Pull 75 - sprockowkeyPrefix
option to enable working with S3 folders - Pull 76 - ArchaniumdistributionFolder
configuration value. This enables you to upload your website files from a custom directory (Pull 12 - pradel)remove
option to tear down what you deploy. (Pull 10 thanks to redroot)Forked from the serverless-client-s3