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
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
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.
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.
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.
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.
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] ...
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
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
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'.
optional, no default
custom: client: ... redirectAllRequestsTo: hostName: [hostName] protocol: [http|https] ...
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'.
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...] ...
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.
redirect property of each rule has five optional parameters:
hostNameis 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.
httpRedirectCodeis the HTTP status code to use for the redirect (e.g. 301, 303, 308).
protocolis the protocol to use for the redirect and must be 'http' or 'https'. Defaults to the protocol from the original request.
replaceKeyPrefixWithspecifies the string to replace the portion of the route specified in the
keyPrefixEqualswith 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
keyPrefixEqualsas '/images' and
replaceKeyPrefixWithas '/assets/images'. Cannot be specified along with
replaceKeyWithspecifies a specific page to redirect requests to (e.g. 'landing.html'). Cannot be specified along with
condition property has two optional parameters:
keyPrefixEqualsspecifies that requests to pages starting with the specified value should be redirected. Often used with the
httpErrorCodeReturnedEqualsspecifies that requests resulting in the given HTTP error code (e.g. 404, 500) should be redirected.
condition is not specified, then all requests will be redirected in accordance with the specified
optional, defaults to value specified in
provider section of
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
is not specified via the CLI, we use the
region option specified under
serverless.yml. If that is not specified, we use the Serverless
region specified under
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.
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.
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.
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.
false (disables confirmation prompt)
serverless client deploy --no-confirm
Use this parameter if you do not want a confirmation prompt to interrupt automated builds.
For guidelines on contributing to the project, please refer to our Contributing page.
- Major refactor of entire codebase to move towards modularity and testability
- Added the ability to set HTTP headers for objects in bucket (Issue 24)
- Added the ability to set redirect and routing options for the website (Initially implemented in Pull 23)
- Added command-line options to disable (Initially implemented in Pull 28):
- Bucket contents being deleted before deployment
- Bucket configuration being overwritten on deployment
- Bucket policy being overwritten on deployment
- Bucket CORS configuration being overwritten on deployment
- Added validation checks for all configuration options
- Removed "stage" command-line option. It was not being used for anything
- Added the ability to set a
distributionFolderconfiguration value. This enables you to upload your website files from a custom directory (Pull 12 - pradel)
- Updated the URL to the official static website endpoint URL (Pull 13 - amsross)
- Added a new AWS region (Pull 14 - daguix)
- Fixed an issue with resolving serverless variables (Pull 18 - shentonfreude)
- Added the
removeoption to tear down what you deploy. (Pull 10 thanks to redroot)
- Fixed automated builds for the project (no functional differences)
- You - If you're interested in having a more active role in development and becoming a maintainer get in touch.
- Fernando Medina Corey - fernando-mc
- Linus Marco - linusmarco
Forked from the serverless-client-s3