webiny-local-development

name: webiny-local-development context: webiny-extensions description: > Deploying, developing locally, managing environments, and debugging Webiny projects. Use this skill when the developer asks about deployment commands (deploy, destroy, info), local development with watch mode (API or Admin), the Local Lambda Development system, environment management (long-lived vs short-lived, production vs dev modes), build parameters, state files, debugging API/Admin/Infrastructure errors, or the redeploy-after-watch requirement.

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:

yarn webiny deploy

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

Deploying Individual Applications

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

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

Get Deployment Info

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:

yarn webiny deploy core api

Admin Development

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)

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:

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:

# 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

# 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:

// 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

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

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