Getting Started

Install as a dev dependency: composer require kirschbaum-development/sst-laravel --dev.
Prerequisites: AWS credentials with deploy permissions, Node/npm for the SST CLI, and Docker if you are building container-based Lambda images.
Run the package installer: php artisan sst:install. This scaffolds the SST wiring, typically sst.config.ts and a Dockerfile. Review those first.
First use case: deploy a disposable stage, e.g. npx sst dev --stage dev for live development or npx sst deploy --stage staging for a real deploy. Confirm the Laravel app responds and runtime env vars are present.
Look first at sst.config.ts for stage/env definitions and the Dockerfile for what gets copied into the Lambda image.

Implementation Patterns

Use one SST stage per environment: dev, staging, pr-123, production. Map stages to Laravel config and keep .env local only.
Define environment variables in sst.config.ts or SST secrets, not in the container image. Since 0.7.4, treat images as environment-agnostic and inject env at runtime.
CI/CD pattern: run composer install --no-dev --optimize-autoloader, npm ci, then npx sst deploy --stage $STAGE. Run migrations as a separate controlled step, not during cold starts.
Local development: use npx sst dev for live Lambda execution and npx sst logs for CloudWatch output. For one-off Artisan commands, use SST shell/remote invocation where available or a temporary admin route.
Configure S3, SQS, Redis, custom domains, and other AWS resources in sst.config.ts; grant the Lambda role only the permissions it needs.
Preview environments: wire PR stages to ephemeral databases/buckets and tear them down with npx sst remove --stage pr-123.

0.7.4 fixes environment handling: env is no longer baked into container images, and unset env outputs are omitted instead of being sent as undefined. Rebuild and redeploy images after upgrading; do not add .env back into the Dockerfile.
Missing env vars may now be absent rather than empty. Validate required variables in Laravel config/bootstrap and fail fast with a clear error.
Lambda storage is ephemeral: use S3 for uploads, Redis/DynamoDB for cache/session, and an external database such as RDS or PlanetScale rather than local SQLite.
Watch image size and cold starts: exclude node_modules, tests, .git, and local env files from the image; keep Composer production-only.
Debug with npx sst logs --stage <stage> and CloudWatch. Check IAM role permissions first when AWS calls fail.
Pin the package version in composer.json. 0.7.4 is a patch release with no breaking changes noted, but the container/env behavior changed enough to warrant a fresh deploy and smoke test.
Extension points: customize the generated sst.config.ts and Dockerfile, add SST constructs for queues/storage/domains, and keep Laravel config/env indirection so stage changes do not require code changes.