Live Preview | Getting Started | Tests | Customize

Full-stack serverless template built on AWS. React web app, Lambda backend, Cognito authentication, frontend E2E tests (Playwright), backend API tests (Postman), and CICD on push to dev / qa / main. Clone it, configure it, push it—you have a deployed app.

Frontend — React 19, TypeScript, Vite, Tailwind, shadcn/ui, Redux Toolkit, React Query, React Router.

Backend — Node.js 22, Express, Serverless Framework, and these AWS services:

Database — Multi-provider support via swappable adapters:

• Node.js 22+
• Python 3.x (for frontend E2E tests)
• AWS account — The template uses: Lambda, API Gateway, Cognito, S3, CloudFront, Route 53, ACM, SES, IAM, CloudFormation
• Serverless Framework — access key
• Database — Database from the Supported Databases list
• Domain — Route 53 hosted zone and ACM certificate in us-east-1

git clone https://github.com/shalev396/Elytra.git
cd Elytra

Or use GitHub's "Use this template" button to create your own copy.

Before running or deploying, replace template URLs and branding with your own:

Live Preview / clone link — Update the top-line links in README.md to your own preview URL and repo.

GitHub Actions — .github/workflows/_test-qa.yml uses secrets.DOMAIN_NAME from the qa environment; no URL edits needed in workflows.

Create environment files from server/.env.example:

cp server/.env.example server/.env.dev

Copy to server/.env.qa and server/.env.prod for other stages. Fill all required values:

Note: Cognito values are created on first deploy. After deploying, copy them from AWS Console into .env.dev for local development.

S3 bucket names are derived from DOMAIN_NAME — no separate config needed.

Backend (port 3000):

cd server
npm install
npm run dev

Frontend (port 5173):

cd client
npm install
npm run dev

CICD deploys automatically on push. To deploy manually:

cd server
npm run deploy:dev   # or deploy:qa, deploy:prod

This deploys backend (Lambda, API Gateway, Cognito, S3, CloudFront, Route 53), then frontend is uploaded to S3 and CloudFront invalidated. CICD performs both steps on push—no manual deploy needed once configured.

Push to dev / qa / main triggers full deploy. Set up once (see CICD Setup) and you're done.

The template uses a single source of truth for branding. Change these files and names propagate everywhere.

client/src/data/app.ts — App identity:

• name, repoUrl, baseUrl, contactEmail, supportEmail, privacyEmail, socialLinks

Favicon — Replace client/public/favicon-light.svg and favicon-dark.svg (paths in client/src/data/favicon.ts).

Logo / assets — client/src/data/assets.ts.

Metadata (title, description) — client/src/data/defaultMetadata.ts.

server/serverless.yml:

• org (line ~35) — Serverless Framework org
• custom.appName (line ~140) — Service name, stack name, Cognito pool name
• custom.appDisplayName (line ~141) — Human-readable name in emails and descriptions

When changing appName in serverless.yml, also set GitHub variable APP_NAME to the same value (CICD uses it for CloudFormation stack lookup). Keep app.name in app.ts aligned for consistent branding and translations.

Out of the box:

• Frontend E2E — Playwright + Python (smoke, accessibility, visual, responsive, security, flows)
• Backend API — Postman (auth, user, dashboard, flows)

PRs to qa run local tests (serverless offline + Vite). PRs to main run tests against live QA.

Full API spec: server/openapi.yaml (OpenAPI 3.0). Use it with Swagger Editor, Postman, or OpenAPI Generator.

Configure OpenID Connect in AWS. Create an IAM role and attach one of:

• AdministratorAccess — Easiest; works for all services below.
• Least-privilege policy — Create a custom policy with permissions for these services used by the template:
  • CloudFormation (create/update/describe stacks)
  • Lambda (create, update, invoke)
  • API Gateway (HTTP APIs)
  • S3 (buckets, objects — deploy and runtime)
  • CloudFront (distributions, invalidations)
  • Cognito (User Pools, App Clients)
  • Route 53 (hosted zones, record sets)
  • ACM (certificates)
  • SES (send email for Cognito verification)
  • IAM (roles, policies for Lambda execution)

Update role-to-assume in .github/workflows/_deploy.yml to match your role name.

Settings > Secrets and variables > Actions.

Repository secrets:

Repository variables:

Per-environment secrets (set under each GitHub environment: dev, qa, prod):