About The Project
A tiny CLI tool to host any of your static next.js sites on AWS S3 and Cloudfront.
There are many great ways to host a Next.js app, especially vercel but there are times, when they are simply just overkill - and can even result in slower load times than a regular static site.
With that said, there are some pros and cons against hosting on S3;
Pros:
- There is no need for a server, your files will be hosted statically, which is simply faster.
- You can utilize Cloudfront's built-in GZipping, which will reduce your load times even more
Cons:
- Only static sites can be hosted on S3, with absolutely no SSR or ISG.
- You can not use any of Next's built-in API or middle-ware logic.
- A 3rd party image optimizer has to be used - or none at all.
I know there are other web frameworks, created for such type of hosting but let's be honest; working on a next.js project can't be compared DX-wise to any other production framework.
Getting Started
Installation
Using NPM
npm install --save-dev next-s3
or using yarn
yarn add -D next-s3
Note: It is recommended to install the page as a dev dependency.
Usage
Run the following command from inside your Next.js project:
next-s3 deploy --bucket <bucket-name> --distribution <cloudfront distribution id>
Note: I assume the package has been installed globally.
Parameters
All the parameters available to use:
| Option | Dotenv key | Required | Description | Default |
|---|---|---|---|---|
| -p, --profile | NEXT_S3_PROFILE | No | Name of the local AWS profile which will be used | - |
| --publicKey | NEXT_S3_PUBLIC_KEY | No | Public access key which will be used during upload | - |
| --secretKey | NEXT_S3_PRIVATE_KEY | No | Secret key generated for the public key | - |
| -b, --bucket | NEXT_S3_BUCKET | Yes | The name of the S3 bucket to be used. | - |
| -d, --distribution | NEXT_S3_DISTRIBUTION | No | Cloudformation ID to be invaidated after deployment. | - |
| -p, --basepath | NEXT_S3_BASEPATH | No | Base path the site will be available under. | '/' |
| --manager | - | No | Package manager to be used to run commands. | 'yarn' |
| -v, --verbose | - | No | Enable verbose logging | false |
Examples
Upload a site to an S3 bucket and Cloudfront:
next-s3 deploy --bucket <bucket-name> --distribution <cloudfront distribution id>
Upload a site to an S3 bucket and Cloudfront using a different profile:
next-s3 deploy --bucket <bucket-name> --distribution <cloudfront distribution id> --profile <profile>
Upload a site to an S3 bucket and Cloudfront using and host under the /production basepath:
next-s3 deploy --bucket <bucket-name> --distribution <cloudfront distribution id> --basepath "/production"
Roadmap
- Create initial version
- Add `dotenv^ support
- Add custom config options
-
Create additional commands
- Project scaffolding
- Create github action
See the open issues for a full list of proposed features (and known issues).
Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
License
Distributed under the MIT License. See LICENSE.txt for more information.
Contact
Balazs Szalay - @szalayme - [email protected]