diff --git a/aws-amplify/POWER.md b/aws-amplify/POWER.md new file mode 100644 index 0000000..2a5f6f6 --- /dev/null +++ b/aws-amplify/POWER.md @@ -0,0 +1,168 @@ +--- +name: "aws-amplify" +displayName: "AWS Amplify" +description: "Build full-stack applications with AWS Amplify Gen 2 using guided workflows for backend, frontend, and deployment" +keywords: ["amplify", "aws", "fullstack", "backend", "frontend", "auth", "graphql", "serverless", "gen2", "typescript", "react", "nextjs"] +author: "AWS" +--- + +# AWS Amplify + +Build production-ready full-stack applications with AWS Amplify Gen 2. This power leverages AWS MCP Agent SOPs for backend implementation, frontend integration, and deployment workflows. + +## Overview + +AWS Amplify Gen 2 is a code-first, TypeScript-native framework for building full-stack applications on AWS. This power provides guided access to three specialized Agent SOPs: + +| Workflow | SOP Name | Use When | +|----------|----------|----------| +| Backend Implementation | `amplify-backend-implementation` | Setting up Auth, Data, Storage, Functions, AI | +| Frontend Integration | `amplify-frontend-integration` | Connecting frontend framework to backend | +| Deployment Guide | `amplify-deployment-guide` | Sandbox, production, CI/CD setup | + +## When to Load Steering Files + +- Building backend services (Auth, Data, Storage, Functions) → `backend-implementation.md` +- Integrating frontend framework with Amplify → `frontend-integration.md` +- Deploying to sandbox or production → `deployment-guide.md` + +## Amplify Gen 2 vs Gen 1 + +**This power is exclusively for Amplify Gen 2.** Gen 1 is deprecated. + +| Approach | Gen 1 (Deprecated) | Gen 2 (Use This) | +|----------|-------------------|------------------| +| Configuration | CLI commands | Code-first TypeScript | +| Resource creation | `amplify add auth` | Define in `amplify/auth/resource.ts` | +| Deployment | `amplify push` | `npx ampx sandbox` or Git-based | +| Type safety | Manual | Auto-generated types | + +**Never use:** `amplify init`, `amplify add`, `amplify push`, `amplify pull` + +## Available MCP Server + +**Server:** `aws-mcp` + +### Tools + +| Tool | Purpose | +|------|---------| +| `retrieve_agent_sop` | Get step-by-step Amplify workflows | +| `search_documentation` | Search Amplify Gen 2 documentation | +| `read_documentation` | Read specific documentation pages | +| `call_aws` | Execute AWS CLI commands | + +### Agent SOPs + +Retrieve workflows using `retrieve_agent_sop` with these SOP names: + +- `amplify-backend-implementation` - Auth, Data, Storage, Functions setup +- `amplify-frontend-integration` - Framework integration patterns +- `amplify-deployment-guide` - Deployment and CI/CD workflows + +## Onboarding + +### Prerequisites + +1. **Node.js 18+** - Required for Amplify Gen 2 +2. **Python 3.10+** - Required for uv package manager +3. **uv package manager** - [Install uv](https://docs.astral.sh/uv/getting-started/installation/) +4. **AWS credentials** - Via `aws configure`, SSO, or environment variables + +### Verify Setup + +```bash +node --version # Should be 18+ +uv --version # Should be installed +aws sts get-caller-identity # Should show your identity +``` + +### Required AWS Permissions + +For AWS MCP Server access: +```json +{ + "Version": "2012-10-17", + "Statement": [{ + "Effect": "Allow", + "Action": [ + "aws-mcp:InvokeMcp", + "aws-mcp:CallReadOnlyTool", + "aws-mcp:CallReadWriteTool" + ], + "Resource": "*" + }] +} +``` + +For Amplify development, attach `AdministratorAccess-Amplify` AWS-managed policy. + +## Quick Start + +Ask your AI assistant: +- "Help me set up authentication for my app" +- "Create a data model for a todo application" +- "Connect my React app to Amplify" +- "Deploy my app to a sandbox environment" + +## Project Structure + +Amplify Gen 2 projects follow this structure: + +``` +my-app/ +├── amplify/ +│ ├── auth/ +│ │ └── resource.ts # Authentication config +│ ├── data/ +│ │ └── resource.ts # Data model schema +│ ├── storage/ +│ │ └── resource.ts # File storage config +│ ├── functions/ +│ │ └── my-function/ # Lambda functions +│ └── backend.ts # Backend entry point +├── src/ # Frontend code +├── amplify_outputs.json # Generated config +└── package.json +``` + +## Supported Frameworks + +Amplify Gen 2 supports these frontend frameworks: + +| Framework | Category | +|-----------|----------| +| React | Web | +| Next.js | Web (SSR) | +| Vue | Web | +| Angular | Web | +| JavaScript/TypeScript | Web | +| React Native | Mobile | +| Flutter | Mobile | +| Swift | iOS | +| Android (Kotlin) | Android | + +## Troubleshooting + +### MCP Connection Issues +1. Verify uv: `uv --version` +2. Check AWS credentials: `aws sts get-caller-identity` +3. Restart Kiro + +### Permission Errors +1. Verify `aws-mcp:*` IAM permissions +2. Check `AdministratorAccess-Amplify` is attached +3. Test: `aws amplify list-apps` + +### Sandbox Failures +1. Check CloudFormation events in AWS Console +2. Verify Node.js 18+ is installed +3. Clear cache: `rm -rf node_modules/.cache` + +## Support + +**CTI:** AWS/Amplify/JS + +--- + +This power integrates with AWS MCP Server (Apache-2.0 license). diff --git a/aws-amplify/mcp.json b/aws-amplify/mcp.json new file mode 100644 index 0000000..7a749d9 --- /dev/null +++ b/aws-amplify/mcp.json @@ -0,0 +1,15 @@ +{ + "mcpServers": { + "aws-mcp": { + "command": "uvx", + "timeout": 100000, + "transport": "stdio", + "args": [ + "mcp-proxy-for-aws@latest", + "--log-level", + "ERROR", + "https://aws-mcp.us-east-1.api.aws/mcp" + ] + } + } +} diff --git a/aws-amplify/steering/backend-implementation.md b/aws-amplify/steering/backend-implementation.md new file mode 100644 index 0000000..cb39ef5 --- /dev/null +++ b/aws-amplify/steering/backend-implementation.md @@ -0,0 +1,83 @@ +# Backend Implementation + +Context and routing for the `amplify-backend-implementation` Agent SOP. + +## When to Use This Workflow + +Use this workflow when: +- Setting up user authentication (Cognito) +- Creating data models with GraphQL (AppSync + DynamoDB) +- Adding file storage (S3) +- Implementing serverless functions (Lambda) +- Integrating AI/ML features (Bedrock) + +## Retrieve the SOP + +``` +Tool: retrieve_agent_sop +Parameters: { "sop_name": "amplify-backend-implementation" } +``` + +The SOP provides comprehensive step-by-step guidance. This steering file provides supplementary context. + +## Backend Features Overview + +### Authentication (Auth) +- **AWS Services:** Amazon Cognito +- **Features:** Email/password, social providers, MFA, passwordless, user groups +- **Key file:** `amplify/auth/resource.ts` + +### Data Layer (Data) +- **AWS Services:** AWS AppSync (GraphQL), Amazon DynamoDB +- **Features:** Real-time subscriptions, authorization rules, relationships +- **Key file:** `amplify/data/resource.ts` + +### File Storage (Storage) +- **AWS Services:** Amazon S3 +- **Features:** Access levels (guest, authenticated, owner), file triggers +- **Key file:** `amplify/storage/resource.ts` + +### Serverless Functions (Functions) +- **AWS Services:** AWS Lambda +- **Features:** Event triggers, environment variables, resource access grants +- **Key directory:** `amplify/functions/` + +### AI Features +- **AWS Services:** Amazon Bedrock +- **Features:** Text generation, summarization, conversation routes +- **Requires:** Bedrock model access in target region + +## Framework-Agnostic Backend + +The backend configuration works with all supported frontend frameworks. The `amplify_outputs.json` file is generated after deployment and contains connection details for your frontend. + +## Common Patterns + +### Owner-based Authorization +```typescript +// Users can only access their own data +.authorization(allow => [allow.owner()]) +``` + +### Public Read, Authenticated Write +```typescript +.authorization(allow => [ + allow.guest().to(['read']), + allow.authenticated().to(['create', 'update', 'delete']) +]) +``` + +### Group-based Access +```typescript +.authorization(allow => [ + allow.group('admins').to(['create', 'read', 'update', 'delete']), + allow.authenticated().to(['read']) +]) +``` + +## Next Steps + +After setting up backend: +1. Deploy to sandbox: `npx ampx sandbox` +2. Integrate frontend: Use `amplify-frontend-integration` SOP +3. Deploy to production: Use `amplify-deployment-guide` SOP diff --git a/aws-amplify/steering/deployment-guide.md b/aws-amplify/steering/deployment-guide.md new file mode 100644 index 0000000..e95e89a --- /dev/null +++ b/aws-amplify/steering/deployment-guide.md @@ -0,0 +1,122 @@ +# Deployment Guide + +Context and routing for the `amplify-deployment-guide` Agent SOP. + +## When to Use This Workflow + +Use this workflow when: +- Setting up sandbox development environment +- Deploying to production +- Configuring CI/CD pipelines +- Managing environment variables and secrets +- Setting up custom domains + +## Retrieve the SOP + +``` +Tool: retrieve_agent_sop +Parameters: { "sop_name": "amplify-deployment-guide" } +``` + +## Deployment Options + +### Sandbox Environment (Development) + +Personal cloud environment for rapid iteration: + +```bash +npx ampx sandbox +``` + +**Features:** +- Isolated per-developer +- Real-time backend hot-reload +- Auto-generates types on changes +- No impact on production + +**Requirements:** +- AWS credentials configured +- Node.js 18+ +- `AdministratorAccess-Amplify` policy + +### Amplify Hosting (Production) + +Git-based deployment with automatic builds: + +1. Connect repository in [Amplify Console](https://console.aws.amazon.com/amplify) +2. Configure build settings +3. Deploy on push to branch + +**Branch Strategy:** + +| Branch | Environment | Purpose | +|--------|-------------|---------| +| `main` | Production | Live users | +| `develop` | Staging | QA testing | +| `feature/*` | Preview | PR reviews | + +### Custom CI/CD + +For custom pipelines: + +```bash +npx ampx pipeline-deploy --branch main --app-id +``` + +## Environment Configuration + +### Secrets + +```typescript +// amplify/backend.ts +import { secret } from '@aws-amplify/backend'; + +// Reference secret (set in Amplify Console) +const apiKey = secret('THIRD_PARTY_API_KEY'); +``` + +### Environment Variables + +Set in Amplify Console -> App settings -> Environment variables + +## CI/CD Examples + +### GitHub Actions + +```yaml +name: Deploy Amplify +on: + push: + branches: [main] +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: aws-actions/configure-aws-credentials@v4 + with: + aws-region: us-east-1 + role-to-assume: arn:aws:iam::ACCOUNT:role/GitHubActionsRole + - run: npx ampx pipeline-deploy --branch main --app-id ${{ vars.AMPLIFY_APP_ID }} +``` + +### AWS CodePipeline + +Amplify Hosting includes built-in CI/CD: +- Automatic builds on push +- Preview deployments for PRs +- Environment variable management +- Build notifications + +## Monitoring + +- **CloudWatch:** Lambda logs, API metrics +- **Amplify Console:** Build logs, deployment status +- **X-Ray:** Distributed tracing (if enabled) + +## Next Steps + +After deployment: +- Monitor in Amplify Console +- Set up custom domain +- Configure CloudWatch alarms diff --git a/aws-amplify/steering/frontend-integration.md b/aws-amplify/steering/frontend-integration.md new file mode 100644 index 0000000..9fc47ef --- /dev/null +++ b/aws-amplify/steering/frontend-integration.md @@ -0,0 +1,94 @@ +# Frontend Integration + +Context and routing for the `amplify-frontend-integration` Agent SOP. + +## When to Use This Workflow + +Use this workflow when: +- Adding Amplify to an existing frontend app +- Implementing authentication UI +- Fetching and mutating data +- Setting up real-time subscriptions +- Configuring state management + +## Retrieve the SOP + +``` +Tool: retrieve_agent_sop +Parameters: { "sop_name": "amplify-frontend-integration" } +``` + +## Framework-Specific Guidance + +### React +- Use `@aws-amplify/ui-react` for pre-built components +- Leverage React hooks for auth state (`useAuthenticator`) +- Configure Amplify in `src/main.tsx` or `src/index.tsx` + +### Next.js +- Supports both App Router and Pages Router +- Server components require special handling +- Use `runWithAmplifyServerContext` for SSR + +### Vue +- Use Composition API with `@aws-amplify/ui-vue` +- Configure in main app entry (`main.ts`) + +### Angular +- Use `@aws-amplify/ui-angular` +- Configure in `app.module.ts` +- Implement route guards for protected routes + +### React Native +- Use `@aws-amplify/ui-react-native` +- Configure secure storage for tokens +- Handle offline scenarios with DataStore + +### Flutter +- Use `amplify_flutter` packages +- Configure in `main.dart` +- Platform-specific setup required (iOS/Android) + +### Swift (iOS) +- Use `Amplify` Swift package +- Async/await patterns for all operations +- Configure in `AppDelegate` or `App` struct + +### Android (Kotlin) +- Use `com.amplifyframework` packages +- Coroutines for async operations +- Configure in `Application` class + +## Common Integration Pattern + +```typescript +// 1. Import and configure (do once at app entry) +import { Amplify } from 'aws-amplify'; +import outputs from '../amplify_outputs.json'; +Amplify.configure(outputs); + +// 2. Generate typed client +import { generateClient } from 'aws-amplify/data'; +import type { Schema } from '../amplify/data/resource'; +const client = generateClient(); + +// 3. Use in components +const { data } = await client.models.Todo.list(); +``` + +## UI Components + +Amplify UI provides pre-built, customizable components: + +| Component | Purpose | +|-----------|---------| +| `Authenticator` | Complete auth flow UI | +| `StorageImage` | Display S3 images | +| `FileUploader` | Upload files to S3 | +| `AccountSettings` | User profile management | + +## Next Steps + +After frontend integration: +- Test locally with sandbox: `npx ampx sandbox` +- Deploy: Use `amplify-deployment-guide` SOP