diff --git a/.serverless-full-stack-webapp-starter-kit/design/DESIGN_PRINCIPLES.md b/.serverless-full-stack-webapp-starter-kit/design/DESIGN_PRINCIPLES.md new file mode 100644 index 0000000..17d5595 --- /dev/null +++ b/.serverless-full-stack-webapp-starter-kit/design/DESIGN_PRINCIPLES.md @@ -0,0 +1,53 @@ +# Design Principles + +This document is for kit maintainers. If you copied this kit to build your own app, you can safely delete the `.serverless-full-stack-webapp-starter-kit/` directory. + +## What this kit is + +A template you **copy** (not fork) and grow into your own app. It is not a framework — users are expected to read, understand, and modify every file. + +## Quality standards + +As an aws-samples project: + +- Correctness is the top priority — users learn patterns from this code. +- Reproducibility — following the README must produce a working deployment. +- Readability — code should be understandable by developers new to serverless. +- One-command deploy — `npx cdk deploy --all` must be the only deployment step. + +The litmus test for any PR: "After this merges, will a developer who copies the kit build their app on a correct understanding?" + +## Design decisions + +### Template, not framework + +- Breaking changes have low impact — users copy and diverge. Major versions can be bumped without a lengthy deprecation cycle. +- The sample app exists solely to prove all kit components work together. Users will delete it. Do not expand sample app features beyond what is needed for this proof. +- Avoid over-abstraction. Readability and modifiability matter more than DRY. + +### What to include + +- Patterns that every serverless full-stack webapp needs (auth, DB, async jobs, real-time). +- Operational essentials (migration, logging, cost-optimized defaults). +- Only what cannot be trivially added later. + +### What to exclude + +- App-specific business logic. +- Dependencies on specific AI models or services. +- Patterns needed by fewer than half of expected users. + +### Technology choices + +| Choice | Rationale | +|--------|-----------| +| `prisma db push` over `prisma migrate` | Simpler default for starter-kit scope. Users can switch to `prisma migrate` when they need migration history. | +| NAT Instance over NAT Gateway | ~$30/month savings. Acceptable trade-off for a starter kit. | +| Single Lambda for all async jobs | Reduces cold starts and simplifies deployment. `cmd` parameter selects the entry point. | +| `proxy.ts` over Next.js middleware | Runs inside Lambda handler, avoiding cold-start CPU starvation from JWKS fetch in middleware. | +| `output: 'standalone'` | Required for Lambda deployment via Docker image. | +| Lambda Web Adapter | Enables response streaming with CloudFront + Lambda Function URL. | + +### Architecture Decision Records (ADR) + +ADRs are not used yet. Introduce `design/adr/` when a major technology decision is made (e.g., ORM migration, database engine change) that requires recording the context, alternatives considered, and rationale. diff --git a/imgs/architecture.png b/.serverless-full-stack-webapp-starter-kit/docs/imgs/architecture.png similarity index 100% rename from imgs/architecture.png rename to .serverless-full-stack-webapp-starter-kit/docs/imgs/architecture.png diff --git a/imgs/signin.png b/.serverless-full-stack-webapp-starter-kit/docs/imgs/signin.png similarity index 100% rename from imgs/signin.png rename to .serverless-full-stack-webapp-starter-kit/docs/imgs/signin.png diff --git a/imgs/top.png b/.serverless-full-stack-webapp-starter-kit/docs/imgs/top.png similarity index 100% rename from imgs/top.png rename to .serverless-full-stack-webapp-starter-kit/docs/imgs/top.png diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2bd2500 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,82 @@ +# AGENTS.md + +## Commands + +```bash +# webapp +cd webapp && npm ci +cd webapp && npm run dev # starts on port 3010 +cd webapp && npm run build +cd webapp && npm run lint +cd webapp && npm run format + +# cdk +cd cdk && npm ci +cd cdk && npm run build +cd cdk && npm test +cd cdk && npm run format +cd cdk && npx cdk deploy --all +cd cdk && npx cdk diff + +# local development (requires Docker) +docker compose up -d # PostgreSQL on port 5432 +cd webapp && npx prisma db push # sync schema to local DB +cd webapp && npm run dev +``` + +## Development guide + +### Authentication + +All server-side mutations must go through `authActionClient` (defined in `lib/safe-action.ts`). It validates the Cognito session via Amplify server-side auth and injects `ctx.userId`. Never call Prisma directly from a Server Action without this middleware. + +`proxy.ts` handles route protection (redirect to `/sign-in` for unauthenticated users). It is NOT a Next.js middleware file — it runs inside the Lambda handler. There is no `middleware.ts` in this project. + +### Async jobs + +The dispatch flow is: Server Action → `runJob()` (Lambda async invoke) → `async-job-runner.ts` (discriminated union dispatch) → job handler → `sendEvent()` (AppSync Events) → client `useEventBus` hook. + +To add a new job: +1. Add a Zod schema with a `type` literal to the discriminated union in `async-job-runner.ts` +2. Implement the handler in `src/jobs/async-job/` +3. Add the case to the switch statement + +All job types share a single Lambda function via `job.Dockerfile`. The CDK `cmd` parameter selects the entry point. + +### Database migration + +`prisma db push` is used for schema sync by default. The migration runner Lambda is invoked automatically during `cdk deploy` via CDK Trigger. For manual invocation, use the `MigrationCommand` from CDK outputs. + +Schema changes: edit `prisma/schema.prisma` → run `npx prisma db push` locally → commit. The `zod-prisma-types` generator auto-generates Zod schemas from the Prisma schema. If you switch to `prisma migrate`, update the migration runner accordingly. + +### Lambda environment + +The webapp runs on Lambda behind CloudFront via Lambda Web Adapter (response streaming). `next.config.ts` uses `output: 'standalone'`. Build-time env vars (prefixed `NEXT_PUBLIC_`) are injected via CDK `ContainerImageBuild` build args — they cannot be changed at runtime. + +### Real-time notifications + +Server → client push uses AppSync Events. Server-side: `sendEvent(channelName, payload)` with IAM SigV4 signing. Client-side: `useEventBus` hook with Cognito user pool auth. The channel namespace is `event-bus/`. + +## Documentation policy + +- Do not document what can be derived from code. An agent can read the codebase. +- Enforce verifiable constraints with tests and linters, not prose. +- Code comments explain "why not" only — the non-obvious reason something was done a certain way. +- Before adding a line to this file, ask: "If I remove this line, will an agent make a mistake?" If no, don't add it. If a root cause is fixed, remove the corresponding line. + +## Conventions + +- PR titles and code comments in English. +- Issues and discussions in English or Japanese. +- PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`, etc.). +- UI components: use [shadcn/ui](https://ui.shadcn.com/). Do not introduce alternative component libraries. +- Logs: use JSON structured output. +- Dependencies: esbuild and Next.js bundle everything, so only packages with native binaries needed at Lambda runtime belong in `dependencies`. Everything else goes in `devDependencies`. + +## Do not + +- Do not bypass `authActionClient` for any mutation. No raw Prisma calls from Server Actions. +- Do not add `middleware.ts`. Route protection is handled by `proxy.ts` inside the Lambda runtime. +- Do not use `prisma migrate` commands unless you have explicitly switched from `prisma db push`. The default setup uses `prisma db push`. +- Do not hardcode AWS region or account IDs. Use CDK context or environment variables. +- Do not add `NEXT_PUBLIC_` env vars to `.env.local` for deployed builds — they must be set as CDK build args in `webapp.ts`. diff --git a/AmazonQ.md b/AmazonQ.md deleted file mode 100644 index af5231f..0000000 --- a/AmazonQ.md +++ /dev/null @@ -1,137 +0,0 @@ -# Serverless Full Stack WebApp Starter Kit Knowledge Base - -This file provides important information about the Serverless Full Stack WebApp Starter Kit repository. AI agent references this to support its work on this project. - -## Project Overview - -This project is a full stack webapp starter kit leveraging AWS serverless services, featuring: - -- Next.js App Router on AWS Lambda -- CloudFront + Lambda function URL with response stream support -- End-to-end type safety (client to server) -- Cognito authentication -- Real-time notifications -- Asynchronous job queue -- Instant deployment via AWS CDK - -## Project Structure - -The project consists of two main components: - -1. **WebApp** - `/webapp` directory - - Next.js application with App Router - - Frontend UI and server components - - Server actions - - TypeScript + React - - Tailwind CSS for styling - -2. **CDK (AWS Cloud Development Kit)** - `/cdk` directory - - Infrastructure as Code definitions - - AWS resource provisioning - - Deployment configurations - -### WebApp Structure - -``` -/webapp/src/ -├── app/ -│ ├── (root)/ -│ │ ├── components/ (feature-specific components) -│ │ ├── actions.ts (server actions) -│ │ ├── schemas.ts (validation schemas) -│ │ └── page.tsx (main page) -│ ├── api/ -│ ├── auth-callback/ -│ └── sign-in/ -├── components/ (shared components) -├── hooks/ -├── jobs/ -├── lib/ -└── middleware.ts -``` - -## Technology Stack - -- **Frontend**: React, Next.js, Tailwind CSS -- **Backend**: Next.js App Router, Server Actions, AWS Lambda -- **Database**: Amazon Aurora PostgreSQL Serverless v2 with Prisma ORM -- **Authentication**: Amazon Cognito -- **Real-time**: AWS AppSync Events -- **Infrastructure**: AWS CDK, CloudFront, Lambda, EventBridge - -## Coding Conventions - -- Use TypeScript for type safety -- Feature-based directory structure -- Function components with hooks for React -- Server actions for backend logic -- Zod for data validation -- Prisma for database interactions - -## Commonly Used Commands - -### WebApp - -```bash -# Development server (with Turbopack) -cd webapp && npm run dev - -# Build the web application -cd webapp && npm run build - -# Formatting -cd webapp && npm run format - -# Check formatting -cd webapp && npm run format:check - -# Linting -cd webapp && npm run lint -``` - -### CDK - -```bash -# Build the CDK project -cd cdk && npm run build - -# Deploy the application to AWS -cd cdk && npm run cdk deploy - -# Check for changes in the infrastructure -cd cdk && npm run cdk diff -``` - -## Development Flow - -1. Create a branch for a new feature or bug fix -2. Implement changes and test locally -3. Run format and lint checks -4. Create a PR with title and description in English and ensure CI passes -5. Request review when the PR is ready - -## Best Practices - -1. **Directory Organization**: - - Group feature-specific components, actions, and schemas in the same directory - - Keep shared components in the top-level components directory - -2. **Code Quality**: - - Use TypeScript for type safety - - Validate inputs with Zod schemas - - Follow Next.js server/client component patterns - -3. **Authentication**: - - Use the built-in auth mechanisms for protected routes - - Follow Cognito authentication patterns - -4. **Database Access**: - - Use Prisma for database operations - - Keep database logic in server actions - -## Troubleshooting - -- **Next.js Errors**: Ensure proper separation of client/server components -- **CDK Deployment Issues**: Check AWS credentials and permissions -- **Authentication Problems**: Verify Cognito user pool configuration -- **Database Connection Errors**: Check Prisma schema and connection string \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4b6a1c..ccaaa83 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,14 @@ documentation, we greatly value feedback and contributions from our community. Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution. +## Language policy + +- PR titles and code comments: English +- Issues and discussions: English or Japanese + +## Commit and PR conventions + +PR titles follow [Conventional Commits](https://www.conventionalcommits.org/) (Angular style). Enforced by CI. Releases are automated via [Release Please](https://github.com/googleapis/release-please). ## Reporting Bugs/Feature Requests @@ -19,7 +27,6 @@ reported the issue. Please try to include as much information as you can. Detail * Any modifications you've made relevant to the bug * Anything unusual about your environment or deployment - ## Contributing via Pull Requests Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: diff --git a/README.md b/README.md index 9e2af82..a262934 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,78 @@ # Serverless Full Stack WebApp Starter Kit [![Build](https://github.com/aws-samples/serverless-full-stack-webapp-starter-kit/actions/workflows/build.yml/badge.svg)](https://github.com/aws-samples/serverless-full-stack-webapp-starter-kit/actions/workflows/build.yml) +[![Release](https://img.shields.io/github/v/release/aws-samples/serverless-full-stack-webapp-starter-kit)](https://github.com/aws-samples/serverless-full-stack-webapp-starter-kit/releases) -This is a full stack webapp kit for starters who want to leverage the power of AWS serverless services! +A serverless full-stack web app template you **copy and grow into your own app**. Not a framework — you own every file. -Features include: +Copy, deploy with a single command, then replace the sample todo app with your own features. -* Next.js App Router on AWS Lambda -* CloudFront + Lambda function URL with response stream support -* End to end type safety from client to server -* Cognito authentication -* Real-time notification from server to client -* Asynchronous job queue -* Instant deployment of the entire app with a single command +## What you get -You can refer to [the blog article](https://tmokmss.github.io/blog/posts/serverless-fullstack-webapp-architecture-2025/) for more details (Also [Japanese version](https://tmokmss.hatenablog.com/entry/serverless-fullstack-webapp-architecture-2025).) +1. **Working sample app** — A todo app with authentication, DB CRUD, async jobs, and real-time notifications wired end-to-end. Designed as a readable reference for AI coding agents and humans alike. +2. **End-to-end type safety** — Types flow from Prisma ORM through Zod schemas and Server Actions to React components in a single chain. +3. **Serverless from day one** — Fully serverless architecture starting under $10/month that scales without operational overhead. +4. **Integrated DB migration** — Schema migration is integrated into the CDK deploy process via CDK Trigger, providing a development-to-production path out of the box. -## Overview -Here is the architecture of this kit. We use: +You can refer to [the blog article](https://tmokmss.github.io/blog/posts/serverless-fullstack-webapp-architecture-2025/) for more details (also [Japanese version](https://tmokmss.hatenablog.com/entry/serverless-fullstack-webapp-architecture-2025)). -* [Amazon Aurora PostgreSQL Serverless v2](https://aws.amazon.com/rds/aurora/serverless/), a serverless relational database with Prisma ORM -* [Next.js App Router](https://nextjs.org/docs/app) on [AWS Lambda](https://aws.amazon.com/lambda/) for a unified frontend and backend solution -* [Amazon CloudFront](https://aws.amazon.com/cloudfront/) + Lambda Function URL with response streaming support for efficient content delivery -* [Amazon Cognito](https://aws.amazon.com/cognito/) for authentication. By default, you can sign in/up by email, but you can federate with other OIDC providers such as Google, Facebook, and more with a little modification. -* [AWS AppSync Events](https://docs.aws.amazon.com/appsync/latest/eventapi/event-api-welcome.html) + AWS Lambda for asynchronous job and real-time notification. -* [Amazon EventBridge](https://aws.amazon.com/eventbridge/) to run scheduled jobs. -* [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/) + S3 for access logging. -* [AWS CDK](https://aws.amazon.com/cdk/) for Infrastructure as Code. It enables you to deploy the entire application with the simplest commands. +## Sample app -![architecture](imgs/architecture.png) +The kit includes a simple todo app to demonstrate how all components work together. -Since it fully leverages AWS serverless services, you can use it with high cost efficiency, scalability, and almost no heavy lifting of managing servers! In terms of cost, we further discuss how much it costs in the below [#Cost](#cost) section. + +Sign in/up page redirects to Cognito Managed Login. +
+ +  -### About the sample app -To show how this kit works, we include a sample web app to manage your todo list. -With this sample, you can easily understand how each component works with other ones, and what the overall experience will be like. + +After login, you can add, delete, and manage your todo items. The translate button triggers an async job and pushes a real-time notification to refresh the page. +
- -Here is a sign in/up page. This will redirect you to Cognito Managed login page. -
+## Architecture - -After a successful login, you can now freely add, delete, and view your todo items. -To demonstrate an asynchronous job feature, we also placed a button to run a asynchronous translation job. After the invocation, the task sends an event to the event bus and your frontend automatically refreshes to fetch the translated items. +![architecture](./.serverless-full-stack-webapp-starter-kit/docs/imgs/architecture.png) -
+| Service | Role | +|---------|------| +| [Aurora PostgreSQL Serverless v2](https://aws.amazon.com/rds/aurora/serverless/) | Relational database with Prisma ORM | +| [Next.js App Router](https://nextjs.org/docs/app) on [Lambda](https://aws.amazon.com/lambda/) | Unified frontend and backend | +| [CloudFront](https://aws.amazon.com/cloudfront/) + Lambda Function URL | Content delivery with response streaming | +| [Cognito](https://aws.amazon.com/cognito/) | Authentication (email by default, OIDC federation supported) | +| [AppSync Events](https://docs.aws.amazon.com/appsync/latest/eventapi/event-api-welcome.html) + Lambda | Async jobs and real-time notifications | +| [EventBridge](https://aws.amazon.com/eventbridge/) | Scheduled jobs | +| [CloudWatch](https://aws.amazon.com/cloudwatch/) + S3 | Access logging | +| [CDK](https://aws.amazon.com/cdk/) | Infrastructure as Code | -You can further improve this sample or remove all the specific code and write your own app. But first let's deploy this sample as-is! +Fully serverless — high cost efficiency, scalability, and minimal operational overhead. -## Deploy -You need the following tools to deploy this sample: +## Getting started -* [Node.js](https://nodejs.org/en/download/) (>= v20) +Prerequisites: +* [Node.js](https://nodejs.org/) (>= v20) * [Docker](https://docs.docker.com/get-docker/) -* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and a configured IAM profile +* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) with a configured IAM profile -Before deployment, you can update the configuration variables in [`bin/cdk.ts`](cdk/bin/cdk.ts). Please read the comments in the code. +### 1. Copy the kit -Then run the following commands: +Use the GitHub template ("Use this template" button) or clone and copy: + +```sh +git clone https://github.com/aws-samples/serverless-full-stack-webapp-starter-kit.git my-app +cd my-app +rm -rf .git && git init +# Record the kit version in your initial commit for future reference +git add -A && git commit -m "Initial commit from serverless-full-stack-webapp-starter-kit vX.Y.Z" +``` + +### 2. Customize (optional) + +- Update the application name (stack name, tags) in [`cdk/bin/cdk.ts`](cdk/bin/cdk.ts) +- Set a custom domain in `cdk/bin/cdk.ts` +- Remove `cdk.context.json` from `cdk/.gitignore` and commit it (recommended for your own project) +- Switch from `prisma db push` to `prisma migrate` if you need migration history + +### 3. Deploy ```sh cd cdk @@ -65,88 +81,50 @@ npx cdk bootstrap npx cdk deploy --all ``` -Initial deployment usually takes about 20 minutes. You can also use `npx cdk deploy` command to deploy when you modified your CDK templates in the future. - -After a successful deployment, you will get a CLI output like the below: +Initial deployment takes about 20 minutes. After success, you'll see: ``` ✅ ServerlessWebappStarterKitStack -✨ Deployment time: 407.12s - Outputs: -ServerlessWebappStarterKitStack.AuthUserPoolClientId8216BF9A = xxxxxxxxxxxxxxxxxx -ServerlessWebappStarterKitStack.AuthUserPoolIdC0605E59 = us-west-2_xxxxxx -ServerlessWebappStarterKitStack.DatabaseDatabaseSecretsCommandF4A622EB = aws secretsmanager get-secret-value --secret-id DatabaseClusterSecretD1FB63-xxxxxxx --region us-west-2 -ServerlessWebappStarterKitStack.DatabasePortForwardCommandC3718B89 = aws ssm start-session --region us-west-2 --target i-xxxxxxxxxx --document-name AWS-StartPortForwardingSessionToRemoteHost --parameters '{"portNumber":["5432"], "localPortNumber":["5432"], "host": ["foo.cluster-bar.us-west-2.rds.amazonaws.com"]}' -ServerlessWebappStarterKitStack.FrontendDomainName = https://web.exmaple.com +ServerlessWebappStarterKitStack.FrontendDomainName = https://web.example.com +ServerlessWebappStarterKitStack.DatabaseSecretsCommand = aws secretsmanager get-secret-value ... +ServerlessWebappStarterKitStack.DatabasePortForwardCommand = aws ssm start-session ... ``` -Opening the URL in `FrontendDomainName` output, you can now try the sample app on your browser. +Open the `FrontendDomainName` URL to try the sample app. -> **Note:** The deployment also outputs operational commands for database management. `DatabasePortForwardCommand` establishes a local connection to your RDS database on port 5433, and `DatabaseSecretsCommand` retrieves database credentials from AWS Secrets Manager. +> **Note:** `DatabasePortForwardCommand` establishes a local connection to your RDS database, and `DatabaseSecretsCommand` retrieves database credentials from Secrets Manager. -### WebApp Deployment +### 4. Add your own features -The Next.js webapp is built and deployed during the CDK deployment process using [deploy-time-build](https://github.com/tmokmss/deploy-time-build). This approach ensures your application is containerized and deployed to AWS Lambda as part of the infrastructure deployment. See the [implementation](./cdk/lib/constructs/webapp.ts) for details. +See [`AGENTS.md`](./AGENTS.md) for development guide — local development setup, authentication patterns, async job setup, DB migration, and coding conventions. -### Database Migration +To add social sign-in (Google, Facebook, etc.), see [Add social sign-in to a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-federation-with-social-idp.html). -Database migrations are automatically executed during CDK deployment using a [CDK Trigger](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.triggers-readme.html). The migration runs with the default `deploy` command. See the [implementation](./cdk/lib/constructs/webapp.ts) and [migration runner](./webapp/src/jobs/migration-runner.ts) for details. +## Maintenance policy -To manually run migrations with different commands: - -```sh -aws lambda invoke \ - --function-name \ - --payload '{"command":"deploy"}' \ - --cli-binary-format raw-in-base64-out \ - /dev/stdout -``` - -Available commands: `deploy` (default), `force` (with --accept-data-loss). - -## Add your own features -To implement your own features, you may want to add frontend pages, API routes, or async jobs. The project uses Next.js App Router, which provides a unified approach for both frontend and backend development. You can follow the conventional Next.js patterns to add pages and API routes. For more details, please refer to the [`webapp/README.md`](./webapp/README.md) guide. - -If you want to add another authentication method such as Google or Facebook federation, you can follow this document: [Add social sign-in to a user pool](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-configuring-federation-with-social-idp.html). - -## Local development -To develop the webapp locally, please refer to the [`webapp/README.md`](./webapp/README.md). - -Before running webapp locally, you have to populate .env.local by the following steps: - -```sh -cp .env.local.example .env.local -# edit .env.local using the stack outputs shown after cdk deploy -``` +This kit follows [Semantic Versioning](https://semver.org/). Since users copy (not fork) this kit, breaking changes are introduced as new major versions without a lengthy deprecation cycle. ## Cost -The following table provides a sample cost breakdown for deploying this system in the us-east-1 (N. Virginia) region for one month (when deployed using less expensive configuration). +Sample cost breakdown for us-east-1, one month, with cost-optimized configuration: | Service | Usage Details | Monthly Cost [USD] | |---------|--------------|-------------------| | Aurora Serverless v2 | 0.5 ACU × 2 hour/day, 1GB storage | 3.6 | -| Cognito | 100 MAU (Monthly Active Users) | 1.5 | +| Cognito | 100 MAU | 1.5 | | AppSync Events | 100 events/month, 10 hours connection/user/month | 0.02 | -| Lambda | 1024MB×200ms/request | 0.15 | -| Lambda@Edge | 128MB×50ms/request | 0.09 | -| VPC | NAT Instance (t4g.nano) x1 | 3.02 | +| Lambda | 1024MB × 200ms/request | 0.15 | +| Lambda@Edge | 128MB × 50ms/request | 0.09 | +| VPC | NAT Instance (t4g.nano) × 1 | 3.02 | | EventBridge | Scheduler 100 jobs/month | 0.0001 | | CloudFront | Data transfer 1kB/request | 0.01 | -| Total | | 8.49 | - -Notes: -- Assumes 100 users per month and 1000 requests per user -- Actual costs may vary depending on usage patterns +| **Total** | | **8.49** | -Costs could be further reduced by leveraging Free Tier benefits where applicable. Lambda, SQS, CloudWatch, CloudFront, EC2, and Cognito offer free tier plans, which allows you to use those services almost freely for small businesses. See [this page for more details](https://aws.amazon.com/free/). +Assumes 100 users/month, 1000 requests/user. Costs could be further reduced with [Free Tier](https://aws.amazon.com/free/). ## Clean up -To avoid incurring future charges, clean up the resources you created. - -You can remove all the AWS resources deployed by this sample running the following command: ```sh cd cdk @@ -154,7 +132,17 @@ npx cdk destroy --force ``` ## Maintainers -* [Kenji Kono (konoken)](https://github.com/konokenj) +* [Kenji Kono (konokenj)](https://github.com/konokenj) + +### Core contributors +* [Masashi Tomooka (tmokmss)](https://github.com/tmokmss) — original author +* [Kazuho Cryer-Shinozuka (badmintoncryer)](https://github.com/badmintoncryer) + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. + +Contributors (human and AI) **must** read [`.serverless-full-stack-webapp-starter-kit/design/DESIGN_PRINCIPLES.md`](./.serverless-full-stack-webapp-starter-kit/design/DESIGN_PRINCIPLES.md) before making changes. It defines the design decisions and constraints that govern this kit. ## Security See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. diff --git a/webapp/AmazonQ.md b/webapp/AmazonQ.md deleted file mode 100644 index c7215d5..0000000 --- a/webapp/AmazonQ.md +++ /dev/null @@ -1,6 +0,0 @@ -## How to add Server Action -* webapp/src/actions/schemas に入力のZodスキーマを定義する - * これはクライアント側とサーバー側双方で共有される -* webapp/src/actionsに Server Actionを定義する - * `import { authActionClient } from '@/lib/safe-action';` を使うことで、必ず認証をかけること - * diff --git a/webapp/README.md b/webapp/README.md index 07c9c4f..9c560ba 100644 --- a/webapp/README.md +++ b/webapp/README.md @@ -1,218 +1,27 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). - ## Run locally -First, run the development server: - ```bash # Run this command in the repository root docker compose up -d -cd webapp -# Run this command in the webapp directory +# Run these commands in the webapp directory +cd webapp +npm ci npx prisma db push cp .env.local.example .env.local -code .env.local -# Then populate values in .env.local - -# run the next.js server +# Edit .env.local with values from CDK deploy outputs npm run dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -## Project Structure - -``` -webapp/ -├── src/ -│ ├── actions/ # Server actions -│ │ └── schemas/ # Zod validation schemas -│ ├── app/ # App router pages -│ ├── components/ # React components -│ ├── hooks/ # Custom React hooks -│ └── lib/ # Utility functions and configurations -├── prisma/ # Prisma schema and migrations -└── public/ # Static assets -``` - - -## How to expand the project - -### Pages - -To add new pages to the application: - -1. Create a new directory under `src/app` with the desired route name -2. Add a `page.tsx` file inside this directory -3. For protected pages, use the authentication session: - -```tsx -import { getSession } from '@/lib/auth'; -import { redirect } from 'next/navigation'; - -export default async function NewPage() { - const session = await getSession(); - - if (!session?.user) { - redirect('/api/auth/signin'); - } - - // Your page content here -} -``` - -### Server Actions - -This project uses type-safe server actions with authentication: - -1. Define input schemas in `src/actions/schemas`: - ```typescript - // src/actions/schemas/example.ts - import { z } from 'zod'; - - export const exampleActionSchema = z.object({ - field1: z.string().min(1, "Field is required"), - field2: z.number().optional(), - }); - ``` - -2. Create server actions in `src/actions`: - ```typescript - // src/actions/example.ts - 'use server'; - - import { authActionClient } from '@/lib/safe-action'; - import { exampleActionSchema } from './schemas/example'; - import { prisma } from '@/lib/prisma'; - import { revalidatePath } from 'next/cache'; - - export const exampleAction = authActionClient.schema(exampleActionSchema).action( - async ({ parsedInput, ctx }) => { - const { field1, field2 } = parsedInput; - const { userId } = ctx; - - // Perform database operations or other logic - const result = await prisma.example.create({ - data: { - field1, - field2, - userId, - }, - }); - - // Revalidate the page to refresh data - revalidatePath('/'); - return { result }; - } - ); - ``` - -3. Use server actions in client components: - - a. With React Hook Form: - ```tsx - 'use client'; - - import { useHookFormAction } from '@next-safe-action/adapter-react-hook-form/hooks'; - import { zodResolver } from '@hookform/resolvers/zod'; - import { exampleAction } from '@/actions/example'; - import { exampleActionSchema } from '@/actions/schemas/example'; - import { toast } from 'sonner'; - - export default function ExampleForm() { - const { - form: { register, formState }, - action, - handleSubmitWithAction, - } = useHookFormAction(exampleAction, zodResolver(exampleActionSchema), { - actionProps: { - onSuccess: () => { - toast.success("Action completed successfully"); - }, - onError: ({ error }) => { - toast.error(typeof error === 'string' ? error : "An error occurred"); - }, - }, - formProps: { - defaultValues: { - field1: '', - field2: 0, - }, - }, - }); - - return ( -
- {/* Form fields */} - - {formState.errors.field1 && ( -

{formState.errors.field1.message}

- )} - -
- ); - } - ``` - - b. For simple actions without forms: - ```tsx - 'use client'; - - import { useAction } from 'next-safe-action/hooks'; - import { simpleAction } from '@/actions/example'; - import { toast } from 'sonner'; - - export default function ExampleButton() { - const { execute, status } = useAction(simpleAction, { - onSuccess: () => { - toast.success("Action completed successfully"); - }, - onError: (error) => { - toast.error(typeof error === 'string' ? error : "An error occurred"); - }, - }); - - return ( - - ); - } - ``` +Open [http://localhost:3010](http://localhost:3010) with your browser to see the result. -### Asynchronous Jobs +## Environment variables -Asynchronous jobs are Lambda functions that handle long-running or background tasks. All async jobs are invoked through a single Lambda function (`async-job-runner.ts`) and can be triggered manually or as scheduled jobs. +- Runtime env vars (e.g. `USER_POOL_ID`, `COGNITO_DOMAIN`) are set in `.env.local` for local development and injected via CDK `environment` for deployed builds. +- Build-time env vars prefixed with `NEXT_PUBLIC_` must be set as CDK build args in `webapp.ts` — they are baked into the Docker image at build time and cannot be changed at runtime. -**File structure:** +See `.env.local.example` for the full list. -Place each job's implementation in a subdirectory under `src/jobs/`: - -``` -webapp/src/jobs/ -├── async-job-runner.ts # Lambda handler entry point (dispatches to jobs) -└── async-job/ # Job implementations directory - └── translate.ts # Job implementation -``` - -The `async-job-runner.ts` handler dispatches to the appropriate job based on the event payload type. - -**Deployment:** - -The `job.Dockerfile` builds all TypeScript files in `src/jobs/` using `esbuild src/jobs/*.ts --bundle`. The CDK stack overrides the entry point using the `cmd` parameter: - -```typescript -// Example from cdk/lib/constructs/async-job.ts -code: DockerImageCode.fromImageAsset(join('..', 'webapp'), { - cmd: ['async-job-runner.handler'], // Override the default CMD - file: 'job.Dockerfile', -}) -``` +## Development guide -This allows multiple Lambda functions to use the same Docker image with different handlers. +See [`AGENTS.md`](../AGENTS.md) in the repository root for authentication patterns, async job setup, DB migration, coding conventions, and constraints.