@fiquu/slseed-web-app

Serveless Seed Web App project with Vue, Element UI, Tailwind CSS, AWS Amplify, automated setup and deploy with AWS CloudFormation, Amazon S3, Amazon CloudFront and other goodies.

Description

This project aims to provide a template with sensible defaults and structure, using a set of technologies that ease development and improve usability with a strong focus on providing a secure and great end-user experience.

This seed or boilerplate does not tie you to any particular stack or backend, it just provides a comprehensive structure that you can use to connect to any endpoint you choose to as you can easily replace the default AWS Amplify Auth and API Client with any other module of your choosing (e.g., Axios, Vue Apollo Client). Adding or removing plugins is just as easy.

The folder structure is intended for scalability in an intuitive and predictable way, even on very large applications.

Technologies

Amazon Web Services

AWS provides great services at competitive prices, most of them have free tiers that you may never fully use. This way, you can have an account for your each stage of your project (ideally created with AWS Organziations) so you don't use the free tier of your main account (.env.production.local) while developing on local (.env.local.local), developing on the cloud (.env.development.local), testing (.env.testing.local) or validating (.env.staging.local).

Vue

Vue allows you to work the way you feel most comfortable as it's very reliable and flexible with great scaling. The community is awesome and growing every day.

Here you can learn how it compares to other frameworks: https://vuejs.org/v2/guide/comparison.html.

TypeScript

TypeScript is a JavaScript superset that allows you to reduce type errors while writing your code and can also help you provide code completion, parameter info, quick info and member lists (AKA IntelliSense) for any component, plugin or module so you may have a simplified development experience.

It's worth noting that it may get in your way sometimes but it may be that you just need to rethink you code.

Element UI

Element UI is a modern and very complete component library that eases a lot of common component implementations. It provides a very wide set of components to choose from and allows you to import just what you need.

Tailwind CSS

Tailwind CSS is a utility-first framework that eases common problems like paddings and margins on your templates with simple and short classes. It provides a lot of classes and utilities to simplify layouting and templating.

This library also helps to better support responsiveness since Element UI is not mobile-first.

Getting started

Most of these steps apply to any project, but we're assuming you'll also be using Slseed Web API for your backend.

Important: You may need to configure the Slseed Web API project first to get the AWS Cognito values. If you don't need that, then you can just add a Cognito User Pool into the app's CloudFormation stack template.

1. Configure your AWS profiles on configs/aws.js for each stage.
2. Run npm i and update as needed.
3. Set the input values to use on the CloudFormation template on configs/stack/values.js.
4. Configure your CloudFormation template on the configs/stack/template/ folder.
5. Run npm run setup and select stack (or npm run setup:stack), select stage and enter the template values.
6. Wait for it to finish (it may take a while)...
7. Configure your AWS Systems Manager parameters to .env values on configs/ssm-env.js. These are the SSM parameter names only as the prefix is taken from the .slseedrc.js file and from the package.json name and title properties by default.
8. Run npm run setup and select env (or npm run setup:env) and select stage to set your .env.{stage}.local file.
9. Run npm start.

That's it. Your App should be running wherever it says it's running.

See the "scripts" section on the package.json for more commands.

Versioning

Versioning is made following the package.json version and using it to create a folder in the S3 bucket for each version and pointing the CloudFront distribution to the last version as origin when a deploy is made.

Pruning

The deploy script can automatically or manually prune old versions by listing the version folders (prefixes) in the deploy bucket and keeping the last 3 deployed versions.

Deploying

Manual

1. Make sure you have the .env file for the stage you want to deploy by running npm run setup:env, selecting the stage and checking if the .env.{stage}.local exists.
2. Run npm version patch|minor|major accordingly to make sure you're deploying a new version.
3. Run npm run deploy, select stage and follow the prompts.

CI/CD

1. Add your AWS credentials environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION).
2. Add the env setup script: npm run setup:env -- --stage <stage> --useAwsProfiles false.
3. Run the deploy script: npm run deploy -- --useAwsProfiles false --autoDeploy true --stage <stage>.

• The stage flag must match the stage names in your project (development, staging, etc.).
• The useAwsProfiles disables the configuration of an AWS profile thus using the env vars.
• The autoDeploy flag skips all deploy prompts and doing the following by default:
  • Builds distributable files.
  • Checks for deployed version and aborting if already deployed.
  • Pruning old versions and keeping the last 3.

Using as seed

1. Create a repo.
2. Add remote as slseed:
   • git remote add slseed git@github.com:fiquu/slseed-web-app.git
3. Disable pushing (!):
   • git remote set-url --push slseed DISABLED
4. Fetch the latest changes:
   • git fetch slseed
5. Merge the master into your branch:
   • git merge slseed/master --allow-unrelated-histories

Repeat the last 2 steps to update your repo with the latest changes from this one:

git fetch slseed && git merge slseed/master --allow-unrelated-histories

And have fun resolving conflicts! :D

Recommended Tools

• Icons: https://realfavicongenerator.net/
• Image Optimization: https://squoosh.app/
• SVG Optimization: https://jakearchibald.github.io/svgomg/