Developing with Webiny

Local Development

2
Lesson 2

Local Development

In this lesson, we'll explore how local development works with Webiny. You'll learn about the development workflow, watch commands, and best practices for efficient development.

In this lesson...

Here are the topics we'll cover

code

Understanding the local development workflow.

speed

Developing Admin and API applications.

settings

Environment variables and type safety.

How Local Development Works

Webiny is a serverless platform that runs on AWS. Before you can start local development, you need to deploy your project to AWS. However, you don't need to deploy everything - Webiny projects consist of three main applications (Core, API, and Admin), and you only need Core and API for local development.

Initial Setup

  1. Deploy Core and API - Run yarn webiny deploy core api to create the necessary AWS infrastructure
  2. Start developing - Use watch commands to develop locally
  3. Deploy changes - Deploy when you need to update cloud infrastructure or share your progress (deploying creates a CloudFront URL that your teammates can access)
Cloud Infrastructure Required

Local development requires deployed Core and API applications in AWS. The watch commands connect to this infrastructure while running your code locally.

Admin Deployment Optional

You don't need to deploy the Admin app for local development. Only deploy it with yarn webiny deploy admin when you need a CloudFront URL to share with others or test in production-like conditions.

Watch Commands

Webiny provides watch commands for the Admin and API applications. These commands monitor your code for changes and automatically rebuild when needed.

Admin Application Development

Developing the Admin application is just like any other React app development. You have a local development server, make your changes, and see them reflected instantly in your browser.

Starting the Admin Dev Server

Terminal
Loading...

This command:

  • Starts a local development server on http://localhost:3001
  • Watches for changes in Admin extensions
  • Provides hot module replacement for instant feedback

What You Can Develop Locally

  • Custom Admin UI extensions
  • White-label branding and themes
  • Custom navigation items
  • New Admin pages and views

API Development - Local AWS Lambda Development

API development uses what we call Local AWS Lambda Development. This approach allows you to run your AWS Lambda code locally, without the need to continuously deploy changes to AWS.

Starting API Development

Terminal
Loading...

How It Works

When you run yarn webiny watch api, here's what happens behind the scenes:

  1. Lambda stubs are deployed - Webiny's Lambda functions (like the GraphQL Lambda that serves the remote GraphQL server) are replaced with stub code that forwards events to your local machine
  2. Event forwarding - When a request comes to AWS, it gets forwarded to your local machine
  3. Local execution environment - Your code runs locally with the full AWS Lambda environment (environment variables, context, etc.)
  4. Response routing - After your local code executes, the response is sent back through the Lambda stub to the user

The key benefit: You can immediately see the results of your backend code changes without waiting for deployments. You can also debug your code since it's running in your local environment.

Why This Hybrid Approach?

This hybrid approach (code runs locally, but connects to cloud services) exists because of the serverless nature of the services Webiny relies on. Running DynamoDB, OpenSearch, S3, Cognito, and other AWS services entirely locally would be complex and unreliable. It's simpler and more practical to run your code locally while connecting to real AWS infrastructure - you get fast iteration with a realistic environment.

Important: Redeploy After Watch

When you stop the watch command, your Lambda functions still contain stub code. You must redeploy your API with yarn webiny deploy api to restore the actual Lambda code and make your API functional again in the cloud. Don't worry - the watch command will print a warning message to remind you of this when you stop it.

What You Can Develop Locally

  • Custom GraphQL schemas and resolvers
  • API lifecycle hooks
  • Business logic and data transformations
  • Security extensions
  • Custom API endpoints
  • Background tasks (workflows)

Infrastructure Development

When you need to modify your AWS infrastructure - such as adding CloudWatch alarms, custom S3 buckets, or changing Lambda configurations - you'll use Pulumi-based infrastructure extensions.

Infrastructure changes are made through dedicated extensions that can target Core, API, or Admin applications:

webiny.config.tsx
Loading...

Key points about infrastructure development:

  • Infrastructure changes require redeploying the affected application (Core, API, or Admin)
  • Changes happen at the cloud level, so you can't test them locally with watch commands
  • Use yarn webiny deploy <app> to apply infrastructure changes
Infrastructure Extensions

Infrastructure extensions will be covered in detail in later lessons. For now, just know that any changes to cloud resources require a deployment to take effect.

Type Safety and Build Validation

Webiny enforces TypeScript type checking during builds. Build fails if types don't match - errors are caught before deployment.

This compile-time validation saves you from runtime errors in production. Your IDE will show type errors as you code, and the build process ensures nothing slips through.

Environment Variables

Webiny makes environment variables optional for most development scenarios. The .env file is not required for local development in most cases.

When you do need to set environment variables, use prefixes to target specific applications:

  • WEBINY_ADMIN_ - Variables with this prefix are only applied in the Admin application
  • WEBINY_API_ - Variables with this prefix are only applied in the API application

Example .env file:

.env
Loading...
Application-Specific Variables

Environment variable prefixes ensure variables are only loaded in the appropriate application. This prevents accidental variable leakage between Admin and API applications.

Website Development

If you're developing with Website Builder, you'll need to run your Website application locally (e.g., a Next.js app) in addition to the watch commands.

Website Builder Development

Website development workflow and setup will be covered in detail in the Website Builder lessons.

Quick Onboarding

What about new developers joining an existing Webiny project? Unlike starting a new project where you'd run npx create-webiny-project, onboarding to an existing project is even simpler.

When a developer joins your team, they don't need to run any project scaffolding commands. They simply clone the repository and install dependencies:

Terminal
Loading...

That's it. No complex setup, no configuration files to create, no additional installation steps. The clean project structure means less configuration, fewer commands, and faster time to productivity.

About .env Files

By default, Webiny projects don't require a .env file. However, if your team has added one for project-specific configuration, it's the team's responsibility to communicate what's needed.

The .env file is typically not committed to git (it's in .gitignore), so teams usually maintain:

  • A .env.example file showing the required variables
  • Documentation explaining what each variable does
  • Internal processes for sharing sensitive values securely

If you're joining a project and see a .env.example file, check with your team about which values you need to set up locally.

Development Best Practices

  1. Deploy Core and API first - Run yarn webiny deploy core api before starting local development

  2. Use watch commands - Use yarn webiny watch during development rather than redeploying repeatedly

  3. Deploy when sharing - Deploy the Admin app when you need to share your work via CloudFront URL or update cloud infrastructure

?

It's time to take a quiz!

Test your knowledge and see what you've just learned.

What applications do you need to deploy before you can start local development with Webiny?

Summary

Webiny's local development experience is designed for productivity:

  • Admin development - Standard React workflow with instant hot-reload
  • API development - Local AWS Lambda Development with full execution environment
  • Cloud infrastructure - Connects to deployed AWS resources for realistic testing

The watch commands and Local AWS Lambda Development make developing with Webiny efficient and productive.

In the next lesson, we'll dive deeper into the extension system and learn how to create your own extensions.

Use Alt + ← / → to navigate