Local Development and Deployment

TL;DR

Webiny is a serverless platform on AWS. Deploy with yarn webiny deploy, develop locally with yarn webiny watch (API uses Local Lambda Development, Admin runs a local React dev server). Projects support multiple environments (long-lived and short-lived). Always redeploy after stopping watch mode.

Deployment

Initial Deployment

Deploy all three applications (Core, API, Admin) at once:

bash
yarn webiny deploy

This deploys to the dev environment by default. First deployment takes 5-15 minutes.

Deploying Individual Applications

bash
yarn webiny deploy core        # Infrastructure only
yarn webiny deploy api         # Backend API only
yarn webiny deploy admin       # Admin frontend only

Deploy to a Specific Environment

bash
yarn webiny deploy --env prod
yarn webiny deploy api --env staging

Get Deployment Info

bash
yarn webiny info              # Shows all URLs (Admin, API, CloudFront)
yarn webiny info --env prod   # Info for a specific environment

Local Development

Before developing locally, you must deploy Core and API first:

bash
yarn webiny deploy core api

Admin Development

bash
yarn webiny watch admin

• Starts a local dev server at http://localhost:3001
• Hot module replacement for instant feedback
• Standard React development experience
• Use for: custom Admin UI extensions, white-label branding, custom views

API Development (Local Lambda Development)

bash
yarn webiny watch api

How it works:

1. Lambda stubs deployed -- real Lambda functions are replaced with stubs that forward events
2. Events forwarded -- requests to AWS get forwarded to your local machine
3. Local execution -- your code runs locally with full AWS Lambda environment
4. Response routing -- responses sent back through the Lambda stub

Benefits:

• See backend code changes instantly (no redeployment)
• Debug locally with standard Node.js tools
• Console logs appear directly in your terminal

IMPORTANT: Redeploy After Watch

When you stop yarn webiny watch api, your Lambda functions still contain stub code. You must redeploy:

bash
yarn webiny deploy api

The watch command prints a reminder when you stop it.

Running Both

You can run both watch commands simultaneously in separate terminals:

bash
# Terminal 1
yarn webiny watch api

# Terminal 2
yarn webiny watch admin

Environments

Long-Lived Environments

Persistent environments maintained over time:

• dev -- daily development
• staging -- pre-production testing
• prod -- production

Best practice: manage via CI/CD pipelines.

Short-Lived Environments

Temporary environments for specific purposes:

• Feature branch testing
• PR previews
• Experimentation

bash
# Create a short-lived environment
yarn webiny deploy --env feature-123

# Destroy when done
yarn webiny destroy --env feature-123

Deployment Modes

Webiny has two deployment templates:

• dev -- smaller, cheaper infrastructure for development
• prod -- production-grade infrastructure with HA, backups, auto-scaling

The mode is determined by whether the environment name is in the ProductionEnvironments list:

tsx
// webiny.config.tsx
<Infra.ProductionEnvironments environments={["prod", "staging"]} />

State Files

State files are JSON files that track the current state of your deployment:

• Store infrastructure resource info, configurations, and metadata
• Essential for managing environments and tracking changes
• Stored in S3 by default

Debugging

API Errors

During yarn webiny watch api:

• Console logs appear directly in the terminal
• Use console.log() for quick debugging
• Use Logger (DI-injected) for production logging to CloudWatch

typescript
import { Logger } from "webiny/api";

// In your extension class
this.logger.info("Processing request...");
this.logger.warn("Something unexpected");
this.logger.error("Something failed");

Admin Errors

Use browser DevTools:

• Console -- view logs and errors
• Network tab -- inspect GraphQL requests/responses
• React Developer Tools -- debug component state/props
• GraphQL Network Inspector -- inspect GraphQL operations

Infrastructure Errors

Deployment errors from Pulumi typically relate to:

• IAM permission issues
• AWS service quotas
• Resource configuration problems

Check the deployment output for specific error messages.

CLI Commands Reference

| Command | Purpose | | --------------------------------------- | ---------------------------------- | | yarn webiny deploy | Deploy all applications | | yarn webiny deploy [core\|api\|admin] | Deploy specific application | | yarn webiny deploy --env <name> | Deploy to specific environment | | yarn webiny destroy --env <name> | Destroy an environment | | yarn webiny watch api | Start local API development | | yarn webiny watch admin | Start local Admin development | | yarn webiny info | Show deployment info and URLs | | yarn webiny info --env <name> | Show info for specific environment | | yarn webiny extension <name> | Install a pre-built extension |

Quick Reference

First deploy:     yarn webiny deploy
Dev API:          yarn webiny watch api
Dev Admin:        yarn webiny watch admin
Get URLs:         yarn webiny info
Deploy env:       yarn webiny deploy --env staging
After watch:      yarn webiny deploy api  (MUST redeploy!)

Related Skills

• webiny-project-structure -- Project layout and webiny.config.tsx
• webiny-infrastructure-extensions -- Customizing AWS infrastructure and environments