szalaybalazs / next-s3

Next-S3

Deploy your static Next.js sites in one command
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Installation
3. Usage
   • Parameters
   • Examples
4. Roadmap
5. Contributing
6. License
7. Contact

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.

(back to top)

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.

(back to top)

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

(back to top)

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"

(back to top)

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).

(back to top)

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!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Balazs Szalay - @szalayme - [email protected]

(back to top)

next-s3's Issues

Add Licence file

Project looks interesting. I would add a licence file so other developers understand whether and how they can use this project.