Purple Stack

What is Purple Stack

Purple stack is a development stack designed by Purple LAB for developing full-stack serverless apps.

It's based on our 6+ years of experience with building big Serverless apps on AWS.

You can read more about how Purple Stack was born on our blog.

Tech being used

Main language: TypeScript
Deployment framework: SST.dev
Frontend: React.js & Next.js
Code bundling: ESbuild
Package manager: PNPM
Linting: ESlint & Prettier
API protocol: tRPC
Business workflows engine: AWS Step Functions
CI/CD: GitHub Actions
Static Application Security Testing (SAST) - eslint-plugin-security & @microsoft/eslint-plugin-sdl
Unit Tests - Vitest
Structured Logging: AWS Lambda Powertools Logger
Conventional Commits - Commitlint
... and more

File structure

.
├── constructs
│   └── # Here go sharable CDK constructs that
│       # you can abstract for multiple services.
│       #
│       # Only individual TS files. No packages.
├── packages
│   └── # Here goes any application code that
│       # you need to share between services.
│       #
│       # Make sure the packages are created
│       # as "npm" packages so that they have
│       # package.json and tsconfig.ts files.
├── services
│   └── # Here goes source code for indivudual
│       # aws services. Inside these folders 
│       # are Lambda handlers and other relevant
│       # source code.
│       #
│       # Make sure the services are created
│       # as "npm" packages so that they have
│       # package.json and tsconfig.ts files.
└── stacks
    └── # Here goes AWS stacks definitions.
        # One folder for each service.
        # Make sure there is always file stack.ts
        # inside each folder.
        #
        # Only individual TS files. No packages.

ENV file

Env file is quite simple in this case. Only AWS_PROFILE is necessary value.

Example

AWS_PROFILE=purple-technology

Setup

There are some settings which need to be changed in order to make this boilerplate project work.

GitHub Actions

.github/workflows/*

replace all CHANGE_ME values
role-session-name - identifier of the application
role-to-assume - usually apps are deployed to "Production" and "Staging" AWS accounts. master branch gets deployed to "Production" and the rest goes to the "Staging" AWS account. Make sure to put there correct deployment roles.
How to setup GitHub OpenID Connect on AWS

SST config

sst.config.ts

Change app name. Current value: name: 'purple-stack'
Change regions. Current value: region: stage === 'master' ? 'eu-central-1' : 'eu-central-1'
Eventually enable tracing if you need. Current value: tracing: 'disabled'

Best practices

1. Separate stateful resources to a separate stack

You can use pre-defined ResourceStack for this.

Separate your application into multiple stacks as dictated by deployment requirements

There is no hard and fast rule to how many stacks your application needs. You'll usually end up basing the decision on your deployment patterns. Keep in mind the following guidelines:

It's typically more straightforward to keep as many resources in the same stack as possible, so keep them together unless you know you want them separated.

Consider keeping stateful resources (like databases) in a separate stack from stateless resources. You can then turn on termination protection on the stateful stack. This way, you can freely destroy or create multiple copies of the stateless stack without risk of data loss.

Stateful resources are more sensitive to construct renaming—renaming leads to resource replacement. Therefore, don't nest stateful resources inside constructs that are likely to be moved around or renamed (unless the state can be rebuilt if lost, like a cache). This is another good reason to put stateful resources in their own stack.

2. Don't turn off ESlint and TSconfig rules

The rules are there for a reason. Always make sure to try all possible solutions to comply with the rules before disabling the rule.

Every time you use any in the code a bunny dies.

3. Take advantage of all the features of SST

SST has a lot of great quirks and features like use, bind etc.

Read their docs.

purple-technology / purple-stack